@aporthq/aport-agent-guardrails 1.0.26 → 1.0.27

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# APort Claude Code hook: reads tool_name + tool_input from JSON stdin,
+# APort Claude Code hook: reads tool_name + tool_input from JSON stdin (path-based Read uses guardrail).
 # maps to APort policy, calls guardrail, outputs hookSpecificOutput deny or exit 0.
 # Exit 0 = allow, exit 2 = block. Other exits = hook error (Claude Code may fail-open).
 # Output format: Claude Code official schema (hookSpecificOutput.permissionDecision), NOT Cursor format.
@@ -14,6 +14,8 @@ ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
 # shellcheck source=bin/lib/guardrail-mode.sh
 . "$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}"
 
 GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
@@ -49,7 +51,8 @@ set -e
 if [ "$JQ_EXIT" -ne 0 ] || [ -z "$TOOL_NAME" ]; then
     TOOL_NAME="unknown"
 fi
-TOOL_NAME_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | tr '[:upper:]' '[:lower:]')"
+# Strip permission-rule specifiers (e.g. Agent(Explore) -> Agent) before normalization.
+TOOL_NAME_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | sed 's/(.*$//' | tr '[:upper:]' '[:lower:]')"
 set +e
 TOOL_INPUT="$(echo "$INPUT" | jq -c '.tool_input // {}' 2> /dev/null)"
 JQ_EXIT=$?
@@ -81,40 +84,45 @@ GUARDRAIL_TOOL=""
 CONTEXT_JSON="{}"
 
 case "$TOOL_NAME_NORM" in
-    bash | shell)
+    bash | shell | powershell | monitor)
         GUARDRAIL_TOOL="bash"
-        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{command: (.command // "")}')"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{command: (.command // .script // "")}')"
         ;;
-    read | glob | ls | grep | todoread | toolsearch | askuserquestion | readfile | semanticsearch)
-        # Read-family + user-interaction tools: allow without calling evaluator
+    read | readfile | semanticsearch)
+        if ! aport_hook_try_read_evaluation "$TOOL_NAME_NORM" "$TOOL_INPUT"; then
+            exit 0
+        fi
+        ;;
+    glob | ls | grep | lsp | todoread | toolsearch | askuserquestion | listmcpresourcestool | readmcpresourcetool | waitformcpservers)
+        # Search/list/read tools without a single file_path: allow without evaluator
         exit 0
         ;;
-    taskget | tasklist | taskoutput | cronlist)
-        # Read-only task/cron queries: allow without evaluator
+    taskget | tasklist | taskoutput | cronlist | schedulewakeup | pushnotification)
+        # Read-only task/cron queries and notifications: allow without evaluator
         exit 0
         ;;
     enterplanmode | exitplanmode)
         # Internal state transitions: allow without evaluator
         exit 0
         ;;
-    write | edit | multiedit | notebookedit | todowrite | delete | strreplace | editnotebook)
+    write | edit | multiedit | notebookedit | todowrite | delete | strreplace | editnotebook | shareonboardingguide)
         GUARDRAIL_TOOL="write"
         CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{file_path: (.file_path // .path // "")}')"
         ;;
     websearch | webfetch)
-        GUARDRAIL_TOOL="webfetch"
-        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // .query // "")}')"
+        GUARDRAIL_TOOL="websearch"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // ""), query: (.query // "")}')"
         ;;
     browser)
         GUARDRAIL_TOOL="browser"
         CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{url: (.url // "")}')"
         ;;
-    task | taskcreate | taskupdate | taskstop | agent | skill | enterworktree | subagent | subagentstart)
+    agent | task | taskcreate | taskupdate | taskstop | skill | enterworktree | exitworktree | subagent | subagentstart | sendmessage | teamcreate | teamdelete | remotetrigger)
         GUARDRAIL_TOOL="session.create"
-        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .prompt // "")}')"
+        CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .prompt // .task // .message // ""), subagent_type: (.subagent_type // .agent_type // "")}')"
         ;;
     croncreate | crondelete)
-        GUARDRAIL_TOOL="cron"
+        GUARDRAIL_TOOL="session.create"
         CONTEXT_JSON="$(safe_jq "$TOOL_INPUT" '{description: (.description // .schedule // "")}')"
         ;;
     mcp__* | mcp:* | callmcptool)
@@ -134,6 +142,14 @@ if [ -n "$HOOK_DECISION_FILE" ]; then
     export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
 fi
 
+# Read tools: send only file_path to the evaluator (Claude may attach large file bodies in tool_input).
+if [ "$GUARDRAIL_TOOL" = "read" ]; then
+    CONTEXT_JSON="$(printf '%s' "$CONTEXT_JSON" | jq -c '{file_path: (.file_path // .path // "")}' 2> /dev/null || echo '{"file_path":""}')"
+    if [ -z "$(printf '%s' "$CONTEXT_JSON" | jq -r '.file_path // ""' 2> /dev/null)" ]; then
+        exit 0
+    fi
+fi
+
 # Call core evaluator (guardrail expects tool name, not policy ID)
 set +e
 "$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null

package/bin/aport-cursor-hook.sh

