@aporthq/aport-agent-guardrails 1.0.20 → 1.0.21

package/README.md

@@ -89,7 +89,7 @@ The security concern is that agent tools and skills can execute sensitive action
 
 ## 🔌 Supported frameworks
 
-**APort Agent Guardrail** adapters are available per framework; the same passport and policies apply. **Node users:** `npx @aporthq/aport-agent-guardrails` (then choose framework) or `npx @aporthq/aport-agent-guardrails <framework>`. **Python users (LangChain/CrewAI/DeerFlow):** run the same CLI for the wizard and config, then install the framework adapter/provider package shown in the framework doc.
+**APort Agent Guardrail** adapters and providers are available per framework; the same passport and policies apply. **Node users:** `npx @aporthq/aport-agent-guardrails` (then choose framework) or `npx @aporthq/aport-agent-guardrails <framework>`. **Python users (LangChain/CrewAI/DeerFlow):** run the same CLI for the wizard and config, then install the Python package shown in the framework doc.
 
 **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).
 
@@ -101,11 +101,12 @@ The security concern is that agent tools and skills can execute sensitive action
 | **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` |
+| **CrewAI** | [docs/frameworks/crewai.md](docs/frameworks/crewai.md) | **Python:** released hook adapter by default; native `GuardrailProvider` mode for CrewAI builds with native provider support | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
 | **DeerFlow** | [docs/frameworks/deerflow.md](docs/frameworks/deerflow.md) | **Python:** generic OAP provider wiring in DeerFlow config | `npx @aporthq/aport-agent-guardrails deerflow` then follow printed `uv`/config steps |
 | **n8n** | [docs/frameworks/n8n.md](docs/frameworks/n8n.md) | *Coming soon* — custom node and runtime in progress | — |
+| **VoltAgent** | [VoltAgent PR #1171](https://github.com/VoltAgent/voltagent/pull/1171) | *In progress* — pluggable `GuardrailProvider` interface landing upstream in `@voltagent/core` | — |
 
-Install via `npx @aporthq/aport-agent-guardrails <framework>` (or choose when prompted). OpenClaw can also use the full installer flow. **For LangChain and CrewAI, the Node CLI only runs the wizard and writes config; you must then run the printed `pip install` and setup commands to install the runtime adapter.** **Python** adapters on PyPI; **Node** adapters on npm (same version as the CLI).
+Install via `npx @aporthq/aport-agent-guardrails <framework>` (or choose when prompted). OpenClaw can also use the full installer flow. **For LangChain, CrewAI, and DeerFlow, the CLI writes config and installs the local runtime into the framework config directory; then install the Python package and wire the provider/callback shown in the framework doc.** **Python** packages are on PyPI; **Node** packages are on npm (same version as the CLI).
 
 **Passport path:** Each framework has its own **default** passport path (where that framework stores data): e.g. Cursor → `~/.cursor/aport/passport.json`, OpenClaw → `~/.openclaw/aport/passport.json`, LangChain → `~/.aport/langchain/aport/passport.json`. The passport wizard’s **first question** is “Passport file path [default]:” — press Enter for the framework default or type a different path. In non-interactive mode (e.g. CI) use **`--output /path/to/passport.json`** to choose the path. Roadmap: [docs/FRAMEWORK_ROADMAP.md](docs/FRAMEWORK_ROADMAP.md).
 
@@ -125,15 +126,15 @@ npx @aporthq/aport-agent-guardrails
 # or: npx @aporthq/aport-agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n
 ```
 
-**Python (LangChain or CrewAI only):** Run the wizard via the Node command above, then install the Python adapter and run the framework setup (see the printed next steps). Or use the Python CLI to see the exact commands:
+**Python (LangChain, CrewAI, or DeerFlow):** Run the wizard via the Node command above, then install the Python package and follow the printed next steps. Or use the Python CLI to see the exact commands:
 ```bash
 pip install aport-agent-guardrails
-aport setup --framework=langchain   # prints: npx ... langchain, then pip install aport-agent-guardrails-langchain, aport-langchain setup
-# or --framework=crewai for CrewAI
+aport setup --framework=langchain
+# or --framework=crewai / deerflow
 ```
-Then run the printed `npx` command to create passport and config, and the printed `pip` / `aport-<framework> setup` to install the adapter.
+Then run the printed `npx` command to create passport and config, and the printed Python 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 LangChain/CrewAI: `pip install aport-agent-guardrails-langchain` + `aport-langchain setup`).
+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).
 
 **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).
 
