@aporthq/aport-agent-guardrails 1.0.12 → 1.0.13

package/bin/openclaw

@@ -374,6 +374,12 @@ YAML
         fi
     fi
 
+    # Backup a file before overwriting (creates .bak); defined here before first use
+    backup_file() {
+        local f="$1"
+        [ -f "$f" ] && cp "$f" "${f}.bak"
+    }
+
     # So the default config (openclaw.json) has plugin mode/apiUrl - gateway often loads it, not config.yaml
     OPENCLAW_JSON="$CONFIG_DIR/openclaw.json"
     if [ -f "$OPENCLAW_JSON" ] && command -v jq &>/dev/null; then
@@ -411,7 +417,7 @@ YAML
                 | .source = "path"
                 | .sourcePath = $plugin_path
                 | .installPath = $plugin_path)
-        ' "$OPENCLAW_JSON" > "$OPENCLAW_JSON.tmp" 2>/dev/null && mv "$OPENCLAW_JSON.tmp" "$OPENCLAW_JSON"; then
+        ' "$OPENCLAW_JSON" > "$OPENCLAW_JSON.tmp" 2>/dev/null && { backup_file "$OPENCLAW_JSON"; mv "$OPENCLAW_JSON.tmp" "$OPENCLAW_JSON"; }; then
             if [ "$USE_HOSTED_PASSPORT" = true ]; then
                 echo "  ✅ Merged plugin config into $OPENCLAW_JSON (mode=$PLUGIN_MODE, hosted passport, allowUnmappedTools=$ALLOW_UNMAPPED)"
             else
@@ -484,7 +490,7 @@ if [ -f "$PASSPORT_FILE" ] && command -v jq &>/dev/null; then
                     .max_execution_time = (.limits.max_execution_time // 300)) |
                 .limits |= del(.allowed_commands, .blocked_patterns, .max_execution_time)
             else . end)
-        ' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"
+        ' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && { backup_file "$PASSPORT_FILE"; mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"; }
         echo "  ✅ Passport normalized."
     fi
     echo "  📋 Updating passport allowed_commands (default commands: bash, sh, ls, mkdir, npm, …)..."
@@ -501,12 +507,12 @@ if [ -f "$PASSPORT_FILE" ] && command -v jq &>/dev/null; then
                 --argjson default "$DEFAULT_CMDS" \
                 '$existing + $default | unique')
         fi
