tool-call-warrant v0.1.0

Pre-execution guard layer for AI agent tool calls. Warrants are structured confirmations that pass through a rule engine before a tool is allowed to execute.

---

Why this exists

AI coding agents (Claude Code, Cursor, AGY, Gemini CLI) execute tool calls with zero pre-execution confirmation. When an agent decides to strace a production server, delete 50k files, DROP TABLE, or POST to a webhook, the human sees only the retrospective log. This is the core "rogue agent" failure mode that developers complain about in production.

tool-call-warrant is a zero-dependency, cross-runtime (Python + Node) plugin that intercepts tool calls before execution and returns a structured warrant verdict: ALLOW, DENY, MODIFY, or CONFIRM.

Install

Python

pip install -e .
warrant-check --help

Node

npm install -g .
warrant-check --help   # uses scripts/warrant-check.mjs via package.json `bin`

Zero runtime dependencies in both languages. dependencies = [] / "dependencies": {}.

Quickstart

As a CLI

# Simulate a destructive call — returns DENY (exit 1)
warrant-check check --tool bash --args '{"command":"rm -rf /app"}' --format json

# Simulate a safe call — returns ALLOW (exit 0)
warrant-check check --tool mcp__filesystem__ls --args '{"path":"/app/docs"}'

# Force ALLOW despite DENY (human override; logs to audit trail)
warrant-check check --tool bash --args '{"command":"rm -rf /app"}' --confirm

# Inspect audit log
warrant-check audit --since 2026-08-09T00:00:00Z --format json

As a library (Python)

import sys; sys.path.insert(0, "src")
from warrant_core import classify_risk, get_verdict

risk, matched = classify_risk("bash", {"command": "rm -rf /"})
# risk = "DESTROY"; matched = ["destroy:recursive delete"]

verdict = get_verdict(risk)  # "DENY"

As a library (Node)

import { classifyRisk, getVerdict } from 'tool-call-warrant';

const [risk, matched] = classifyRisk("bash", { command: "rm -rf /" });
// risk = "DESTROY"; matched = ["destroy:recursive delete"]

const verdict = getVerdict(risk); // "DENY"

Risk Classification

Risk	Patterns	Verdict	Exit code
DESTROY	rm -rf, DROP TABLE, TRUNCATE, kill -9, shutdown, mkfs	DENY	1
EXFILTRATE	Private IPs, curl | sh, eval(base64_decode(...)), ~/.env, DB dumps, printenv	CONFIRM	2
EXECUTE	bash -c, eval(, subprocess, child_process.spawn, gcc/go build/rustc/npm install, | sh	CONFIRM	2
OBSERVE	ps aux, SELECT *, chmod 777, ls -R /, cat ~/.ssh/id_rsa	ALLOW	0
BENIGN	ls, git status, cat README.md, find ., npm test	ALLOW	0
UNKNOWN	(no pattern matched)	CONFIRM	2

Global blocks (always force DENY → DESTROY):

• curl <anything> | sh
• wget -O- | sh
• eval(base64_decode(...))

CLI Subcommands

Subcommand	Purpose	Exit codes
check	Evaluate a tool call against rules	0=ALLOW/MODIFY, 1=DENY, 2=CONFIRM
diff	Show arg changes (proposed → allowed)	0=ok, 1=invalid input
audit	Read historical warrant decisions	0=ok, 1=invalid input
parse	Validate warrant JSON schema	0=valid, 1=invalid

check flags

Flag	Effect
--tool NAME	(required) Tool name
--args JSON	Tool arguments as JSON object (default {})
--rules PATH	Path to rules file (reserved for v0.2)
--format json|text	Output format (default text)
--confirm	Human override: force ALLOW
--reject	Human override: force DENY
--modify	Human override: emit MODIFY verdict
--dry-run	Do not write audit log entry
--audit	With --dry-run: still write audit log

Hook Integration (per-agent)

{
  "event": "pre_tool_call",
  "tool": "*",
  "handler": "warrant-check --tool ${TOOL_NAME} --args ${TOOL_ARGS} --format json",
  "on_allow": "proceed",
  "on_deny": "block_and_log",
  "on_confirm": "pause_and_notify"
}

See skills/tool-call-warrant/SKILL.md for per-framework integration notes.

Cited Evidence (Honest Pillar)

1. HN Ask: How do you enforce permissions for AI agent tool calls in production? — 350+ points, multiple "how do I prevent rogue agents" threads
2. HN signal: "AgentWard — After an AI agent deleted files, I built a runtime enforcer."
3. HN signal: "Runtime security for AI agents (injection, tool abuse, data exfiltration)"
4. GitHub Search: @twire/guard (Edge/Node only, 0.1.1) and @jc4649/pi-toolcall-guard (pi-specific, 0.1.0) — both narrow in scope, neither Python+Node cross-runtime
5. npm + PyPI: tool-call-guard, tool-call-confirm, tool-interceptor — no cross-runtime distribution found

Named Competitors

Package	Runtime	Limit
@twire/guard	Edge/Node only	No Python, narrow scope
@jc4649/pi-toolcall-guard	pi-agent only	Framework-locked, no general plugin

Limitations / Non-Goals

• Rule engine is synchronous, single-process. No distributed enforcement across hosts.
• Rules file is plaintext. No schema validation beyond JSON syntax (custom rules loader is v0.2).
• First-run UX requires manual --audit to inspect behavior before enabling auto-confirm.
• Not an OS-level sandbox. Use seccomp, firejail, gVisor for kernel-level isolation.
• Not an LLM-side guardrail. Does not filter agent output or detect prompt-injection.
• Not a substitute for human review. Edge cases (compound operations, multi-step plans) need operator judgment.

Plugin Manifest

See plugin.json for the full agent-runtime plugin declaration (hooks, scripts, rules, skills). The manifest declares dependencies: [] per spec.

Architecture

tool-call-warrant/
├── plugin.json             # Agent-runtime manifest
├── pyproject.toml          # Python packaging (zero deps)
├── package.json            # Node packaging (zero deps)
├── src/
│   ├── warrant_core.py     # Python rule engine (zero deps)
│   ├── index.mjs           # Node rule engine mirror (zero deps)
│   └── index.d.ts          # TypeScript definitions
├── scripts/
│   ├── warrant_check.py     # Python CLI
│   ├── warrant-check.mjs   # Node CLI
│   └── pre-push-gate.sh    # Mechanical gate before push
├── rules/
│   └── tool-warrant-rules.md
├── skills/
│   └── tool-call-warrant/SKILL.md
├── tests/
│   ├── COVERAGE.md         # 50 enumerated acceptance criteria
│   ├── test_warrant.py     # 128 pytest tests
│   └── test_warrant.mjs    # 107 Node tests
├── README.md
├── LICENSE                 # MIT
├── CHANGELOG.md
└── QA_REPORT.md            # Self-review (build card)

Verification

pytest -q             # 128 passed
npm test              # 107 passed
warrant-check --help  # CLI works
node scripts/warrant-check.mjs --help

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.