@aporthq/aport-agent-guardrails 1.0.19 → 1.0.21

package/README.md

@@ -89,23 +89,24 @@ 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 evaluator or framework callback in your app so each tool call is verified. 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).
+**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).
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|
-| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | `before_tool_call` plugin | `npx @aporthq/aport-agent-guardrails openclaw` |
+| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | Native `GuardrailProvider` or plugin | `npm i @aporthq/aport-agent-guardrails-core && npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor** | [docs/frameworks/cursor.md](docs/frameworks/cursor.md) | `beforeShellExecution` / `preToolUse` hooks → writes `~/.cursor/hooks.json`. **Runtime enforcement is the bash hook;** the Node package `@aporthq/aport-agent-guardrails-cursor` is a helper only (Evaluator, `getHookPath()`). | `npx @aporthq/aport-agent-guardrails cursor` |
 | **Claude Code** | [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md) | PreToolUse hook → writes `~/.claude/settings.json` (Claude Code format; not Cursor). | `npx @aporthq/aport-agent-guardrails claude-code` |
 | **LangChain / LangGraph** | [docs/frameworks/langchain.md](docs/frameworks/langchain.md) | **Python:** `APortCallback` (`on_tool_start`) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |
-| **CrewAI** | [docs/frameworks/crewai.md](docs/frameworks/crewai.md) | **Python:** `@before_tool_call` hook, `register_aport_guardrail` | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
+| **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