@aporthq/aport-agent-guardrails 1.0.11 → 1.0.13

package/README.md

@@ -60,7 +60,7 @@ Your agent should **only do what you explicitly allow**. APort runs in the hook
 
 | Policy | What it guards |
 |--------|----------------|
-| **system.command.execute.v1** | Shell commands — allowlist, 40+ blocked patterns (`rm -rf`, `sudo`, injection) |
+| **system.command.execute.v1** | Shell commands — allowlist, 50+ blocked patterns (`rm -rf`, `sudo`, `nc`, `find -exec rm`, injection); passport `allowed_paths` override for path rules |
 | **mcp.tool.execute.v1** | MCP tool calls — server allowlist, rate limits |
 | **messaging.message.send.v1** | Message sends — rate caps, capability checks |
 | **agent.session.create.v1** / **agent.tool.register.v1** | Sessions and tool registration |
@@ -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 | — |
@@ -335,7 +336,7 @@ graph TB
 **✅ Pre-action authorization (agent misbehavior):**
 - **Prompt injection** - Hook-based enforcement; agent cannot bypass via prompts
 - **Malicious skills** - Third-party OpenClaw skills validated before execution
-- **Unauthorized commands** - Allowlist + 40+ blocked patterns (rm -rf, sudo, etc.)
+- **Unauthorized commands** - Allowlist + 50+ blocked patterns (rm -rf, sudo, nc, find -exec rm, etc.)
 - **Data exfiltration** - File access, messaging, web requests controlled by policy
 - **Resource limits** - Rate limits, size caps, transaction amounts enforced
 

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

@@ -503,6 +503,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"

package/bin/aport-guardrail-bash.sh

@@ -44,8 +44,9 @@ if [ -n "$DEBUG_APORT" ]; then
     echo "DEBUG: CONTEXT length=${#CONTEXT_JSON}" >&2
 fi
 
-# Ensure APort data dir exists (for decision.json, audit.log)
+# Ensure APort data dir exists (for decision.json, audit.log) with restricted permissions
 mkdir -p "$(dirname "$AUDIT_LOG")"