@@ -147,7 +148,7 @@ aport-guardrail system.command.execute '{"command":"rm -rf /"}'  # DENY (blocked
 ```
 *(If you use `npx` without `-g`, run `npx aport-guardrail ...`.)*
 
-**Python:** Use the guardrail in your app (e.g. add `APortCallback()` to your LangChain agent, or `register_aport_guardrail()` for CrewAI). The guardrail runs on every tool call. To test allow/deny from the shell without Node, use `npx aport-guardrail ...` as above, or see your framework doc for in-app testing.
+**Python:** Use the guardrail in your app (e.g. add `APortCallback()` to your LangChain agent, use `register_aport_guardrail()` for released CrewAI, or `enable_guardrail(OAPGuardrailProvider(...))` for CrewAI builds with native provider support). The guardrail runs on every tool call. To test allow/deny from the shell without Node, use `npx aport-guardrail ...` as above, or see your framework doc for in-app testing.
 
 **Check passport status and audit:**
 
@@ -397,14 +398,14 @@ See [Verification methods](docs/VERIFICATION_METHODS.md) for a detailed comparis
 | `aport` | OpenClaw one-command setup (passport + plugin + wrappers). Optional: `aport <agent_id>` for hosted passport. |
 | `aport-guardrail` | Run guardrail check from the CLI (e.g. `aport-guardrail system.command.execute '{"command":"ls"}'`). Uses passport from your framework config dir. |
 
-**Python:** After `pip install aport-agent-guardrails` you get `aport` (setup helper). For LangChain or CrewAI, install the adapter and framework setup:
+**Python:** After `pip install aport-agent-guardrails` you get `aport` (setup helper). For LangChain or CrewAI, install the framework package and setup:
 
 | Command | Purpose |
 |--------|---------|
 | `aport setup --framework=langchain` | Print next-step commands (npx wizard, then `pip install aport-agent-guardrails-langchain`, `aport-langchain setup`). |
-| `aport setup --framework=crewai` | Same for CrewAI: npx wizard, then `pip install aport-agent-guardrails-crewai`, `aport-crewai setup`. |
+| `aport setup --framework=crewai` | Default released CrewAI path: bootstrap config/runtime, then use `pip install aport-agent-guardrails-crewai` and `aport-crewai setup`. |
+| `aport setup --framework=crewai --integration-mode=native` | Native CrewAI path: bootstrap config/runtime, then use `uv add aport-agent-guardrails` and `OAPGuardrailProvider`. |
 | `aport-langchain setup` | LangChain config and wizard (after installing `aport-agent-guardrails-langchain`). |
-| `aport-crewai setup` | CrewAI config and wizard (after installing `aport-agent-guardrails-crewai`). |
 
 Use the framework-specific doc for where config and passport live and for any extra steps (e.g. Cursor: restart IDE; LangChain/CrewAI: add callback/hook in code).
 
@@ -429,7 +430,7 @@ Use the framework-specific doc for where config and passport live and for any ex
 | → [Cursor](docs/frameworks/cursor.md) | beforeShellExecution / preToolUse hooks, `~/.cursor/hooks.json` |
 | → [Claude Code](docs/frameworks/claude-code.md) | PreToolUse hook, `~/.claude/settings.json` |
 | → [LangChain / LangGraph](docs/frameworks/langchain.md) | `APortCallback` handler |
-| → [CrewAI](docs/frameworks/crewai.md) | `@before_tool_call` hook, `register_aport_guardrail` |
+| → [CrewAI](docs/frameworks/crewai.md) | Released hook adapter by default; native provider mode when available |
 | → [DeerFlow](docs/frameworks/deerflow.md) | Generic provider wiring via DeerFlow `config.yaml` |
 | → [n8n](docs/frameworks/n8n.md) | Custom node, branch on allow/deny |
 | [Framework roadmap](docs/FRAMEWORK_ROADMAP.md) | Support status and roadmap |

package/bin/agent-guardrails

@@ -28,9 +28,22 @@ SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 FRAMEWORKS_DIR="$SCRIPT_DIR/frameworks"
 LIB_DIR="$SCRIPT_DIR/lib"
+SUPPORTED_FRAMEWORKS=(openclaw langchain crewai cursor claude-code deerflow n8n)
+
+framework_supported() {
+  local candidate="${1:-}"
+  local supported
+  for supported in "${SUPPORTED_FRAMEWORKS[@]}"; do
+    if [[ "$candidate" == "$supported" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
 
 # Parse --framework= and -f (skip detection when set)
 framework=""
+integration_mode=""
 REST=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -47,6 +60,19 @@ while [[ $# -gt 0 ]]; do
         exit 1
       fi
       ;;
+    --integration-mode=*)
+      integration_mode="${1#--integration-mode=}"
+      shift
+      ;;
+    --integration-mode)
+      if [[ $# -gt 1 ]]; then
+        integration_mode="$2"
+        shift 2
+      else
+        echo "[aport] ERROR: --integration-mode requires a value (compat or native)" >&2
+        exit 1
+      fi
+      ;;
     *)
       REST+=("$1")
       shift
@@ -59,16 +85,11 @@ if [[ -z "$framework" ]] && [[ ${#REST[@]} -gt 0 ]]; then
   first_arg="${REST[0]}"
   # Check if first arg looks like a framework name (lowercase alphanumeric + hyphen)
   if [[ "$first_arg" =~ ^[a-z0-9-]+$ ]]; then
-    # Valid framework names
-    valid_frameworks=(openclaw langchain crewai cursor claude-code n8n deerflow)
-    for valid_fw in "${valid_frameworks[@]}"; do
-      if [[ "$first_arg" == "$valid_fw" ]]; then
-        framework="$first_arg"
-        # Remove framework from REST so remaining args are pass-through
-        REST=("${REST[@]:1}")
-        break
-      fi
-    done
+    if framework_supported "$first_arg"; then
+      framework="$first_arg"
+      # Remove framework from REST so remaining args are pass-through
+      REST=("${REST[@]:1}")
+    fi
   fi
 fi
 
@@ -98,7 +119,7 @@ if [[ -z "$framework" ]]; then
           echo "  ─────────────────────────────────────────"
           echo "  Multiple frameworks detected: $detected_list"
           echo "  Choose one: openclaw | langchain | crewai | cursor | claude-code | deerflow | n8n"
-          echo "  Example: npx @aporthq/agent-guardrails --framework=openclaw"
+          echo "  Example: npx @aporthq/aport-agent-guardrails --framework=openclaw"
           echo ""
           read -p "  Framework [${framework:-openclaw}]: " choice
           framework="${choice:-${framework:-openclaw}}"
@@ -121,8 +142,8 @@ if [[ -z "$framework" ]]; then
   echo "  ─────────────────────────────────────────"
   echo "  No framework detected in current directory."
   echo "  Choose: openclaw | langchain | crewai | cursor | claude-code | deerflow | n8n"
-  echo "  Example: npx @aporthq/agent-guardrails openclaw"
-  echo "           npx @aporthq/agent-guardrails --framework=langchain"
+  echo "  Example: npx @aporthq/aport-agent-guardrails openclaw"
+  echo "           npx @aporthq/aport-agent-guardrails --framework=langchain"
   echo ""
   read -p "  Framework [openclaw]: " framework
   framework="${framework:-openclaw}"
@@ -136,6 +157,29 @@ if [[ ! "$framework" =~ ^[a-z0-9-]+$ ]]; then
   exit 1
 fi
 
+if ! framework_supported "$framework"; then
+  echo "[aport] ERROR: Unknown or unsupported framework: $framework" >&2
+  echo "  Supported: ${SUPPORTED_FRAMEWORKS[*]}" >&2
+  exit 1
+fi
+
+echo "[aport] Selected framework: $framework" >&2
+
+if [[ -n "$integration_mode" ]]; then
+  case "$integration_mode" in
+    compat|native) ;;
+    *)
+      echo "[aport] ERROR: Unsupported integration mode: $integration_mode (expected compat or native)" >&2
+      exit 1
+      ;;
+  esac
+  if [[ "$framework" != "crewai" ]]; then
+    echo "[aport] ERROR: --integration-mode is only supported for CrewAI" >&2
+    exit 1
+  fi
+  REST+=("--integration-mode=$integration_mode")
+fi
+
 script="$FRAMEWORKS_DIR/${framework}.sh"
 
 # n8n: custom node not yet available; warn before running wizard-only script
@@ -160,7 +204,3 @@ if [[ -x "$generic_script" ]]; then
   export APORT_FRAMEWORK="$framework"
   exec "$generic_script" ${REST+"${REST[@]}"}
 fi
-
-echo "[aport] ERROR: Unknown or unsupported framework: $framework" >&2
-echo "  Supported: openclaw, langchain, crewai, cursor, claude-code, deerflow, n8n" >&2
-exit 1

package/bin/aport-create-passport.sh

@@ -15,7 +15,7 @@
 set -e
 
 PASSPORT_FILE=""
-NON_INTERACTIVE=""
+NON_INTERACTIVE="${APORT_NONINTERACTIVE:-${CI:-}}"
 # Parse --output, --non-interactive, --framework=
 while [ $# -gt 0 ]; do
     case "$1" in

package/bin/aport-guardrail-api.sh

@@ -14,6 +14,8 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # Resolve paths: config_dir/aport/ (new) or config_dir (legacy); same as bash guardrail
 # shellcheck source=bin/aport-resolve-paths.sh
 . "${SCRIPT_DIR}/bin/aport-resolve-paths.sh"
+# shellcheck source=bin/lib/tool-mapping.sh
+. "${SCRIPT_DIR}/bin/lib/tool-mapping.sh"
 
 NODE_EVALUATOR="$SCRIPT_DIR/src/evaluator.js"
 
@@ -48,41 +50,12 @@ if [ -z "$APORT_AGENT_ID" ] && [ ! -f "$PASSPORT_FILE" ]; then
     exit 1
 fi
 
-# Map tool to policy pack ID
-POLICY_ID=""
-case "$TOOL_NAME" in
-    git.create_pr | git.merge | git.push | git.*)
-        POLICY_ID="code.repository.merge.v1"
-        ;;
-    exec.run | exec.* | system.command.* | system.*)
-        POLICY_ID="system.command.execute.v1"
-        ;;
-    message.send | message.* | messaging.*)
-        POLICY_ID="messaging.message.send.v1"
-        ;;
-    mcp.tool.* | mcp.*)
-        POLICY_ID="mcp.tool.execute.v1"
-        ;;
-    agent.session.* | session.create | session.*)
-        POLICY_ID="agent.session.create.v1"
-        ;;
-    agent.tool.* | tool.register | tool.*)
-        POLICY_ID="agent.tool.register.v1"
-        ;;
-    payment.refund | payment.* | finance.payment.refund)
-        POLICY_ID="finance.payment.refund.v1"
-        ;;
-    payment.charge | finance.payment.charge)
-        POLICY_ID="finance.payment.charge.v1"
-        ;;
-    database.write | database.* | data.export)
-        POLICY_ID="data.export.create.v1"
-        ;;
-    *)
-        echo "Error: Tool '$TOOL_NAME' is not mapped to a policy pack" >&2
-        exit 1
-        ;;
-esac
+# Map tool to policy pack ID from the shared JSON source of truth.
+POLICY_ID="$(resolve_policy_id_from_tool_name "$TOOL_NAME" || true)"
+if [[ -z "$POLICY_ID" ]]; then
+    echo "Error: Tool '$TOOL_NAME' is not mapped to a policy pack" >&2
+    exit 1
+fi
 
 # Call Node.js evaluator with API
 if [ -n "$DEBUG_APORT" ]; then

package/bin/aport-guardrail-bash.sh

@@ -13,6 +13,8 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # Source validation library for input sanitization
 # shellcheck source=bin/lib/validation.sh
 . "${SCRIPT_DIR}/bin/lib/validation.sh"
+# shellcheck source=bin/lib/tool-mapping.sh
+. "${SCRIPT_DIR}/bin/lib/tool-mapping.sh"
 
 # Get script directory to find submodules (external/ per GIT_SUBMODULES_EXPLAINED.md)
 POLICIES_DIR="$SCRIPT_DIR/external/aport-policies"
@@ -94,11 +96,14 @@ write_decision() {
     local deny_message="${4:-Policy evaluation failed}"
 
     local decision_id=$(uuidgen 2> /dev/null || echo "local-$(date +%s)")
-    local passport_id=$(jq -r '.passport_id // "unknown"' "$PASSPORT_FILE")
+    local passport_id=$(jq -r '.passport_id // .agent_id // "unknown"' "$PASSPORT_FILE")
+    local agent_id=$(jq -r '.agent_id // .passport_id // "unknown"' "$PASSPORT_FILE")
     local owner_id=$(jq -r '.owner_id // "unknown"' "$PASSPORT_FILE")
     local assurance_level=$(jq -r '.assurance_level // "L0"' "$PASSPORT_FILE")
     local passport_digest=$(compute_passport_digest "$PASSPORT_FILE")
     local issued_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    local created_at="$issued_at"
+    local expires_in=3600
     local expires_at=$(date -u -v+1H +%Y-%m-%dT%H:%M:%SZ 2> /dev/null || date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)
 
     # Build reasons array per OAP v1.0 spec
@@ -126,12 +131,15 @@ write_decision() {
         --arg decision_id "$decision_id" \
         --arg policy_id "$policy_id" \
         --arg passport_id "$passport_id" \
+        --arg agent_id "$agent_id" \
         --arg owner_id "$owner_id" \
         --arg assurance_level "$assurance_level" \
         --argjson allow "$allow" \
         --argjson reasons "$reasons" \
         --arg issued_at "$issued_at" \
+        --arg created_at "$created_at" \
         --arg expires_at "$expires_at" \
+        --argjson expires_in "$expires_in" \
         --arg passport_digest "$passport_digest" \
         --arg prev_decision_id "$prev_decision_id" \
         --arg prev_content_hash "$prev_content_hash" \
@@ -139,12 +147,15 @@ write_decision() {
             decision_id: $decision_id,
             policy_id: $policy_id,
             passport_id: $passport_id,
+            agent_id: $agent_id,
             owner_id: $owner_id,
             assurance_level: $assurance_level,
             allow: $allow,
             reasons: $reasons,
             issued_at: $issued_at,
+            created_at: $created_at,
             expires_at: $expires_at,
+            expires_in: $expires_in,
             passport_digest: $passport_digest,
             signature: "local-unsigned",
             kid: "oap:local:dev-key",
@@ -216,58 +227,12 @@ if [ "$SPEC_VERSION" != "oap/1.0" ]; then
     write_decision false "unknown" "oap.passport_version_mismatch" "Passport spec version is '$SPEC_VERSION', expected 'oap/1.0'"
 fi
 
-# Map tool to policy pack ID
-POLICY_ID=""
-case "$TOOL_NAME" in
-    git.create_pr | git.merge | git.push | git.*)
-        POLICY_ID="code.repository.merge.v1"
-        ;;
-    exec | exec.run | exec.* | system.* | bash | shell | command)
-        POLICY_ID="system.command.execute.v1"
-        ;;
-    gateway | gateway.* | process | process.*)
-        # High risk operations - treat as command execution
-        POLICY_ID="system.command.execute.v1"
-        ;;
-    message.send | message.* | messaging.* | sms | whatsapp | slack | email)
-        POLICY_ID="messaging.message.send.v1"
-        ;;
-    read | file.read | file.read.* | data.file.read | data.file.read.*)
-        POLICY_ID="data.file.read.v1"
-        ;;
-    write | edit | file.write | file.write.* | file.edit | file.edit.* | data.file.write | data.file.write.*)
-        POLICY_ID="data.file.write.v1"
-        ;;
-    web_fetch | webfetch | web.fetch | web.fetch.* | web_search | websearch | web.search | web.search.*)
-        POLICY_ID="web.fetch.v1"
-        ;;
-    browser | browser.* | web.browser | web.browser.*)
-        POLICY_ID="web.browser.v1"
-        ;;
-    mcp.*)
-        POLICY_ID="mcp.tool.execute.v1"
-        ;;
-    agent.session.* | session.create | session.* | sessions.* | sessions_spawn | sessions_send)
-        POLICY_ID="agent.session.create.v1"
-        ;;
-    cron | cron.*)
-        # Scheduled tasks - treat as session management
-        POLICY_ID="agent.session.create.v1"
-        ;;
-    agent.tool.* | tool.register)
-        POLICY_ID="agent.tool.register.v1"
-        ;;
-    payment.refund | refund | payment.charge | charge | payment.* | finance.*)
-        POLICY_ID="finance.payment.refund.v1"
-        ;;
-    database.write | database.insert | database.update | database.delete | data.export | data.export.*)
-        POLICY_ID="data.export.create.v1"
-        ;;
-    *)
-        # Unknown tool - deny by default for security
-        write_decision false "unknown" "oap.unknown_capability" "Tool '$TOOL_NAME' is not mapped to a policy pack"
-        ;;
-esac
+# Map tool to policy pack ID from the shared JSON source of truth.
+POLICY_ID="$(resolve_policy_id_from_tool_name "$TOOL_NAME" || true)"
+if [[ -z "$POLICY_ID" ]]; then
+    # Unknown tool - deny by default for security.
+    write_decision false "unknown" "oap.unknown_capability" "Tool '$TOOL_NAME' is not mapped to a policy pack"
+fi
 
 # Capability-specific context summary for audit log (command, recipient, repo/branch, file_path, etc.)
 CONTEXT_SUMMARY=""

package/bin/aport-resolve-paths.sh

@@ -56,8 +56,8 @@ resolve_aport_paths() {
     # 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
+        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
             fi
         fi

package/bin/frameworks/generic.sh

@@ -13,23 +13,79 @@ FRAMEWORKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
 source "$LIB/common.sh"
 # shellcheck source=../lib/passport.sh
 source "$LIB/passport.sh"
+# shellcheck source=../lib/runtime.sh
+source "$LIB/runtime.sh"
 # shellcheck source=../lib/config.sh
 source "$LIB/config.sh"
 
 framework="${APORT_FRAMEWORK:?APORT_FRAMEWORK must be set by the dispatcher}"
+crewai_integration_mode="${APORT_CREWAI_INTEGRATION_MODE:-compat}"
+
+FORWARD_ARGS=()
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --integration-mode=*)
+            crewai_integration_mode="${1#--integration-mode=}"
+            ;;
+        --integration-mode)
+            if [[ $# -lt 2 ]]; then
+                log_error "--integration-mode requires compat or native"
+                exit 1
+            fi
+            crewai_integration_mode="$2"
+            shift
+            ;;
+        *)
+            FORWARD_ARGS+=("$1")
+            ;;
+    esac
+    shift
+done
+
+case "$crewai_integration_mode" in
+    compat | native) ;;
+    *)
+        log_error "Unsupported CrewAI integration mode: $crewai_integration_mode"
+        exit 1
+        ;;
+esac
+
+if [[ "$framework" != "crewai" && "$crewai_integration_mode" != "compat" ]]; then
+    log_error "--integration-mode is only supported for CrewAI"
+    exit 1
+fi
+
+resolve_next_steps_file() {
+    if [[ "$framework" == "crewai" ]]; then
+        if [[ "$crewai_integration_mode" == "native" ]]; then
+            echo "$FRAMEWORKS_DIR/next-steps.d/crewai-native.txt"
+            return
+        fi
+    fi
+    echo "$FRAMEWORKS_DIR/next-steps.d/$framework.txt"
+}
 
 run_setup() {
     log_info "Setting up APort guardrails for $framework..."
     config_dir="$(write_config_template "$framework")"
     mkdir -p "$config_dir/aport"
     chmod 700 "$config_dir/aport"
+    install_runtime_tree "$config_dir"
     export APORT_FRAMEWORK="$framework"
-    run_passport_wizard "$@"
+    if [[ "$framework" == "crewai" ]]; then
+        log_info "CrewAI integration mode: $crewai_integration_mode"
+    fi
+    if ((${#FORWARD_ARGS[@]} > 0)); then
+        run_passport_wizard "${FORWARD_ARGS[@]}"
+    else
+        run_passport_wizard
+    fi
     # Harden permissions on passport (contains policy/capabilities)
     [ -f "$config_dir/aport/passport.json" ] && chmod 600 "$config_dir/aport/passport.json"
+    log_info "Local runtime installed at: $config_dir/aport/runtime"
 
     # Print framework-specific next steps from data file
-    next_steps="$FRAMEWORKS_DIR/next-steps.d/$framework.txt"
+    next_steps="$(resolve_next_steps_file)"
     if [ -f "$next_steps" ]; then
         echo ""
         # Substitute $config_dir in the template
@@ -57,4 +113,4 @@ run_setup() {
     fi
 }
 
-run_setup "$@"
+run_setup

package/bin/frameworks/next-steps.d/crewai-native.txt

@@ -0,0 +1,21 @@
+  Next steps (CrewAI native provider mode):
+  ───────────────────────────────────────
+  Requires a CrewAI build with native guardrail provider support.
+
+  1. Install the Python runtime package:
+     uv add aport-agent-guardrails
+  2. Config written to: $config_dir
+  3. Enable the native provider before running your crew:
+
+     from crewai.hooks import enable_guardrail
+     from aport_guardrails.providers import OAPGuardrailProvider
+     enable_guardrail(
+         OAPGuardrailProvider(framework="crewai", config_path="$config_dir/config.yaml"),
+         fail_closed=True,
+     )
+     crew.kickoff()
+
+  Released CrewAI compatibility mode:
+     rerun without --integration-mode=native
+
+  See: docs/frameworks/crewai.md

package/bin/frameworks/next-steps.d/crewai.txt

@@ -1,6 +1,8 @@
   Next steps (CrewAI):
   ───────────────────
-  1. Install the Python adapter (required for runtime enforcement):
+  Default mode targets released CrewAI without native guardrail provider support.
+
+  1. Install the CrewAI adapter package:
      pip install aport-agent-guardrails-crewai
      aport-crewai setup
   2. Config written to: $config_dir
@@ -10,4 +12,7 @@
      register_aport_guardrail()
      crew.kickoff()
 
-  Or: @with_aport_guardrail on your entry point. See: docs/frameworks/crewai.md
+  Optional native mode:
+     rerun with --integration-mode=native
+
+  See: docs/frameworks/crewai.md

package/bin/lib/error.sh

@@ -182,13 +182,13 @@ get_resolution() {
             echo "Reduce context data size by removing unnecessary fields or summarizing large data. Default limit: 100KB."
             ;;
         "$ERROR_PATH_NOT_ALLOWED")
-            echo "Use standard APort directories: ~/.openclaw/, ~/.aport/, or /tmp/aport-*. Contact administrator to add custom allowed directories."
+            echo "Use standard framework config directories such as ~/.openclaw/, ~/.aport/, ~/.cursor/, ~/.claude/, ~/.n8n/, or /tmp/aport-*. Contact administrator to add custom allowed directories."
             ;;
         "$ERROR_PATH_TRAVERSAL")
             echo "Use absolute paths without parent directory references (../ or /..). This is a security feature to prevent path traversal attacks."
             ;;
         "$ERROR_PASSPORT_NOT_FOUND")
-            echo "Create a passport by running: npx @aporthq/aport-agent-guardrails openclaw. See: https://github.com/aporthq/agent-guardrails#passport-setup"
+            echo "Create a passport by running: npx @aporthq/aport-agent-guardrails <framework>. See: https://github.com/aporthq/aport-agent-guardrails/tree/main/docs/frameworks"
             ;;
         "$ERROR_PASSPORT_MISSING_CAP")
             echo "Request capability be added to passport or generate new passport with required capabilities."
@@ -206,7 +206,7 @@ get_resolution() {
             echo "Wait for rate limit to reset, reduce request frequency, or use local evaluation mode instead of API mode."
             ;;
         "$ERROR_MISCONFIGURED")
-            echo "Run setup: npx @aporthq/aport-agent-guardrails <framework>. Check passport exists at ~/.openclaw/passport.json"
+            echo "Run setup: npx @aporthq/aport-agent-guardrails <framework>. Check your framework config directory for aport/passport.json and aport/runtime/bin/aport-guardrail.sh."
             ;;
         *)
             echo ""

package/bin/lib/runtime-manifest.txt

@@ -0,0 +1,17 @@
+file bin/aport-create-passport.sh
+file bin/aport-guardrail.sh
+file bin/aport-guardrail-bash.sh
+file bin/aport-guardrail-api.sh
+file bin/aport-guardrail-v2.sh
+file bin/aport-resolve-paths.sh
+file bin/aport-status.sh
+file bin/lib/common.sh
+file bin/lib/config.sh
+file bin/lib/passport.sh
+file bin/lib/tool-mapping.sh
+file bin/lib/validation.sh
+file python/aport_guardrails/core/tool-pack-mapping.json
+file src/evaluator.js
+tree external/aport-policies
+file external/aport-spec/oap/passport-schema.json
+mkdir local-overrides/policies

package/bin/lib/runtime.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Runtime asset installation for local APort evaluation.
+# Installs a self-contained shell runtime under <config_dir>/aport/runtime
+# from the repo/npm package sources in bin/, external/, and src/.
+
+set -euo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+MANIFEST_FILE="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)/runtime-manifest.txt"
+
+_runtime_copy_file() {
+    local runtime_dir="$1"
+    local rel_path="$2"
+    local src="$ROOT_DIR/$rel_path"
+    local dest="$runtime_dir/$rel_path"
+
+    if [[ ! -f "$src" ]]; then
+        log_error "Runtime source missing: $src"
+        exit 1
+    fi
+
+    mkdir -p "$(dirname "$dest")"
+    cp "$src" "$dest"
+    chmod +x "$dest" 2> /dev/null || true
+}
+
+_runtime_copy_tree() {
+    local runtime_dir="$1"
+    local rel_path="$2"
+    local src="$ROOT_DIR/$rel_path"
+    local dest="$runtime_dir/$rel_path"
+
+    if [[ ! -d "$src" ]]; then
+        log_error "Runtime source directory missing: $src"
+        exit 1
+    fi
+
+    rm -rf "$dest"
+    mkdir -p "$(dirname "$dest")"
+    cp -R "$src" "$dest"
+}
+
+install_runtime_tree() {
+    local config_dir="$1"
+    local runtime_dir="$config_dir/aport/runtime"
+    local kind=""
+    local rel_path=""
+
+    mkdir -p "$runtime_dir"
+
+    if [[ ! -f "$MANIFEST_FILE" ]]; then
+        log_error "Runtime manifest missing: $MANIFEST_FILE"
+        exit 1
+    fi
+
+    while read -r kind rel_path; do
+        [[ -z "$kind" ]] && continue
+        [[ "$kind" == \#* ]] && continue
+        case "$kind" in
+            file)
+                _runtime_copy_file "$runtime_dir" "$rel_path"
+                ;;
+            tree)
+                _runtime_copy_tree "$runtime_dir" "$rel_path"
+                ;;
+            mkdir)
+                mkdir -p "$runtime_dir/$rel_path"
+                ;;
+            *)
+                log_error "Unsupported runtime manifest entry: $kind $rel_path"
+                exit 1
+                ;;
+        esac
+    done < "$MANIFEST_FILE"
+
+    chmod -R u+rwX "$runtime_dir" 2> /dev/null || true
+}
+
+export -f install_runtime_tree

package/bin/lib/tool-mapping.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+_aport_tool_mapping_file() {
+    local lib_dir
+    lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
+
+    local candidates=(
+        "$lib_dir/../../python/aport_guardrails/core/tool-pack-mapping.json"
+        "$lib_dir/../python/aport_guardrails/core/tool-pack-mapping.json"
+        "$lib_dir/../../aport/runtime/python/aport_guardrails/core/tool-pack-mapping.json"
+    )
+
+    local candidate=""
+    for candidate in "${candidates[@]}"; do
+        if [[ -f "$candidate" ]]; then
+            printf '%s\n' "$candidate"
+            return 0
+        fi
+    done
+    return 1
+}
+
+resolve_policy_id_from_tool_name() {
+    local tool_name="${1:-}"
+    local mapping_file=""
+    local normalized=""
+    local policy_id=""
+
+    normalized="$(printf '%s' "$tool_name" | tr '[:upper:]' '[:lower:]')"
+    mapping_file="$(_aport_tool_mapping_file)" || return 1
+
+    policy_id="$(
+        jq -r --arg tool "$normalized" '
+            first(
+              .rules[]?
+              | select(
+                  (.prefixes // [] | any(. as $prefix | $tool | startswith($prefix)))
+                  or
+                  (.substrings // [] | any(. as $substring | $tool | contains($substring)))
+                )
+              | .pack
+            ) // empty
+        ' "$mapping_file"
+    )"
+
+    if [[ -n "$policy_id" && "$policy_id" != "null" ]]; then
+        printf '%s\n' "$policy_id"
+        return 0
+    fi
+
+    return 1
+}

package/bin/lib/validation.sh

@@ -58,9 +58,9 @@ validate_tool_name() {
     return 0
 }
 
-# Validate passport path is within allowed directories
-# Returns 0 if safe, 1 if potentially dangerous
-validate_passport_path() {
+# Validate explicit operator-provided passport paths.
+# Returns 0 if the path is hygienic, 1 if it contains dangerous constructs.
+validate_explicit_passport_path() {
     local path="$1"
 
     # Check for empty
@@ -68,11 +68,28 @@ validate_passport_path() {
         return 1
     fi
 
+    # Check for path traversal attempts
+    if echo "$path" | grep -qE '\.\./|/\.\./|/\.\.$'; then
+        return 1
+    fi
+
+    return 0
+}
+
+# Validate auto-discovered/default passport paths against trusted framework dirs.
+# Returns 0 if safe, 1 if potentially dangerous.
+validate_passport_path() {
+    local path="$1"
+
+    if ! validate_explicit_passport_path "$path"; then
+        return 1
+    fi
+
     # Expand to absolute path
     local abs_path
     abs_path=$(readlink -f "$path" 2> /dev/null || realpath "$path" 2> /dev/null || echo "$path")
 
-    # Allowed base directories for passport storage
+    # Allowed base directories for auto-discovery
     local allowed_bases=(
         "$HOME/.openclaw"
         "$HOME/.aport"
@@ -82,7 +99,6 @@ validate_passport_path() {
         "/tmp/aport-"
     )
 
-    # Check if path starts with any allowed base
     local is_allowed=false
     for base in "${allowed_bases[@]}"; do
         case "$abs_path" in
@@ -90,6 +106,10 @@ validate_passport_path() {
                 is_allowed=true
                 break
                 ;;
+            "/private$base"*)
+                is_allowed=true
+                break
+                ;;
         esac
     done
 
@@ -97,16 +117,6 @@ validate_passport_path() {
         return 1
     fi
 
-    # Check for path traversal attempts
-    if echo "$path" | grep -qE '\.\./|/\.\./|/\.\.$'; then
-        return 1
-    fi
-
-    # Check for null bytes
-    if echo "$path" | grep -qF $'\0'; then
-        return 1
-    fi
-
     return 0
 }
 

package/docs/FRAMEWORK_ROADMAP.md

@@ -9,7 +9,7 @@ Public developer view of supported frameworks and roadmap. Details per framework
 | **OpenClaw** | Shipped | Full: plugin, wizard, local/API | [openclaw.md](frameworks/openclaw.md) | `npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor**   | Shipped | Full: hooks installer + script | [cursor.md](frameworks/cursor.md) | `npx @aporthq/aport-agent-guardrails cursor` |
 | **LangChain / LangGraph** | Shipped | **Python only:** callback, `aport-langchain setup` | [langchain.md](frameworks/langchain.md) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |
