@aporthq/aport-agent-guardrails 1.0.27 → 1.0.29

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
@@ -72,6 +96,7 @@ npx @aporthq/aport-agent-guardrails
 
 - **I need OpenClaw now:** [docs/QUICKSTART_OPENCLAW_PLUGIN.md](docs/QUICKSTART_OPENCLAW_PLUGIN.md)
 - **I already have agent_id:** [docs/HOSTED_PASSPORT_SETUP.md](docs/HOSTED_PASSPORT_SETUP.md)
+- **I’m deploying for an IT team:** [docs/ENTERPRISE_DEVICE_DEPLOYMENT.md](docs/ENTERPRISE_DEVICE_DEPLOYMENT.md)
 - **I need framework setup docs:** [docs/frameworks](docs/frameworks)
 - **I want Claude marketplace install:** [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md#marketplace-install-claude-plugins)
 
@@ -94,7 +119,7 @@ The security concern is that agent tools and skills can execute sensitive action
 
 **Two ways to use APort:** (1) **Guardrails (CLI/setup)** — run the installer to create your passport and config; (2) **Core (library)** — use the `OAPGuardrailProvider` ([docs/PROVIDER.md](docs/PROVIDER.md)) in your app so each tool call is verified. One provider per language (Python + TypeScript), works with any framework. Framework docs: [OpenClaw](docs/frameworks/openclaw.md), [Cursor](docs/frameworks/cursor.md), [Claude Code](docs/frameworks/claude-code.md), [LangChain](docs/frameworks/langchain.md), [CrewAI](docs/frameworks/crewai.md), [DeerFlow](docs/frameworks/deerflow.md), [n8n](docs/frameworks/n8n.md).
 
-**CLI-supported frameworks:** `openclaw`, `langchain`, `crewai`, `cursor`, `claude-code`, `deerflow`, `n8n`. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. See [Deployment readiness](docs/DEPLOYMENT_READINESS.md).
+**CLI-supported frameworks:** `openclaw`, `langchain`, `crewai`, `cursor`, `claude-code`, `deerflow`, `n8n`. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. For IT-managed device rollout, see [Enterprise device deployment](docs/ENTERPRISE_DEVICE_DEPLOYMENT.md).
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|
@@ -159,11 +184,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 +470,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

@@ -9,6 +9,11 @@ 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"
@@ -16,7 +21,7 @@ ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 . "$ROOT_DIR/bin/lib/guardrail-mode.sh"
 # shellcheck source=bin/lib/hook-read-policy.sh
 . "$ROOT_DIR/bin/lib/hook-read-policy.sh"
-load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.claude}"
+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
@@ -136,9 +141,10 @@ 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
 

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,6 +13,11 @@ 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"
@@ -20,7 +25,7 @@ ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 . "$ROOT_DIR/bin/lib/guardrail-mode.sh"
 # shellcheck source=bin/lib/hook-read-policy.sh
 . "$ROOT_DIR/bin/lib/hook-read-policy.sh"
-load_guardrail_mode_for_hooks "${OPENCLAW_CONFIG_DIR:-$HOME/.cursor}"
+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
@@ -164,9 +169,10 @@ 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
 
@@ -202,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-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 ""
 }
 

package/bin/frameworks/generic.sh

@@ -19,6 +19,8 @@ source "$LIB/runtime.sh"
 source "$LIB/config.sh"
 # shellcheck source=../lib/guardrail-mode.sh
 source "$LIB/guardrail-mode.sh"
+# shellcheck source=../lib/quick-hosted.sh
+source "$LIB/quick-hosted.sh"
 
 framework="${APORT_FRAMEWORK:?APORT_FRAMEWORK must be set by the dispatcher}"
 crewai_integration_mode="${APORT_CREWAI_INTEGRATION_MODE:-compat}"
@@ -46,7 +48,11 @@ while [[ ${#remaining_args[@]} -gt 0 ]]; do
             crewai_integration_mode="${remaining_args[0]}"
             remaining_args=("${remaining_args[@]:1}")
             ;;
-        ap_[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])
+        ap_* | apt_* | agt_inst_* | agt_tmpl_*)
+            if ! is_aport_hosted_agent_id "$arg"; then
+                log_error "Invalid hosted passport ID format: $arg"
+                exit 1
+            fi
             hosted_agent_id="$arg"
             ;;
         *)
