@aporthq/aport-agent-guardrails 1.0.26 → 1.0.28

package/README.md

@@ -46,17 +46,41 @@ From the live APort Vault adversarial testbed:
 
 ## Start Here
 
-### Install in 30 seconds
+### Install in 60 seconds
 
 ```bash
 npx @aporthq/aport-agent-guardrails
 ```
 
 - Choose your framework: `openclaw`, `cursor`, `claude-code`, `langchain`, `crewai`, `deerflow`, `n8n`
-- OpenClaw direct: `npx @aporthq/aport-agent-guardrails openclaw`
-- Hosted passport: `npx @aporthq/aport-agent-guardrails openclaw <agent_id>`
+- Claude Code direct: `npx @aporthq/aport-agent-guardrails claude-code`
+- Curl install URL: `curl -fsSL https://aport.io/install.sh | bash -s -- claude-code`
+- Existing hosted passport: `npx @aporthq/aport-agent-guardrails claude-code <agent_id>`
 - Reset a framework to a clean APort state: `npx @aporthq/aport-agent-guardrails reset claude-code --yes`
 
+When prompted for passport setup, the choices are:
+
+1. `Create hosted APort passport now` — recommended; creates a hosted passport and narrow setup key.
+2. `Use existing hosted passport ID` — paste an existing `agent_id`.
+3. `Create local passport file` — offline/local JSON passport.
+
+For a new hosted setup, choose option `1`. The installer creates a passport, creates a narrow setup key, writes the framework hook/config, and starts sending decisions to APort. For non-interactive installs:
+
+```bash
+npx --yes @aporthq/aport-agent-guardrails claude-code \
+  --quick-hosted \
+  --email you@example.com \
+  --non-interactive
+```
+
+Equivalent environment-variable form:
+
+```bash
+APORT_OWNER_EMAIL="you@example.com" \
+APORT_QUICK_HOSTED=1 \
+npx --yes @aporthq/aport-agent-guardrails claude-code --non-interactive
+```
+
 ### Why Developers and teams trust APort
 
 - **Deterministic enforcement:** runtime hook, not prompt instructions
@@ -159,11 +183,11 @@ aport setup --framework=langchain
 ```
 Then install the framework-specific Python package and follow the printed integration step for your framework.
 
-This runs the **passport wizard** and writes config for your framework. Follow the **next steps** printed at the end (e.g. restart Cursor; or for CrewAI: by default install `aport-agent-guardrails-crewai` for released CrewAI, or opt into native-provider mode if your CrewAI build supports it).
+This runs setup and writes config for your framework. Choose hosted setup for passport and setup-key creation, or local setup for an on-disk passport. Follow the **next steps** printed at the end (e.g. restart Cursor; or for CrewAI: by default install `aport-agent-guardrails-crewai` for released CrewAI, or opt into native-provider mode if your CrewAI build supports it).
 
 **Guardrail mode (local vs API)** — On the **Node** installer (`npx @aporthq/aport-agent-guardrails …` / `bin/agent-guardrails`), every framework accepts the same flags: `--mode=api` (with optional `--api-url`, default `https://api.aport.io`) or `--mode=local`, and an optional hosted `ap_<hex>` argument (API mode, no local passport). That flow writes `…/aport/guardrail-mode.env` where the hooks/generic installers need it. The **Python** `aport setup` CLI does not parse those flags yet; use the Node command above for API/local mode during setup, or set mode in your framework `config.yaml` per the framework doc.
 
