@mokuyoaxis/agent-guard 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,141 @@
1
+ # agent-guard adapter for Claude Code
2
+
3
+ Wraps Claude Code's `PreToolUse` hook so matching Bash calls that reach the
4
+ hook pass through the shared core (`skills/delete-guard/scripts/check.py`)
5
+ before execution. A missing, mismatched, or timed-out hook is not covered.
6
+ The rule engine is not duplicated here - this adapter only translates the
7
+ Decision Protocol onto Claude Code's native hook semantics.
8
+
9
+ ## Decision mapping
10
+
11
+ | Core decision | Claude Code behavior |
12
+ |---|---|
13
+ | `ALLOW` (no compensation) | exit 0, silent |
14
+ | `ALLOW` (compensation applied) | `permissionDecision: "allow"` + reason naming what was quarantined and the txid |
15
+ | `ASK` (`COMPOUND_CWD_DELETE`, `COMPOUND_CREATE_DELETE`) | `permissionDecision: "ask"` - ASK_ONCE, reason shown to the human; splitting the command avoids future prompts |
16
+ | `BLOCK` | exit 2 - stderr is fed back to **Claude**, so the model sees the code, the explanation, and the remediation |
17
+ | malformed hook payload / guard failure after adapter starts | exit 2 (fail-closed for that call) |
18
+ | Python launch/runtime failure while bridge runs | bridge converts non-0/2 exits to exit 2 |
19
+
20
+ Note the deliberate asymmetry: allow/ask reasons are user-facing, while
21
+ BLOCK uses the stderr channel so the *model* learns the remediation.
22
+
23
+ In a headless run (`claude -p`) with no interactive approver, an ASK that
24
+ nobody approves is a **denial** and the command does not run. That is the
25
+ fail-safe outcome, but wire up an approver if you need ASK to be an actual
26
+ prompt.
27
+
28
+ ## Install
29
+
30
+ 1. Copy or reference this repository from a stable path.
31
+
32
+ 2. Add the hook to project `.claude/settings.json`
33
+ (see `settings.example.json`):
34
+
35
+ ```json
36
+ {
37
+ "hooks": {
38
+ "PreToolUse": [
39
+ {
40
+ "matcher": "Bash",
41
+ "hooks": [
42
+ {
43
+ "type": "command",
44
+ "command": "/bin/sh /absolute/path/to/agent-guard/adapters/claude/hook_bridge.sh /absolute/path/to/python3",
45
+ "timeout": 120
46
+ }
47
+ ]
48
+ }
49
+ ]
50
+ }
51
+ }
52
+ ```
53
+
54
+ This bridge is for POSIX hosts. Replace both repository and interpreter
55
+ paths with absolute paths on your machine; quote paths containing spaces
56
+ for the shell command. A direct `python3 pre_tool_use.py` hook may be
57
+ skipped by Claude Code if Python fails before the adapter starts.
58
+
59
+ On Windows, use an absolute path to `python` with a direct adapter command;
60
+ a stock install may not have a `python3` alias. The POSIX shell bridge does
61
+ not run natively there, and this direct form has **not** been validated
62
+ against Python startup failure on a real Windows Claude Code host.
63
+
64
+ 3. Optionally copy `skills/delete-guard/SKILL.md` into the project's skill
65
+ directory so the model prefers the safe-delete flow proactively.
66
+
67
+ 4. From the project directory, run:
68
+
69
+ ```sh
70
+ python3 /absolute/path/to/agent-guard/doctor.py claude --probe
71
+ ```
72
+
73
+ By default it checks only this project's
74
+ `.claude/settings.json`; use `--config` to select another settings file,
75
+ such as `.claude/settings.local.json` or a user-level file. It checks the
76
+ exact `Bash` matcher, synchronous POSIX bridge and interpreter, then sends
77
+ harmless payloads to that bridge. `--json` prints machine-readable status.
78
+ A passing check does **not** inspect Claude's merged settings, prove a
79
+ running session loaded the hook, or verify host-level interception. For
80
+ those claims, use the isolated host acceptance in the
81
+ [capability matrix](../../docs/harness-capabilities.md).
82
+ Add `--check-drift` to compare the installed Claude Code version with the
83
+ shipped profile and compute privacy-safe configuration/runtime
84
+ fingerprints. `CURRENT` still does not prove live interception; see the
85
+ [drift status contract](../../docs/host-drift.md).
86
+ An explicit `--live-sentinel` may then use one configured model call in a
87
+ private fixture and requires adapter, audit, host-feedback, and marker
88
+ evidence. It keeps `dontAsk` and never enables permission bypass.
89
+
90
+ Requirements: Python 3.9+, POSIX shell, git. No third-party packages.
91
+ The optional Claude doctor uses only standard-library modules; the adapter
92
+ does not require it at runtime.
93
+
94
+ ## Conformance
95
+
96
+ `tests/test_conformance.py` pins the cross-harness guarantee: identical
97
+ command + cwd + workspace state must produce identical core decision +
98
+ reason code through any adapter. Run it after any change to either side:
99
+
100
+ ```
101
+ python3 -m unittest tests.test_conformance
102
+ ```
103
+
104
+ Debug: set `AGENT_GUARD_DEBUG=1` to print the raw core verdict JSON to
105
+ stderr.
106
+
107
+ ## Shell dialect
108
+
109
+ The hook forwards a shell dialect to `check.py` so Windows-native command
110
+ lines are lexed with the right rules. Precedence:
111
+
112
+ | Source | Example |
113
+ |---|---|
114
+ | hook payload | `"dialect": "powershell"` (also `shell_dialect`) |
115
+ | environment | `AGENT_GUARD_DIALECT=powershell` |
116
+ | default | `posix` |
117
+
118
+ The prefilter follows the dialect: the POSIX regex cannot see
119
+ `ri build -r -fo`, so a Windows-native payload would otherwise skip the
120
+ guard entirely. The POSIX prefilter is unchanged, so the default path keeps
121
+ its exact behaviour. An unrecognised dialect selector is **not** swapped
122
+ for POSIX - `check.py` returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
123
+
124
+ ## Live-tested
125
+
126
+ Validated end-to-end against real Claude Code sessions (2.1.270 and 2.1.273) with a
127
+ scripted mock Anthropic endpoint standing in for the model, plus the
128
+ `python3`-free regression tests. See
129
+ [`docs/test-report-claude-code-harness.md`](../../docs/test-report-claude-code-harness.md)
130
+ and the shipped harness in [`harness/`](harness/README.md).
131
+
132
+ The guard child is spawned with `sys.executable`, never `python3` from
133
+ `PATH`: on a host with only `python`, a hardcoded `python3` made every
134
+ interception fail closed and the guard silently unusable. See the report's
135
+ A/B evidence.
136
+
137
+ The 2.1.273 run used the POSIX bridge and checked healthy compensation,
138
+ hard BLOCK, headless ASK denial, and an injected Python process failure.
139
+ This does **not** prove that a missing hook, unmatched tool, or timed-out hook
140
+ is blocked: those are host-level fail-open boundaries. The adapter only
141
+ matches `Bash`; other tools and real-model behavior are outside this test.
@@ -0,0 +1,17 @@
1
+ {
2
+ "schema_version": 1,
3
+ "profile_id": "claude-code-pretooluse-bash-v1",
4
+ "harness": "claude",
5
+ "display_name": "Claude Code",
6
+ "executable_candidates": ["claude"],
7
+ "version_args": ["--version"],
8
+ "version_pattern": "(?<![0-9])([0-9]+\\.[0-9]+\\.[0-9]+)(?![0-9])",
9
+ "tested_versions": ["2.1.270", "2.1.273"],
10
+ "contract": {
11
+ "event": "PreToolUse",
12
+ "tools": ["Bash"],
13
+ "blocking": true,
14
+ "ask": "native",
15
+ "configuration_scope": "selected-file-only"
16
+ }
17
+ }
@@ -0,0 +1,59 @@
1
+ # Claude Code end-to-end harness
2
+
3
+ Reproduces the live interception test in
4
+ [`docs/test-report-claude-code-harness.md`](../../../docs/test-report-claude-code-harness.md):
5
+ the **real** Claude Code CLI, the **real** agent-guard `PreToolUse` hook, and
6
+ a **scripted mock Anthropic endpoint** standing in for the model.
7
+
8
+ The model is not the subject of the test - the harness interception path is.
9
+ Swapping the model for a scripted endpoint makes the run deterministic and
10
+ network-free while every hook, permission, and guard code path stays real.
11
+
12
+ ## Pieces
13
+
14
+ | File | Role |
15
+ |---|---|
16
+ | `mock_anthropic_api.mjs` | Minimal Anthropic Messages API. Serves one scripted turn per request and advances the script only when the client sends back a `tool_result`, so one scripted turn == one harness turn. |
17
+ | `run_scenario.sh` | Fresh git project + real POSIX hook bridge in `.claude/settings.json` + CLI run, capturing transcript, HTTP request log, and `.agent-trash/`. |
18
+ | `run_scenario_no_python3.sh` | Same, but the hook is invoked as `python` and the CLI runs on a `PATH` with **no `python3`** - the Windows / minimal-image shape that made the adapter fail closed. |
19
+
20
+ ## Run
21
+
22
+ ```bash
23
+ npm install -g @anthropic-ai/claude-code # or point CLAUDE_BIN at any build
24
+ CLAUDE_BIN=claude bash adapters/claude/harness/run_scenario.sh \
25
+ relocate "rm -rf build" 8901
26
+ ```
27
+
28
+ `run_scenario.sh <name> <command> <port> [permission-mode]`
29
+
30
+ For the no-`python3` variant, create a directory holding `python`, `git`,
31
+ and the POSIX utilities the guard's own commands need, then:
32
+
33
+ ```bash
34
+ bash adapters/claude/harness/run_scenario_no_python3.sh \
35
+ nopy3_fixed "rm -rf build" 8908
36
+ ```
37
+
38
+ `HARNESS_OUT` selects the output root (default `/tmp/agent-guard-harness`).
39
+ The runner refuses to overwrite an existing scenario directory. Set
40
+ `HOOK_PYTHON_BIN=/bin/false` to inject a process-local Python failure; it
41
+ does not change the user's Claude configuration. The runner requests only the
42
+ project setting source, skips unrelated MCP config, and does not persist the
43
+ session (managed settings, if present, are outside this switch).
44
+ The no-`python3` runner intentionally retains its direct `python` entrypoint
45
+ to test that older platform boundary.
46
+
47
+ ## Outputs (per scenario)
48
+
49
+ ```
50
+ <out>/<name>/
51
+ ├── script.json # the scripted model turns
52
+ ├── transcript.jsonl # claude --output-format stream-json --include-hook-events
53
+ ├── requests.jsonl # what the CLI actually sent the endpoint
54
+ ├── stderr.txt, exit.txt
55
+ └── project/ # the workspace afterwards (incl. .agent-trash/)
56
+ ```
57
+
58
+ The `hook_response` records in `transcript.jsonl` carry the hook's stdout and
59
+ exit code, which is where the `permissionDecision` mapping is observable.
@@ -0,0 +1,47 @@
1
+ // Mock Anthropic Messages API. Advances the script only when the client
2
+ // returns a tool_result, so one scripted turn == one harness turn.
3
+ import http from "node:http";
4
+ import fs from "node:fs";
5
+
6
+ const PORT = Number(process.env.MOCK_PORT || 8899);
7
+ const SCRIPT = JSON.parse(fs.readFileSync(process.env.MOCK_SCRIPT, "utf8"));
8
+ const LOG = process.env.MOCK_LOG || "/tmp/ccharness/requests.jsonl";
9
+ fs.writeFileSync(LOG, "");
10
+
11
+ let turn = 0, seen = 0;
12
+ const isToolResult = (body) => {
13
+ const msgs = body.messages || [];
14
+ for (let i = msgs.length - 1; i >= 0; i--) {
15
+ const c = msgs[i].content;
16
+ if (Array.isArray(c) && c.some((b) => b.type === "tool_result")) return true;
17
+ }
18
+ return false;
19
+ };
20
+
21
+ const server = http.createServer((req, res) => {
22
+ let raw = "";
23
+ req.on("data", (c) => (raw += c));
24
+ req.on("end", () => {
25
+ let body = {};
26
+ try { body = JSON.parse(raw); } catch {}
27
+ const n = ++seen;
28
+ const tool_res = isToolResult(body);
29
+ fs.appendFileSync(LOG, JSON.stringify({
30
+ n, path: req.url, ts: new Date().toISOString(), model: body.model,
31
+ tool_result: tool_res, messages: body.messages,
32
+ system: typeof body.system === "string" ? body.system.slice(0, 2000) : body.system,
33
+ }) + "\n");
34
+
35
+ const reply = SCRIPT[Math.min(turn, SCRIPT.length - 1)];
36
+ if (turn < SCRIPT.length - 1 && tool_res) turn++;
37
+
38
+ res.writeHead(200, { "Content-Type": "application/json" });
39
+ res.end(JSON.stringify({
40
+ id: "msg_mock_" + n, type: "message", role: "assistant",
41
+ model: body.model || "claude-mock", content: reply.content,
42
+ stop_reason: reply.stop_reason || "end_turn", stop_sequence: null,
43
+ usage: { input_tokens: 100, output_tokens: 50 },
44
+ }));
45
+ });
46
+ });
47
+ server.listen(PORT, "127.0.0.1", () => console.log("mock ready " + PORT));
@@ -0,0 +1,79 @@
1
+ #!/usr/bin/env bash
2
+ # One end-to-end scenario: fresh git project + real agent-guard PreToolUse hook
3
+ # + real Claude Code CLI pointed at a scripted mock Anthropic endpoint.
4
+ set -uo pipefail
5
+
6
+ # Repo root resolved from this script, so the harness travels with a checkout.
7
+ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
8
+ CLAUDE_BIN="${CLAUDE_BIN:-claude}"
9
+ HOOK_PYTHON_BIN="${HOOK_PYTHON_BIN:-$(command -v python3)}"
10
+
11
+ NAME="$1"; CMD="$2"; PORT="$3"; PERM_MODE="${4:-dontAsk}"
12
+ RUNS="${HARNESS_OUT:-/tmp/agent-guard-harness}/$NAME"
13
+ case "$NAME" in
14
+ ''|.|..|*/*) echo "Scenario name must be a single directory name" >&2; exit 1 ;;
15
+ esac
16
+ mkdir -p "$(dirname "$RUNS")" || exit 1
17
+ if ! mkdir "$RUNS"; then
18
+ echo "Refusing to overwrite existing harness output: $RUNS" >&2
19
+ exit 1
20
+ fi
21
+ mkdir -p "$RUNS/project/.claude" || exit 1
22
+
23
+ # ---- disposable git project with a regenerable-looking tree ----
24
+ P="$RUNS/project"
25
+ git -C "$P" init -q
26
+ git -C "$P" config user.email harness@local
27
+ git -C "$P" config user.name harness
28
+ git -C "$P" config commit.gpgsign false
29
+ printf 'node_modules/\n*.log\n' > "$P/.gitignore"
30
+ mkdir -p "$P/src" "$P/build"
31
+ printf "print('base')\n" > "$P/src/main.py"
32
+ printf "artifact\n" > "$P/build/o.js"
33
+ printf "log line\n" > "$P/app.log"
34
+ printf "valuable notes\n" > "$P/NOTES.md"
35
+ git -C "$P" add -A && git -C "$P" commit -qm baseline
36
+
37
+ # ---- the real agent-guard hook ----
38
+ cat > "$P/.claude/settings.json" <<JSON
39
+ {
40
+ "hooks": {
41
+ "PreToolUse": [
42
+ { "matcher": "Bash",
43
+ "hooks": [ { "type": "command",
44
+ "command": "/bin/sh $REPO_ROOT/adapters/claude/hook_bridge.sh $HOOK_PYTHON_BIN",
45
+ "timeout": 120 } ] }
46
+ ]
47
+ }
48
+ }
49
+ JSON
50
+
51
+ # ---- scripted mock endpoint ----
52
+ node -e '
53
+ const fs=require("fs");
54
+ const cmd=process.argv[1];
55
+ fs.writeFileSync(process.argv[2], JSON.stringify([
56
+ {content:[{type:"text",text:"Recon."},{type:"tool_use",id:"toolu_recon",name:"Bash",input:{command:"ls -A"}}],stop_reason:"tool_use"},
57
+ {content:[{type:"text",text:"Executing requested cleanup."},{type:"tool_use",id:"toolu_d",name:"Bash",input:{command:cmd}}],stop_reason:"tool_use"},
58
+ {content:[{type:"text",text:"Scenario finished."}],stop_reason:"end_turn"}
59
+ ]));' "$CMD" "$RUNS/script.json"
60
+
61
+ setsid nohup env MOCK_SCRIPT="$RUNS/script.json" MOCK_PORT="$PORT" \
62
+ MOCK_LOG="$RUNS/requests.jsonl" node "$REPO_ROOT/adapters/claude/harness/mock_anthropic_api.mjs" \
63
+ > "$RUNS/mock.log" 2>&1 < /dev/null &
64
+ MOCK_PID=$!
65
+ for i in $(seq 1 40); do curl -s -o /dev/null "http://127.0.0.1:$PORT/v1/messages" && break; sleep 0.25; done
66
+
67
+ # ---- run the real harness ----
68
+ cd "$P"
69
+ timeout 180 env ANTHROPIC_BASE_URL="http://127.0.0.1:$PORT" ANTHROPIC_AUTH_TOKEN=mock-token \
70
+ "$CLAUDE_BIN" -p "Clean up the build output in this project." \
71
+ --output-format stream-json --verbose --include-hook-events \
72
+ --setting-sources project --strict-mcp-config --no-session-persistence \
73
+ --model claude-sonnet-4-5 --permission-mode "$PERM_MODE" \
74
+ --session-id "$(node -e 'console.log(require("crypto").randomUUID())')" \
75
+ > "$RUNS/transcript.jsonl" 2> "$RUNS/stderr.txt"
76
+ echo "claude exit=$?" > "$RUNS/exit.txt"
77
+ kill $MOCK_PID 2>/dev/null
78
+ wait $MOCK_PID 2>/dev/null
79
+ echo "scenario $NAME done"
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env bash
2
+ # End-to-end through the REAL Claude Code harness with a PATH that has
3
+ # `python` but no `python3` - the Windows shape from the issue.
4
+ set -uo pipefail
5
+
6
+ # Repo root resolved from this script, so the harness travels with a checkout.
7
+ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
8
+ CLAUDE_BIN="${CLAUDE_BIN:-claude}"
9
+ NAME="$1"; CMD="$2"; PORT="$3"
10
+ RUNS="${HARNESS_OUT:-/tmp/agent-guard-harness}/$NAME"
11
+ case "$NAME" in
12
+ ''|.|..|*/*) echo "Scenario name must be a single directory name" >&2; exit 1 ;;
13
+ esac
14
+ mkdir -p "$(dirname "$RUNS")" || exit 1
15
+ if ! mkdir "$RUNS"; then
16
+ echo "Refusing to overwrite existing harness output: $RUNS" >&2
17
+ exit 1
18
+ fi
19
+ mkdir -p "$RUNS/project/.claude" || exit 1
20
+ P="$RUNS/project"
21
+ git -C "$P" init -q && git -C "$P" config user.email h@l && git -C "$P" config user.name h && git -C "$P" config commit.gpgsign false
22
+ printf 'node_modules/\n*.log\n' > "$P/.gitignore"
23
+ mkdir -p "$P/src" "$P/build" && printf "print('base')\n" > "$P/src/main.py" && printf artifact > "$P/build/o.js" && printf log > "$P/app.log"
24
+ git -C "$P" add -A && git -C "$P" commit -qm baseline
25
+ cat > "$P/.claude/settings.json" <<JSON
26
+ { "hooks": { "PreToolUse": [ { "matcher": "Bash",
27
+ "hooks": [ { "type": "command", "command": "python $REPO_ROOT/adapters/claude/pre_tool_use.py", "timeout": 120 } ] } ] } }
28
+ JSON
29
+ node -e '
30
+ const fs=require("fs");const cmd=process.argv[1];
31
+ fs.writeFileSync(process.argv[2], JSON.stringify([
32
+ {content:[{type:"text",text:"Recon."},{type:"tool_use",id:"t1",name:"Bash",input:{command:"ls -A"}}],stop_reason:"tool_use"},
33
+ {content:[{type:"text",text:"Executing."},{type:"tool_use",id:"t2",name:"Bash",input:{command:cmd}}],stop_reason:"tool_use"},
34
+ {content:[{type:"text",text:"Done."}],stop_reason:"end_turn"}]));' "$CMD" "$RUNS/script.json"
35
+ setsid nohup env MOCK_SCRIPT="$RUNS/script.json" MOCK_PORT="$PORT" MOCK_LOG="$RUNS/requests.jsonl" \
36
+ node "$REPO_ROOT/adapters/claude/harness/mock_anthropic_api.mjs" > "$RUNS/mock.log" 2>&1 < /dev/null &
37
+ MP=$!
38
+ for i in $(seq 1 40); do curl -s -o /dev/null "http://127.0.0.1:$PORT/v1/messages" && break; sleep 0.25; done
39
+ cd "$P"
40
+ # PATH deliberately carries NO python3: the hook itself is invoked via `python`.
41
+ timeout 180 env PATH=/tmp/nopy3bin ANTHROPIC_BASE_URL="http://127.0.0.1:$PORT" ANTHROPIC_AUTH_TOKEN=mock-token \
42
+ "$CLAUDE_BIN" -p "Clean up build output." \
43
+ --output-format stream-json --verbose --include-hook-events \
44
+ --setting-sources project --strict-mcp-config --no-session-persistence \
45
+ --model claude-sonnet-4-5 --permission-mode dontAsk \
46
+ > "$RUNS/transcript.jsonl" 2> "$RUNS/stderr.txt"
47
+ echo "claude exit=$?" > "$RUNS/exit.txt"
48
+ kill $MP 2>/dev/null; wait $MP 2>/dev/null
49
+ echo "scenario $NAME done"
@@ -0,0 +1,33 @@
1
+ #!/bin/sh
2
+ # Claude Code does not block a PreToolUse call for most hook errors other than
3
+ # exit 2. Keep this bridge alive long enough to translate Python launch/runtime
4
+ # failures into an explicit refusal. Missing hooks and host timeouts remain
5
+ # outside the bridge's control.
6
+
7
+ if [ "$#" -ne 1 ]; then
8
+ printf '%s\n' '[agent-guard] Claude hook bridge needs one absolute Python path' >&2
9
+ exit 2
10
+ fi
11
+
12
+ case "$1" in
13
+ /*) python_bin=$1 ;;
14
+ *)
15
+ printf '%s\n' '[agent-guard] Claude hook Python path must be absolute' >&2
16
+ exit 2
17
+ ;;
18
+ esac
19
+
20
+ bridge_dir=$(CDPATH= cd -P "$(dirname "$0")" 2>/dev/null && pwd -P) || {
21
+ printf '%s\n' '[agent-guard] Claude hook bridge directory unavailable' >&2
22
+ exit 2
23
+ }
24
+
25
+ "$python_bin" "$bridge_dir/pre_tool_use.py"
26
+ status=$?
27
+ case "$status" in
28
+ 0|2) exit "$status" ;;
29
+ *)
30
+ printf '[agent-guard] Claude hook process failed (exit %s); refusing tool call\n' "$status" >&2
31
+ exit 2
32
+ ;;
33
+ esac