-| **CrewAI**   | Shipped | **Python only:** hook, decorator, `aport-crewai setup` | [crewai.md](frameworks/crewai.md) | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
+| **CrewAI**   | Shipped | **Python:** released hook adapter by default; native provider mode when available | [crewai.md](frameworks/crewai.md) | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
 
 **Coming soon:** n8n — custom node and runtime in progress ([n8n.md](frameworks/n8n.md)). Not listed in CLI options until shipped.
 

package/docs/PROVIDER.md

@@ -26,7 +26,7 @@ result = provider.evaluate(request)   # sync
 result = await provider.aevaluate(request)  # async
 ```
 
-**Supported frameworks:** DeerFlow, any Python framework with a `GuardrailProvider` protocol.
+**Supported frameworks:** DeerFlow, CrewAI builds with native provider support, and any Python framework with a `GuardrailProvider` protocol.
 
 **Config:** `~/.aport/<framework>/config.yaml` (created by `aport setup --framework <name>`)
 

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.18 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.21 (see [CHANGELOG.md](../CHANGELOG.md)).
 
 We keep **one version number** across all published packages (Node core, Python core, and every framework adapter). That avoids “core is 1.2 but CLI is 0.9” and keeps the story simple for users and support.
 
@@ -32,7 +32,7 @@ So: **root = CLI/setup**; **core = library**. We publish core so that (1) the ad
 ## 2. Tooling
 
 - **Changesets** (Node): fixed mode so all workspace packages are in one “fixed” group and get the same version on release.
-- **sync-version script**: after `changeset version`, copies the new version from root `package.json` into all Python `pyproject.toml` and `aport_guardrails/__init__.py`.
+- **sync-version script**: after `changeset version`, reads the canonical version from the fixed workspace group and propagates it to the root CLI package, Python packages, manifests, lockfiles, and release docs.
 
 ---
 
@@ -43,7 +43,7 @@ So: **root = CLI/setup**; **core = library**. We publish core so that (1) the ad
    ```bash
    npm run version
    ```  
-   This runs `changeset version` (updates all Node `package.json` and CHANGELOGs) then `node scripts/sync-version.mjs` (updates Python packages to the same version).
+   This runs `changeset version` for the fixed workspace group, then `node scripts/sync-version.mjs` to align the root CLI package, Python packages, lockfiles, manifests, and release docs to that same version.
 3. **Commit** the version bump and changelog updates (e.g. “chore(release): 1.3.0”).
 4. **Tag and push** — this triggers the release workflow and publishes both npm and PyPI:
    ```bash