-**2. Hosted passport (optional)** — If you already have an agent_id from [aport.io](https://aport.io), use it to skip the wizard: `npx @aporthq/aport-agent-guardrails openclaw <agent_id>`. See [Hosted passport setup](docs/HOSTED_PASSPORT_SETUP.md).
+**2. Hosted passport (optional)** — The installer can create a hosted passport during setup. If you already have an agent_id from [aport.io](https://aport.io), use it to skip passport creation: `npx @aporthq/aport-agent-guardrails claude-code <agent_id>`. See [Hosted passport setup](docs/HOSTED_PASSPORT_SETUP.md).
 
 **3. Test that policy runs** — After setup, the guardrail runs automatically when your agent uses tools (Cursor hook, LangChain callback, OpenClaw plugin, etc.). To try allow/deny from the command line (any framework), use the installed `aport-guardrail` command (Node) or call the evaluator from Python; both use your existing passport from the framework config dir (e.g. `~/.cursor/aport/`, `~/.aport/langchain/aport/`).
 
@@ -445,7 +469,7 @@ Use the framework-specific doc for where config and passport live and for any ex
 
 | Doc | Description |
 |-----|-------------|
-| [QuickStart: OpenClaw Plugin](docs/QUICKSTART_OPENCLAW_PLUGIN.md) | 5-minute OpenClaw setup |
+| [QuickStart: OpenClaw Plugin](docs/QUICKSTART_OPENCLAW_PLUGIN.md) | One-command OpenClaw setup |
 | [Hosted passport setup](docs/HOSTED_PASSPORT_SETUP.md) | Use passport from aport.io — `npx ... openclaw <agent_id>` or choose hosted in wizard |
 | [Verification methods (local vs API)](docs/VERIFICATION_METHODS.md) | Deep dive: bash vs API evaluator |
 | [Quick Start Guide](docs/QUICKSTART.md) | Passport wizard, copy-paste option |

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# APort Claude Code hook: reads tool_name + tool_input from JSON stdin,
+# APort Claude Code hook: reads tool_name + tool_input from JSON stdin (path-based Read uses guardrail).
 # 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.
@@ -9,12 +9,19 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+# Anchor data paths to Claude Code config before resolve (hosted/API installs may have no passport.json).
+# shellcheck source=bin/lib/framework-hook-paths.sh
+. "$ROOT_DIR/bin/lib/framework-hook-paths.sh"
+aport_hook_prepare_framework_paths "claude-code" "${APORT_CLAUDE_CODE_CONFIG_DIR:-}" "$HOME/.claude"
+
 # Path resolver: probes ~/.claude, ~/.cursor, ~/.openclaw, etc.
 # shellcheck source=bin/aport-resolve-paths.sh
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
 # shellcheck source=bin/lib/guardrail-mode.sh
 . "$ROOT_DIR/bin/lib/guardrail-mode.sh"
-load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.claude}"
+# shellcheck source=bin/lib/hook-read-policy.sh
+. "$ROOT_DIR/bin/lib/hook-read-policy.sh"
+load_guardrail_mode_for_hooks "${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-$HOME/.claude}}"
 
 GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
 if [ "${APORT_GUARDRAIL_MODE:-local}" = "api" ]; then
@@ -49,7 +56,8 @@ set -e
 if [ "$JQ_EXIT" -ne 0 ] || [ -z "$TOOL_NAME" ]; then
     TOOL_NAME="unknown"
 fi
-TOOL_NAME_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | tr '[:upper:]' '[:lower:]')"
+# Strip permission-rule specifiers (e.g. Agent(Explore) -> Agent) before normalization.
+TOOL_NAME_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | sed 's/(.*$//' | tr '[:upper:]' '[:lower:]')"
 set +e
 TOOL_INPUT="$(echo "$INPUT" | jq -c '.tool_input // {}' 2> /dev/null)"
 JQ_EXIT=$?
@@ -81,40 +89,45 @@ GUARDRAIL_TOOL=""
 CONTEXT_JSON="{}"
 
 case "$TOOL_NAME_NORM" in
-    bash | shell)
+    bash | shell | powershell | monitor)
         GUARDRAIL_TOOL="bash"
-        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{command: (.command // "")}')"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{command: (.command // .script // "")}')"
+        ;;
+    read | readfile | semanticsearch)
+        if ! aport_hook_try_read_evaluation "$TOOL_NAME_NORM" "$TOOL_INPUT"; then
+            exit 0
+        fi
         ;;
-    read | glob | ls | grep | todoread | toolsearch | askuserquestion | readfile | semanticsearch)
-        # Read-family + user-interaction tools: allow without calling evaluator
+    glob | ls | grep | lsp | todoread | toolsearch | askuserquestion | listmcpresourcestool | readmcpresourcetool | waitformcpservers)
+        # Search/list/read tools without a single file_path: allow without evaluator
         exit 0
         ;;