@@ -18,6 +18,8 @@ ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 . "$ROOT_DIR/bin/aport-resolve-paths.sh"
 # shellcheck source=bin/lib/guardrail-mode.sh
 . "$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}"
 
 GUARDRAIL="$ROOT_DIR/bin/aport-guardrail-bash.sh"
@@ -82,8 +84,10 @@ HOOK_EVENT="$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2> /dev/null)"
 TOOL_NAME="$(echo "$INPUT" | jq -r '.tool_name // ""' 2> /dev/null)"
 
 if [ "$HOOK_EVENT" = "beforeReadFile" ] || { [ -z "$HOOK_EVENT" ] && [ -z "$TOOL_NAME" ] && echo "$INPUT" | jq -e '.file_path and .content' &> /dev/null; }; then
-    # beforeReadFile: file reads — allow without evaluator (same as Claude Code)
-    exit 0
+    FILE_PATH="$(echo "$INPUT" | jq -r '.file_path // ""' 2> /dev/null || true)"
+    if ! aport_hook_try_read_evaluation_from_file_path "$FILE_PATH"; then
+        exit 0
+    fi
 
 elif [ "$HOOK_EVENT" = "subagentStart" ] || { [ -z "$HOOK_EVENT" ] && echo "$INPUT" | jq -e '.subagent_id' &> /dev/null; }; then
     # subagentStart: sub-agent spawning
@@ -96,36 +100,48 @@ elif [ "$HOOK_EVENT" = "beforeMCPExecution" ] || { [ -n "$TOOL_NAME" ] && echo "
     CONTEXT_JSON="$(safe_jq "$INPUT" '{tool_name: (.tool_name // ""), tool_input: (.tool_input // {})}')"
 
 elif [ -n "$TOOL_NAME" ]; then
-    # preToolUse: Cursor tool names — Shell, Read, Write, Grep, Delete, Task, MCP:<name>
-    # Normalize: trim whitespace, lowercase (patterns must match TOOL_NORM)
-    TOOL_NORM="$(echo "$TOOL_NAME" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')"
+    # preToolUse: Shell, Read, Write, Grep, Delete, Task, WebSearch, Agent, MCP:*, etc.
+    # See docs/FRAMEWORK_TOOL_MAPPING_AUDIT.md and https://cursor.com/docs/agent/hooks
+    TOOL_NORM="$(printf '%s' "$TOOL_NAME" | tr -d '[:space:]' | sed 's/^functions\.//' | sed 's/(.*$//' | tr '[:upper:]' '[:lower:]')"
     case "$TOOL_NORM" in
-        shell)
+        shell | bash)
             GUARDRAIL_TOOL="bash"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{command: (.tool_input.command // "")}')"
             ;;
-        read | grep | glob | semanticsearch)
-            # Read-family: allow without calling evaluator (matches Claude Code behavior)
+        read | readfile | semanticsearch)
+            TOOL_INPUT="$(safe_jq "$INPUT" '.tool_input // {}')"
+            if ! aport_hook_try_read_evaluation "$TOOL_NORM" "$TOOL_INPUT"; then
+                exit 0
+            fi
+            ;;
+        grep | glob | ls | lsp | listmcpresourcestool | readmcpresourcetool | toolsearch | waitformcpservers | taskget | tasklist | taskoutput | cronlist)
             exit 0
             ;;
-        write | strreplace | editnotebook)
+        write | strreplace | edit | multiedit | editnotebook | applypatch | notebookedit | delete)
             GUARDRAIL_TOOL="write"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{file_path: (.tool_input.file_path // .tool_input.path // "")}')"
             ;;
-        delete)
-            GUARDRAIL_TOOL="write"
-            CONTEXT_JSON="$(safe_jq "$INPUT" '{file_path: (.tool_input.file_path // .tool_input.path // "")}')"
+        websearch | webfetch)
+            GUARDRAIL_TOOL="websearch"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{url: (.tool_input.url // ""), query: (.tool_input.query // "")}')"
+            ;;
+        browser)
+            GUARDRAIL_TOOL="browser"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{url: (.tool_input.url // "")}')"
             ;;
-        task)
+        task | agent | taskcreate | taskupdate | taskstop | skill | subagent | subagentstart | sendmessage | teamcreate | teamdelete)
             GUARDRAIL_TOOL="session.create"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.tool_input.description // .tool_input.prompt // "")}')"
             ;;
-        mcp:*)
+        croncreate | crondelete)
+            GUARDRAIL_TOOL="session.create"
+            CONTEXT_JSON="$(safe_jq "$INPUT" '{description: (.tool_input.description // .tool_input.schedule // "")}')"
+            ;;
+        mcp__* | mcp:* | callmcptool)
             GUARDRAIL_TOOL="mcp.tool"
             CONTEXT_JSON="$(safe_jq "$INPUT" '{tool_name: (.tool_name // ""), tool_input: (.tool_input // {})}')"
             ;;
         *)
-            # Unknown preToolUse tool: fail-closed
             deny "🛡️ APort: unknown tool '$TOOL_NAME' — fail-closed policy"
             ;;
     esac
@@ -154,6 +170,15 @@ if [ -n "$HOOK_DECISION_FILE" ]; then
     export OPENCLAW_DECISION_FILE="$HOOK_DECISION_FILE"
 fi
 
