@stigmer/runner 3.0.2-dev.20260609093630 → 3.0.3

package/src/activities/execute-cursor/approval-policy.ts

@@ -18,7 +18,9 @@
 
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { classifyTool } from "../../shared/tool-kind.js";
 
 /**
  * A single tool's merged approval decision after evaluating all policy layers.
@@ -31,61 +33,141 @@ export interface MergedToolPolicy {
 }
 
 /**
- * Built-in (non-MCP) Cursor tools that mutate the workspace or execute
- * commands. These require approval when auto_approve_all is false, mirroring
- * the native harness's DANGEROUS_PLATFORM_TOOLS (write/edit/create/delete/
- * execute/shell). Each value is an approval-message template resolved against
- * the tool args (see resolveApprovalMessage); its placeholder names the same
- * field the grant matcher keys on (path/command/target_notebook).
+ * Built-in Cursor tools the preToolUse hook gates, named as the hook receives
+ * them.
+ *
+ * Critical: the Cursor preToolUse hook and the SDK event stream use DIFFERENT
+ * tool taxonomies for the same operation. The hook's `tool_name` is PascalCase
+ * (`Write` for any file create/edit, `Shell`, `Delete`); the stream's
+ * `event.name` is lowercase (`edit`, `shell`, `delete`). This set is the HOOK
+ * taxonomy because it is consulted only to build the hook's gated set and its
+ * name->category mapping. Cross-layer correlation never compares these raw
+ * names — it uses {@link approvalCategory} (see below).
  */