+chmod 700 "$(dirname "$AUDIT_LOG")" 2> /dev/null || true
 
 # Function to load policy from upstream or local-overrides
 load_policy() {
@@ -160,9 +161,11 @@ write_decision() {
     local final_json
     final_json=$(echo "$base_json" | jq -c --arg h "$content_hash" '. + {content_hash: $h}')
     echo "$final_json" > "$DECISION_FILE"
+    chmod 600 "$DECISION_FILE" 2> /dev/null || true
 
     # Update chain state for next decision (best-effort; do not block or fail the script)
     echo "{\"last_decision_id\":\"$decision_id\",\"last_content_hash\":\"$content_hash\"}" > "$chain_state" 2> /dev/null || true
+    chmod 600 "$chain_state" 2> /dev/null || true
 
     audit_context=""
     if [ -n "${CONTEXT_SUMMARY:-}" ]; then
@@ -514,8 +517,9 @@ if [[ "$POLICY_ID" == "data.file.write.v1" ]]; then
             fi
         done < <(echo "$LIMITS" | jq -r '.blocked_paths[]? // empty')
 
-        # Check allowed extensions (if configured)
-        if [ -n "$(echo "$LIMITS" | jq -r '.allowed_extensions | length' 2> /dev/null)" ]; then
+        # Check allowed extensions (only when the list has entries)
+        _ext_count="$(echo "$LIMITS" | jq -r 'if .allowed_extensions then (.allowed_extensions | length) else 0 end' 2> /dev/null || echo "0")"
+        if [ "$_ext_count" -gt 0 ] 2> /dev/null; then
             FILE_EXT=$(echo "$FILE_PATH" | grep -o '\.[^.]*$' | tr '[:upper:]' '[:lower:]')
             if [ -n "$FILE_EXT" ]; then
                 EXT_ALLOWED=false

package/bin/aport-resolve-paths.sh

@@ -14,8 +14,24 @@ resolve_aport_paths() {
     local passport_path
     local data_dir
 
+    # Source validation if available (for validate_passport_path)
+    local _resolve_script_dir
+    _resolve_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    if [ -f "$_resolve_script_dir/lib/validation.sh" ]; then
+        # shellcheck source=lib/validation.sh
+        . "$_resolve_script_dir/lib/validation.sh" 2> /dev/null || true
+    elif [ -f "$_resolve_script_dir/../bin/lib/validation.sh" ]; then
+        . "$_resolve_script_dir/../bin/lib/validation.sh" 2> /dev/null || true
+    fi
+
     # 1) Explicit path set and file exists → use it (plugin or wrapper)
     if [ -n "${OPENCLAW_PASSPORT_FILE:-}" ] && [ -f "$OPENCLAW_PASSPORT_FILE" ]; then
+        # Validate env-provided path if validator is available
+        if type validate_passport_path &> /dev/null; then
+            if ! validate_passport_path "$OPENCLAW_PASSPORT_FILE"; then
+                echo "[aport] WARN: OPENCLAW_PASSPORT_FILE path failed validation: $OPENCLAW_PASSPORT_FILE" >&2
+            fi
+        fi
         data_dir="$(dirname "$OPENCLAW_PASSPORT_FILE")"
         passport_path="$OPENCLAW_PASSPORT_FILE"
     # 2) Explicit path set but file missing → legacy: try parent dir (e.g. .../openclaw/passport.json)
@@ -31,7 +47,7 @@ resolve_aport_paths() {
     # 3) No env → probe framework-specific default paths (where each framework stores data), then OpenClaw legacy
     else
         config_dir=""
-        for candidate in "$HOME/.cursor" "$HOME/.openclaw" "$HOME/.aport/langchain" "$HOME/.aport/crewai" "$HOME/.n8n"; do
+        for candidate in "$HOME/.claude" "$HOME/.cursor" "$HOME/.openclaw" "$HOME/.aport/langchain" "$HOME/.aport/crewai" "$HOME/.n8n"; do
             if [ -f "${candidate}/aport/passport.json" ]; then
                 config_dir="$candidate"
                 break

package/bin/aport-status.sh

@@ -218,11 +218,17 @@ if [ -f "$AUDIT_LOG" ] && [ -s "$AUDIT_LOG" ]; then
         # Parse log line: [timestamp] tool=X decision_id=Y allow=Z ... context="..." (optional)
         timestamp=$(echo "$line" | sed -n 's/.*\[\([^]]*\)\].*/\1/p')
         tool=$(echo "$line" | sed -n 's/.*tool=\([^ ]*\).*/\1/p')
+        decision_id=$(echo "$line" | sed -n 's/.*decision_id=\([^ ]*\).*/\1/p')
         allow=$(echo "$line" | sed -n 's/.*allow=\([^ ]*\).*/\1/p')
         context=$(echo "$line" | sed -n 's/.*context="\([^"]*\)".*/\1/p')
         timestamp=${timestamp:-unknown}
         tool=${tool:-unknown}
         allow=${allow:-unknown}
+        # Synthetic decision_id for old log formats that lack one
+        if [ -z "$decision_id" ]; then
+            ctx_slug=$(printf '%.16s' "${context:-}" | tr ' ' '_')
+            decision_id="${timestamp}-${tool}-${ctx_slug}"
+        fi
 
         short_time=$(echo "$timestamp" | cut -d' ' -f1-2 | cut -d'.' -f1)
         # Show capability + context when present (e.g. "exec.run | cat test.md"); truncate long context

package/bin/frameworks/claude-code.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Claude Code framework installer/setup.
+# Runs passport wizard and writes ~/.claude/settings.json with PreToolUse hook
+# pointing at aport-claude-code-hook.sh. Format is Claude Code official schema
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+# shellcheck source=../lib/common.sh
+source "$LIB/common.sh"
+# shellcheck source=../lib/passport.sh
+source "$LIB/passport.sh"
+# shellcheck source=../lib/config.sh
+source "$LIB/config.sh"
+
+run_setup() {
+    log_info "Setting up APort guardrails for Claude Code..."
+    config_dir="$(get_config_dir claude-code)"
+    config_dir="${config_dir/#\~/$HOME}"
+    mkdir -p "$config_dir/aport"
+    chmod 700 "$config_dir/aport"
+
+    export APORT_FRAMEWORK=claude-code
+    run_passport_wizard "$@"
+
+    # Harden permissions on passport (contains policy/capabilities)
+    [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
+
+    # Resolve absolute path to hook script (works from repo or npx package)
+    HOOK_SCRIPT="${APORT_CLAUDE_CODE_HOOK_SCRIPT:-}"
+    if [ -z "$HOOK_SCRIPT" ]; then
+        ROOT_FOR_HOOK="$(cd "$LIB/../.." && pwd)"
+        HOOK_SCRIPT="$ROOT_FOR_HOOK/bin/aport-claude-code-hook.sh"
+    fi
+    if [ ! -f "$HOOK_SCRIPT" ]; then
+        log_warn "Hook script not found at $HOOK_SCRIPT; settings.json will reference it (create the file for hooks to work)."
+    else
+        HOOK_SCRIPT="$(cd "$(dirname "$HOOK_SCRIPT")" && pwd)/$(basename "$HOOK_SCRIPT")"
+    fi
+
+    CLAUDE_DIR="${APORT_CLAUDE_CODE_CONFIG_DIR:-$HOME/.claude}"
+    CLAUDE_DIR="${CLAUDE_DIR/#\~/$HOME}"
+    SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+    mkdir -p "$CLAUDE_DIR"
+
+    _write_claude_settings "$SETTINGS_FILE" "$HOOK_SCRIPT"
+    chmod 600 "$SETTINGS_FILE"
+
+    echo ""
+    echo "  Next steps (Claude Code):"
+    echo "  ─────────────────────────"
+    echo "  1. Settings written to: $SETTINGS_FILE"
+    echo "  2. Hook script: $HOOK_SCRIPT"
+    echo "  3. Restart Claude Code so the PreToolUse hook is picked up."
+    echo "  4. Tool use will be checked by APort policy (exit 2 = block)."
+    echo ""
+    echo "  Audit log: $config_dir/aport/audit.log"
+    echo ""
+    echo "  Note: claude --dangerously-skip-permissions bypasses ALL hooks including APort."
+    echo "  See: docs/frameworks/claude-code.md"
+    echo ""
+}
+
+# Write ~/.claude/settings.json in Claude Code official format (PreToolUse, matcher "*").
+# Merges with existing settings.json without clobbering other settings.
+_write_claude_settings() {
+    local file="$1"
+    local cmd="$2"
+
+    if [ -f "$file" ] && command -v jq &> /dev/null; then
+        if jq -e '.hooks' "$file" &> /dev/null; then
+            # Merge: add APort to PreToolUse array, dedup by command
+            local tmpfile
+            tmpfile="$(mktemp "${file}.XXXXXX")"
+            jq -c --arg cmd "$cmd" '
+                (.hooks.PreToolUse // []) as $p |
+                .hooks.PreToolUse = ($p | map(select(
+                    (.hooks[0].command != $cmd)
+                )) | . + [{"matcher":"*","hooks":[{"type":"command","command":$cmd}]}])
+            ' "$file" > "$tmpfile" && mv "$tmpfile" "$file"
+            return
+        fi
+    fi
+
+    # Write fresh settings (Claude Code format: hooks.PreToolUse, matcher "*")
+    if command -v jq &> /dev/null; then
+        jq -n --arg cmd "$cmd" '{
+            hooks: {
+                PreToolUse: [{"matcher":"*","hooks":[{"type":"command","command":$cmd}]}]
+            }
+        }' > "$file"
+    else
+        # Escape special JSON characters in cmd path (quotes, backslashes)
+        local escaped_cmd
+        escaped_cmd="$(printf '%s' "$cmd" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+        cat > "$file" << EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${escaped_cmd}"
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+    fi
+}
+
+run_setup "$@"

package/bin/frameworks/crewai.sh

@@ -14,8 +14,11 @@ run_setup() {
     log_info "Setting up APort guardrails for CrewAI..."
     config_dir="$(write_config_template crewai)"
     mkdir -p "$config_dir/aport"
+    chmod 700 "$config_dir/aport"
     export APORT_FRAMEWORK=crewai
     run_passport_wizard "$@"
+    # Harden permissions on passport (contains policy/capabilities)
+    [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
     echo ""
     echo "  Next steps (CrewAI):"
     echo "  ───────────────────"

package/bin/frameworks/cursor.sh

@@ -16,10 +16,14 @@ run_setup() {
     # Passport and data live under Cursor's config dir (~/.cursor/aport/ by default).
     config_dir="$(get_config_dir cursor)"
     mkdir -p "$config_dir/aport"
+    chmod 700 "$config_dir/aport"
 
     export APORT_FRAMEWORK=cursor
     run_passport_wizard "$@"
 
+    # Harden permissions on passport (contains policy/capabilities)
+    [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
+
     # Resolve absolute path to hook script (works from repo or npx package)
     HOOK_SCRIPT="${APORT_CURSOR_HOOK_SCRIPT:-}"
     if [ -z "$HOOK_SCRIPT" ]; then
@@ -48,6 +52,7 @@ run_setup() {
         .hooks.beforeShellExecution = ($b | map(select(.command != $cmd)) | . + [{ "command": $cmd }]) |
         .hooks.preToolUse = ($p | map(select(.command != $cmd)) | . + [{ "command": $cmd }])
       ')
+            [ -f "$CURSOR_HOOKS_FILE" ] && cp "$CURSOR_HOOKS_FILE" "${CURSOR_HOOKS_FILE}.bak"
             echo "$NEW_HOOKS" > "$CURSOR_HOOKS_FILE"
         else
             _write_cursor_hooks_file "$CURSOR_HOOKS_FILE" "$HOOK_SCRIPT"
@@ -55,6 +60,7 @@ run_setup() {
     else
         _write_cursor_hooks_file "$CURSOR_HOOKS_FILE" "$HOOK_SCRIPT"
     fi
+    chmod 600 "$CURSOR_HOOKS_FILE"
 
     echo ""
     echo "  Next steps (Cursor):"
@@ -64,7 +70,7 @@ run_setup() {
     echo "  3. Restart Cursor (or reload window) so hooks are picked up."
     echo "  4. Shell commands and tool use will be checked by APort policy (exit 2 = block)."
     echo ""
-    echo "  Same script works for VS Code + Copilot and Claude Code — see: docs/frameworks/cursor.md"
+    echo "  Same script works for VS Code + Copilot. For Claude Code use the dedicated integration: docs/frameworks/claude-code.md"
     echo ""
 }
 
@@ -80,12 +86,14 @@ _write_cursor_hooks_file() {
       }
     }' > "$file"
     else
+        local escaped_cmd
+        escaped_cmd="$(printf '%s' "$cmd" | sed 's/\\/\\\\/g; s/"/\\"/g')"
         cat > "$file" << EOF
 {
   "version": 1,
   "hooks": {
-    "beforeShellExecution": [{"command": "$cmd"}],
-    "preToolUse": [{"command": "$cmd"}]
+    "beforeShellExecution": [{"command": "${escaped_cmd}"}],
+    "preToolUse": [{"command": "${escaped_cmd}"}]
   }
 }
 EOF

package/bin/frameworks/langchain.sh

@@ -14,8 +14,11 @@ run_setup() {
     log_info "Setting up APort guardrails for LangChain..."
     config_dir="$(write_config_template langchain)"
     mkdir -p "$config_dir/aport"
+    chmod 700 "$config_dir/aport"
     export APORT_FRAMEWORK=langchain
     run_passport_wizard "$@"
+    # Harden permissions on passport (contains policy/capabilities)
+    [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
     echo ""
     echo "  Next steps (LangChain):"
     echo "  ───────────────────────"

package/bin/frameworks/n8n.sh

@@ -20,8 +20,11 @@ run_setup() {
     log_info "Setting up APort guardrails for n8n..."
     config_dir="$(write_config_template n8n)"
     mkdir -p "$config_dir/aport"
+    chmod 700 "$config_dir/aport"
     export APORT_FRAMEWORK=n8n
     run_passport_wizard "$@"
+    # Harden permissions on passport (contains policy/capabilities)
+    [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
     echo ""
     echo "  Next steps (n8n):"
     echo "  ────────────────"

package/bin/lib/allowlist.sh

@@ -5,14 +5,16 @@
 # shellcheck source=./common.sh
 source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
 
-# Placeholder: allowlist check logic can be shared between bash evaluator and API
-# Returns 0 if command is allowed, 1 if denied
+# Stub: command allowlist checking is implemented directly in aport-guardrail-bash.sh
+# (safe_prefix_match + blocked_patterns). This file is kept for backward compatibility
+# but callers MUST NOT rely on this function for security enforcement.
 check_command_allowed() {
     local command_line="$1"
     local allowed_list="${2:-*}"
-    # TODO: Implement against passport allowed_commands + blocked patterns
     [[ -z "$command_line" ]] && return 1
-    return 0
+    # SECURITY: Not implemented here — use aport-guardrail-bash.sh for actual enforcement
+    echo "[aport] WARN: check_command_allowed is a stub; use aport-guardrail-bash.sh" >&2
+    return 1
 }
 
 export -f check_command_allowed

package/bin/lib/config.sh

@@ -15,6 +15,7 @@ get_config_dir() {
         crewai) echo "${APORT_CREWAI_CONFIG_DIR:-$HOME/.aport/crewai}" ;;
         n8n) echo "${APORT_N8N_CONFIG_DIR:-$HOME/.n8n}" ;;
         cursor) echo "${APORT_CURSOR_CONFIG_DIR:-$HOME/.cursor}" ;;
+        claude-code) echo "${APORT_CLAUDE_CODE_CONFIG_DIR:-$HOME/.claude}" ;;
         *) echo "${APORT_CONFIG_DIR:-$HOME/.aport}" ;;
     esac
 }

package/bin/lib/detect.sh

@@ -32,7 +32,12 @@ detect_frameworks_list() {
         grep -qi 'crewai' "$dir/requirements.txt" 2> /dev/null && list+=(crewai)
     fi
 
-    # Dedupe preserving order (first occurrence wins). Safe for set -u when list is empty.
+    # Claude Code: detect claude binary or ~/.claude directory
+    if command -v claude &> /dev/null || [[ -d "$HOME/.claude" ]]; then
+        list+=(claude-code)
+    fi
+
+    # Dedupe preserving order
     local seen=() out=()
     if [[ ${#list[@]} -gt 0 ]]; then
         for fw in "${list[@]}"; do