package/docs/development/ERROR_CODES.md

@@ -516,10 +516,10 @@ sudo yum install jq
 **Resolution**:
 ```bash
 # Check passport exists
-ls -la ~/.openclaw/passport.json
+ls -la ~/.openclaw/aport/passport.json
 
-# Check guardrail script exists
-ls -la ~/.openclaw/.skills/aport-guardrail.sh
+# Check local runtime exists
+ls -la ~/.openclaw/aport/runtime/bin/aport-guardrail.sh
 
 # Run setup if missing
 npx @aporthq/aport-agent-guardrails openclaw

package/docs/frameworks/crewai.md

@@ -1,51 +1,55 @@
-# APort Agent Guardrail — CrewAI
+# APort Agent Guardrails — CrewAI
 
-CrewAI supports **tool call hooks** that run before (and after) every tool execution. The **APort Agent Guardrail for CrewAI** plugs into the **before tool call** hook: we verify the tool and parameters against your passport and policy; if the decision is deny, we return `False` and CrewAI blocks execution. This matches CrewAI’s [Tool Call Hooks](https://docs.crewai.com/en/learn/tool-hooks) model.
+APort supports CrewAI in two ways:
 
-## How CrewAI agent guardrails work
+1. **Released CrewAI compatibility mode** via the existing `before_tool_call` adapter
+2. **Native provider mode** for CrewAI builds that expose a native guardrail provider seam
 
-- **Hooks:** CrewAI runs **before_tool_call** hooks before every tool execution. The hook receives a `ToolCallHookContext` (tool name, tool input, agent, task, crew). Returning `False` blocks execution; `True` or `None` allows it.
-- **Registration:** You can register a hook **globally** with `register_before_tool_call_hook()`, or use the `@before_tool_call` decorator, or use **crew-scoped** `@before_tool_call_crew` on a `@CrewBase` class.
-- **Multi-task crews:** The same hook runs for every tool call across all tasks and agents, so multi-task crews are supported by default.
+The default bootstrap path targets released CrewAI so it works today without waiting
+for upstream provider support.
 
-Our adapter provides a function that fits this API: it calls the APort evaluator (sync) and returns `False` on deny, `None` on allow. You register it once before running your crew.
+## Option 1: Released CrewAI Compatibility Mode
 
-- **Integration:** CrewAI `before_tool_call` hook (global or crew-scoped)
-- **Config:** `~/.aport/crewai/config.yaml` or `.aport/config.yaml` (see [Verification methods](../VERIFICATION_METHODS.md))
+This is the default mode.
 
-## Two ways to use APort
+Bootstrap config, passport, and local runtime with the Python-native CLI:
 
-| Use case | What it is | When to use it |
-|----------|------------|----------------|
-| **Guardrails (CLI/setup)** | One-line installer: runs the **passport wizard**, writes config, prints next steps. Does not run your app. | Getting started: create passport and config so the library can find them. |
-| **Core (library)** | The **evaluator** and **before-tool-call hook** in your code. Calls policy + passport to allow/deny each tool call. | Integrating into your app: register the hook so CrewAI blocks tool runs when policy denies. |
-
-You typically use **both**: run the CLI once to create passport and config, then use the library in your CrewAI app so every tool call is verified.
+```bash
+uvx --from aport-agent-guardrails aport setup --framework=crewai
+```
 
----
+Or use the Node bootstrap if you prefer:
 
-## Setup (Guardrails — create passport and config)
+```bash
+npx -y @aporthq/aport-agent-guardrails crewai
+```
 
-**Python**
+For CI or other non-interactive environments with the Python-native CLI:
 
 ```bash