-const BUILT_IN_GATED = new Map<string, string>([
-  ["Write", "Write file: {{args.path}}"],
-  ["StrReplace", "Edit file: {{args.path}}"],
-  ["EditNotebook", "Edit notebook: {{args.target_notebook}}"],
-  ["Shell", "Run command: {{args.command}}"],
-  ["Delete", "Delete: {{args.path}}"],
+const BUILT_IN_GATED: ReadonlySet<string> = new Set([
+  "Write",
+  "StrReplace",
+  "EditNotebook",
+  "Shell",
+  "Delete",
 ]);
 
+/**
+ * Canonical approval category for a gated tool, derived from EITHER taxonomy's
+ * name via the shared {@link classifyTool}.
+ *
+ * The hook (`Write`/`Shell`/`Delete`) and the stream (`edit`/`shell`/`delete`)
+ * name the same operation differently, so neither raw name is a stable
+ * cross-layer identity. The category collapses both onto one value so the denial
+ * ledger (recorded by the hook) correlates to the streamed tool call (read by
+ * the runner) and so an approval grant matches the agent's re-attempt on
+ * reinvocation regardless of which taxonomy named it. `FILE_WRITE` and
+ * `FILE_EDIT` both map to `write` because the Cursor hook reports every file
+ * mutation — create or edit — as `Write`.
+ *
+ * Returns undefined for non-gated tools (read-only built-ins, MCP tools, and
+ * anything `classifyTool` does not place in a mutating kind).
+ */
+export type ApprovalCategory = "write" | "delete" | "shell";
+
+export function approvalCategory(toolName: string): ApprovalCategory | undefined {
+  switch (classifyTool(toolName)) {
+    case ToolKind.FILE_WRITE:
+    case ToolKind.FILE_EDIT:
+      return "write";
+    case ToolKind.FILE_DELETE:
+      return "delete";
+    case ToolKind.SHELL:
+      return "shell";
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Human-readable approval-message template per canonical category. Keyed by
+ * category (not raw tool name) so a denial surfaced from either taxonomy renders
+ * the same message. Placeholders resolve against the tool args via
+ * {@link resolveApprovalMessage}; `{{args.path}}` and `{{args.command}}` are the
+ * stream-side field names (the runner builds the approval surface from the
+ * streamed tool call, whose args use `path`/`command`).
+ */
+const CATEGORY_APPROVAL_MESSAGE: Record<ApprovalCategory, string> = {
+  write: "Write file: {{args.path}}",
+  delete: "Delete: {{args.path}}",
+  shell: "Run command: {{args.command}}",
+};
+
 /**
  * Top-level tool-argument fields, in priority order, that identify the specific
- * resource a built-in tool acts on. Used to render approval messages and to key
- * HITL approval grants (see approval-state.ts). Authored here once and injected
- * into the generated preToolUse hook script so the runner and the hook always
- * agree on which field to match.
+ * resource a built-in tool acts on. The list deliberately spans BOTH taxonomies'
+ * arg shapes: the hook input names a file `file_path` and the stream names it
+ * `path`; both name a shell command `command`. Extracting the same resource
+ * VALUE on both sides (the absolute path / the command string) is what lets the
+ * hook-recorded denial token equal the stream-computed token. Authored here once
+ * and injected into the generated preToolUse hook script so the runner and the
+ * hook never disagree on which field to match.
  */
-export const SALIENT_ARG_FIELDS = ["path", "command", "target_notebook"] as const;
+export const SALIENT_ARG_FIELDS = ["file_path", "path", "target_notebook", "command"] as const;
 
 /**
  * Check whether a built-in (non-MCP) Cursor tool requires user approval.
  *
- * Only the explicitly gated, mutating/destructive tools require approval;
- * everything else (read-only built-ins, and — at the hook layer — auto-approved
- * MCP tools) is allowed. This "gate the dangerous set, allow the rest" model
- * mirrors the native harness's resolveToolApproval, which also defaults
- * unlisted tools to no-approval. It is deliberately fail-OPEN for unknown
- * tools: the merged MCP policy map carries only the tools that REQUIRE
- * approval, so a fail-closed default would wrongly deny every auto-approved
- * MCP tool, which the hook cannot distinguish from an unknown built-in by name.
+ * Resolved via {@link approvalCategory} so it answers correctly for BOTH
+ * taxonomies — the hook's `Write`/`Shell`/`Delete` and the stream's
+ * `edit`/`shell`/`delete` all return true. Only mutating/destructive tools are
+ * gated; everything else (read-only built-ins, and — at the hook layer —
+ * auto-approved MCP tools) is allowed. This "gate the dangerous set, allow the
+ * rest" model mirrors the native harness's resolveToolApproval. It is
+ * deliberately fail-OPEN for unknown tools: the merged MCP policy map carries
+ * only the tools that REQUIRE approval, so a fail-closed default would wrongly
+ * deny every auto-approved MCP tool, which the hook cannot distinguish from an
+ * unknown built-in by name.
  */
 export function builtInRequiresApproval(toolName: string): boolean {
-  return BUILT_IN_GATED.has(toolName);
+  return approvalCategory(toolName) !== undefined;
 }
 
 /**
  * Returns the built-in tool names that require approval (the gated set the
  * preToolUse hook denies unless auto-approved or granted on reinvocation).
+ *
+ * These are HOOK-taxonomy names (PascalCase), because the hook matches its own
+ * `tool_name`. See {@link approvalCategory} for the cross-layer identity.
  */
 export function getBuiltInGatedList(): string[] {
-  return [...BUILT_IN_GATED.keys()];
+  return [...BUILT_IN_GATED];
+}
+
+/**
+ * Returns the gated built-in tools as `(hookToolName, category)` pairs.
+ *
+ * Injected into the generated preToolUse hook so the bash script can map its
+ * incoming `tool_name` to the canonical category used for the denial/grant
+ * token — the same category the runner computes from the stream side via
+ * {@link approvalCategory}. Authoring it here keeps the mapping single-sourced;
+ * a gated built-in with no category would be a programming error, so it is
+ * filtered out (and would simply not be gated rather than crash the hook).
+ */
+export function getBuiltInGatedCategories(): Array<[string, ApprovalCategory]> {
+  const pairs: Array<[string, ApprovalCategory]> = [];
+  for (const name of BUILT_IN_GATED) {
+    const category = approvalCategory(name);
+    if (category) pairs.push([name, category]);
+  }
+  return pairs;
 }
 
 /**
- * Approval-message template for a gated built-in tool, or undefined when the
- * tool is not a known gated built-in. Callers resolve the placeholders against
- * the tool args via resolveApprovalMessage.
+ * Approval-message template for a gated built-in tool (either taxonomy), or
+ * undefined when the tool is not gated. Resolved via {@link approvalCategory}
+ * so stream-side names (`edit`/`shell`/`delete`) and hook-side names
+ * (`Write`/`Shell`/`Delete`) both map to the same template. Callers resolve the
+ * placeholders against the tool args via resolveApprovalMessage.
  */
 export function getBuiltInApprovalMessage(toolName: string): string | undefined {
-  return BUILT_IN_GATED.get(toolName);
+  const category = approvalCategory(toolName);
+  return category ? CATEGORY_APPROVAL_MESSAGE[category] : undefined;
 }
 
 /**

package/src/activities/execute-cursor/approval-state.ts

@@ -8,27 +8,29 @@
  * State file format (JSON):
  * {
  *   "autoApproveAll": false,
- *   "builtInGatedList": ["Write", "StrReplace", "Shell", ...],
  *   "mcpToolPolicies": {
  *     "apply_cloud_resource": { "requiresApproval": true, "message": "..." }
  *   },
- *   "approvedGrants": [{ "toolName": "Write", "mcpServerSlug": "", "argKey": "a.txt" }],
- *   "approvedGrantTokens": ["V3JpdGUKYS50eHQ="]
+ *   "approvedGrants": [{ "toolName": "edit", "mcpServerSlug": "", "key": "write", "salient": "a.txt" }],
+ *   "approvedGrantTokens": ["d3JpdGUKYS50eHQ="]
  * }
  *
- * The hook gates only the explicitly dangerous set (builtInGatedList) and the
- * MCP tools that require approval (mcpToolPolicies, which by construction holds
- * only require-approval entries); every other tool is allowed. This mirrors the
- * native harness and avoids denying auto-approved MCP tools, which are absent
- * from the policy map and indistinguishable from unknown tools by name.
+ * The hook gates the dangerous built-in set and the MCP tools that require
+ * approval (mcpToolPolicies, which by construction holds only require-approval
+ * entries); every other tool is allowed. The gated built-in set and its
+ * name->category mapping are baked into the generated hook script (from
+ * approval-policy.ts), not carried in the state file — only the dynamic inputs
+ * (autoApproveAll, mcpToolPolicies, approvedGrantTokens) live here. This mirrors
+ * the native harness and avoids denying auto-approved MCP tools, which are
+ * absent from the policy map and indistinguishable from unknown tools by name.
  *
  * Why grants instead of tool-call ids: a resumed Cursor agent re-issues the
  * approved tool with a BRAND NEW call id, so matching on the original call id
- * can never let the re-attempt through. Instead we grant by tool identity —
- * tool name plus a "salient" argument (the file path for Write, the command for
- * Shell, …; see extractArgKey). On reinvocation the hook allows a tool call
- * only if its (name, salient-arg) matches an approved grant; rejected/skipped
- * tools and any newly proposed dangerous tool are re-gated.
+ * can never let the re-attempt through. Instead we grant by canonical tool
+ * identity — the approval category plus a "salient" resource value (the file
+ * path, the shell command; see {@link toolIdentity}). On reinvocation the hook
+ * allows a tool call only if its (category, salient) matches an approved grant;
+ * rejected/skipped tools and any newly proposed dangerous tool are re-gated.
  *
  * Tokens: the hook is a self-contained bash script, so it cannot parse an array
  * of grant objects. `approvedGrantTokens` is the flat, base64-encoded form of
@@ -56,30 +58,66 @@ import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agente
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { MergedToolPolicy } from "./approval-policy.js";
-import { getBuiltInGatedList, extractArgKey } from "./approval-policy.js";
+import { extractArgKey, approvalCategory } from "./approval-policy.js";
 
 export interface McpToolPolicyEntry {
   requiresApproval: boolean;
   message?: string;
 }
 
+/**
+ * The canonical, taxonomy-agnostic identity of a tool call.
+ *
+ * The Cursor preToolUse hook and the SDK stream name the same operation
+ * differently (hook `Write`/`Shell`/`Delete`; stream `edit`/`shell`/`delete`),
+ * so the raw tool name cannot be a cross-layer identity. Instead:
+ * - `key` is the {@link approvalCategory} (`write`/`delete`/`shell`) for gated
+ *   built-ins, and the tool name for MCP tools (whose name is consistent across
+ *   layers). It is the part that survives the name divergence.
+ * - `salient` is the resource the tool acts on (the absolute file path or the
+ *   shell command) — identical on both sides because it is the argument VALUE,
+ *   not the field name. Empty for MCP tools, matched by `key` alone.
+ *
+ * The denial ledger (hook) and the stream reconciliation (runner) both reduce a
+ * tool call to this identity, so they correlate exactly; an approval grant uses
+ * the same identity so the agent's re-attempt is allowed on reinvocation even
+ * though it carries a fresh tool-call id and a different-taxonomy name.
+ */
+export interface ToolIdentity {
+  key: string;
+  salient: string;
+}
+
+export function toolIdentity(
+  toolName: string,
+  mcpServerSlug: string,
+  args: Record<string, unknown> | undefined,
+): ToolIdentity {
+  if (mcpServerSlug) {
+    return { key: toolName, salient: "" };
+  }
+  const category = approvalCategory(toolName);
+  // A gated built-in keys on its category; an unknown/non-gated tool falls back
+  // to its own name (harmless — it is not gated, so it never enters the ledger).
+  return { key: category ?? toolName, salient: extractArgKey(args) };
+}
+
 /**
  * The identity of an approved tool call, stable across agent resume.
  *
- * - argKey is the salient argument (path/command/…) for built-in tools; matched
- *   exactly so only the approved resource is allowed through on the resumed turn.
- * - argKey is empty for MCP tools (and built-in tools with no salient field);
- *   the grant then matches by name alone, since the user approved that tool.
+ * - `key`/`salient` are the canonical {@link ToolIdentity} the hook matches on.
+ * - `toolName`/`mcpServerSlug` are retained for readability, debugging, and the
+ *   structured-vs-token cross-check (the two are always generated together).
  */
 export interface ApprovalGrant {
   toolName: string;
   mcpServerSlug: string;
-  argKey: string;
+  key: string;
+  salient: string;
 }
 
 export interface ApprovalStateFile {
   autoApproveAll: boolean;
-  builtInGatedList: string[];
   mcpToolPolicies: Record<string, McpToolPolicyEntry>;
   approvedGrants: ApprovalGrant[];
   approvedGrantTokens: string[];
@@ -87,17 +125,19 @@ export interface ApprovalStateFile {
 
 /**
  * Compute the flat token the bash hook matches on. The hook recomputes the same
- * token from the incoming tool call (`base64(toolName \n salientArg)`), so the
- * encoding here must stay byte-identical to the hook script in hook-script.ts.
+ * token from the incoming tool call (`base64(key \n salient)` — see
+ * {@link toolIdentity}), so the encoding here must stay byte-identical to the
+ * hook script in hook-script.ts.
  */
-export function grantToken(toolName: string, argKey: string): string {
-  return Buffer.from(`${toolName}\n${argKey}`, "utf-8").toString("base64");
+export function grantToken(key: string, salient: string): string {
+  return Buffer.from(`${key}\n${salient}`, "utf-8").toString("base64");
 }
 
 /**
  * Build approval grants from the pending approvals the user adjudicated and
- * their decisions. Only APPROVE decisions produce grants. Built-in tools are
- * keyed by their salient argument; MCP tools are keyed by name only.
+ * their decisions. Only APPROVE / APPROVE_ALL decisions produce grants. Each
+ * grant carries the canonical {@link ToolIdentity} (category + salient resource)
+ * so the hook allows the exact approved resource on the resumed turn.
  */
 export function buildApprovalGrants(
   pendingApprovals: PendingApproval[],
@@ -113,11 +153,12 @@ export function buildApprovalGrants(
     const decision = decisions.get(pa.toolCallId);
     if (decision !== ApprovalAction.APPROVE && decision !== ApprovalAction.APPROVE_ALL) continue;
 
-    const argKey = pa.mcpServerSlug ? "" : extractArgKey(parseArgs(pa.argsPreview));
+    const id = toolIdentity(pa.toolName, pa.mcpServerSlug, parseArgs(pa.argsPreview));
     grants.push({
       toolName: pa.toolName,
       mcpServerSlug: pa.mcpServerSlug,
-      argKey,
+      key: id.key,
+      salient: id.salient,
     });
   }
   return grants;
@@ -137,11 +178,13 @@ function parseArgs(argsPreview: string): Record<string, unknown> | undefined {
  * Build the approval state file content from merged policies and any approval
  * grants from a previous HITL cycle.
  *
- * The state file drives the hook script's allow/deny decisions:
- * - builtInGatedList: dangerous built-in tools the hook denies (unless granted)
+ * The state file carries the hook script's DYNAMIC inputs:
  * - mcpToolPolicies: per-tool policy for MCP tools requiring approval
  * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
  *   cycle, allowed through on reinvocation
+ *
+ * The static gated built-in set and its category mapping are baked into the
+ * generated hook script (from approval-policy.ts), not carried here.
  */
 export function buildApprovalState(
   mergedPolicies: Map<string, MergedToolPolicy>,
@@ -160,10 +203,9 @@ export function buildApprovalState(
 
   return {
     autoApproveAll,
-    builtInGatedList: getBuiltInGatedList(),
     mcpToolPolicies,
     approvedGrants,
-    approvedGrantTokens: approvedGrants.map((g) => grantToken(g.toolName, g.argKey)),
+    approvedGrantTokens: approvedGrants.map((g) => grantToken(g.key, g.salient)),
   };
 }
 

package/src/activities/execute-cursor/hook-script.ts

@@ -18,59 +18,100 @@
  *
  * The script is self-contained (no Node.js required) for portability. It uses
  * bash + grep/cut for lightweight JSON field extraction. All policy decisions
- * are pre-computed by the runner into the state file; the hook only performs
- * mechanical field extraction and string lookups — the policy itself is
- * authored once in TypeScript (approval-policy.ts / approval-state.ts).
+ * are pre-computed by the runner into the state file (and into this generated
+ * script); the hook only performs mechanical field extraction and string
+ * lookups — the policy itself is authored once in TypeScript (approval-policy.ts
+ * / approval-state.ts).
+ *
+ * Cross-taxonomy identity (the crux):
+ * The preToolUse hook and the SDK event stream name the same operation
+ * differently — the hook receives PascalCase `tool_name` (`Write` for any file
+ * create/edit, `Shell`, `Delete`) while the stream emits lowercase `event.name`
+ * (`edit`, `shell`, `delete`). They also name the salient argument differently
+ * (`file_path` in the hook input vs `path` in the stream). So the hook and the
+ * runner cannot correlate on the raw name. Instead both reduce a tool call to a
+ * canonical identity — `base64(category \n salient)` — where `category` is the
+ * approval category (`write`/`delete`/`shell`, baked into the case statement
+ * below from approval-policy.ts) and `salient` is the resource VALUE (the file
+ * path or shell command), which is identical on both sides. The runner mirrors
+ * this exactly in approval-state.ts (toolIdentity + grantToken), so a denial
+ * recorded here correlates to the streamed tool call, and an approval grant
+ * matches the agent's re-attempt on reinvocation.
  *
  * Policy evaluation order (first match wins). The model is "gate the dangerous
  * set, allow the rest" — matching the native harness and avoiding denial of
  * auto-approved MCP tools (which are absent from mcpToolPolicies):
  * 1. autoApproveAll → allow
- * 2. Matches an approved grant token → allow (reinvocation after approval)
- * 3. Tool name in builtInGatedList → deny
- * 4. Tool name in mcpToolPolicies (require-approval) → deny
- * 5. Everything else (read-only built-ins, auto-approved MCP, unknown) → allow
+ * 2. Gated built-in (category non-empty):
+ *    a. identity token in approvedGrantTokens → allow (reinvocation grant)
+ *    b. otherwise → record denial, deny
+ * 3. MCP tool present in mcpToolPolicies (require-approval):
+ *    a. name token in approvedGrantTokens → allow
+ *    b. otherwise → record denial, deny
+ * 4. Everything else (read-only built-ins, auto-approved MCP, unknown) → allow
  */
 
-import { SALIENT_ARG_FIELDS } from "./approval-policy.js";
+import { SALIENT_ARG_FIELDS, getBuiltInGatedCategories } from "./approval-policy.js";
 
 const APPROVAL_REQUIRED_AGENT_MESSAGE =
   "STIGMER_APPROVAL_REQUIRED: This tool call requires user approval before " +
-  "execution. Do not attempt alternative approaches or workarounds. The " +
-  "execution will resume after the user reviews and approves this tool call.";
+  "execution. Do not attempt alternative approaches or workarounds (including " +
+  "shell commands). Stop and wait — the execution will resume after the user " +
+  "reviews and approves this tool call.";
+
+/**
+ * Build the bash `case` arms that map an incoming hook `tool_name` to its
+ * canonical approval category. Generated from approval-policy.ts so the hook and
+ * the runner never disagree on which built-ins are gated or how they categorize.
+ */
+function buildCategoryCaseArms(): string {
+  const byCategory = new Map<string, string[]>();
+  for (const [name, category] of getBuiltInGatedCategories()) {
+    const names = byCategory.get(category) ?? [];
+    names.push(name);
+    byCategory.set(category, names);
+  }
+  const arms: string[] = [];
+  for (const [category, names] of byCategory) {
+    const pattern = names.map((n) => `"${n}"`).join("|");
+    arms.push(`    ${pattern}) CATEGORY="${category}" ;;`);
+  }
+  return arms.join("\n");
+}
 
 /**
  * Generates the bash hook script content.
  *
  * The script reads a JSON state file written by the cursor-runner before
  * each agent.send() call. The state file is the single source of truth
- * for all approval decisions.
+ * for the dynamic approval inputs (autoApproveAll, mcpToolPolicies,
+ * approvedGrantTokens). The static policy (which built-ins are gated and their
+ * categories, and which arg fields are salient) is baked into the script at
+ * generation time from approval-policy.ts.
  *
- * Approved grants are matched by a base64 token of `toolName \n salientArg`,
- * recomputed here from the incoming tool call. The salient-arg field list is
- * injected from SALIENT_ARG_FIELDS so the runner and the hook never disagree on
- * which argument identifies the resource. The encoding must stay byte-identical
+ * The identity token encoding (`base64(key \n salient)`) must stay byte-identical
  * to grantToken() in approval-state.ts.
  */
 export function generateHookScript(stateFilePath: string, ledgerFilePath: string): string {
   const salientFields = SALIENT_ARG_FIELDS.join(" ");
+  const categoryCaseArms = buildCategoryCaseArms();
   return `#!/bin/bash
 # Stigmer HITL approval hook for Cursor preToolUse
 # Generated by cursor-runner — do not edit manually.
 #
-# Reads tool call from stdin (JSON), checks approval state file,
-# returns permission decision on stdout (JSON). On a deny, appends the call's
+# Reads tool call from stdin (JSON), checks approval state file, returns a
+# permission decision on stdout (JSON). On a deny, appends the call's canonical
 # identity token to the denial ledger so the runner can mark the gated tool call
-# as WAITING_APPROVAL.
+# as WAITING_APPROVAL. See hook-script.ts for the cross-taxonomy identity design.
 
 set -euo pipefail
 
 INPUT=$(cat)
 
-# Extract tool_name from the hook input JSON.
-# Cursor sends the actual tool name (e.g. "search_services" for MCP tools).
-# Every extraction ends with '|| true': under 'set -e' a non-matching grep would
-# otherwise abort the script and emit no decision.
+# Extract tool_name from the hook input JSON. The hook receives PascalCase names
+# (Write/Shell/Delete/Read/...). Every extraction ends with '|| true': under
+# 'set -e' a non-matching grep would otherwise abort the script and emit no
+# decision.
 TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
 
 STATE_FILE="${stateFilePath}"
@@ -90,66 +131,67 @@ if echo "$STATE" | grep -q '"autoApproveAll":true'; then
   exit 0
 fi
 
-# --- 2. Approved grants (reinvocation after SubmitApproval) ---
-# Build the same base64 token the runner stored for an approved tool call and
-# match it against approvedGrantTokens. Match by (name + salient arg); fall back
-# to name-only for grants with no salient arg (MCP tools). Salient-arg field
-# order is injected from SALIENT_ARG_FIELDS (single source of truth).
-TOKEN_NAME=$(printf '%s\\n' "$TOOL_NAME" | base64 | tr -d '\\n')
-if echo "$STATE" | grep -q "\\"$TOKEN_NAME\\""; then
-  echo '{"permission":"allow"}'
-  exit 0
-fi
+# --- Salient resource value (file path / command), spanning both taxonomies'
+# arg field names (file_path here, path on the stream side). First match wins. ---
 SALIENT=""
 for field in ${salientFields}; do
   v=$(echo "$INPUT" | grep -o "\\"$field\\":\\"[^\\"]*\\"" | head -1 | cut -d'"' -f4 || true)
   if [ -n "$v" ]; then SALIENT="$v"; break; fi
 done
-if [ -n "$SALIENT" ]; then
-  TOKEN_SALIENT=$(printf '%s\\n%s' "$TOOL_NAME" "$SALIENT" | base64 | tr -d '\\n')
-  if echo "$STATE" | grep -q "\\"$TOKEN_SALIENT\\""; then
-    echo '{"permission":"allow"}'
-    exit 0
-  fi
-fi
 
-# Identity token recorded on a deny so the runner can correlate the gated call
-# back to its streamed tool call. Prefer the salient-arg token (identifies the
-# specific resource); fall back to name-only. Byte-identical to grantToken().
-if [ -n "$SALIENT" ]; then DENY_TOKEN="$TOKEN_SALIENT"; else DENY_TOKEN="$TOKEN_NAME"; fi
+# --- Canonical approval category for this hook tool_name (baked from
+# approval-policy.ts). Empty for non-gated tools. ---
+CATEGORY=""
+case "$TOOL_NAME" in
+${categoryCaseArms}
+    *) CATEGORY="" ;;
+esac
 
 # Append a denial record to the ledger. Best-effort: a ledger write failure must
 # never abort the decision (the deny still goes out on stdout). toolName is raw
 # for human-readable debugging; token drives correlation in the runner.
 record_denial() {
-  echo '{"toolName":"'"$TOOL_NAME"'","token":"'"$DENY_TOKEN"'"}' >> "$LEDGER_FILE" 2>/dev/null || true
+  echo '{"toolName":"'"$TOOL_NAME"'","token":"'"$1"'"}' >> "$LEDGER_FILE" 2>/dev/null || true
 }
 
-# --- 3. Gated built-in tools (Write, StrReplace, Shell, ...) → deny ---
-GATED_LIST=$(echo "$STATE" | grep -o '"builtInGatedList":\\[[^]]*\\]' | head -1 || true)
-if [ -n "$GATED_LIST" ] && [ -n "$TOOL_NAME" ] && echo "$GATED_LIST" | grep -q "\\"$TOOL_NAME\\""; then
-  record_denial
+# --- 2. Gated built-in tools (category non-empty) ---
+if [ -n "$CATEGORY" ]; then
+  # Canonical identity token: base64("$CATEGORY\\n$SALIENT").
+  TOKEN=$(printf '%s\\n%s' "$CATEGORY" "$SALIENT" | base64 | tr -d '\\n')
+  # Reinvocation grant: this exact resource was approved earlier → allow.
+  if echo "$STATE" | grep -qF "\\"$TOKEN\\""; then
+    echo '{"permission":"allow"}'
+    exit 0
+  fi
+  record_denial "$TOKEN"
   echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"Tool requires approval: '"$TOOL_NAME"'"}'
   exit 0
 fi
 
-# --- 4. MCP tools that require approval → deny ---
+# --- 3. MCP tools that require approval → deny ---
 # mcpToolPolicies holds only require-approval tools (auto-approved MCP tools are
-# absent), so presence means "deny" unless an entry is explicitly false.
+# absent), so presence means "deny" unless an entry is explicitly false. MCP tool
+# names are consistent across the hook and the stream, so the identity token is
+# name-only: base64("$TOOL_NAME\\n").
 if echo "$STATE" | grep -q "\\"mcpToolPolicies\\"" && [ -n "$TOOL_NAME" ]; then
   TOOL_POLICY=$(echo "$STATE" | grep -o "\\"$TOOL_NAME\\":{[^}]*}" | head -1 || true)
   if [ -n "$TOOL_POLICY" ] && ! echo "$TOOL_POLICY" | grep -q '"requiresApproval":false'; then
+    MCP_TOKEN=$(printf '%s\\n' "$TOOL_NAME" | base64 | tr -d '\\n')
+    if echo "$STATE" | grep -qF "\\"$MCP_TOKEN\\""; then
+      echo '{"permission":"allow"}'
+      exit 0
+    fi
     MSG=$(echo "$TOOL_POLICY" | grep -o '"message":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
     if [ -z "$MSG" ]; then
       MSG="Tool requires approval: $TOOL_NAME"
     fi
-    record_denial
+    record_denial "$MCP_TOKEN"
     echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"'"$MSG"'"}'
     exit 0
   fi
 fi
 
-# --- 5. Everything else → allow ---
+# --- 4. Everything else → allow ---
 # Read-only built-ins, auto-approved MCP tools, and anything not explicitly
 # gated. Fail-open mirrors the native harness (gate the dangerous set, allow the
 # rest) and prevents denying auto-approved MCP tools the state cannot enumerate.