-    taskget | tasklist | taskoutput | cronlist)
-        # Read-only task/cron queries: allow without evaluator
+    taskget | tasklist | taskoutput | cronlist | schedulewakeup | pushnotification)
+        # Read-only task/cron queries and notifications: allow without evaluator
         exit 0
         ;;
     enterplanmode | exitplanmode)
         # Internal state transitions: allow without evaluator
         exit 0
         ;;
-    write | edit | multiedit | notebookedit | todowrite | delete | strreplace | editnotebook)
+    write | edit | multiedit | notebookedit | todowrite | delete | strreplace | editnotebook | shareonboardingguide)
         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 // "")}')"
+        GUARDRAIL_TOOL="websearch"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // ""), query: (.query // "")}')"
         ;;
     browser)
         GUARDRAIL_TOOL="browser"
         CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // "")}')"
         ;;
-    task | taskcreate | taskupdate | taskstop | agent | skill | enterworktree | subagent | subagentstart)
+    agent | task | taskcreate | taskupdate | taskstop | skill | enterworktree | exitworktree | subagent | subagentstart | sendmessage | teamcreate | teamdelete | remotetrigger)
         GUARDRAIL_TOOL="session.create"
-        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .prompt // "")}')"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .prompt // .task // .message // ""), subagent_type: (.subagent_type // .agent_type // "")}')"
         ;;
     croncreate | crondelete)
-        GUARDRAIL_TOOL="cron"
+        GUARDRAIL_TOOL="session.create"
         CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .schedule // "")}')"
         ;;
     mcp__* | mcp:* | callmcptool)
@@ -128,12 +141,21 @@ case "$TOOL_NAME_NORM" in
 esac
 
 # Use a per-invocation decision file to avoid race conditions with concurrent tool calls
-HOOK_DECISION_FILE="${OPENCLAW_DECISION_FILE:-}"
+HOOK_DECISION_FILE="${APORT_DECISION_FILE:-${OPENCLAW_DECISION_FILE:-}}"
 if [ -n "$HOOK_DECISION_FILE" ]; then
     HOOK_DECISION_FILE="${HOOK_DECISION_FILE%.json}-$$.json"
+    export APORT_DECISION_FILE="$HOOK_DECISION_FILE"
     export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
 fi
 
+# Read tools: send only file_path to the evaluator (Claude may attach large file bodies in tool_input).
+if [ "$GUARDRAIL_TOOL" = "read" ]; then
+    CONTEXT_JSON="$(printf '%s' "$CONTEXT_JSON" | jq -c '{file_path: (.file_path // .path // "")}' 2> /dev/null || echo '{"file_path":""}')"
+    if [ -z "$(printf '%s' "$CONTEXT_JSON" | jq -r '.file_path // ""' 2> /dev/null)" ]; then
+        exit 0
+    fi
+fi
+
 # Call core evaluator (guardrail expects tool name, not policy ID)
 set +e
 "$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null

package/bin/aport-create-passport.sh

@@ -45,8 +45,9 @@ fi
 PASSPORT_FILE="${PASSPORT_FILE/#\~/$HOME}"
 
 # Config dir: from env, or derived from passport path (e.g. .../aport/passport.json -> parent of aport)
-if [ -n "${OPENCLAW_CONFIG_DIR:-}" ]; then
-    CONFIG_DIR="${OPENCLAW_CONFIG_DIR/#\~/$HOME}"
+if [ -n "${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-}}" ]; then
+    CONFIG_DIR="${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-}}"
+    CONFIG_DIR="${CONFIG_DIR/#\~/$HOME}"
 else
     CONFIG_DIR="$(dirname "$PASSPORT_FILE")"
     case "$PASSPORT_FILE" in

package/bin/aport-cursor-hook.sh

@@ -13,12 +13,19 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+# Anchor data paths to Cursor config before resolve (hosted/API installs may have no passport.json).
+# shellcheck source=bin/lib/framework-hook-paths.sh
+. "$ROOT_DIR/bin/lib/framework-hook-paths.sh"
+aport_hook_prepare_framework_paths "cursor" "${APORT_CURSOR_CONFIG_DIR:-}" "$HOME/.cursor"
+
 # Passport/config: resolver probes ~/.cursor, ~/.openclaw, ~/.aport/*, etc.
 # shellcheck source=bin/aport-resolve-paths.sh
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
 # shellcheck source=bin/lib/guardrail-mode.sh
 . "$ROOT_DIR/bin/lib/guardrail-mode.sh"