-npx @aporthq/aport-agent-guardrails crewai   # wizard + config (optional)
-pip install aport-agent-guardrails-crewai
-aport-crewai setup
+APORT_CREWAI_CONFIG_DIR=.aport/crewai \
+uvx --from aport-agent-guardrails aport setup \
+  --framework=crewai \
+  --ci
 ```
 
-**Node**
+The equivalent Node bootstrap is:
 
 ```bash
-npx @aporthq/aport-agent-guardrails crewai   # wizard + config
-npm install @aporthq/aport-agent-guardrails-crewai   # beforeToolCall, withAPortGuardrail (depends on -core)
+APORT_CREWAI_CONFIG_DIR=.aport/crewai \
+npx -y @aporthq/aport-agent-guardrails crewai \
+  --output .aport/crewai/aport/passport.json \
+  --non-interactive
 ```
 
-`aport-crewai setup` (Python) writes config to `~/.aport/crewai/`, runs the passport wizard (or use `--ci` / `--no-wizard` for non-interactive), and prints next steps.
+Install the released CrewAI adapter:
 
-## Using the library (Core) in your app
+```bash
+pip install aport-agent-guardrails-crewai
+aport-crewai setup
+```
 
-**Python — Option 1: Register the hook before kickoff**
+Register the hook before your crew runs:
 
 ```python
 from aport_guardrails_crewai import register_aport_guardrail