-        jq --argjson merged "$MERGED" '.limits["system.command.execute"].allowed_commands = $merged' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"
+        jq --argjson merged "$MERGED" '.limits["system.command.execute"].allowed_commands = $merged' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && { backup_file "$PASSPORT_FILE"; mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"; }
     else
         # New nested block: default to ["*"] per README (blocked_patterns still apply)
         MERGED='["*"]'
         jq --argjson merged "$MERGED" \
-            '.limits["system.command.execute"] = ((.limits["system.command.execute"] // {}) | .allowed_commands = $merged | .blocked_patterns = (.blocked_patterns // ["rm -rf", "sudo"]) | .max_execution_time = (.max_execution_time // 300))' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"
+            '.limits["system.command.execute"] = ((.limits["system.command.execute"] // {}) | .allowed_commands = $merged | .blocked_patterns = (.blocked_patterns // ["rm -rf", "sudo"]) | .max_execution_time = (.max_execution_time // 300))' "$PASSPORT_FILE" > "$PASSPORT_FILE.tmp" && { backup_file "$PASSPORT_FILE"; mv "$PASSPORT_FILE.tmp" "$PASSPORT_FILE"; }
     fi
     echo "  ✅ Passport updated: default commands are in allowed_commands."
     echo ""

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.8 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.13 (see [CHANGELOG.md](../CHANGELOG.md)).
 
 We keep **one version number** across all published packages (Node core, Python core, and every framework adapter). That avoids “core is 1.2 but CLI is 0.9” and keeps the story simple for users and support.
 

package/docs/frameworks/claude-code.md

@@ -0,0 +1,109 @@
+# APort Agent Guardrail — Claude Code
+
+Claude Code's **PreToolUse** hook runs as a separate process before each tool executes — outside Claude's reasoning context. The model cannot reason past it. This integration registers APort's guardrail with that hook so every tool use (Bash, Write, WebSearch, etc.) is checked against your passport before it runs.
+
+**Why this is different from prompts:** A developer shared a session where Claude Code said "That file is outside my writable sandbox" then immediately escaped the sandbox when told to. Advisory guardrails live inside the model's context and can be reasoned around. The PreToolUse hook runs outside that context and cannot be bypassed. See [HN thread 47256614](https://news.ycombinator.com/item?id=47256614).
+
+---
+
+## How it works
+
+- **Settings file:** Claude Code uses `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level). This is **not** `~/.cursor/hooks.json` — different location and JSON structure.
+- **PreToolUse hook:** The hook receives JSON on stdin with `tool_name` and `tool_input`, runs the APort guardrail, and must output Claude Code's exact deny format on stdout when blocking: `hookSpecificOutput.permissionDecision: "deny"`. Exit 0 = allow; exit 2 = block.
+- **Hook script:** `bin/aport-claude-code-hook.sh` — maps all Claude Code tool names (Bash, Read, Write, Edit, MultiEdit, Glob, LS, Grep, WebSearch, WebFetch, Browser, TodoRead, TodoWrite, Task, MCP tools) to APort policies and calls the core evaluator.
+
+---
+
+## Setup
+
+```bash
+npx @aporthq/aport-agent-guardrails claude-code
+# or
+npx @aporthq/aport-agent-guardrails --framework=claude-code
+```
+
+This runs the **passport wizard** and writes **`~/.claude/settings.json`** with the APort hook registered for **all tools** via `"matcher": "*"`. Default passport path: **`~/.claude/aport/passport.json`**. Restart Claude Code after setup so the PreToolUse hook is picked up.
+
+---
+
+## What's protected (tool → policy)
+
+| Claude Code tool   | APort policy              | Default   |
+|--------------------|---------------------------|----------|
+| Bash               | system.command.execute.v1 | Enforce  |
+| Read, Glob, LS, Grep, TodoRead | data.file.read.v1  | **Allow by default** (no evaluator call) |
+| Write, Edit, MultiEdit, TodoWrite | data.file.write.v1 | Enforce  |
+| WebSearch, WebFetch | web.fetch.v1             | Enforce  |
+| Browser            | web.browser.v1            | Enforce  |
+| Task               | agent.session.create.v1   | Enforce  |
+| mcp__<server>__<tool> | mcp.tool.execute.v1 | Enforce  |
+| **Unknown tool**    | —                         | **Denied (fail-closed)** |
+
+Read-family tools (Read, Glob, LS, Grep, TodoRead) exit 0 immediately without calling the evaluator to save ~40ms per file read. The HN incident was about Bash escaping a sandbox — not reads.
+
+---
+
+## What's NOT protected
+
+- **`claude --dangerously-skip-permissions`** — This flag bypasses **all** hooks including PreToolUse. When set, APort is completely inactive. This cannot be mitigated in code; it is an intentional override. Document it prominently and do not rely on APort when this flag is used.
+- **You typing in your terminal** — The hook runs only when the Claude Code agent is about to use a tool. Commands you run yourself are not intercepted.
+
+---
+
+## Testing the guardrail
+
+From the repo root (or where the hook script lives):
+
+```bash
+# Allow: Read-family (exit 0, no output)
+echo '{"tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' | bin/aport-claude-code-hook.sh
+echo "Exit: $?"
+
+# Allow: Bash with allowed command (exit 0)
+echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' | bin/aport-claude-code-hook.sh
+echo "Exit: $?"
+
+# Deny: Bash with blocked pattern (exit 2, hookSpecificOutput JSON)
+echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' | bin/aport-claude-code-hook.sh
+echo "Exit: $?"
+
+# Deny: Unknown tool (fail-closed, exit 2)
+echo '{"tool_name":"UnknownTool","tool_input":{}}' | bin/aport-claude-code-hook.sh
+echo "Exit: $?"
+```
+
+---
+
+## Audit log and config
+
+- **Audit log:** `~/.claude/aport/audit.log` (when using default config dir).
+- **Passport:** `~/.claude/aport/passport.json` (default). Path resolver probes `~/.claude` first, then `~/.cursor`, `~/.openclaw`, etc.
+- **Status:** `bin/aport-status.sh` (uses same path resolution).
+
+---
+
+## Suspend / resume
+
+Same as all frameworks: **passport is the source of truth**. Set passport `status` to `suspended` (or `active` to resume). The guardrail denies every call until the passport is active again.
+
+---
+
+## Why this is different from the Cursor doc
+
+The Cursor integration uses `~/.cursor/hooks.json` and outputs `permission: allow|deny`. Claude Code uses `~/.claude/settings.json` and expects **`hookSpecificOutput.permissionDecision`** on deny. The output formats are incompatible. Do not use the Cursor hook script for Claude Code; use this integration instead.
+
+---
+
+## Node package (optional)
+
+```bash
+npm install @aporthq/aport-agent-guardrails-claude-code
+```
+
+```ts
+import { Evaluator, getHookPath } from '@aporthq/aport-agent-guardrails-claude-code';
+
+const hookPath = getHookPath(); // default: ~/.claude/aport-claude-code-hook.sh
+```
+
+Runtime enforcement is done by the **bash hook**; the package is for programmatic use and hook path resolution.

package/docs/frameworks/cursor.md

@@ -1,6 +1,14 @@
-# APort Agent Guardrail — Cursor (and VS Code Copilot / Claude Code)
+# APort Agent Guardrail — Cursor (and VS Code Copilot)
 
-Cursor, VS Code with GitHub Copilot, and Claude Code support **config-driven hooks** that run before shell execution or tool use. The **APort hook script** reads JSON from stdin, calls the existing APort guardrail (policy + passport), and returns allow/deny; **exit 2** blocks the action. One script works across Cursor, Copilot, and Claude Code.
+> **Update (v1.0.13):** The claim that the cursor hook works for Claude Code is incorrect.
+> The cursor hook outputs `permission: allow/deny` — Claude Code expects `hookSpecificOutput.permissionDecision`.
+> A dedicated Claude Code integration is now available:
+> ```bash
+> npx @aporthq/aport-agent-guardrails claude-code
+> ```
+> See [docs/frameworks/claude-code.md](./claude-code.md).
+
+Cursor and VS Code with GitHub Copilot support **config-driven hooks** that run before shell execution or tool use. The **APort hook script** reads JSON from stdin, calls the existing APort guardrail (policy + passport), and returns allow/deny; **exit 2** blocks the action.
 
 ## Two ways to use APort
 
@@ -17,9 +25,9 @@ For Cursor, you almost always use **Guardrails (CLI)** once to install the hook;
 
 - **Hooks:** Cursor uses `~/.cursor/hooks.json` (or `.cursor/hooks.json` in the project). Hooks such as `beforeShellExecution` and `preToolUse` run a command (our script). The host sends JSON to stdin and reads JSON from stdout; **exit code 2** = block.
 - **VS Code Copilot:** Agent hooks (Preview) use `~/.claude/settings.json` or `.github/hooks/*.json` with `PreToolUse`; same idea: command, stdin JSON, stdout JSON, exit 2 = block.
-- **Claude Code:** `~/.claude/settings.json`, same PreToolUse style.
+- **Claude Code:** Uses `~/.claude/settings.json` with a **different** output format (`hookSpecificOutput.permissionDecision`). Use the **dedicated Claude Code integration** instead of this Cursor hook — see [claude-code.md](./claude-code.md).
 
-Our script accepts Cursor- and Copilot-style payloads (e.g. `command`, or `tool`/`input`), maps to the **system.command.execute** policy, calls the bash guardrail, and returns `permission: allow|deny` plus optional `agentMessage`. No VS Code extension is required for interception; hooks are the mechanism.
+Our script accepts Cursor- and Copilot-style payloads (e.g. `command`, or `tool`/`input`), maps to the **system.command.execute** policy, calls the bash guardrail, and returns `permission: allow|deny` plus optional `agentMessage`.
 
 **Hook script path:** The hook script (`aport-cursor-hook.sh`) resolves `bin/aport-guardrail-bash.sh` relative to its own directory (script dir → parent = package root). When you install via **npx**, the installer writes the path to the script inside the npx cache (e.g. `…/node_modules/@aporthq/aport-agent-guardrails/bin/aport-cursor-hook.sh`), so the guardrail script is found at `…/bin/aport-guardrail-bash.sh`. If you copy the hook script elsewhere, ensure `bin/aport-guardrail-bash.sh` exists at the same relative location or set `APORT_GUARDRAIL_SCRIPT` (or equivalent) so the hook can find the evaluator.
 
@@ -121,10 +129,11 @@ Then run `bin/aport-status.sh` and `cat ~/.cursor/aport/audit.log` to confirm th
 
 Same as all frameworks: **passport is the source of truth**. Set passport `status` to `suspended` (or `active` to resume). The guardrail denies every call until the passport is active again.
 
-## Using the same script in VS Code (Copilot) and Claude Code
+## Using the same script in VS Code (Copilot)
 
 - **VS Code + GitHub Copilot:** Add a PreToolUse hook in `~/.claude/settings.json` (or project `.claude/settings.json`, or `.github/hooks/*.json`) that runs the same script. See [Agent hooks (Preview)](https://code.visualstudio.com/docs/copilot/customization/hooks).
-- **Claude Code:** Configure `~/.claude/settings.json` to run the same APort hook script for PreToolUse.
+
+For **Claude Code**, use the [dedicated Claude Code integration](./claude-code.md) instead — it uses the correct output format (`hookSpecificOutput.permissionDecision`) and supports all Claude Code tool types.
 
 The script accepts multiple input shapes (e.g. `command`, `tool`/`input`) and returns the host-expected JSON; **exit 0** = allow, **exit 2** = block.
 
@@ -156,4 +165,4 @@ Runtime enforcement in Cursor is done by the **hook script**, not by this packag
 
 ## Status
 
-Implemented (Story E). **APort Agent Guardrail for Cursor.** Installer: `npx @aporthq/aport-agent-guardrails cursor`; hook script: `bin/aport-cursor-hook.sh`; config: `~/.cursor/hooks.json`. Same script usable for VS Code Copilot and Claude Code.
+Implemented (Story E). **APort Agent Guardrail for Cursor.** Installer: `npx @aporthq/aport-agent-guardrails cursor`; hook script: `bin/aport-cursor-hook.sh`; config: `~/.cursor/hooks.json`. Same script usable for VS Code Copilot. For Claude Code, use the dedicated integration: `npx @aporthq/aport-agent-guardrails claude-code` (see [claude-code.md](./claude-code.md)).