-load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.cursor}"
+# shellcheck source=bin/lib/hook-read-policy.sh
+. "$ROOT_DIR/bin/lib/hook-read-policy.sh"
+load_guardrail_mode_for_hooks "${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-$HOME/.cursor}}"
 
 GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
 if [ "${APORT_GUARDRAIL_MODE:-local}" = "api" ]; then
@@ -82,8 +89,10 @@ 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
+    FILE_PATH="$(echo "$INPUT" | jq -r '.file_path // ""' 2> /dev/null || true)"
+    if ! aport_hook_try_read_evaluation_from_file_path "$FILE_PATH"; then
+        exit 0
+    fi
 
 elif [ "$HOOK_EVENT" = "subagentStart" ] || { [ -z "$HOOK_EVENT" ] && echo "$INPUT" | jq -e '.subagent_id' &> /dev/null; }; then
     # subagentStart: sub-agent spawning
@@ -96,36 +105,48 @@ elif [ "$HOOK_EVENT" = "beforeMCPExecution" ] || { [ -n "$TOOL_NAME" ] && echo "
     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>
-    # Normalize: trim whitespace, lowercase (patterns must match TOOL_NORM)
-    TOOL_NORM="$(echo "$TOOL_NAME" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')"
+    # preToolUse: Shell, Read, Write, Grep, Delete, Task, WebSearch, Agent, MCP:*, etc.
+    # See docs/FRAMEWORK_TOOL_MAPPING_AUDIT.md and https://cursor.com/docs/agent/hooks
+    TOOL_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | sed 's/(.*$//' | tr '[:upper:]' '[:lower:]')"
     case "$TOOL_NORM" in
-        shell)
+        shell | bash)
             GUARDRAIL_TOOL="bash"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{command: (.tool_input.command // "")}')"
             ;;
-        read | grep | glob | semanticsearch)
-            # Read-family: allow without calling evaluator (matches Claude Code behavior)
+        read | readfile | semanticsearch)
+            TOOL_INPUT="$(safe_jq "$INPUT" '.tool_input // {}')"
+            if ! aport_hook_try_read_evaluation "$TOOL_NORM" "$TOOL_INPUT"; then
+                exit 0
+            fi
+            ;;
+        grep | glob | ls | lsp | listmcpresourcestool | readmcpresourcetool | toolsearch | waitformcpservers | taskget | tasklist | taskoutput | cronlist)
             exit 0
             ;;
-        write | strreplace | editnotebook)
+        write | strreplace | edit | multiedit | editnotebook | applypatch | notebookedit | delete)
             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 // "")}')"
+        websearch | webfetch)
+            GUARDRAIL_TOOL="websearch"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{url: (.tool_input.url // ""), query: (.tool_input.query // "")}')"
             ;;
-        task)
+        browser)
+            GUARDRAIL_TOOL="browser"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{url: (.tool_input.url // "")}')"
+            ;;
+        task | agent | taskcreate | taskupdate | taskstop | skill | subagent | subagentstart | sendmessage | teamcreate | teamdelete)
             GUARDRAIL_TOOL="session.create"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.tool_input.description // .tool_input.prompt // "")}')"
             ;;
-        mcp:*)
+        croncreate | crondelete)
+            GUARDRAIL_TOOL="session.create"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.tool_input.description // .tool_input.schedule // "")}')"
+            ;;
+        mcp__* | mcp:* | callmcptool)
             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
@@ -148,12 +169,22 @@ else
 fi
 
 # Use a per-invocation decision file to avoid race conditions with concurrent tool calls
-HOOK_DECISION_FILE="${OPENCLAW_DECISION_FILE:-}"
+HOOK_DECISION_FILE="${APORT_DECISION_FILE:-${OPENCLAW_DECISION_FILE:-}}"
 if [ -n "$HOOK_DECISION_FILE" ]; then
     HOOK_DECISION_FILE="${HOOK_DECISION_FILE%.json}-$$.json"