@@ -54,66 +58,96 @@ register_aport_guardrail()
 crew.kickoff()
 ```
 
-**Python — Option 2: Decorator on your entry point**
+This path works with released CrewAI because it plugs directly into CrewAI's existing
+`before_tool_call` hook behavior.
 
-```python
-from aport_guardrails_crewai import with_aport_guardrail
+## Option 2: Native Provider Mode
 
-@with_aport_guardrail
-def main():
-    crew.kickoff()
+Use this only with a CrewAI build that exposes the native guardrail provider API.
 
-main()
+Bootstrap with native-mode instructions using the Python-native CLI:
+
+```bash
+uvx --from aport-agent-guardrails aport setup \
+  --framework=crewai \
+  --integration-mode=native
 ```
 
-**Python — Option 3: Use the hook with `@before_tool_call`**
+The equivalent Node bootstrap is:
 
-```python
-from crewai.hooks import before_tool_call
-from aport_guardrails_crewai import aport_guardrail_before_tool_call
+```bash
+npx -y @aporthq/aport-agent-guardrails crewai --integration-mode=native
+```
 
-@before_tool_call
-def my_guardrail(context):
-    return aport_guardrail_before_tool_call(context)
+Install the Python runtime package:
+
+```bash
+uv add aport-agent-guardrails
 ```
 
-**Node:** Call `beforeToolCall` in your flow before each tool run (CrewAI Node SDK does not expose a global hook). Return `false` to block, `null` to allow. Or wrap your entry point with `withAPortGuardrail(fn)`.
+Enable the provider before your crew runs:
 
-```ts
-import { beforeToolCall, withAPortGuardrail } from '@aporthq/aport-agent-guardrails-crewai';
+```python
+from crewai.hooks import enable_guardrail
+from aport_guardrails.providers import OAPGuardrailProvider
 
-// In your tool-call flow, before executing a tool:
-const result = beforeToolCall({ tool_name: 'run_command', tool_input: { command: 'ls' } });
-if (result === false) {
-  // Block this tool call
-  return;
-}
+enable_guardrail(
+    OAPGuardrailProvider(
+        framework="crewai",
+        config_path="~/.aport/crewai/config.yaml",
+    ),
+    fail_closed=True,
+)
 
-// Or wrap your crew kickoff so guardrail is in scope:
-withAPortGuardrail(() => {
-  crew.kickoff();
-});
+crew.kickoff()
 ```
 