@@ -134,6 +140,9 @@ persist_python_framework_config() {
 
     if [[ "$selected_mode" == "api" ]]; then
         _config_replace_or_append "$config_file" "api_url" "$(_yaml_quote "${selected_api_url:-$DEFAULT_APORT_API_URL}")"
+        if [[ -n "${APORT_API_KEY:-}" ]]; then
+            _config_replace_or_append "$config_file" "api_key" "$(_yaml_quote "$APORT_API_KEY")"
+        fi
         if [[ -n "$hosted_id" ]]; then
             _config_replace_or_append "$config_file" "agent_id" "$(_yaml_quote "$hosted_id")"
             _config_remove_key "$config_file" "passport_path"
@@ -146,6 +155,7 @@ persist_python_framework_config() {
             _config_replace_or_append "$config_file" "passport_path" "$(_yaml_quote "$local_passport_path")"
         fi
         _config_remove_key "$config_file" "agent_id"
+        _config_remove_key "$config_file" "api_key"
     fi
 
     chmod 600 "$config_file" 2> /dev/null || true
@@ -166,6 +176,9 @@ run_setup() {
     fi
     if [[ -n "$hosted_agent_id" ]]; then
         log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
+    elif aport_maybe_configure_hosted_passport "$framework" "$config_dir"; then
+        hosted_agent_id="$APORT_AGENT_ID"
+        log_info "Using hosted passport (agent_id: $hosted_agent_id) — skipping wizard."
     elif ((${#FORWARD_ARGS[@]} > 0)); then
         run_passport_wizard "${FORWARD_ARGS[@]}"
     else

package/bin/lib/framework-hook-paths.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Framework hook path normalization.
+# GUI tools can inherit stale legacy OPENCLAW_* variables from another framework
+# session. Hooks should default to their own framework config unless the caller
+# explicitly opts into an external passport path.
+
+aport_hook_expand_path() {
+    local input="$1"
+    printf '%s' "${input/#\~/$HOME}"
+}
+
+aport_hook_known_config_owner() {
+    local config_dir
+    config_dir="$(aport_hook_expand_path "$1")"
+
+    case "$config_dir" in
+        "$HOME/.claude" | "$HOME/.claude/"*) echo "claude-code" ;;
+        "$HOME/.cursor" | "$HOME/.cursor/"*) echo "cursor" ;;
+        "$HOME/.openclaw" | "$HOME/.openclaw/"*) echo "openclaw" ;;
+        "$HOME/.aport/langchain" | "$HOME/.aport/langchain/"*) echo "langchain" ;;
+        "$HOME/.aport/crewai" | "$HOME/.aport/crewai/"*) echo "crewai" ;;
+        "$HOME/.aport/deerflow" | "$HOME/.aport/deerflow/"*) echo "deerflow" ;;
+        "$HOME/.n8n" | "$HOME/.n8n/"*) echo "n8n" ;;
+        *) echo "" ;;
+    esac
+}
+
+aport_hook_prepare_framework_paths() {
+    local framework="$1"
+    local framework_config_dir="${2:-}"
+    local default_config_dir="$3"
+    local selected_config_dir owner passport_path decision_path audit_path
+
+    if [ -n "$framework_config_dir" ]; then
+        selected_config_dir="$framework_config_dir"
+    else
+        selected_config_dir="${APORT_CONFIG_DIR:-${OPENCLAW_CONFIG_DIR:-}}"
+        owner="$(aport_hook_known_config_owner "$selected_config_dir")"
+        if [ -n "$owner" ] && [ "$owner" != "$framework" ]; then
+            selected_config_dir="$default_config_dir"
+        fi
+    fi
+
+    selected_config_dir="${selected_config_dir:-$default_config_dir}"
+    selected_config_dir="$(aport_hook_expand_path "$selected_config_dir")"
+    export APORT_CONFIG_DIR="$selected_config_dir"
+    export OPENCLAW_CONFIG_DIR="$selected_config_dir"
+
+    if [ -n "${APORT_PASSPORT_FILE:-${OPENCLAW_PASSPORT_FILE:-}}" ] && [ -z "${APORT_ALLOW_EXTERNAL_PASSPORT_FILE:-}" ]; then
+        passport_path="$(aport_hook_expand_path "${APORT_PASSPORT_FILE:-${OPENCLAW_PASSPORT_FILE:-}}")"
+        case "$passport_path" in
+            "$APORT_CONFIG_DIR"/*)
+                export APORT_PASSPORT_FILE="$passport_path"
+                export OPENCLAW_PASSPORT_FILE="$passport_path"
+                ;;
+            *)
+                unset APORT_PASSPORT_FILE
+                unset OPENCLAW_PASSPORT_FILE
+                ;;
+        esac
+    fi
+
+    if [ -n "${APORT_ALLOW_EXTERNAL_PASSPORT_FILE:-}" ] && [ -n "${APORT_PASSPORT_FILE:-${OPENCLAW_PASSPORT_FILE:-}}" ]; then
+        passport_path="$(aport_hook_expand_path "${APORT_PASSPORT_FILE:-${OPENCLAW_PASSPORT_FILE:-}}")"
+        export APORT_PASSPORT_FILE="$passport_path"
+        export OPENCLAW_PASSPORT_FILE="$passport_path"
+    fi
+
+    if [ -n "${APORT_DECISION_FILE:-${OPENCLAW_DECISION_FILE:-}}" ]; then
+        decision_path="$(aport_hook_expand_path "${APORT_DECISION_FILE:-${OPENCLAW_DECISION_FILE:-}}")"
+        case "$decision_path" in
+            "$APORT_CONFIG_DIR"/*)
+                export APORT_DECISION_FILE="$decision_path"
+                export OPENCLAW_DECISION_FILE="$decision_path"
+                ;;
+            *)
+                unset APORT_DECISION_FILE
+                unset OPENCLAW_DECISION_FILE
+                ;;
+        esac
+    fi
+
+    if [ -n "${APORT_AUDIT_LOG:-${OPENCLAW_AUDIT_LOG:-}}" ]; then
+        audit_path="$(aport_hook_expand_path "${APORT_AUDIT_LOG:-${OPENCLAW_AUDIT_LOG:-}}")"
+        case "$audit_path" in
+            "$APORT_CONFIG_DIR"/*)
+                export APORT_AUDIT_LOG="$audit_path"
+                export OPENCLAW_AUDIT_LOG="$audit_path"
+                ;;
+            *)
+                unset APORT_AUDIT_LOG
+                unset OPENCLAW_AUDIT_LOG
+                ;;
+        esac
+    fi
+}