+    export APORT_DECISION_FILE="$HOOK_DECISION_FILE"
     export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
 fi
 
+# Read tools: send only file_path to the evaluator (Cursor may attach large file bodies in tool_input).
+if [ "$GUARDRAIL_TOOL" = "read" ]; then
+    CONTEXT_JSON="$(printf '%s' "$CONTEXT_JSON" | jq -c '{file_path: (.file_path // .path // "")}' 2> /dev/null || echo '{"file_path":""}')"
+    if [ -z "$(printf '%s' "$CONTEXT_JSON" | jq -r '.file_path // ""' 2> /dev/null)" ]; then
+        echo '{"permission":"allow","allowed":true}'
+        exit 0
+    fi
+fi
+
 # Call core evaluator
 set +e
 "$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null
@@ -177,7 +208,7 @@ if [ -n "$HOOK_DECISION_FILE" ] && [ -f "$HOOK_DECISION_FILE" ]; then
 fi
 # 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
+    for DEC in "${APORT_CONFIG_DIR:-${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)"
             [ -n "$R" ] && REASON="$R" && break

package/bin/aport-guardrail-api.sh

@@ -63,6 +63,8 @@ if [ -n "$DEBUG_APORT" ]; then
 fi
 
 # Export environment variables for evaluator (APORT_API_URL, APORT_AGENT_ID, APORT_API_KEY passed through)
+export APORT_PASSPORT_FILE="$PASSPORT_FILE"
+export APORT_DECISION_FILE="$DECISION_FILE"
 export OPENCLAW_PASSPORT_FILE="$PASSPORT_FILE"
 export OPENCLAW_DECISION_FILE="$DECISION_FILE"
 

package/bin/aport-guardrail-bash.sh

@@ -301,6 +301,17 @@ else
     LIMITS=$(echo "$PASSPORT" | jq ".limits.\"$POLICY_BASE\" // {}")
 fi
 
