@aporthq/aport-agent-guardrails 1.0.11 → 1.0.13

package/bin/lib/validation.sh

@@ -2,15 +2,32 @@
 # validation.sh - Input validation functions for security
 # Used to prevent command injection, path traversal, and other injection attacks
 
-# Validate command string doesn't contain bash metacharacters
-# Returns 0 if safe, 1 if contains dangerous characters
+# Validate command string for dangerous injection patterns.
+# Returns 0 if safe, 1 if contains dangerous patterns.
+# NOTE: Pipes (|), chains (&&/||), redirects (>), and variable refs ($) are legitimate
+# shell syntax used by Claude Code, Cursor, and other AI tools. We block dangerous
+# OPERATIONS (handled by built-in security patterns and blocked_patterns in the evaluator),
+# not normal shell syntax. This function catches injection-specific patterns only.
 validate_command_string() {
     local cmd="$1"
 
-    # Check for bash metacharacters that could be used for injection
-    # Allow: alphanumeric, space, dash, underscore, dot, slash, equals, colon
-    # Block: $, `, |, &, ;, <, >, (, ), {, }, [, ], *, ?, \, newline, tab
-    if echo "$cmd" | grep -qE '[$`|&;<>(){}[\]*?\\\n\t]'; then
+    # Block backtick command substitution (injection vector; $() is caught by patterns below)
+    if echo "$cmd" | grep -qF '`'; then
+        return 1
+    fi
+
+    # Block $( ) command substitution containing dangerous commands
+    if echo "$cmd" | grep -qE '\$\([^)]*\b(rm|dd|mkfs|curl|wget|chmod|chown|sudo|kill|nc|netcat)\b'; then
+        return 1
+    fi
+
+    # Block null bytes (string termination attack)
+    if printf '%s' "$cmd" | grep -qP '\x00' 2> /dev/null; then
+        return 1
+    fi
+
+    # Block control characters (except tab/newline which are normal in shell)
+    if printf '%s' "$cmd" | grep -qP '[\x01-\x08\x0e-\x1f]' 2> /dev/null; then
         return 1
     fi
 
@@ -55,10 +72,13 @@ validate_passport_path() {
     local abs_path
     abs_path=$(readlink -f "$path" 2> /dev/null || realpath "$path" 2> /dev/null || echo "$path")
 
-    # Allowed base directories (home .openclaw, .aport, /tmp/aport-*)
+    # Allowed base directories for passport storage
     local allowed_bases=(
         "$HOME/.openclaw"
         "$HOME/.aport"
+        "$HOME/.claude"
+        "$HOME/.cursor"
+        "$HOME/.n8n"
         "/tmp/aport-"
     )
 

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/OPENCLAW_TOOLS_AND_POLICIES.md

@@ -32,6 +32,7 @@ Per the **Open Agent Passport (OAP) spec**, the passport has a **limits** object
 - **read** and **write** are **now mapped** to APort policies:
   - **read** → `data.file.read.v1` (enforces path allowlists, blocked patterns for SSH keys/credentials/.env)
   - **write** → `data.file.write.v1` (enforces path allowlists, blocks system directories, optional extension restrictions)
+- **Middleware param spreading:** The LangChain and CrewAI Node middlewares automatically parse tool input JSON and spread parameters (e.g. `file_path`) into the top-level verification context. This is required because the API's policy schema validates `file_path` as a required field. Without this, `read`/`write` tool calls would fail with 400 Bad Request.
 - Configure passport limits for file operations:
   - `limits.data.file.read.allowed_paths` - Array of allowed path prefixes (e.g. `["/tmp/*", "/home/user/projects/*"]`)
   - `limits.data.file.read.blocked_patterns` - Array of patterns to block (e.g. `["**/.ssh/**", "**/.env"]`)
@@ -41,6 +42,23 @@ Per the **Open Agent Passport (OAP) spec**, the passport has a **limits** object
 
 ---
 
+## Passport-configurable path overrides
+
+The `system.command.execute.v1` policy includes hardcoded security patterns that block access to sensitive system directories (`/etc/`, `/sys/`, `/proc/`, etc.), sensitive hidden files, credential files, and more. Passport owners can override **path-sensitivity heuristics** by setting `limits.allowed_paths` or `limits.allowed_directories` in the passport:
+
+```json
+{
+  "limits": {
+    "allowed_paths": ["/root/", "/home/agent/work/"],
+    "allowed_commands": ["*"]
+  }
+}
+```
+
+When `allowed_paths` is set and the command references one of those paths, overridable rules (like "Access to sensitive system directories" or "Access to secrets and credentials files") are skipped. **Catastrophic protections are never overridable** — fork bombs, `rm -rf /`, reverse shells, `nc`/`netcat`, and `find -exec rm` are always blocked regardless of passport config.
+
+---
+
 ## Summary table
 
 | OpenClaw tool (examples) | APort policy              | Passport limits (key)                    |

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/SECURITY_MODEL.md

@@ -30,8 +30,9 @@ APort operates as a **pre-action authorization layer** that enforces policies **
 
 **Unauthorized tool usage:**
 - Agent tries to execute commands not in allowlist
-- Commands match blocked patterns (`rm -rf`, `sudo`, `chmod 777`, etc.)
+- Commands match blocked patterns (`rm -rf`, `sudo`, `chmod 777`, `nc`/`netcat`, `find -exec rm`, etc.)
 - Shell escapes and interpreter bypasses (python -c, base64 encoding)
+- Stderr redirects (`2>/dev/null`) are allowed; dangerous redirects to files are blocked
 - Result: Only allowlisted, non-dangerous commands execute
 
 **Resource exhaustion and limit violations:**
@@ -135,7 +136,7 @@ APort's three-layer security model:
 - Use case: Testing custom policies before registering them
 
 **Example policies (out of the box):**
-- `system.command.execute.v1` - Shell commands (allowlist, 40+ blocked patterns)
+- `system.command.execute.v1` - Shell commands (allowlist, 50+ blocked patterns, passport `allowed_paths` override)
 - `data.file.read.v1` / `data.file.write.v1` - File access control
 - `web.fetch.v1` / `web.browser.v1` - Web requests and browser automation
 - `messaging.message.send.v1` - Message rate limits, recipient allowlist
@@ -292,6 +293,7 @@ APort's three-layer security model:
 APort uses secure defaults out of the box:
 
 ✅ `failClosed: true` - Block tools on errors (security over availability)
+✅ `fail_open_on_api_error: false` - API infrastructure errors (4xx/5xx, network) also fail closed by default
 ✅ `allowUnmappedTools: false` - Unmapped tools blocked (deny-by-default)
 ✅ API mode recommended for production
 ✅ Passport status checked first (suspended/revoked → deny all)
@@ -335,6 +337,25 @@ APort uses secure defaults out of the box:
 
 ---
 
+#### `fail_open_on_api_error: false` vs `fail_open_on_api_error: true`
+
+**False (default, recommended):**
+- API infrastructure errors (4xx/5xx, network failures, timeouts) → deny tool execution
+- Same behavior as `failClosed: true` for API errors
+
+**True (use with caution):**
+- API infrastructure errors → allow tool execution with `[fail-open]` warning
+- Genuine policy denials (HTTP 200 with `allow: false`) are **never** overridden—always denied
+- Useful when API availability is unreliable but you still want policy enforcement when the API is reachable
+
+**Security impact:** MEDIUM - Only API errors become allow; actual policy denials still block.
+
+**When to use true:** Production environments where API downtime shouldn't halt agent operations, combined with monitoring for `[fail-open]` decisions.
+
+**Config:** Set in `config.yaml` as `fail_open_on_api_error: true` or env var `APORT_FAIL_OPEN_ON_API_ERROR=1`.
+
+---
+
 #### `allowUnmappedTools: false` vs `allowUnmappedTools: true`
 
 **False (default, recommended):**
@@ -546,7 +567,10 @@ A: API for production (signed decisions, protected passport, global suspend). Lo
 A: In API mode, policies come from APort API over HTTPS. In local mode, policies are embedded in bash scripts (protected by filesystem permissions). Custom policies can be passed in request body for testing.
 
 **Q: What if the API is down?**
-A: Default behavior (failClosed: true) denies tool calls. For high-availability scenarios, consider running a self-hosted agent-passport instance or use local mode as fallback.
+A: Default behavior (failClosed: true) denies tool calls. You can set `fail_open_on_api_error: true` to allow on API infrastructure errors while still enforcing genuine policy denials. For high-availability scenarios, consider running a self-hosted agent-passport instance or use local mode as fallback.
+
+**Q: Can passport owners override blocked path rules (e.g. allow /root/)?**
+A: Yes. Set `limits.allowed_paths` (or `limits.allowed_directories`) in the passport to override path-sensitivity heuristics like "Access to sensitive system directories." Catastrophic protections (fork bombs, `rm -rf /`, reverse shells, `nc`/`netcat`) can **never** be overridden by passport config.
 
 **Q: Can decisions be tampered with?**
 A: Local mode: hash-protected (detects naive tampering). API mode: cryptographically signed (Ed25519, cannot forge).

package/docs/VERIFICATION_METHODS.md

@@ -93,5 +93,6 @@ So: **local is robust enough for the core policies** (exec, messaging, repo merg
 
 - **Local (bash):** Useful for privacy, offline, and the core use cases (exec allowlist/blocklist, messaging recipient, repo/PR limits). For full OAP parity and future policy packs, use **API mode**.
 - **API (default):** Recommended for production and when you want the same behavior as [APort in Goose](https://raw.githubusercontent.com/aporthq/.github/refs/heads/main/profile/APORT_GOOSE_ARCHITECTURE.md) and the full generic evaluator (JSON Schema, assurance, regions, evaluation_rules, signed decisions).
+- **`fail_open_on_api_error`:** In API mode, set this config option to `true` if you want API infrastructure errors (4xx/5xx, network failures) to return allow instead of deny. Genuine policy denials (HTTP 200 with `allow: false`) are **never** overridden. Default: `false` (fail-closed on API errors). Set via config YAML or env var `APORT_FAIL_OPEN_ON_API_ERROR=1`.
 
 The installer (`./bin/openclaw`) defaults to **API mode**; choose local only when you need to run without the network.

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/crewai.md

@@ -95,10 +95,15 @@ withAPortGuardrail(() => {
 });
 ```
 
+### How tool parameters are handled
+
+The Node middleware automatically spreads object tool inputs into the verification context. For example, `{ tool_input: { file_path: "/tmp/data.txt" } }` will pass `file_path` at the top level of the context, ensuring policies like `data.file.read.v1` receive required fields for validation.
+
 ## Config
 
 - **Config path:** `~/.aport/crewai/config.yaml`, or `.aport/config.yaml` in the project root.
 - **Mode:** `api` (default for production) or `local` (bash evaluator, no network). Same options as [LangChain](langchain.md) and OpenClaw.
+- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
 
 ## Suspend (kill switch)
 

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)).

package/docs/frameworks/langchain.md

@@ -58,10 +58,15 @@ const callback = new APortGuardrailCallback(); // optional: { configPath: '...',
 // On deny, the callback throws GuardrailViolationError.
 ```
 
+### How tool parameters are handled
+
+The Node middleware automatically parses JSON tool input and spreads parameters (e.g. `file_path`, `command`) into the verification context. This ensures policies like `data.file.read.v1` and `data.file.write.v1` receive the required `file_path` field at the top level for proper validation.
+
 ## Config
 
 - **Config:** `~/.aport/langchain/` or `.aport/config.yaml`
 - **Usage:** Add the callback to your agent (see above).
+- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
 
 ## Suspend (kill switch)