@aporthq/aport-agent-guardrails 1.0.12 → 1.0.14

package/README.md

@@ -86,12 +86,13 @@ The **kill switch suspends the agent**: once active, every tool call is denied u
 
 **Two ways to use APort:** (1) **Guardrails (CLI/setup)** — run the installer to create your passport and config; (2) **Core (library)** — use the evaluator or framework callback in your app so each tool call is verified. Each framework doc ([LangChain](docs/frameworks/langchain.md), [CrewAI](docs/frameworks/crewai.md), [Cursor](docs/frameworks/cursor.md), [OpenClaw](docs/frameworks/openclaw.md)) describes both and how to use them for that framework (Python and Node where applicable).
 
-**Production-ready today:** OpenClaw (plugin + full installer), Cursor (hooks), **Python** LangChain/CrewAI (`pip install aport-agent-guardrails-langchain` / `aport-agent-guardrails-crewai`), and **Node** (CLI + `@aporthq/aport-agent-guardrails-core`, `-langchain`, `-crewai`, `-cursor` published via CI). See [Deployment readiness](docs/DEPLOYMENT_READINESS.md).
+**Production-ready today:** OpenClaw (plugin + full installer), Cursor (hooks), **Claude Code** (PreToolUse hook), **Python** LangChain/CrewAI (`pip install aport-agent-guardrails-langchain` / `aport-agent-guardrails-crewai`), and **Node** (CLI + `@aporthq/aport-agent-guardrails-core`, `-langchain`, `-crewai`, `-cursor`, `-claude-code` published via CI). See [Deployment readiness](docs/DEPLOYMENT_READINESS.md).
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|
 | **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | `before_tool_call` plugin | `npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor** | [docs/frameworks/cursor.md](docs/frameworks/cursor.md) | `beforeShellExecution` / `preToolUse` hooks → writes `~/.cursor/hooks.json`. **Runtime enforcement is the bash hook;** the Node package `@aporthq/aport-agent-guardrails-cursor` is a helper only (Evaluator, `getHookPath()`). | `npx @aporthq/aport-agent-guardrails cursor` |
+| **Claude Code** | [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md) | PreToolUse hook → writes `~/.claude/settings.json` (Claude Code format; not Cursor). | `npx @aporthq/aport-agent-guardrails claude-code` |
 | **LangChain / LangGraph** | [docs/frameworks/langchain.md](docs/frameworks/langchain.md) | **Python:** `APortCallback` (`on_tool_start`) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |
 | **CrewAI** | [docs/frameworks/crewai.md](docs/frameworks/crewai.md) | **Python:** `@before_tool_call` hook, `register_aport_guardrail` | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
 | **n8n** | [docs/frameworks/n8n.md](docs/frameworks/n8n.md) | *Coming soon* — custom node and runtime in progress | — |

package/bin/agent-guardrails

@@ -6,7 +6,7 @@
 #   agent-guardrails openclaw ap_xxx    # openclaw with agent_id (pass-through)
 #   agent-guardrails --framework=langchain
 #   agent-guardrails -f crewai
-# Supported: openclaw | langchain | crewai | cursor (n8n coming soon)
+# Supported: openclaw | langchain | crewai | cursor | claude-code (n8n coming soon)
 #
 # Backward compatibility: All arguments after the framework are passed through to
 # the framework script. For OpenClaw, bin/openclaw receives them (e.g. agent_id).
@@ -72,14 +72,14 @@ if [[ -z "$framework" ]]; then
           noninteractive="${APORT_NONINTERACTIVE:-${CI:-}}"
           if [[ -n "$noninteractive" ]]; then
             echo "[aport] ERROR: Multiple frameworks detected: $detected_list" >&2
-            echo "  Set APORT_FRAMEWORK or use --framework=openclaw | langchain | crewai | cursor" >&2
+            echo "  Set APORT_FRAMEWORK or use --framework=openclaw | langchain | crewai | cursor | claude-code" >&2
             exit 1
           fi
           echo ""
           echo "  APort Agent Guardrails — Framework setup"
           echo "  ─────────────────────────────────────────"
           echo "  Multiple frameworks detected: $detected_list"
-          echo "  Choose one: openclaw | langchain | crewai | cursor"
+          echo "  Choose one: openclaw | langchain | crewai | cursor | claude-code"
           echo "  Example: npx @aporthq/agent-guardrails --framework=openclaw"
           echo ""
           read -p "  Framework [${framework:-openclaw}]: " choice
@@ -95,14 +95,14 @@ if [[ -z "$framework" ]]; then
   noninteractive="${APORT_NONINTERACTIVE:-${CI:-}}"
   if [[ -n "$noninteractive" ]]; then
     echo "[aport] ERROR: No framework detected in current directory." >&2
-    echo "  Set APORT_FRAMEWORK or use --framework=openclaw | langchain | crewai | cursor" >&2
+    echo "  Set APORT_FRAMEWORK or use --framework=openclaw | langchain | crewai | cursor | claude-code" >&2
     exit 1
   fi
   echo ""
   echo "  APort Agent Guardrails — Framework setup"
   echo "  ─────────────────────────────────────────"
   echo "  No framework detected in current directory."
-  echo "  Choose: openclaw | langchain | crewai | cursor"
+  echo "  Choose: openclaw | langchain | crewai | cursor | claude-code"
   echo "  Example: npx @aporthq/agent-guardrails openclaw"
   echo "           npx @aporthq/agent-guardrails --framework=langchain"
   echo ""
@@ -111,6 +111,13 @@ if [[ -z "$framework" ]]; then
 fi
 
 framework="$(echo "$framework" | tr '[:upper:]' '[:lower:]')"
+
+# SECURITY: Validate framework name (alphanumeric + hyphen only, prevents path traversal)
+if [[ ! "$framework" =~ ^[a-z0-9-]+$ ]]; then
+  echo "[aport] ERROR: Invalid framework name: $framework (alphanumeric and hyphens only)" >&2
+  exit 1
+fi
+
 script="$FRAMEWORKS_DIR/${framework}.sh"
 
 # n8n: custom node not yet available; warn before running wizard-only script
@@ -129,5 +136,5 @@ if [[ "$framework" == "openclaw" ]]; then
 fi
 
 echo "[aport] ERROR: Unknown or unsupported framework: $framework" >&2
-echo "  Supported: openclaw, langchain, crewai, cursor (n8n coming soon)" >&2
+echo "  Supported: openclaw, langchain, crewai, cursor, claude-code (n8n coming soon)" >&2
 exit 1

package/bin/aport-claude-code-hook.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# APort Claude Code hook: reads tool_name + tool_input from JSON stdin,
+# maps to APort policy, calls guardrail, outputs hookSpecificOutput deny or exit 0.
+# Exit 0 = allow, exit 2 = block. Other exits = hook error (Claude Code may fail-open).
+# Output format: Claude Code official schema (hookSpecificOutput.permissionDecision), NOT Cursor format.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
+
+# Path resolver: probes ~/.claude, ~/.cursor, ~/.openclaw, etc.
+# shellcheck source=bin/aport-resolve-paths.sh
+. "$ROOT_DIR/bin/aport-resolve-paths.sh"
+
+# Read stdin
+INPUT=""
+if [ -t 0 ]; then
+    INPUT='{}'
+else
+    INPUT="$(cat)"
+fi
+
+# No input = allow (fail-open for bad input)
+[ -z "$INPUT" ] && exit 0
+
+# Parse tool_name and tool_input (requires jq)
+if ! command -v jq &> /dev/null; then
+    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"🛡️ APort: jq is required"}}'
+    exit 2
+fi
+
+# Parse with error handling: jq failure must exit 2 (deny), never undefined exit codes
+set +e
+TOOL_NAME="$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2> /dev/null)"
+JQ_EXIT=$?
+set -e
+if [ "$JQ_EXIT" -ne 0 ] || [ -z "$TOOL_NAME" ]; then
+    TOOL_NAME="unknown"
+fi
+set +e
+TOOL_INPUT="$(echo "$INPUT" | jq -c '.tool_input // {}' 2> /dev/null)"
+JQ_EXIT=$?
+set -e
+if [ "$JQ_EXIT" -ne 0 ] || [ -z "$TOOL_INPUT" ]; then
+    TOOL_INPUT='{}'
+fi
+
+# Safe jq extraction: returns '{}' on any jq error instead of crashing under set -e
+safe_jq() {
+    local input="$1" filter="$2"
+    local result
+    result="$(echo "$input" | jq -c "$filter" 2> /dev/null)" || result='{}'
+    [ -z "$result" ] && result='{}'
+    echo "$result"
+}
+
+# Deny helper: outputs Claude Code hookSpecificOutput JSON and exits 2
+deny() {
+    local reason="$1"
+    jq -n --arg reason "$reason" \
+        --arg event "PreToolUse" \
+        '{hookSpecificOutput:{hookEventName:$event,permissionDecision:"deny",permissionDecisionReason:$reason}}'
+    exit 2
+}
+
+# Tool name passed to guardrail (must match aport-guardrail-bash.sh case patterns)
+GUARDRAIL_TOOL=""
+CONTEXT_JSON="{}"
+
+case "$TOOL_NAME" in
+    Bash)
+        GUARDRAIL_TOOL="bash"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{command: (.command // "")}')"
+        ;;
+    Read | Glob | LS | Grep | TodoRead | ToolSearch | AskUserQuestion)
+        # Read-family + user-interaction tools: allow without calling evaluator
+        exit 0
+        ;;
+    TaskGet | TaskList | TaskOutput | CronList)
+        # Read-only task/cron queries: allow without evaluator
+        exit 0
+        ;;
+    EnterPlanMode | ExitPlanMode)
+        # Internal state transitions: allow without evaluator
+        exit 0
+        ;;
+    Write | Edit | MultiEdit | NotebookEdit | TodoWrite)
+        GUARDRAIL_TOOL="write"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{file_path: (.file_path // .path // "")}')"
+        ;;
+    WebSearch | WebFetch)
+        GUARDRAIL_TOOL="webfetch"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // .query // "")}')"
+        ;;
+    Browser)
+        GUARDRAIL_TOOL="browser"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // "")}')"
+        ;;
+    Task | TaskCreate | TaskUpdate | TaskStop | Agent | Skill | EnterWorktree)
+        GUARDRAIL_TOOL="session.create"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .prompt // "")}')"
+        ;;
+    CronCreate | CronDelete)
+        GUARDRAIL_TOOL="cron"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .schedule // "")}')"
+        ;;
+    mcp__*)
+        GUARDRAIL_TOOL="mcp.tool"
+        CONTEXT_JSON="$TOOL_INPUT"
+        ;;
+    unknown | *)
+        # Unknown tool: fail-closed (deny)
+        deny "🛡️ APort: unknown tool '$TOOL_NAME' — fail-closed policy"
+        ;;
+esac
+
+# Use a per-invocation decision file to avoid race conditions with concurrent tool calls
+HOOK_DECISION_FILE="${OPENCLAW_DECISION_FILE:-}"
+if [ -n "$HOOK_DECISION_FILE" ]; then
+    HOOK_DECISION_FILE="${HOOK_DECISION_FILE%.json}-$$.json"
+    export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
+fi
+
+# Call core evaluator (guardrail expects tool name, not policy ID)
+set +e
+"$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null
+GUARDRAIL_EXIT=$?
+set -e
+
+# Clean up per-invocation decision file on exit
+cleanup_decision() { [ -n "$HOOK_DECISION_FILE" ] && rm -f "$HOOK_DECISION_FILE" 2> /dev/null; }
+
+if [ "$GUARDRAIL_EXIT" -eq 0 ]; then
+    cleanup_decision
+    exit 0
+fi
+
+# Deny: read reason from decision file
+REASON="Policy denied this action."
+if [ -n "$HOOK_DECISION_FILE" ] && [ -f "$HOOK_DECISION_FILE" ] && command -v jq &> /dev/null; then
+    R="$(jq -r '.reasons[0].message // empty' "$HOOK_DECISION_FILE" 2> /dev/null)"
+    [ -n "$R" ] && REASON="$R"
+fi
+cleanup_decision
+deny "🛡️ APort: $REASON"

package/bin/aport-create-passport.sh

@@ -109,6 +109,64 @@ DEFAULT_AGENT_NAME=${DEFAULT_AGENT_NAME:-"OpenClaw Agent"}
 DEFAULT_AGENT_DESC=$(get_identity_description) || true
 DEFAULT_AGENT_DESC=${DEFAULT_AGENT_DESC:-"Local OpenClaw AI agent with APort guardrails"}
 
+# Framework-aware defaults: each framework needs different capabilities to function
+case "${APORT_FRAMEWORK:-}" in
+    claude-code)
+        # Claude Code: file ops, web, sub-agents, MCP tools are core functionality
+        DEFAULT_FILE_READ=y
+        DEFAULT_FILE_WRITE=y
+        DEFAULT_WEB_FETCH=y
+        DEFAULT_WEB_BROWSER=y
+        DEFAULT_AGENT_SESSION=y
+        DEFAULT_MCP_TOOL=y
+        ;;
+    cursor)
+        # Cursor: IDE with shell, file ops, web search, agent mode
+        DEFAULT_FILE_READ=y
+        DEFAULT_FILE_WRITE=y
+        DEFAULT_WEB_FETCH=y
+        DEFAULT_WEB_BROWSER=n
+        DEFAULT_AGENT_SESSION=y
+        DEFAULT_MCP_TOOL=n
+        ;;
+    crewai)
+        # CrewAI: multi-agent framework — agents spawn sub-agents, use tools
+        DEFAULT_FILE_READ=y
+        DEFAULT_FILE_WRITE=y
+        DEFAULT_WEB_FETCH=y
+        DEFAULT_WEB_BROWSER=n
+        DEFAULT_AGENT_SESSION=y
+        DEFAULT_MCP_TOOL=y
+        ;;
+    langchain)
+        # LangChain/LangGraph: tool calling, web, files
+        DEFAULT_FILE_READ=y
+        DEFAULT_FILE_WRITE=y
+        DEFAULT_WEB_FETCH=y
+        DEFAULT_WEB_BROWSER=n
+        DEFAULT_AGENT_SESSION=n
+        DEFAULT_MCP_TOOL=n
+        ;;
+    n8n)
+        # n8n: workflow automation — HTTP, file, database, messaging
+        DEFAULT_FILE_READ=y
+        DEFAULT_FILE_WRITE=y
+        DEFAULT_WEB_FETCH=y
+        DEFAULT_WEB_BROWSER=n
+        DEFAULT_AGENT_SESSION=n
+        DEFAULT_MCP_TOOL=n
+        ;;
+    *)
+        # Generic / unknown framework: conservative defaults
+        DEFAULT_FILE_READ=n
+        DEFAULT_FILE_WRITE=n
+        DEFAULT_WEB_FETCH=n
+        DEFAULT_WEB_BROWSER=n
+        DEFAULT_AGENT_SESSION=n
+        DEFAULT_MCP_TOOL=n
+        ;;
+esac
+
 if [ -n "$NON_INTERACTIVE" ]; then
     # CI/tests: use defaults, no prompts. Use --output or APORT_FRAMEWORK for default path. Match interactive defaults (README: messaging out of the box).
     owner_id="$DEFAULT_EMAIL"
@@ -119,10 +177,12 @@ if [ -n "$NON_INTERACTIVE" ]; then
     exec_cap=y
     msg_cap=y
     data_cap=n
-    file_read_cap=n
-    file_write_cap=n
-    web_fetch_cap=n
-    web_browser_cap=n
+    file_read_cap=$DEFAULT_FILE_READ
+    file_write_cap=$DEFAULT_FILE_WRITE
+    web_fetch_cap=$DEFAULT_WEB_FETCH
+    web_browser_cap=$DEFAULT_WEB_BROWSER
+    agent_session_cap=$DEFAULT_AGENT_SESSION
+    mcp_tool_cap=$DEFAULT_MCP_TOOL
     max_pr_size=500
     max_prs_per_day=10
     max_msgs_per_day=100
@@ -195,7 +255,11 @@ else
     # Choose capabilities
     echo "  🔐 Capabilities"
     echo "  ───────────────"
-    echo "  Choose what your agent can do (y/n). Defaults: PRs, exec, and messaging = yes (matches README/docs); others = no."
+    if [ "${APORT_FRAMEWORK:-}" = "claude-code" ]; then
+        echo "  Choose what your agent can do (y/n). Claude Code defaults: most capabilities = yes."
+    else
+        echo "  Choose what your agent can do (y/n). Defaults: PRs, exec, and messaging = yes (matches README/docs); others = no."
+    fi
     echo ""
     read -p "  • Create and merge pull requests? [Y/n]: " pr_cap
     pr_cap=${pr_cap:-y}
@@ -206,21 +270,51 @@ else
     read -p "  • Send messages (email, SMS, etc.)? [Y/n]: " msg_cap
     msg_cap=${msg_cap:-y}
 
-    read -p "  • Read files from disk? [y/N]: " file_read_cap
-    file_read_cap=${file_read_cap:-n}
+    if [ "$DEFAULT_FILE_READ" = "y" ]; then
+        read -p "  • Read files from disk? [Y/n]: " file_read_cap
+    else
+        read -p "  • Read files from disk? [y/N]: " file_read_cap
+    fi
+    file_read_cap=${file_read_cap:-$DEFAULT_FILE_READ}
 
-    read -p "  • Write/edit files on disk? [y/N]: " file_write_cap
-    file_write_cap=${file_write_cap:-n}
+    if [ "$DEFAULT_FILE_WRITE" = "y" ]; then
+        read -p "  • Write/edit files on disk? [Y/n]: " file_write_cap
+    else
+        read -p "  • Write/edit files on disk? [y/N]: " file_write_cap
+    fi
+    file_write_cap=${file_write_cap:-$DEFAULT_FILE_WRITE}
 
-    read -p "  • Fetch data from web (HTTP requests)? [y/N]: " web_fetch_cap
-    web_fetch_cap=${web_fetch_cap:-n}
+    if [ "$DEFAULT_WEB_FETCH" = "y" ]; then
+        read -p "  • Fetch data from web (HTTP requests)? [Y/n]: " web_fetch_cap
+    else
+        read -p "  • Fetch data from web (HTTP requests)? [y/N]: " web_fetch_cap
+    fi
+    web_fetch_cap=${web_fetch_cap:-$DEFAULT_WEB_FETCH}
 
-    read -p "  • Automate web browser? [y/N]: " web_browser_cap
-    web_browser_cap=${web_browser_cap:-n}
+    if [ "$DEFAULT_WEB_BROWSER" = "y" ]; then
+        read -p "  • Automate web browser? [Y/n]: " web_browser_cap
+    else
+        read -p "  • Automate web browser? [y/N]: " web_browser_cap
+    fi
+    web_browser_cap=${web_browser_cap:-$DEFAULT_WEB_BROWSER}
 
     read -p "  • Export data (database, files, etc.)? [y/N]: " data_cap
     data_cap=${data_cap:-n}
 
+    if [ "$DEFAULT_AGENT_SESSION" = "y" ]; then
+        read -p "  • Spawn sub-agents and tasks? [Y/n]: " agent_session_cap
+    else
+        read -p "  • Spawn sub-agents and tasks? [y/N]: " agent_session_cap
+    fi
+    agent_session_cap=${agent_session_cap:-$DEFAULT_AGENT_SESSION}
+
+    if [ "$DEFAULT_MCP_TOOL" = "y" ]; then
+        read -p "  • Use MCP tools (external integrations)? [Y/n]: " mcp_tool_cap
+    else
+        read -p "  • Use MCP tools (external integrations)? [y/N]: " mcp_tool_cap
+    fi
+    mcp_tool_cap=${mcp_tool_cap:-$DEFAULT_MCP_TOOL}
+
     echo ""
 
     # Configure limits
@@ -351,6 +445,12 @@ fi
 if [ "$data_cap" = "y" ] || [ "$data_cap" = "Y" ]; then
     capabilities_json="$capabilities_json{\"id\": \"data.export\"},"
 fi
+if [ "${agent_session_cap:-n}" = "y" ] || [ "${agent_session_cap:-n}" = "Y" ]; then
+    capabilities_json="$capabilities_json{\"id\": \"agent.session.create\"},"
+fi
+if [ "${mcp_tool_cap:-n}" = "y" ] || [ "${mcp_tool_cap:-n}" = "Y" ]; then
+    capabilities_json="$capabilities_json{\"id\": \"mcp.tool.execute\"},"
+fi
 # Remove trailing comma
 capabilities_json="${capabilities_json%,}]"
 
@@ -438,6 +538,14 @@ if [ "$data_cap" = "y" ] || [ "$data_cap" = "Y" ]; then
     limits_json="$limits_json\"data.export\": {\"max_rows\": $max_export_rows, \"allow_pii\": $allow_pii_bool, \"allowed_collections\": [\"*\"]},"
 fi
 
+if [ "${agent_session_cap:-n}" = "y" ] || [ "${agent_session_cap:-n}" = "Y" ]; then
+    limits_json="$limits_json\"agent.session.create\": {\"max_concurrent\": 10},"
+fi
+
+if [ "${mcp_tool_cap:-n}" = "y" ] || [ "${mcp_tool_cap:-n}" = "Y" ]; then
+    limits_json="$limits_json\"mcp.tool.execute\": {\"allowed_servers\": [\"*\"]},"
+fi
+
 # Remove trailing comma
 limits_json="${limits_json%,}}"
 
@@ -503,6 +611,11 @@ else
 EOF
 fi
 
+# Archive existing passport before overwrite
+if [ -f "$PASSPORT_FILE" ]; then
+    cp "$PASSPORT_FILE" "${PASSPORT_FILE}.bak"
+fi
+
 # Format JSON with jq if available
 if command -v jq &> /dev/null; then
     jq . "$PASSPORT_FILE.tmp" > "$PASSPORT_FILE"
@@ -535,7 +648,13 @@ echo "  🔐 Capabilities:"
 [ "$pr_cap" = "y" ] || [ "$pr_cap" = "Y" ] && echo "    • Create and merge pull requests"
 [ "$exec_cap" = "y" ] || [ "$exec_cap" = "Y" ] && echo "    • Execute system commands"
 [ "$msg_cap" = "y" ] || [ "$msg_cap" = "Y" ] && echo "    • Send messages"
+[ "$file_read_cap" = "y" ] || [ "$file_read_cap" = "Y" ] && echo "    • Read files"
+[ "$file_write_cap" = "y" ] || [ "$file_write_cap" = "Y" ] && echo "    • Write/edit files"
+[ "$web_fetch_cap" = "y" ] || [ "$web_fetch_cap" = "Y" ] && echo "    • Fetch from web"
+[ "$web_browser_cap" = "y" ] || [ "$web_browser_cap" = "Y" ] && echo "    • Automate browser"
 [ "$data_cap" = "y" ] || [ "$data_cap" = "Y" ] && echo "    • Export data"
+[ "${agent_session_cap:-n}" = "y" ] || [ "${agent_session_cap:-n}" = "Y" ] && echo "    • Spawn sub-agents and tasks"
+[ "${mcp_tool_cap:-n}" = "y" ] || [ "${mcp_tool_cap:-n}" = "Y" ] && echo "    • Use MCP tools"
 echo ""
 echo "  📝 Next steps:"
 echo "    • Review limits:  vim $PASSPORT_FILE"

package/bin/aport-cursor-hook.sh

@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
-# APort Cursor/Copilot/Claude Code hook: read JSON from stdin, call guardrail, return allow/deny; exit 2 = block.
-# Compatible with Cursor (beforeShellExecution, preToolUse), VS Code Copilot, and Claude Code.
-# Input: JSON with "command" and/or "tool"/"name"/"input" (host-dependent). We map to system.command.execute.
-# Output: JSON with "permission": "allow"|"deny" (Cursor) and "allowed": true|false; optional "agentMessage"/"reason".
-# Exit: 0 = allow, 2 = block (deny). Other exits = hook error (host may proceed or fail-open).
+# APort Cursor hook: reads JSON from stdin, maps tool to APort policy, calls guardrail.
+# Handles all Cursor hook events: beforeShellExecution, preToolUse, beforeMCPExecution,
+# beforeReadFile, subagentStart.
+# Output: JSON with "permission": "allow"|"deny"; optional "agentMessage"/"user_message".
+# Exit: 0 = allow, 2 = block (deny). Other exits = hook error (Cursor may fail-open).
+#
+# Cursor preToolUse tool_name values: Shell, Read, Write, Grep, Delete, Task, MCP:<name>
+# See: https://cursor.com/docs/hooks
 
 set -e
 
@@ -11,14 +14,13 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
 
-# Passport/config: resolver probes ~/.cursor, ~/.openclaw, ~/.aport/langchain, etc. when OPENCLAW_CONFIG_DIR not set
+# Passport/config: resolver probes ~/.cursor, ~/.openclaw, ~/.aport/*, etc.
 # shellcheck source=bin/aport-resolve-paths.sh
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
 
 # Read stdin (single JSON object; Cursor sends one payload per invocation)
 INPUT=""
 if [ -t 0 ]; then
-    # No stdin (e.g. manual test): treat as allow to avoid blocking
     INPUT='{}'
 else
     INPUT="$(cat)"
@@ -30,61 +32,145 @@ if [ -z "$INPUT" ]; then
     exit 0
 fi
 
-# Parse and normalize to tool + context for guardrail
-# Cursor beforeShellExecution: { "command": "..." }
-# preToolUse / Copilot: { "tool": "runTerminalCommand", "input": { "command": "..." } } or similar
-TOOL_NAME="exec.run"
+# Require jq for JSON parsing
+if ! command -v jq &> /dev/null; then
+    echo '{"permission":"deny","allowed":false,"agentMessage":"APort: jq is required"}'
+    exit 2
+fi
+
+# Deny helper: outputs Cursor-format JSON and exits 2
+deny() {
+    local reason="$1"
+    jq -n -c --arg reason "$reason" \
+        '{permission:"deny",allowed:false,agentMessage:$reason,reason:$reason}'
+    exit 2
+}
+
+# Safe jq extraction: returns '{}' on any jq error
+safe_jq() {
+    local input="$1" filter="$2"
+    local result
+    result="$(echo "$input" | jq -c "$filter" 2> /dev/null)" || result='{}'
+    [ -z "$result" ] && result='{}'
+    echo "$result"
+}
+
+# Detect hook event type from input fields and route accordingly.
+# Cursor sends different JSON shapes per hook event:
+#   beforeShellExecution: { "command": "...", "cwd": "..." }
+#   preToolUse:           { "tool_name": "Shell|Read|Write|...", "tool_input": {...} }
+#   beforeMCPExecution:   { "tool_name": "...", "tool_input": {...}, "server": "..." }
+#   beforeReadFile:       { "file_path": "...", "content": "..." }
+#   subagentStart:        { "subagent_id": "...", "subagent_type": "...", "task": "..." }
+# We detect by checking for distinguishing fields.
+
+GUARDRAIL_TOOL=""
 CONTEXT_JSON="{}"
-if command -v jq &> /dev/null; then
-    CMD=$(echo "$INPUT" | jq -r '.command // .input.command // .input.cmd // .args[0] // ""')
-    if [ -n "$CMD" ] && [ "$CMD" != "null" ]; then
-        CONTEXT_JSON=$(echo "$INPUT" | jq -c '{command: (.command // .input.command // .input.cmd), args: (.args // .input.args // [])}' 2> /dev/null || echo "{}")
-        if [ -z "$CONTEXT_JSON" ] || [ "$CONTEXT_JSON" = "null" ]; then
-            CONTEXT_JSON=$(jq -n -c --arg cmd "$CMD" '{command: $cmd}')
-        fi
-    fi
-    # If no command found, still pass through; guardrail may deny unknown
-    if [ -z "$CONTEXT_JSON" ] || [ "$CONTEXT_JSON" = "null" ]; then
-        CONTEXT_JSON="$INPUT"
-    fi
+
+# Check for hook_event_name first (newer Cursor versions include it)
+HOOK_EVENT="$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2> /dev/null)"
+TOOL_NAME="$(echo "$INPUT" | jq -r '.tool_name // ""' 2> /dev/null)"
+
+if [ "$HOOK_EVENT" = "beforeReadFile" ] || { [ -z "$HOOK_EVENT" ] && [ -z "$TOOL_NAME" ] && echo "$INPUT" | jq -e '.file_path and .content' &> /dev/null; }; then
+    # beforeReadFile: file reads — allow without evaluator (same as Claude Code)
+    exit 0
+
+elif [ "$HOOK_EVENT" = "subagentStart" ] || { [ -z "$HOOK_EVENT" ] && echo "$INPUT" | jq -e '.subagent_id' &> /dev/null; }; then
+    # subagentStart: sub-agent spawning
+    GUARDRAIL_TOOL="session.create"
+    CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.task // ""), subagent_type: (.subagent_type // "")}')"
+
+elif [ "$HOOK_EVENT" = "beforeMCPExecution" ] || { [ -n "$TOOL_NAME" ] && echo "$INPUT" | jq -e '.server // .url' &> /dev/null; }; then
+    # beforeMCPExecution: MCP tool calls (has server/url field)
+    GUARDRAIL_TOOL="mcp.tool"
+    CONTEXT_JSON="$(safe_jq "$INPUT" '{tool_name: (.tool_name // ""), tool_input: (.tool_input // {})}')"
+
+elif [ -n "$TOOL_NAME" ]; then
+    # preToolUse: Cursor tool names — Shell, Read, Write, Grep, Delete, Task, MCP:<name>
+    case "$TOOL_NAME" in
+        Shell)
+            GUARDRAIL_TOOL="bash"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{command: (.tool_input.command // "")}')"
+            ;;
+        Read | Grep)
+            # Read-family: allow without calling evaluator
+            exit 0
+            ;;
+        Write)
+            GUARDRAIL_TOOL="write"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{file_path: (.tool_input.file_path // .tool_input.path // "")}')"
+            ;;
+        Delete)
+            GUARDRAIL_TOOL="write"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{file_path: (.tool_input.file_path // .tool_input.path // "")}')"
+            ;;
+        Task)
+            GUARDRAIL_TOOL="session.create"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.tool_input.description // .tool_input.prompt // "")}')"
+            ;;
+        MCP:*)
+            GUARDRAIL_TOOL="mcp.tool"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{tool_name: (.tool_name // ""), tool_input: (.tool_input // {})}')"
+            ;;
+        *)
+            # Unknown preToolUse tool: fail-closed
+            deny "🛡️ APort: unknown tool '$TOOL_NAME' — fail-closed policy"
+            ;;
+    esac
+
+elif echo "$INPUT" | jq -e '.command' &> /dev/null; then
+    # beforeShellExecution: { "command": "..." }
+    GUARDRAIL_TOOL="bash"
+    CMD="$(echo "$INPUT" | jq -r '.command // ""' 2> /dev/null)"
+    CONTEXT_JSON="$(jq -n -c --arg cmd "$CMD" '{command: $cmd}')"
+
+elif echo "$INPUT" | jq -e '.tool // .input.command' &> /dev/null; then
+    # Legacy Copilot-style: { "tool": "runTerminalCommand", "input": { "command": "..." } }
+    GUARDRAIL_TOOL="bash"
+    CMD="$(echo "$INPUT" | jq -r '.input.command // .input.cmd // .args[0] // ""' 2> /dev/null)"
+    CONTEXT_JSON="$(jq -n -c --arg cmd "$CMD" '{command: $cmd}')"
+
 else
-    CONTEXT_JSON="$INPUT"
+    # Unrecognized input shape: fail-closed
+    deny "🛡️ APort: unrecognized hook input — fail-closed policy"
+fi
+
+# Use a per-invocation decision file to avoid race conditions with concurrent tool calls
+HOOK_DECISION_FILE="${OPENCLAW_DECISION_FILE:-}"
+if [ -n "$HOOK_DECISION_FILE" ]; then
+    HOOK_DECISION_FILE="${HOOK_DECISION_FILE%.json}-$$.json"
+    export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
 fi
 
-# Call existing bash guardrail: exit 0 = allow, exit 1 = deny (forward config for subprocess)
+# Call core evaluator
 set +e
-OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" OPENCLAW_PASSPORT_FILE="${OPENCLAW_PASSPORT_FILE:-}" OPENCLAW_DECISION_FILE="${OPENCLAW_DECISION_FILE:-}" "$GUARDRAIL" "$TOOL_NAME" "$CONTEXT_JSON" 2> /dev/null
+"$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null
 GUARDRAIL_EXIT=$?
 set -e
 
+# Clean up per-invocation decision file
+cleanup_decision() { [ -n "$HOOK_DECISION_FILE" ] && rm -f "$HOOK_DECISION_FILE" 2> /dev/null; }
+
 if [ "$GUARDRAIL_EXIT" -eq 0 ]; then
+    cleanup_decision
     echo '{"permission":"allow","allowed":true}'
     exit 0
 fi
 
-# Deny: output reason from decision file if available (guardrail writes decision before exit 1)
+# Deny: read reason from decision file
 REASON="Policy denied this action."
-if [ -n "${OPENCLAW_DECISION_FILE:-}" ] && [ -f "$OPENCLAW_DECISION_FILE" ] && command -v jq &> /dev/null; then
-    R=$(jq -r '.reasons[0].message // empty' "$OPENCLAW_DECISION_FILE" 2> /dev/null)
-    if [ -n "$R" ]; then
-        REASON="$R"
-    fi
+if [ -n "$HOOK_DECISION_FILE" ] && [ -f "$HOOK_DECISION_FILE" ]; then
+    R="$(jq -r '.reasons[0].message // empty' "$HOOK_DECISION_FILE" 2> /dev/null)"
+    [ -n "$R" ] && REASON="$R"
 fi
-# If no decision file was set, try common config dirs so we can show actual deny reason
-if [ "$REASON" = "Policy denied this action." ] && command -v jq &> /dev/null; then
+# Fallback: try common config dirs
+if [ "$REASON" = "Policy denied this action." ]; then
     for DEC in "${OPENCLAW_CONFIG_DIR:-$HOME/.cursor}/aport/decision.json" "$HOME/.cursor/aport/decision.json" "$HOME/.openclaw/aport/decision.json"; do
         if [ -f "$DEC" ]; then
-            R=$(jq -r '.reasons[0].message // empty' "$DEC" 2> /dev/null)
-            if [ -n "$R" ]; then
-                REASON="$R"
-                break
-            fi
+            R="$(jq -r '.reasons[0].message // empty' "$DEC" 2> /dev/null)"
+            [ -n "$R" ] && REASON="$R" && break
         fi
     done
 fi
-# Fallback: help user debug guardrail/script errors
-if [ "$REASON" = "Policy denied this action." ]; then
-    REASON="Policy denied or guardrail error. Check passport and guardrail script (see docs/frameworks/cursor.md)."
-fi
-echo "{\"permission\":\"deny\",\"allowed\":false,\"agentMessage\":$(echo "$REASON" | jq -Rs .),\"reason\":$(echo "$REASON" | jq -Rs .)}"
-exit 2
+cleanup_decision
+deny "🛡️ APort: $REASON"