+# Read tools: send only file_path to the evaluator (Cursor may attach large file bodies in tool_input).
+if [ "$GUARDRAIL_TOOL" = "read" ]; then
+    CONTEXT_JSON="$(printf '%s' "$CONTEXT_JSON" | jq -c '{file_path: (.file_path // .path // "")}' 2> /dev/null || echo '{"file_path":""}')"
+    if [ -z "$(printf '%s' "$CONTEXT_JSON" | jq -r '.file_path // ""' 2> /dev/null)" ]; then
+        echo '{"permission":"allow","allowed":true}'
+        exit 0
+    fi
+fi
+
 # Call core evaluator
 set +e
 "$GUARDRAIL" "$GUARDRAIL_TOOL" "$CONTEXT_JSON" 2> /dev/null

package/bin/aport-guardrail-bash.sh

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

package/bin/lib/hook-read-policy.sh

@@ -0,0 +1,61 @@
+# Shared path-based read tool handling for Claude Code and Cursor hooks.
+# shellcheck shell=bash
+#
+# Usage (after defining safe_jq in the hook):
+#   aport_hook_try_read_evaluation "$TOOL_NORM" "$TOOL_INPUT"
+# On success: sets GUARDRAIL_TOOL=read and CONTEXT_JSON with file_path; returns 0.
+# On skip (no path / not a path-based read tool): returns 1 — caller may allow without evaluator.
+
+aport_hook_read_tools_with_path() {
+    case "$1" in
+        read | readfile | semanticsearch) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+aport_hook_read_context_json() {
+    local file_path="$1"
+    jq -n -c --arg file_path "$file_path" '{file_path: $file_path}' 2> /dev/null
+}
+
+aport_hook_try_read_evaluation() {
+    local tool_norm="$1"
+    local tool_input="$2"
+    local file_path context
+
+    if ! aport_hook_read_tools_with_path "$tool_norm"; then
+        return 1
+    fi
+
+    file_path="$(echo "$tool_input" | jq -r '.file_path // .path // ""' 2> /dev/null || true)"
+    if [ -z "$file_path" ]; then
+        return 1
+    fi
+
+    context="$(aport_hook_read_context_json "$file_path")"
+    if [ -z "$context" ]; then
+        return 1
+    fi
+
+    GUARDRAIL_TOOL="read"
+    CONTEXT_JSON="$context"
+    return 0
+}
+
+aport_hook_try_read_evaluation_from_file_path() {
+    local file_path="$1"
+    local context
+
+    if [ -z "$file_path" ]; then
+        return 1
+    fi
+
+    context="$(aport_hook_read_context_json "$file_path")"
+    if [ -z "$context" ]; then
+        return 1
+    fi
+
+    GUARDRAIL_TOOL="read"
+    CONTEXT_JSON="$context"
+    return 0
+}

package/bin/lib/tool-mapping.sh