-### How tool parameters are handled
+If you bootstrap into a project-local config directory, point `config_path` at that
+file instead.
+
+## What The Bootstrap Installs
 
-The Node middleware automatically spreads object tool inputs into the verification context. For example, `{ tool_input: { file_path: "/tmp/data.txt" } }` will pass `file_path` at the top level of the context, ensuring policies like `data.file.read.v1` receive required fields for validation.
+Both modes write:
 
-## Config
+- `~/.aport/crewai/config.yaml`
+- `~/.aport/crewai/aport/passport.json`
+- `~/.aport/crewai/aport/runtime/...`
 
-- **Config path:** `~/.aport/crewai/config.yaml`, or `.aport/config.yaml` in the project root.
-- **Mode:** `api` (default for production) or `local` (bash evaluator, no network). Same options as [LangChain](langchain.md) and OpenClaw.
-- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
+The compatibility and native modes share the same APort config and local runtime.
+Only the CrewAI integration layer changes.
 
-## Suspend (kill switch)
+## How APort Fits
 
-Same as all frameworks: **passport is the source of truth**. Local: set passport `status` to `suspended` (or `active` to resume). API: suspend the passport in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+- **Compatibility mode:** APort adapts to CrewAI's existing hook surface.
+- **Native mode:** CrewAI defines the seam, and APort plugs in as an external
+  `OAPGuardrailProvider`.
 