+is_default_sensitive_read_path() {
+    local path_lower
+    path_lower="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
+    case "$path_lower" in
+        .env* | */.env* | .aws/* | */.aws/* | .ssh/* | */.ssh/* | *credentials* | *id_rsa* | *id_dsa* | *id_ecdsa* | *id_ed25519* | *.pem | *.key | *password* | .gnupg/* | */.gnupg/* | .kube/* | */.kube/*)
+            return 0
+            ;;
+    esac
+    return 1
+}
+
 # Evaluate policy-specific limits
 if [[ "$POLICY_ID" == "code.repository.merge"* ]]; then
     FILES_CHANGED=$(echo "$CONTEXT_JSON" | jq -r '.files_changed // .files // 0')
@@ -426,6 +437,10 @@ fi
 if [[ "$POLICY_ID" == "data.file.read.v1" ]]; then
     FILE_PATH=$(echo "$CONTEXT_JSON" | jq -r '.file_path // .path // ""')
     if [ -n "$FILE_PATH" ]; then
+        if is_default_sensitive_read_path "$FILE_PATH"; then
+            write_decision false "$POLICY_ID" "oap.blocked_pattern" "File path matches default sensitive read pattern"
+        fi
+
         # Check allowed paths
         PATH_ALLOWED=false
         while IFS= read -r allowed_path; do

package/bin/aport-resolve-paths.sh

@@ -5,14 +5,19 @@
 #   - aport-guardrail-api.sh
 #   - aport-status.sh
 # (aport-create-passport.sh uses --output; wrappers set env so children get resolved paths.)
-# Sets: OPENCLAW_PASSPORT_FILE, OPENCLAW_DECISION_FILE, OPENCLAW_AUDIT_LOG
-# and PASSPORT_FILE, DECISION_FILE, AUDIT_LOG. Passport status (active|suspended|revoked) is source of truth for suspend; no separate file.
+# Sets canonical APORT_* path variables plus legacy OPENCLAW_* aliases for compatibility.
+# Also sets PASSPORT_FILE, DECISION_FILE, AUDIT_LOG. Passport status (active|suspended|revoked)
+# is source of truth for suspend; no separate file.
 # Caller must ensure APORT_DATA_DIR exists before writing (e.g. mkdir -p "$(dirname "$AUDIT_LOG")").
 
 resolve_aport_paths() {
     local config_dir
     local passport_path
     local data_dir
+    local explicit_passport="${APORT_PASSPORT_FILE:-${OPENCLAW_PASSPORT_FILE:-}}"
+    local explicit_decision="${APORT_DECISION_FILE:-${OPENCLAW_DECISION_FILE:-}}"
+    local explicit_audit="${APORT_AUDIT_LOG:-${OPENCLAW_AUDIT_LOG:-}}"
+    local explicit_config="${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-}}"
 
     # Source validation if available (for validate_passport_path)
     local _resolve_script_dir
@@ -24,9 +29,14 @@ resolve_aport_paths() {
         . "$_resolve_script_dir/../bin/lib/validation.sh" 2> /dev/null || true
     fi
 
+    [ -n "$explicit_passport" ] && explicit_passport="${explicit_passport/#\~/$HOME}"
+    [ -n "$explicit_decision" ] && explicit_decision="${explicit_decision/#\~/$HOME}"
+    [ -n "$explicit_audit" ] && explicit_audit="${explicit_audit/#\~/$HOME}"
+    [ -n "$explicit_config" ] && explicit_config="${explicit_config/#\~/$HOME}"
+
     # 0) AGENTS.md enforcement block (repo-scoped, highest priority after explicit env)
-    #    Only checked when no explicit env var is set — OPENCLAW_PASSPORT_FILE always wins.
-    if [ -z "${OPENCLAW_PASSPORT_FILE:-}" ]; then
+    #    Only checked when no explicit passport env var is set.
+    if [ -z "$explicit_passport" ]; then
         local _agentsmd_lib="$_resolve_script_dir/lib/agentsmd.sh"
         [ ! -f "$_agentsmd_lib" ] && _agentsmd_lib="$_resolve_script_dir/../bin/lib/agentsmd.sh"
         if [ -f "$_agentsmd_lib" ]; then
@@ -39,53 +49,61 @@ resolve_aport_paths() {
                 if [ -n "$AGENTSMD_PASSPORT" ] && [ -f "$AGENTSMD_PASSPORT" ]; then
                     passport_path="$AGENTSMD_PASSPORT"
                     data_dir="$(dirname "$AGENTSMD_PASSPORT")"
+                    explicit_decision="${explicit_decision:-${data_dir}/decision.json}"
+                    explicit_audit="${explicit_audit:-${data_dir}/audit.log}"
+
+                    export APORT_PASSPORT_FILE="$passport_path"
                     export OPENCLAW_PASSPORT_FILE="$passport_path"
-                    if [ -z "${OPENCLAW_DECISION_FILE:-}" ]; then
-                        export OPENCLAW_DECISION_FILE="${data_dir}/decision.json"
-                    fi
-                    export OPENCLAW_AUDIT_LOG="${data_dir}/audit.log"
+                    export APORT_DECISION_FILE="$explicit_decision"
+                    export OPENCLAW_DECISION_FILE="$explicit_decision"
+                    export APORT_AUDIT_LOG="$explicit_audit"
+                    export OPENCLAW_AUDIT_LOG="$explicit_audit"
+
                     PASSPORT_FILE="$passport_path"
-                    DECISION_FILE="${OPENCLAW_DECISION_FILE}"
-                    AUDIT_LOG="${data_dir}/audit.log"
+                    DECISION_FILE="$explicit_decision"
+                    AUDIT_LOG="$explicit_audit"
                     return 0
                 fi
             fi
         fi
     fi
 
-    # 1) Explicit path set and file exists → use it (plugin or wrapper)
-    if [ -n "${OPENCLAW_PASSPORT_FILE:-}" ] && [ -f "$OPENCLAW_PASSPORT_FILE" ]; then
+    # 1) Explicit path set and file exists -> use it (plugin or wrapper)
+    if [ -n "$explicit_passport" ] && [ -f "$explicit_passport" ]; then
         # Validate env-provided path if validator is available
         if type validate_explicit_passport_path &> /dev/null; then
-            if ! validate_explicit_passport_path "$OPENCLAW_PASSPORT_FILE"; then
-                echo "[aport] WARN: OPENCLAW_PASSPORT_FILE path failed validation: $OPENCLAW_PASSPORT_FILE" >&2
+            if ! validate_explicit_passport_path "$explicit_passport"; then
+                echo "[aport] WARN: APORT_PASSPORT_FILE path failed validation: $explicit_passport" >&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)
-    elif [ -n "${OPENCLAW_PASSPORT_FILE:-}" ]; then
-        config_dir="$(cd "$(dirname "$OPENCLAW_PASSPORT_FILE")/.." 2> /dev/null && pwd)"
+        data_dir="$(dirname "$explicit_passport")"
+        passport_path="$explicit_passport"
+    # 2) Explicit path set but file missing -> legacy: try parent dir (e.g. .../openclaw/passport.json)
+    elif [ -n "$explicit_passport" ]; then
+        config_dir="$(cd "$(dirname "$explicit_passport")/.." 2> /dev/null && pwd)"
         if [ -f "${config_dir}/passport.json" ]; then
             passport_path="${config_dir}/passport.json"
             data_dir="$config_dir"
         else
-            passport_path="$OPENCLAW_PASSPORT_FILE"
-            data_dir="$(dirname "$OPENCLAW_PASSPORT_FILE")"
+            passport_path="$explicit_passport"
+            data_dir="$(dirname "$explicit_passport")"
         fi
-    # 3) No env → probe framework-specific default paths (where each framework stores data), then OpenClaw legacy
+    # 3) Probe framework paths, or honor APORT_CONFIG_DIR / OPENCLAW_CONFIG_DIR set by framework hooks.
     else
-        config_dir=""
-        for candidate in "$HOME/.claude" "$HOME/.cursor" "$HOME/.openclaw" "$HOME/.aport/langchain" "$HOME/.aport/crewai" "$HOME/.aport/deerflow" "$HOME/.n8n"; do
-            if [ -f "${candidate}/aport/passport.json" ]; then
-                config_dir="$candidate"
-                break
+        if [ -n "$explicit_config" ]; then
+            config_dir="$explicit_config"
+        else
+            config_dir=""
+            for candidate in "$HOME/.claude" "$HOME/.cursor" "$HOME/.openclaw" "$HOME/.aport/langchain" "$HOME/.aport/crewai" "$HOME/.aport/deerflow" "$HOME/.n8n"; do
+                if [ -f "${candidate}/aport/passport.json" ]; then
+                    config_dir="$candidate"
+                    break
+                fi
+            done
+            if [ -z "$config_dir" ]; then
+                config_dir="$HOME/.openclaw"
             fi
-        done
-        if [ -z "$config_dir" ]; then
-            config_dir="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
         fi
-        config_dir="${config_dir/#\~/$HOME}"
         if [ -f "${config_dir}/aport/passport.json" ]; then
             passport_path="${config_dir}/aport/passport.json"
             data_dir="${config_dir}/aport"
@@ -98,19 +116,28 @@ resolve_aport_paths() {
         fi
     fi
 
+    export APORT_PASSPORT_FILE="$passport_path"
     export OPENCLAW_PASSPORT_FILE="$passport_path"
-    # Preserve explicitly set decision path (e.g. tests set OPENCLAW_DECISION_FILE); otherwise use data_dir
-    if [ -n "${OPENCLAW_DECISION_FILE:-}" ]; then
-        export OPENCLAW_DECISION_FILE="$OPENCLAW_DECISION_FILE"
+
+    # Preserve explicitly set decision/audit paths (e.g. tests); otherwise use data_dir.
+    if [ -n "$explicit_decision" ]; then
+        export APORT_DECISION_FILE="$explicit_decision"
+    else
+        export APORT_DECISION_FILE="${data_dir}/decision.json"
+    fi
+    export OPENCLAW_DECISION_FILE="$APORT_DECISION_FILE"
+
+    if [ -n "$explicit_audit" ]; then
+        export APORT_AUDIT_LOG="$explicit_audit"
     else
-        export OPENCLAW_DECISION_FILE="${data_dir}/decision.json"
+        export APORT_AUDIT_LOG="${data_dir}/audit.log"
     fi
-    export OPENCLAW_AUDIT_LOG="${data_dir}/audit.log"
+    export OPENCLAW_AUDIT_LOG="$APORT_AUDIT_LOG"
 
-    PASSPORT_FILE="$OPENCLAW_PASSPORT_FILE"
-    DECISION_FILE="$OPENCLAW_DECISION_FILE"
-    AUDIT_LOG="$OPENCLAW_AUDIT_LOG"
+    PASSPORT_FILE="$APORT_PASSPORT_FILE"
+    DECISION_FILE="$APORT_DECISION_FILE"
+    AUDIT_LOG="$APORT_AUDIT_LOG"
 }
 
-# When sourced, resolve immediately so callers just use the vars
+# When sourced, resolve immediately so callers just use the vars.
 resolve_aport_paths

package/bin/frameworks/claude-code.sh

@@ -14,6 +14,8 @@ source "$LIB/config.sh"
 source "$LIB/framework-setup.sh"
 # shellcheck source=../lib/guardrail-mode.sh
 source "$LIB/guardrail-mode.sh"
+# shellcheck source=../lib/quick-hosted.sh
+source "$LIB/quick-hosted.sh"
 
 run_setup() {
     parse_guardrail_mode_args "$@"
@@ -28,6 +30,9 @@ run_setup() {
         hosted_agent_id="$APORT_HOSTED_AGENT_ID_CLI"
         export APORT_AGENT_ID="$hosted_agent_id"
         log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    elif aport_maybe_configure_hosted_passport "claude-code" "$config_dir"; then
+        hosted_agent_id="$APORT_AGENT_ID"
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
     else
         # Check AGENTS.md for enforcement config — skip wizard if already configured
         # shellcheck source=../lib/agentsmd.sh
@@ -65,6 +70,11 @@ run_setup() {
     _write_claude_settings "$SETTINGS_FILE" "$HOOK_SCRIPT"
     chmod 600 "$SETTINGS_FILE"
 
+    # Audit log is appended by hooks; create empty file so the advertised path exists after install.
+    mkdir -p "$config_dir/aport"
+    : >> "$config_dir/aport/audit.log"
+    chmod 600 "$config_dir/aport/audit.log" 2> /dev/null || true
+
     echo ""
     echo "  Next steps (Claude Code):"
     echo "  ─────────────────────────"
@@ -78,7 +88,7 @@ run_setup() {
     echo "  5. Restart Claude Code so the PreToolUse hook is picked up."
     echo "  6. Tool use will be checked by APort policy (exit 2 = block)."
     echo ""
-    echo "  Audit log: $config_dir/aport/audit.log"
+    echo "  Audit log: $config_dir/aport/audit.log (entries added on each policy check)"
     echo ""
     echo "  Note: claude --dangerously-skip-permissions bypasses ALL hooks including APort."
     echo "  See: docs/frameworks/claude-code.md"

package/bin/frameworks/cursor.sh

@@ -14,6 +14,8 @@ source "$LIB/config.sh"
 source "$LIB/framework-setup.sh"
 # shellcheck source=../lib/guardrail-mode.sh
 source "$LIB/guardrail-mode.sh"
+# shellcheck source=../lib/quick-hosted.sh
+source "$LIB/quick-hosted.sh"
 
 run_setup() {
     parse_guardrail_mode_args "$@"
@@ -29,6 +31,9 @@ run_setup() {
         hosted_agent_id="$APORT_HOSTED_AGENT_ID_CLI"
         export APORT_AGENT_ID="$hosted_agent_id"
         log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    elif aport_maybe_configure_hosted_passport "cursor" "$config_dir"; then
+        hosted_agent_id="$APORT_AGENT_ID"
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
     else
         # Check AGENTS.md for enforcement config — skip wizard if already configured
         # shellcheck source=../lib/agentsmd.sh
@@ -102,7 +107,7 @@ run_setup() {
     echo "  5. Restart Cursor (or reload window) so hooks are picked up."
     echo "  6. Shell commands and tool use will be checked by APort policy (exit 2 = block)."
     echo ""
-    echo "  Same script works for VS Code + Copilot. For Claude Code use the dedicated integration: docs/frameworks/claude-code.md"
+    echo "  For other frameworks like Claude Code, use the dedicated integration: docs/frameworks"
     echo ""
 }