@@ -5,6 +5,7 @@ _aport_tool_mapping_file() {
     lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
 
     local candidates=(
+        "$lib_dir/../../packages/core/src/core/tool-pack-mapping.json"
         "$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"
@@ -26,7 +27,7 @@ resolve_policy_id_from_tool_name() {
     local normalized=""
     local policy_id=""
 
-    normalized="$(printf '%s' "$tool_name" | tr '[:upper:]' '[:lower:]')"
+    normalized="$(printf '%s' "$tool_name" | tr '[:upper:]' '[:lower:]' | sed 's/^functions\.//' | sed 's/(.*$//')"
     mapping_file="$(_aport_tool_mapping_file)" || return 1
 
     policy_id="$(
@@ -43,6 +44,9 @@ resolve_policy_id_from_tool_name() {
         ' "$mapping_file"
     )"
 
+    # Do not apply JSON "default" here: bash/API guardrail must deny unmapped tool names.
+    # Python/TypeScript adapters use tool_to_pack_id() / toolToPackId() which apply default for custom tools.
+
     if [[ -n "$policy_id" && "$policy_id" != "null" ]]; then
         printf '%s\n' "$policy_id"
         return 0

package/docs/FRAMEWORK_TOOL_MAPPING_AUDIT.md

@@ -0,0 +1,158 @@
+# Framework tool mapping audit
+
+Last reviewed against upstream docs and this repo’s mapping sources.
+
+## Mapping layers (do not conflate)
+
+| Layer | Source | Used by |
+|-------|--------|---------|
+| **Host tool name** | Framework-native string (`Bash`, `exec`, `sessions_spawn`, LangChain tool `.name`) | Hooks / plugin receive this |
+| **Guardrail tool id** | Hook alias passed to `aport-guardrail-bash.sh` (`bash`, `session.create`, `cron`, …) | Claude Code / Cursor hooks only |
+| **Policy pack id** | `tool-pack-mapping.json` or `mapToolToPolicy()` | All evaluators |
+| **Passport capability** | `external/aport-policies/*/policy.json` → `requires_capabilities` | Passport + evaluator |
+
+Canonical pack mapping for **generic** tool names: `packages/core/src/core/tool-pack-mapping.json` (mirrored in `python/aport_guardrails/core/tool-pack-mapping.json`). TypeScript/Python adapters call `toolToPackId()` / `tool_to_pack_id()`. Bash/API guardrails use `bin/lib/tool-mapping.sh` (same JSON + `default` fallback).
+
+---
+
+## Framework summary
+
+| Framework | Integration | Tool mapping implementation | Unmapped tools |
+|-----------|-------------|----------------------------|----------------|
+| **Claude Code** | `bin/aport-claude-code-hook.sh` | Host name → guardrail id → JSON | **Fail-closed** (deny) |
+| **Cursor** | `bin/aport-cursor-hook.sh` | Same pattern as Claude Code | **Fail-closed** |
+| **OpenClaw** | `extensions/openclaw-aport/tool-mapping.js` | `mapToolToPolicy()` in plugin | **Allow** if `allowUnmappedTools: true` (default) |
+| **LangChain / LangGraph** | `APortCallback` / `APortGuardrailCallback` | `tool_to_pack_id(tool.name)` only | Uses JSON `default` → `system.command.execute.v1` |
+| **CrewAI** | Python/TS hook middleware | `tool_to_pack_id(tool_name)` only | Same as LangChain |
+| **DeerFlow** | `OAPGuardrailProvider` | `tool_to_pack_id(tool_name)` only | Same as LangChain |
+| **n8n** | Not shipped | — | — |
+| **Generic CLI** | `aport-guardrail-bash.sh` | JSON only | Deny if no rule and no default |
+
+---
+
+## Claude Code
+
+**Official tools** ([Tools reference](https://code.claude.com/docs/en/tools-reference)) include: `Agent`, `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `WebSearch`, `WebFetch`, `Skill`, `TaskCreate`/`TaskUpdate`/`TaskStop`/`TaskGet`/`TaskList`, `CronCreate`/`CronDelete`/`CronList`, `EnterWorktree`/`ExitWorktree`, `PowerShell`, `Monitor`, MCP tools (`mcp__server__tool`), etc.
+
+| Host tool | Guardrail id | Policy pack | Capability |
+|-----------|--------------|-------------|------------|
+| `Bash`, `PowerShell`, `Monitor` | `bash` | `system.command.execute.v1` | `system.command.execute` |
+| `Read`, `Glob`, `Grep`, `LSP`, MCP list/read/wait tools, `TaskGet`/`TaskList`, `CronList`, … | *(allow, no evaluator)* | — | — |
+| `Write`, `Edit`, `MultiEdit`, `NotebookEdit`, `TodoWrite`, … | `write` | `data.file.write.v1` | `data.file.write` |
+| `WebSearch`, `WebFetch` | `websearch` | `web.fetch.v1` | `web.fetch` |
+| `Browser` | `browser` | `web.browser.v1` | `web.browser` |
+| `Agent`, `Task`, `TaskCreate`, `Skill`, worktree, teams, … | `session.create` | `agent.session.create.v1` | `agent.session.create` |
+| `CronCreate`, `CronDelete` | `cron` | `agent.session.create.v1` | `agent.session.create` |
+| `mcp__*`, `CallMcpTool` | `mcp.tool` | `mcp.tool.execute.v1` | `mcp.tool.execute` |
+
+Programmatic map: `packages/claude-code/src/claudeCodeTools.ts`.
+
+---
+
+## Cursor
+
+**Documented preToolUse tools** ([Cursor hooks](https://cursor.com/docs/agent/hooks)): `Shell`, `Read`, `Write`, `Grep`, `Delete`, `Task`, `WebSearch` (when emitted), `Agent`, `Edit`, MCP (`MCP:…` / `mcp:…`), plus `beforeShellExecution` / `subagentStart` events.
+
+Hook aligned with Claude Code (v1.0.27+): `WebSearch`, `WebFetch`, `Agent`, `Edit`, `ApplyPatch`, `browser`, `cron`, MCP variants. Read-family tools still skip the evaluator for latency.
+
+**Caveats (upstream, not APort):**
+
+- Built-in web search may not always emit `preToolUse` depending on Cursor model/routing ([forum report](https://forum.cursor.com/t/bug-pretooluse-agent-hooks-do-not-emit-for-built-in-web-search-in-cursor-agent-works-in-claude-code/160761)).
+- `ApplyPatch` may not emit hooks in some CLI builds ([Codex issue #16732](https://github.com/openai/codex/issues/16732)) — APort cannot enforce what the host does not emit.
+
+---
+
+## OpenClaw
+
+**Official session tools** ([Session tools](https://docs.openclaw.ai/concepts/session-tool)): `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`. Plus `exec`, `message`, `read`/`write`/`edit`, `git.*`, MCP `server__tool`, etc.
+
+| OpenClaw tool | Policy pack | Capability |
+|---------------|-------------|------------|
+| `exec`, `exec.*`, `process`, `gateway` | `system.command.execute.v1` | `system.command.execute` |
+| `message` (send-family actions) | `messaging.message.send.v1` | `messaging.message.send` |
+| `read`, `view`, `glob` | `data.file.read.v1` | `data.file.read` |
+| `write`, `edit`, `multiedit` | `data.file.write.v1` | `data.file.write` |
+| `web_search`, `webfetch`, `browser` | `web.fetch.v1` / `web.browser.v1` | `web.fetch` / `web.browser` |
+| `sessions_spawn`, `sessions_send`, `sessions_yield`, `subagents`, `session_status` | `agent.session.create.v1` | `agent.session.create` |
+| `sessions_list`, `sessions_history` | `data.file.read.v1` | `data.file.read` |
+| `server__tool`, `mcp.*` | `mcp.tool.execute.v1` | `mcp.tool.execute` |
+| `git.*` | `code.repository.merge.v1` | `repo.merge` / `repo.pr.create` |
+
+Plugin: `extensions/openclaw-aport/tool-mapping.js`. With `allowUnmappedTools: false`, unmapped tools are denied.
+
+---
+
+## LangChain / CrewAI / DeerFlow
+
+No host-specific tool names: mapping is **only** `tool-pack-mapping.json` on whatever name the tool registers (e.g. `bash`, `read_file`, `web_search`, custom `my_tool`).
+
+DeerFlow-tested names (see `python/aport_guardrails/tests/test_oap_provider_e2e.py`):
+
+| Tool name | Policy pack |
+|-----------|-------------|
+| `bash` | `system.command.execute.v1` |
+| `write_file`, `str_replace` | `data.file.write.v1` |
+| `read_file`, `ls`, `present_file`, `view_image` | `data.file.read.v1` |
+| `web_search` | `web.fetch.v1` |
+| `git.create_pr` | `code.repository.merge.v1` |
+| `mcp.github.issues` | `mcp.tool.execute.v1` |
+| `messaging.send` | `messaging.message.send.v1` |
+
+Custom LangChain tools must use names that match a prefix/substring in `tool-pack-mapping.json`, or they resolve to **`default`** (`system.command.execute.v1`).
+
+---
+
+## Policy packs reference
+
+| Policy pack | Capability id | Notes |
+|-------------|---------------|--------|
+| `system.command.execute.v1` | `system.command.execute` | Shell/exec; JSON `default` |
+| `data.file.read.v1` | `data.file.read` | |
+| `data.file.write.v1` | `data.file.write` | |
+| `web.fetch.v1` | `web.fetch` | WebSearch/WebFetch |
+| `web.browser.v1` | `web.browser` | Browser automation (no separate `cron.v1`) |
+| `agent.session.create.v1` | `agent.session.create` | Subagents, tasks, **cron** guardrail alias `cron` |
+| `mcp.tool.execute.v1` | `mcp.tool.execute` | |
+| `messaging.message.send.v1` | `messaging.message.send` | |
+| `code.repository.merge.v1` | `repo.merge`, `repo.pr.create` | |
+
+There is **no** `cron.v1` policy; scheduled-task tools map to `agent.session.create.v1`.
+
+**Guardrail id note:** Hooks pass `session.create` (not a bare `cron` alias) for `CronCreate`/`CronDelete` so `cronlist` is not misclassified via a `cron*` prefix.
+
+## Deploy / security review (internal)
+
+| Check | Status |
+|-------|--------|
+| `packages/core` and `python/.../tool-pack-mapping.json` identical | Enforced in `tests/unit/test-tool-pack-mapping.sh` |
+| Bash `resolve_policy_id_from_tool_name` fail-closed on unknown | Yes — JSON `default` is **not** applied in bash (adapters still use default) |
+| Hooks fail-closed on unknown host tools | Claude Code + Cursor |
+| `cronlist` → read, not session | Fixed (avoid bare `cron` prefix) |
+| OpenClaw `cronlist` before `cron*` match | Fixed (explicit tool names only) |
+| Published npm tarball includes mapping JSON | `python/aport_guardrails/core/tool-pack-mapping.json` in root `package.json` `files` |
+
+**Known DRY debt (acceptable for now):** host hooks (`aport-*-hook.sh`) duplicate case lists; OpenClaw uses `tool-mapping.js`. Both must stay aligned with `tool-pack-mapping.json` when adding tools. `claudeCodeTools.ts` is documentation-only.
+
+**Prefix caveat:** bare `agent` prefix matches any tool name starting with `agent` (e.g. hypothetical `agentic_search`). Prefer explicit host names in hooks.
+
+---
+
+## Tests
+
+| Test | Coverage |
+|------|----------|
+| `tests/unit/test-tool-pack-mapping.sh` | JSON resolution (Claude/OpenClaw/DeerFlow names) |
+| `tests/unit/test-claude-code-hook.sh` | Claude hook allow/deny |
+| `tests/unit/test-cursor-hook.sh` | Cursor hook |
+| `tests/extensions/openclaw-aport.test.js` | `mapToolToPolicy()` |
+
+---
+
+## Maintenance
+
+When a framework adds tools:
+
+1. Confirm the **exact** `tool_name` from host docs or a captured hook payload.
+2. Update the **hook** (Claude/Cursor) or **openclaw-aport/tool-mapping.js** if host-specific.
+3. Add prefixes to **`tool-pack-mapping.json`** (and sync Python copy).
+4. Extend unit tests and this audit doc.

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.26 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.27 (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.
 

package/docs/TOOL_POLICY_MAPPING.md

@@ -14,7 +14,10 @@ This mapping is implemented in `bin/aport-guardrail-api.sh` and `bin/aport-guard
 | `read`, `file.read`, `data.file.read` | `data.file.read.v1` | API / evaluator |
 | `write`, `file.write`, `data.file.write` | `data.file.write.v1` | API / evaluator |
 | `mcp.tool.*`, `mcp.*` | `mcp.tool.execute.v1` | API / evaluator |
-| `agent.session.*`, `session.create`, `session.*` | `agent.session.create.v1` | API / evaluator |
+| `agent.session.*`, `session.create`, `session.*`, `cron`, `sessions_spawn`, `sessions_send`, `sessions_yield`, `subagents`, `session_status` | `agent.session.create.v1` | API / evaluator |
+| `sessions_list`, `sessions_history`, `view` | `data.file.read.v1` | API / evaluator |
+| `websearch`, `web_search`, `webfetch`, `web_fetch` | `web.fetch.v1` | API / evaluator |
+| `browser`, `web.browser` | `web.browser.v1` | API / evaluator |
 | `agent.tool.*`, `tool.register`, `tool.*` | `agent.tool.register.v1` | API / evaluator |
 | `payment.refund`, `payment.*`, `finance.payment.refund` | `finance.payment.refund.v1` | `external/aport-policies/finance.payment.refund.v1/` |
 | `payment.charge`, `finance.payment.charge` | `finance.payment.charge.v1` | `external/aport-policies/finance.payment.charge.v1/` |
@@ -41,6 +44,8 @@ To add a new tool → policy mapping, edit the `case` block in:
 
 and add a new pattern and policy pack ID. The policy pack must exist under `external/aport-policies/<pack_id>/` (or in local-overrides / API).
 
+Per-framework host tool names and hook behavior: [FRAMEWORK_TOOL_MAPPING_AUDIT.md](FRAMEWORK_TOOL_MAPPING_AUDIT.md).
+
 ## Reference
 
 - OAP spec: `external/aport-spec/`

package/docs/frameworks/claude-code.md

@@ -71,16 +71,20 @@ This command intentionally runs the same supported installer flow (`npx @aporthq
 
 | Claude Code tool   | APort policy              | Default   |
 |--------------------|---------------------------|----------|
-| Bash               | system.command.execute.v1 | Enforce  |
-| Read, Glob, LS, Grep, TodoRead | data.file.read.v1  | **Allow by default** (no evaluator call) |
-| Write, Edit, MultiEdit, TodoWrite | data.file.write.v1 | Enforce  |
+| Bash, PowerShell, Monitor | system.command.execute.v1 | Enforce  |
+| Read, ReadFile, SemanticSearch (with `file_path`) | data.file.read.v1 | **Enforce** (sensitive paths blocked; API/local) |
+| Glob, Grep, LSP, ListMcpResourcesTool, ReadMcpResourceTool, ToolSearch, WaitForMcpServers, TaskGet, TaskList, TodoRead | data.file.read.v1 | Allow without evaluator (no single path) |
+| Write, Edit, MultiEdit, NotebookEdit, TodoWrite, ShareOnboardingGuide | data.file.write.v1 | Enforce  |
 | WebSearch, WebFetch | web.fetch.v1             | Enforce  |
 | Browser            | web.browser.v1            | Enforce  |
-| Task               | agent.session.create.v1   | Enforce  |
+| Agent, Task, TaskCreate, TaskUpdate, TaskStop, Skill, EnterWorktree, ExitWorktree, SendMessage, TeamCreate, TeamDelete, RemoteTrigger | agent.session.create.v1 | Enforce  |
+| CronCreate, CronDelete | agent.session.create.v1 | Enforce  |
 | mcp__<server>__<tool> | mcp.tool.execute.v1 | Enforce  |
 | **Unknown tool**    | —                         | **Denied (fail-closed)** |
 
-Read-family tools (Read, Glob, LS, Grep, TodoRead) exit 0 immediately without calling the evaluator to save ~40ms per file read. The HN incident was about Bash escaping a sandbox — not reads.
+Permission-rule specifiers such as `Agent(Explore)` are stripped before mapping (the hook receives `Agent(Explore)` and normalizes to `agent`).
+
+Path-based **Read** tools call the guardrail with only `file_path` in context (not full file bodies). **Glob/Grep/LS** and similar tools still allow without an evaluator call when no single `file_path` is present.
 
 ---
 

package/docs/frameworks/deerflow.md

@@ -105,14 +105,18 @@ guardrails:
 
 ## Tool-to-policy mapping
 
-| DeerFlow tool | OAP policy pack |
-|---|---|
-| `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.file.read.v1` |
-| `ask_clarification`, `task` | `agent.session.create.v1` |
-| MCP tools (dynamic) | `mcp.tool.execute.v1` |
+| DeerFlow tool | OAP policy pack | Passport capability |
+|---|---|---|
+| `bash` | `system.command.execute.v1` | `system.command.execute` |
+| `write_file`, `str_replace` | `data.file.write.v1` | `data.file.write` |
+| `web_search`, `web_fetch`, `image_search` | `web.fetch.v1` | `web.fetch` |
+| `read_file`, `ls`, `present_file`, `view_image` | `data.file.read.v1` | `data.file.read` |
+| `git.create_pr`, `git.*` | `code.repository.merge.v1` | `repo.merge` / `repo.pr.create` |
+| `messaging.send`, `message.*` | `messaging.message.send.v1` | `messaging.message.send` |
+| `ask_clarification`, `task` | `agent.session.create.v1` | `agent.session.create` |
+| MCP tools (`mcp.*`, dynamic names) | `mcp.tool.execute.v1` | `mcp.tool.execute` |
+
+Mapping is implemented in `packages/core/src/core/tool-pack-mapping.json` (via `tool_to_pack_id()`). DeerFlow passes the raw tool name from each tool invocation.
 
 ## Evaluation modes
 

package/extensions/openclaw-aport/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog - APort OpenClaw Plugin
 
+## 1.0.27
+
 ## 1.0.26
 
 ## 1.0.25

package/extensions/openclaw-aport/local-evaluator.js

@@ -152,6 +152,19 @@ function allowByList(value, list, matcher) {
   return list.some((entry) => matcher(value, entry));
 }
 
+function isDefaultSensitiveReadPath(filePath) {
+  const value = String(filePath).toLowerCase();
+  return /(^|\/)\.env/.test(value) ||
+    /(^|\/)\.aws\//.test(value) ||
+    /(^|\/)\.ssh\//.test(value) ||
+    value.includes("credentials") ||
+    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)/.test(value) ||
+    /\.(pem|key)$/.test(value) ||
+    value.includes("password") ||
+    /(^|\/)\.gnupg\//.test(value) ||
+    /(^|\/)\.kube\//.test(value);
+}
+
 function makeDeny(baseParams, code, message) {
   return buildDecision({ allow: false, code, message, ...baseParams });
 }
@@ -267,6 +280,10 @@ export function evaluateLocalDecision({ policyName, context, passportFile }) {
 
   if (policyName === "data.file.read.v1") {
     const filePath = String(context.file_path ?? context.path ?? "");
+    if (isDefaultSensitiveReadPath(filePath)) {
+      return makeDeny(params, "oap.blocked_pattern", "File path matches default sensitive read pattern");
+    }
+
     if (!allowByList(filePath, limits.allowed_paths, (value, pattern) => value.startsWith(pattern) || pattern === "*")) {
       return makeDeny(params, "oap.path_not_allowed", `File path '${filePath}' is not in allowed list`);
     }

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.26",
+  "version": "1.0.27",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

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

@@ -1,12 +1,12 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@aporthq/openclaw-aport",
-      "version": "1.0.26",
+      "version": "1.0.27",
       "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.26",
+  "version": "1.0.27",
   "description": "OpenClaw plugin for deterministic pre-action authorization via APort guardrails",
   "main": "index.js",
   "type": "module",

package/extensions/openclaw-aport/tool-mapping.js

@@ -63,7 +63,9 @@ export function mapToolToPolicy(toolName, params) {
   if (tool.match(/exec\.(run|shell)/)) return "system.command.execute.v1";
   if (tool.startsWith("exec.")) return "system.command.execute.v1";
   if (tool.startsWith("system.command.")) return "system.command.execute.v1";
-  if (tool === "bash" || tool === "shell" || tool === "command") return "system.command.execute.v1";
+  if (tool === "bash" || tool === "shell" || tool === "command" || tool === "powershell" || tool === "monitor") {
+    return "system.command.execute.v1";
+  }
 
   if (tool === "message") {
     return MESSAGE_SEND_ACTIONS.has(readAction(params)) ? "messaging.message.send.v1" : null;
@@ -81,9 +83,10 @@ export function mapToolToPolicy(toolName, params) {
     return "messaging.message.send.v1";
   }
 
-  if (tool === "read") return "data.file.read.v1";
+  if (tool === "read" || tool === "view") return "data.file.read.v1";
   if (tool.startsWith("file.read")) return "data.file.read.v1";
   if (tool.startsWith("data.file.read")) return "data.file.read.v1";
+  if (tool === "sessions_list" || tool === "sessions_history") return "data.file.read.v1";
   if (tool === "write" || tool === "edit") return "data.file.write.v1";
   if (tool === "multiedit" || tool === "notebookedit") return "data.file.write.v1";
   if (tool === "glob" || tool === "ls" || tool === "grep" || tool === "toolsearch") {
@@ -91,9 +94,35 @@ export function mapToolToPolicy(toolName, params) {
   }
   if (tool === "todoread") return "data.file.read.v1";
   if (tool === "todowrite") return "data.file.write.v1";
-  if (tool === "taskget" || tool === "tasklist" || tool === "taskoutput") return "data.file.read.v1";
+  if (tool === "taskget" || tool === "tasklist" || tool === "taskoutput" || tool === "cronlist") {
+    return "data.file.read.v1";
+  }
+  if (
+    tool === "agent" ||
+    tool === "task" ||
+    tool === "taskcreate" ||
+    tool === "taskupdate" ||
+    tool === "taskstop" ||
+    tool === "skill" ||
+    tool === "enterworktree" ||
+    tool === "exitworktree" ||
+    tool === "subagent" ||
+    tool === "subagentstart" ||
+    tool === "sendmessage" ||
+    tool === "teamcreate" ||
+    tool === "teamdelete" ||
+    tool === "remotetrigger" ||
+    tool === "sessions_spawn" ||
+    tool === "sessions_send" ||
+    tool === "sessions_yield" ||
+    tool === "subagents" ||
+    tool === "session_status" ||
+    tool === "croncreate" ||
+    tool === "crondelete"
+  ) {
+    return "agent.session.create.v1";
+  }
   if (tool === "askuserquestion" || tool === "enterplanmode" || tool === "exitplanmode") return null;
-  if (tool === "cronlist") return "data.file.read.v1";
   if (tool.startsWith("file.write")) return "data.file.write.v1";
   if (tool.startsWith("file.edit")) return "data.file.write.v1";
   if (tool.startsWith("data.file.write")) return "data.file.write.v1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",

package/python/aport_guardrails/core/tool-pack-mapping.json

@@ -1 +1,111 @@
-{"default":"system.command.execute.v1","rules":[{"prefixes":["git."],"pack":"code.repository.merge.v1"},{"prefixes":["exec.","system.","bash","shell","command","run_command","execute_command","gateway","process"],"pack":"system.command.execute.v1"},{"prefixes":["message.","messaging.","sms","whatsapp","slack","email"],"pack":"messaging.message.send.v1"},{"prefixes":["mcp."],"pack":"mcp.tool.execute.v1"},{"prefixes":["agent.session.","session.","sessions.","sessions_spawn","sessions_send","cron"],"pack":"agent.session.create.v1"},{"prefixes":["agent.tool."],"substrings":["tool.register"],"pack":"agent.tool.register.v1"},{"substrings":["payment.refund","finance.payment.refund"],"pack":"finance.payment.refund.v1"},{"substrings":["payment.charge","finance.payment.charge"],"pack":"finance.payment.charge.v1"},{"prefixes":["database.","data.export"],"pack":"data.export.create.v1"},{"prefixes":["write_file","str_replace","write","edit","file.write","file.edit","data.file.write"],"pack":"data.file.write.v1"},{"prefixes":["read_file","ls","present_file","view_image","read","file.read","data.file.read"],"pack":"data.file.read.v1"},{"prefixes":["web_search","web_fetch","image_search","webfetch","web.search","web.fetch"],"pack":"web.fetch.v1"},{"prefixes":["browser","web.browser"],"pack":"web.browser.v1"},{"prefixes":["ask_clarification"],"substrings":["task"],"pack":"agent.session.create.v1"}]}
+{
+  "default": "system.command.execute.v1",
+  "rules": [
+    { "prefixes": ["git."], "pack": "code.repository.merge.v1" },
+    {
+      "prefixes": [
+        "exec.",
+        "system.",
+        "bash",
+        "shell",
+        "command",
+        "run_command",
+        "execute_command",
+        "gateway",
+        "process",
+        "powershell",
+        "monitor"
+      ],
+      "pack": "system.command.execute.v1"
+    },
+    {
+      "prefixes": ["message.", "messaging.", "sms", "whatsapp", "slack", "email"],
+      "pack": "messaging.message.send.v1"
+    },
+    { "prefixes": ["mcp."], "pack": "mcp.tool.execute.v1" },
+    {
+      "prefixes": [
+        "agent.session.",
+        "session.",
+        "sessions.",
+        "sessions_spawn",
+        "sessions_send",
+        "sessions_yield",
+        "subagents",
+        "session_status",
+        "croncreate",
+        "crondelete",
+        "taskcreate",
+        "taskupdate",
+        "taskstop",
+        "subagent",
+        "subagentstart",
+        "skill",
+        "enterworktree",
+        "exitworktree",
+        "sendmessage",
+        "teamcreate",
+        "teamdelete",
+        "remotetrigger",
+        "schedulewakeup"
+      ],
+      "pack": "agent.session.create.v1"
+    },
+    { "prefixes": ["agent.tool."], "substrings": ["tool.register"], "pack": "agent.tool.register.v1" },
+    { "prefixes": ["agent"], "pack": "agent.session.create.v1" },
+    { "substrings": ["payment.refund", "finance.payment.refund"], "pack": "finance.payment.refund.v1" },
+    { "substrings": ["payment.charge", "finance.payment.charge"], "pack": "finance.payment.charge.v1" },
+    { "prefixes": ["database.", "data.export"], "pack": "data.export.create.v1" },
+    {
+      "prefixes": [
+        "write_file",
+        "str_replace",
+        "write",
+        "edit",
+        "multiedit",
+        "notebookedit",
+        "file.write",
+        "file.edit",
+        "data.file.write",
+        "shareonboardingguide"
+      ],
+      "pack": "data.file.write.v1"
+    },
+    {
+      "prefixes": [
+        "read_file",
+        "ls",
+        "present_file",
+        "view_image",
+        "view",
+        "sessions_list",
+        "sessions_history",
+        "cronlist",
+        "read",
+        "glob",
+        "grep",
+        "lsp",
+        "file.read",
+        "data.file.read",
+        "listmcpresourcestool",
+        "readmcpresourcetool",
+        "toolsearch",
+        "waitformcpservers"
+      ],
+      "pack": "data.file.read.v1"
+    },
+    {
+      "prefixes": [
+        "web_search",
+        "web_fetch",
+        "websearch",
+        "image_search",
+        "webfetch",
+        "web.search",
+        "web.fetch"
+      ],
+      "pack": "web.fetch.v1"
+    },
+    { "prefixes": ["browser", "web.browser"], "pack": "web.browser.v1" }
+  ]
+}