-## Example and tests
+That keeps CrewAI vendor-neutral while letting Open Agent Passport remain the
+portable policy/passport format across frameworks.
 
-- **Example:** [examples/crewai/run_with_guardrail.py](../../examples/crewai/run_with_guardrail.py) — temp config, ALLOW then DENY, `register_aport_guardrail()`.
-- **Unit tests:** [python/crewai_adapter/tests/test_hook.py](../../python/crewai_adapter/tests/test_hook.py) — hook return value and context with mocked evaluator.
+## Configuration
 
-## Status
+The provider and adapter read the standard APort config:
+
+- `mode: local` for the local shell evaluator
+- `mode: api` for hosted evaluation
+- `agent_id` for hosted passports
+- `passport_path` for explicit local passport paths
+- `guardrail_script` to override the local evaluator script path
+- `audit_log` to enable or disable audit logging
+
+With the default bootstrap, you usually do not need to set `guardrail_script`
+manually because the local runtime is installed under the framework config
+directory.
+
+## Validation
+
+After bootstrap, you can smoke-test the local evaluator directly:
+
+```bash
+~/.aport/crewai/aport/runtime/bin/aport-guardrail.sh \
+  system.command.execute \
+  '{"command":"git status"}'
+```
 
-Implemented (Story D). **APort Agent Guardrail for CrewAI.** Package: `aport-agent-guardrails-crewai`; CLI: `aport-crewai setup`; hook: `aport_guardrail_before_tool_call` / `register_aport_guardrail` / `with_aport_guardrail`.
+Exit code `0` means allow. Exit code `1` means deny.

package/docs/frameworks/deerflow.md

@@ -107,7 +107,7 @@ guardrails:
 | `bash`, `write_file`, `str_replace` | `system.command.execute.v1` |
 | `web_search`, `web_fetch`, `image_search` | `web.fetch.v1` |
 | `read_file`, `ls` | `data.file.read.v1` |
-| `present_file`, `view_image` | `data.export.create.v1` |
+| `present_file`, `view_image` | `data.file.read.v1` |
 | `ask_clarification`, `task` | `agent.session.create.v1` |
 | MCP tools (dynamic) | `mcp.tool.execute.v1` |
 

package/extensions/openclaw-aport/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog - APort OpenClaw Plugin
 
+## 1.0.21
+
 All notable changes to the APort OpenClaw plugin will be documented in this file.
 
-## [1.1.0] - 2026-02-19
+## [1.0.21] - 2026-02-19
 
 ### Changed - OpenClaw 2026.2 Compatibility
 
@@ -24,6 +26,7 @@ All notable changes to the APort OpenClaw plugin will be documented in this file
 ### Technical Details
 
 **Old Architecture (< 2026.2):**
+
 ```javascript
 export default function (api) {
   api.on("before_tool_call", async (event, ctx) => { ... });
@@ -31,6 +34,7 @@ export default function (api) {
 ```
 
 **New Architecture (>= 2026.2):**
+
 ```typescript
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 

package/extensions/openclaw-aport/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-aport",
   "name": "APort Guardrails",
   "description": "Deterministic pre-action authorization via APort policy enforcement. Registers before_tool_call to block disallowed tools.",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/extensions/openclaw-aport/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.10",
+  "version": "1.0.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@aporthq/openclaw-aport",
-      "version": "1.0.10",
+      "version": "1.0.21",
       "license": "Apache-2.0",
       "devDependencies": {
         "@types/node": "^18.0.0",

package/extensions/openclaw-aport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "OpenClaw plugin for deterministic pre-action authorization via APort guardrails",
   "main": "index.js",
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",
@@ -20,8 +20,9 @@
     "sync-submodules": "git submodule update --init --recursive",
     "sync-submodules:latest": "git submodule update --init --remote --recursive",
     "changeset": "changeset",
-    "version": "changeset version && node scripts/sync-version.mjs",
+    "version": "CI=1 changeset version && node scripts/sync-version.mjs",
     "sync-version": "node scripts/sync-version.mjs",
+    "prepush:check": "bash scripts/pre-push-check.sh",
     "build": "npm run build:core && npm run build --workspaces --if-present",
     "build:core": "npm run build -w @aporthq/aport-agent-guardrails-core",
     "release:version": "npm run version",