@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

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

@@ -54,23 +54,45 @@
  * recorded here correlates to the streamed tool call, and an approval grant
  * matches the agent's re-attempt on reinvocation.
  *
+ * Content-exact identity (the sibling-hole fix): for a file edit the coarse
+ * (category, salient) is not enough — approving one edit to a file must not let
+ * a DIFFERENT edit to the SAME file ride through. So the hook ALSO computes a
+ * CONTENT token `base64(category \n salient \n contentDigest)`, where
+ * contentDigest is a sha256 over the edit content (mirror of file-tools.ts
+ * contentDigest; see buildContentDigestScript). It allows a built-in when EITHER
+ * the content token (a file edit approved with this exact content) OR the coarse
+ * token (shell/delete, or a content-less degrade) is granted, and records the
+ * content token as the denial identity. The runner grants the content token when
+ * it has the approved content (the persisted approval_content_digest), so a
+ * sibling edit re-gates; it degrades to the coarse grant only when the content is
+ * unrecoverable.
+ *
  * 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):
  * 0. Scope guard: not the runner's own agent → allow (never touch the ledger)
- * 1. Missing state file → deny (fail-closed); autoApproveAll → allow
+ * 1. Missing state file → deny (fail-closed); autoApproveAll (the pre-armed
+ *    spec.auto_approve_all global bypass) → allow
  * 2. beforeMCPExecution event → MCP tool present in mcpToolPolicies
  *    (require-approval):
  *    a. name token in approvedGrantTokens → allow (reinvocation grant)
  *    b. otherwise → record denial, deny
- *    (auto-approved / unlisted MCP tools fall through → allow)
+ *    (auto-approved / unlisted MCP tools fall through → allow; a server-scoped
+ *     lease drops the server's tools from mcpToolPolicies, so they fall through)
  * 3. preToolUse event → gated built-in (category non-empty):
  *    a. identity token in approvedGrantTokens → allow (reinvocation grant)
- *    b. otherwise → record denial, deny
+ *    b. category in leasedCategories → allow (run-lifetime scoped lease)
+ *    c. otherwise → record denial, deny
  *    (read-only / ungated built-ins fall through → allow)
  */
 
 import { SALIENT_ARG_FIELDS, getBuiltInGatedCategories } from "./approval-policy.js";
+import {
+  EDIT_OLD_FIELDS,
+  EDIT_NEW_FIELDS,
+  WRITE_CONTENT_FIELDS,
+} from "../../shared/file-tools.js";
+import { buildObservationStagingScript, CAS_OBSERVATIONS_DIRNAME } from "./cas-observations.js";
 
 // Shown to the model when the gate denies a tool call. It must NOT teach the
 // model to ask for permission in prose or to "stop and wait" — that framing
@@ -83,9 +105,24 @@ import { SALIENT_ARG_FIELDS, getBuiltInGatedCategories } from "./approval-policy
 // quotes, apostrophes, or backslashes.
 const APPROVAL_REQUIRED_AGENT_MESSAGE =
   "This action has been submitted to the user for approval automatically; you " +
-  "do not need to ask for permission. Do not retry it or attempt a workaround " +
-  "for this action. The platform will resume you automatically after the user " +
-  "responds — continue with the rest of the task.";
+  "do not need to ask for permission. This is the platform approval gate working " +
+  "as intended — it is not an error and not a Cursor misconfiguration, so never " +
+  "tell the user to change Cursor settings or enable hooks. Do not retry it or " +
+  "attempt a workaround for this action. The platform will resume you " +
+  "automatically after the user responds — continue with the rest of the task.";
+
+// Shown to the model when a secret-like gitignored write is hard-blocked (DD-E /
+// DD-18). Unlike APPROVAL_REQUIRED_AGENT_MESSAGE, this must NOT promise a resume:
+// the write is discarded and never captured for review, so the model must move on
+// rather than wait or retry. Same embedding constraint (single-quoted bash echo
+// of a JSON object): no double quotes, apostrophes, or backslashes.
+const SECRET_BLOCKED_AGENT_MESSAGE =
+  "This file was blocked for security because its path matches a secret-like " +
+  "pattern Stigmer will not capture for review. Nothing was written. This is the " +
+  "platform safety gate working as intended — it is not an error and not a Cursor " +
+  "misconfiguration, so never tell the user to change Cursor settings or enable " +
+  "hooks. Do not retry this write or attempt a workaround; the write will not be " +
+  "applied. Continue with the rest of the task.";
 
 /**
  * Build the bash `case` arms that map an incoming hook `tool_name` to its
@@ -107,20 +144,53 @@ function buildCategoryCaseArms(): string {
   return arms.join("\n");
 }
 
+/**
+ * Build the inline content-digest extractor — a BYTE-IDENTICAL MIRROR of
+ * {@link file://../../shared/file-tools.ts} `contentDigest()`.
+ *
+ * Computes the same `sha256(JSON.stringify(["w", content]))` /
+ * `sha256(JSON.stringify(["e", old, new]))` from the parsed tool_input `a`,
+ * using the SAME union field lists injected from file-tools.ts (so the
+ * file_path/path & content/contents cross-layer name divergence is normalized
+ * identically) and the SAME Node binary as the runner — so the hook-side and
+ * runner-side digests agree. Any change to the format here or in
+ * file-tools.ts MUST be mirrored in the other. Empty (`dig===""`) for a tool
+ * with no edit content (shell/delete/read/MCP).
+ *
+ * Authored as part of a single-quoted bash string, so the JS must not contain
+ * single quotes (JSON.stringify emits double quotes).
+ */
+function buildContentDigestScript(): string {
+  const wc = JSON.stringify(WRITE_CONTENT_FIELDS);
+  const eo = JSON.stringify(EDIT_OLD_FIELDS);
+  const en = JSON.stringify(EDIT_NEW_FIELDS);
+  return [
+    `const pick=(fl)=>{for(const f of fl){const v=a[f];if(typeof v==="string")return v;}return null;};`,
+    `const sha=(x)=>require("crypto").createHash("sha256").update(x,"utf8").digest("hex");`,
+    `let dig="";`,
+    `const _wc=pick(${wc});`,
+    `if(_wc!==null){dig=sha(JSON.stringify(["w",_wc]));}`,
+    `else{const _o=pick(${eo}),_n=pick(${en});if(_o!==null||_n!==null){dig=sha(JSON.stringify(["e",_o===null?"":_o,_n===null?"":_n]));}}`,
+  ].join("");
+}
+
 /**
  * Build the inline Node.js identity extractor embedded in the hook script.
  *
  * Parses the hook's stdin JSON properly (the bash fallback's grep truncates
- * string values at the first escaped quote) and emits five lines: tool_name,
- * canonical category, identity token, MCP name-token, and hook_event_name (the
- * event discriminator: `preToolUse` for built-ins, `beforeMCPExecution` for MCP).
- * The token encodings must stay byte-identical to grantToken() in
- * approval-state.ts.
+ * string values at the first escaped quote) and emits SEVEN lines: tool_name,
+ * canonical category, coarse identity token, MCP name-token, hook_event_name
+ * (the event discriminator: `preToolUse` for built-ins, `beforeMCPExecution`
+ * for MCP), base64(JSON(tool_input)) — the authoritative pre-execution args the
+ * runner overlays onto the gated tool call for the approval preview — and the
+ * CONTENT token (base64(category \n salient \n contentDigest), empty when the
+ * tool has no edit content). The token encodings must stay byte-identical to
+ * grantToken()/contentToken() in approval-state.ts.
  *
  * Authored as a single-quoted bash string, so the JS must not contain single
- * quotes. The category map and salient field list are baked from
- * approval-policy.ts — the same source the runner uses — so the two sides can
- * never disagree.
+ * quotes. The category map, salient field list, and edit/content field lists are
+ * baked from approval-policy.ts / file-tools.ts — the same source the runner
+ * uses — so the two sides can never disagree.
  */
 function buildNodeIdentityScript(): string {
   const categoryMap: Record<string, string> = {};
@@ -133,51 +203,79 @@ function buildNodeIdentityScript(): string {
     `const t=JSON.parse(require("fs").readFileSync(0,"utf8"));`,
     `const name=typeof t.tool_name==="string"?t.tool_name:"";`,
     `const cat=(${categories})[name]||"";`,
-    `const a=(t.tool_input&&typeof t.tool_input==="object")?t.tool_input:{};`,
+    // tool_input is an object for built-ins (preToolUse) but a JSON STRING for
+    // MCP tools (beforeMCPExecution). Parse the string form so the captured
+    // input is the same object shape on both paths.
+    `let a={};`,
+    `if(t.tool_input&&typeof t.tool_input==="object"){a=t.tool_input;}`,
+    `else if(typeof t.tool_input==="string"){try{const p=JSON.parse(t.tool_input);if(p&&typeof p==="object")a=p;}catch(e){}}`,
     `let s="";`,
     `for(const f of ${fields}){const v=a[f];if(typeof v==="string"&&v){s=v;break;}}`,
     `const b=(x)=>Buffer.from(x,"utf8").toString("base64");`,
+    // Content digest of the edit (mirror of file-tools.ts contentDigest); `dig`
+    // is "" for a non-edit tool, in which case the content token (line 7) is "".
+    buildContentDigestScript(),
     `const ev=typeof t.hook_event_name==="string"?t.hook_event_name:"";`,
-    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n")+"\\n"+ev);`,
+    // Line 6 is base64(JSON(tool_input)): the AUTHORITATIVE pre-execution args
+    // the runner overlays onto the gated tool call so the approval card can show
+    // the proposed change before the user approves. Base64 keeps the bash side
+    // free of quoting/escaping concerns even for large multi-line file content.
+    // Line 7 is the CONTENT token (empty when no digest) — the exact-identity
+    // grant the runner authorizes for a file edit. Line 8 is base64(salient) —
+    // the raw resource value (file path / command) capture mode needs to run
+    // `git check-ignore` on a file path; base64 keeps newlines/quotes out of the
+    // line-oriented bash parse.
+    `process.stdout.write(name+"\\n"+cat+"\\n"+b(cat+"\\n"+s)+"\\n"+b(name+"\\n")+"\\n"+ev+"\\n"+b(JSON.stringify(a))+"\\n"+(dig?b(cat+"\\n"+s+"\\n"+dig):"")+"\\n"+b(s));`,
   ].join("");
 }
 
 /**
- * Generates the bash hook script content.
+ * Generates the STABLE bash hook script content.
+ *
+ * The script is STABLE across executions in a runner process — its only inputs
+ * are the absolute path of the active-turn pointer (and the runner's Node
+ * binary), both constant for a given workspace. This is deliberate and
+ * load-bearing: the Cursor SDK loads `<workspace>/.cursor/hooks.json` (the hook
+ * script PATH) ONCE per runner process and caches it, ignoring later
+ * per-execution rewrites. A per-session script with per-session baked paths
+ * therefore gets cached at the FIRST execution and reused for every later one,
+ * recording their denials into the FIRST session's ledger while each later runner
+ * reads its own (empty) ledger and silently completes — the no-approval-button /
+ * "execution completed" regression. Keeping the script stable and resolving the
+ * CURRENT turn's artifacts from the pointer (which bash re-reads every
+ * invocation; see {@link ActiveTurnPointer}/writeActiveTurnPointer) makes a
+ * long-lived multi-session runner correct.
  *
- * 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 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.
+ * From the pointer the script reads the current turn's approval-state file (the
+ * single source of truth for the dynamic inputs: autoApproveAll, leasedCategories,
+ * mcpToolPolicies, approvedGrantTokens), denial ledger, and runner PID. The
+ * static policy (which built-ins are gated, their categories, the salient arg
+ * fields) is baked at generation time from approval-policy.ts.
  *
  * The identity token encoding (`base64(key \n salient)`) must stay byte-identical
  * to grantToken() in approval-state.ts.
  *
  * Scope guard (the crux of issue #173): the Cursor SDK loads project hooks from
- * `<workspace>/.cursor/hooks.json`, which is the SAME per-repo surface every
- * Cursor client reads. When a session runs against the user's real repo, the
- * user's own interactive Cursor IDE would otherwise load and run this hook too —
- * gating the IDE, polluting the denial ledger with the IDE's tool calls, and (in
- * multi-root windows) failing closed. We make the gate apply ONLY to the
- * runner's own agent by baking in the runner process PID and checking, on every
- * invocation, whether the runner is an ancestor of the hook process. The SDK
- * runs hooks in-process via child_process, so the runner's own agent (and its
- * delegated sub-agents) spawn the hook as a descendant of the runner; any other
- * Cursor client spawns it under a different process tree. A non-descendant
- * invocation is allowed immediately and never touches the ledger. This also
- * makes a leftover hooks.json self-neutralizing: once the runner exits, no
- * invocation can match its (now-dead) PID, so the gate is inert.
+ * `<workspace>/.cursor/hooks.json`, the SAME per-repo surface every Cursor client
+ * reads. When a session runs against the user's real repo, the user's own
+ * interactive Cursor IDE would otherwise load and run this hook too — gating the
+ * IDE, polluting the denial ledger, and (in multi-root windows) failing closed.
+ * We make the gate apply ONLY to the runner's own agent by checking, on every
+ * invocation, whether the runner PID (FROM THE POINTER) is an ancestor of the
+ * hook process. The SDK runs hooks in-process via child_process, so the runner's
+ * own agent (and its delegated sub-agents) spawn the hook as a descendant of the
+ * runner; any other Cursor client spawns it under a different process tree. A
+ * non-descendant invocation is allowed immediately and never touches the ledger.
+ * Combined with pointer teardown, a leftover hooks.json is self-neutralizing:
+ * once the turn ends (pointer removed) or the runner exits (PID dead), no
+ * invocation gates, so the gate is inert.
  */
-export function generateHookScript(
-  stateFilePath: string,
-  ledgerFilePath: string,
-  runnerPid: number,
-): string {
+export function generateHookScript(activePointerPath: string, workspaceRoot = ""): string {
   const salientFields = SALIENT_ARG_FIELDS.join(" ");
   const categoryCaseArms = buildCategoryCaseArms();
   const nodeIdentityScript = buildNodeIdentityScript();
+  const observationStagingScript = buildObservationStagingScript();
+  const nodeBin = process.execPath;
   return `#!/bin/bash
 # Stigmer HITL approval hook for Cursor (preToolUse + beforeMCPExecution).
 # Generated by cursor-runner — do not edit manually.
@@ -193,9 +291,47 @@ set -euo pipefail
 
 INPUT=$(cat)
 
-STATE_FILE="${stateFilePath}"
-LEDGER_FILE="${ledgerFilePath}"
-RUNNER_PID="${runnerPid}"
+NODE_BIN="${nodeBin}"
+ACTIVE_FILE="${activePointerPath}"
+# Baked workspace root for capture-mode's gitignore check (empty in unit tests
+# that don't exercise capture mode; the check then falls back to the path's dir).
+GIT_ROOT="${workspaceRoot}"
+
+# --- Resolve the CURRENT turn from the runner-written pointer ----------------
+# The Cursor SDK caches .cursor/hooks.json (the hook script PATH) for the runner
+# process, so THIS script is stable across executions and the per-turn pointer
+# (active.json) — which bash re-reads on every invocation — is the only thing
+# that changes. It names the CURRENT turn's approval-state, denial ledger, and
+# runner PID. This indirection is what makes a long-lived runner correct: a
+# per-session script baked with per-session paths would be cached at the FIRST
+# execution and reused for every later one, recording their denials to the FIRST
+# session's ledger while each later runner reads its own empty ledger and
+# silently completes (the no-approval-button / "completed" regression).
+#
+# A missing/garbled pointer means no active Stigmer turn (between turns, after
+# teardown, or a dead runner) -> allow (inert), matching the
+# leftover-hooks.json-is-inert invariant (issue #173).
+if [ ! -f "$ACTIVE_FILE" ]; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+PTR=$(ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e 'const p=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));process.stdout.write((p.stateFile||"")+"\\n"+(p.ledgerFile||"")+"\\n"+((p.runnerPid==null)?"":String(p.runnerPid)))' "$ACTIVE_FILE" 2>/dev/null || true)
+if [ -n "$PTR" ]; then
+  STATE_FILE=$(printf '%s\\n' "$PTR" | sed -n 1p)
+  LEDGER_FILE=$(printf '%s\\n' "$PTR" | sed -n 2p)
+  RUNNER_PID=$(printf '%s\\n' "$PTR" | sed -n 3p)
+else
+  # Node unavailable: the pointer holds plain ~/.stigmer paths and an integer
+  # (no JSON-escaped quotes), so grep/cut is reliable here.
+  STATE_FILE=$(grep -o '"stateFile":"[^"]*"' "$ACTIVE_FILE" | head -1 | cut -d'"' -f4 || true)
+  LEDGER_FILE=$(grep -o '"ledgerFile":"[^"]*"' "$ACTIVE_FILE" | head -1 | cut -d'"' -f4 || true)
+  RUNNER_PID=$(grep -o '"runnerPid":[0-9]*' "$ACTIVE_FILE" | head -1 | cut -d: -f2 || true)
+fi
+if [ -z "$RUNNER_PID" ]; then
+  # Pointer unreadable -> no scope owner to gate for; stay inert.
+  echo '{"permission":"allow"}'
+  exit 0
+fi
 
 # --- Scope guard: gate ONLY the runner's own agent (issue #173) -------------
 # The Cursor SDK runs hooks in-process, so the runner's own agent invocations
@@ -230,14 +366,31 @@ if ! __stigmer_is_own_agent; then
   exit 0
 fi
 
+# --- Capture-mode helper: is a path gitignored? -----------------------------
+# In capture mode the runner snapshots the working tree with git and reconciles
+# it to the user's per-file decisions on resume, but a gitignored path (e.g.
+# .env, build output) is invisible to that snapshot — so it can be neither
+# captured for review nor reverted on reject. Such writes/deletes therefore stay
+# on the deny-gate. Returns 0 (true) when the path is ignored. A non-git context
+# or a missing path returns non-zero (treated as not-ignored -> allow).
+__stigmer_is_gitignored() {
+  _p="$1"
+  [ -z "$_p" ] && return 1
+  if [ -n "$GIT_ROOT" ]; then
+    git -C "$GIT_ROOT" check-ignore -q -- "$_p" 2>/dev/null
+  else
+    git -C "$(dirname "$_p")" check-ignore -q -- "$_p" 2>/dev/null
+  fi
+}
+
 # --- Canonical identity: tool_name / category / identity token / MCP token ---
 # Computed by the same Node.js binary that runs the cursor-runner (absolute path
 # baked at generation time) so JSON string values — file paths and especially
 # shell commands containing quotes, newlines, or unicode escapes — decode to the
 # exact bytes the runner sees in the stream event. ELECTRON_RUN_AS_NODE makes
 # the invocation safe when the runner is embedded in an Electron app (where
-# process.execPath is the Electron binary).
-NODE_BIN="${process.execPath}"
+# process.execPath is the Electron binary). NODE_BIN is defined once near the top
+# (it also parses the active-turn pointer).
 IDENTITY=$(printf '%s' "$INPUT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${nodeIdentityScript}' 2>/dev/null || true)
 if [ -n "$IDENTITY" ]; then
   TOOL_NAME=$(printf '%s\\n' "$IDENTITY" | sed -n 1p)
@@ -245,6 +398,16 @@ if [ -n "$IDENTITY" ]; then
   TOKEN=$(printf '%s\\n' "$IDENTITY" | sed -n 3p)
   MCP_TOKEN=$(printf '%s\\n' "$IDENTITY" | sed -n 4p)
   HOOK_EVENT=$(printf '%s\\n' "$IDENTITY" | sed -n 5p)
+  # base64(JSON(tool_input)) — the authoritative args the runner overlays onto
+  # the gated tool call. A single unwrapped base64 line (Node does not wrap), so
+  # sed reads it whole even for large file content.
+  INPUT_B64=$(printf '%s\\n' "$IDENTITY" | sed -n 6p)
+  # Content token (base64 of category\\nsalient\\ndigest), empty for a non-edit
+  # tool. The exact-identity grant the runner authorizes for a file edit.
+  CONTENT_TOKEN=$(printf '%s\\n' "$IDENTITY" | sed -n 7p)
+  # Raw salient (base64) — the file path / command. Capture mode decodes it to
+  # run git check-ignore on a file path.
+  SALIENT=$(printf '%s\\n' "$IDENTITY" | sed -n 8p | base64 -d 2>/dev/null || true)
 else
   # Fallback when the Node binary cannot run: grep/cut extraction. Best-effort
   # only — '"field":"[^"]*"' truncates at the first JSON-escaped quote, so the
@@ -266,6 +429,11 @@ ${categoryCaseArms}
   esac
   TOKEN=$(printf '%s\\n%s' "$CATEGORY" "$SALIENT" | base64 | tr -d '\\n')
   MCP_TOKEN=$(printf '%s\\n' "$TOOL_NAME" | base64 | tr -d '\\n')
+  # The grep fallback cannot reliably capture full multi-line tool_input, so the
+  # gated call degrades to today's stream-recovered args (no authoritative input)
+  # and cannot compute a content digest — the coarse token is the only identity.
+  INPUT_B64=""
+  CONTENT_TOKEN=""
 fi
 
 # --- Failsafe: missing state file → deny (fail-closed) ---
@@ -276,6 +444,66 @@ fi
 
 STATE=$(cat "$STATE_FILE")
 
+# Capture mode (git workspaces): file mutations flow during the turn and are
+# captured/gated per-file by the runner at the turn boundary (see
+# shared/filereview/git-substrate.ts). Read once; consulted only in the
+# gated-built-in arm below.
+CAPTURE_MODE=false
+if echo "$STATE" | grep -q '"captureMode":true'; then
+  CAPTURE_MODE=true
+fi
+# CAS capture of gitignored writes (the deep-agent parity switch). Set only when
+# capture mode is on AND an artifact storage is configured (to persist blobs). It
+# governs whether a non-secret gitignored write is staged+flowed for review vs.
+# kept on the deny-gate. Read here; consulted only in the gitignored-capture arm
+# below, which runs BEFORE auto-approve-all (capture is a turn property).
+CAPTURE_IGNORED=false
+if echo "$STATE" | grep -q '"captureIgnored":true'; then
+  CAPTURE_IGNORED=true
+fi
+# gitWorkspace selects the capture substrate (Slice 2c). Default true when the
+# key is absent (older state files). When false the workspace is NOT a git tree:
+# there is no git snapshot, so EVERY file write is CAS-staged below (not only
+# gitignored ones), the git-tracked flow arm is skipped, and a delete stays gated
+# (no CAS delete-capture path, parity with the deep-agent).
+GIT_WORKSPACE=true
+if echo "$STATE" | grep -q '"gitWorkspace":false'; then
+  GIT_WORKSPACE=false
+fi
+
+# --- Capture mode: observe CAS-owned writes for review ----------------------
+# Runs BEFORE the auto-approve-all shortcut and the grant/lease checks because
+# capture is a property of the TURN, not authorization: a non-secret CAS-owned
+# write must be staged and reviewed even under the global bypass, and a
+# secret-like one must be hard-blocked in every mode. WHICH writes are CAS-owned
+# depends on the substrate: in a git tree it is only the GITIGNORED writes (git
+# captures the tracked ones); in a NON-GIT workspace it is EVERY write (there is
+# no git snapshot). Only a built-in write/edit (category "write") takes this arm;
+# deletes and shell/MCP stay on the deny-gate below (parity with the deep-agent
+# approval gate). The staging runs on the runner's own Node binary (the
+# disk-backed mirror of CasCaptureFilesystemBackend.recordBefore): the salient
+# path rides stdin (no argv escaping), the workspace root and the per-turn
+# cas-observations dir ride argv. "captured" -> allow (apply-then-review);
+# "secret" -> hard-block; "error"/Node-unavailable -> fail closed (deny, since a
+# write we cannot capture cannot be reviewed).
+if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "write" ] && [ -n "$SALIENT" ] && { [ "$GIT_WORKSPACE" = "false" ] || __stigmer_is_gitignored "$SALIENT"; }; then
+  OBS_DIR="$(dirname "$STATE_FILE")/${CAS_OBSERVATIONS_DIRNAME}"
+  OBS_RESULT=$(printf '%s' "$SALIENT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${observationStagingScript}' "$GIT_ROOT" "$OBS_DIR" 2>/dev/null || echo error)
+  if [ "$OBS_RESULT" = "captured" ]; then
+    echo '{"permission":"allow"}'
+    exit 0
+  elif [ "$OBS_RESULT" = "secret" ]; then
+    echo '{"permission":"deny","agent_message":"${SECRET_BLOCKED_AGENT_MESSAGE}","user_message":"Blocked for security: this file matches a secret-like path and was not written or captured for review."}'
+    exit 0
+  else
+    # Node unavailable or a staging error: fail closed. A gitignored write we
+    # cannot stage cannot be captured for review, so keep gating it (today's
+    # behavior) rather than letting unreviewable bytes flow.
+    echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"Tool requires approval: '"$TOOL_NAME"'"}'
+    exit 0
+  fi
+fi
+
 # --- 1. Auto-approve all ---
 if echo "$STATE" | grep -q '"autoApproveAll":true'; then
   echo '{"permission":"allow"}'
@@ -284,9 +512,13 @@ fi
 
 # 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.
+# for human-readable debugging; token drives correlation in the runner; input is
+# base64(JSON(tool_input)) — the authoritative pre-execution args the runner
+# overlays for the approval preview (empty on the grep fallback path). Written
+# with printf (a builtin, so no ARG_MAX limit) because the input can be a large
+# multi-MB file body.
 record_denial() {
-  echo '{"toolName":"'"$TOOL_NAME"'","token":"'"$1"'"}' >> "$LEDGER_FILE" 2>/dev/null || true
+  printf '{"toolName":"%s","token":"%s","input":"%s"}\\n' "$TOOL_NAME" "$1" "$INPUT_B64" >> "$LEDGER_FILE" 2>/dev/null || true
 }
 
 # --- 2. MCP tools (beforeMCPExecution event) ---
@@ -321,12 +553,46 @@ fi
 
 # --- 3. Gated built-in tools (preToolUse event, category non-empty) ---
 if [ -n "$CATEGORY" ]; then
-  # Reinvocation grant: this exact resource was approved earlier → allow.
-  if echo "$STATE" | grep -qF "\\"$TOKEN\\""; then
+  # Capture mode (GIT tree only): a git-tracked file mutation (write/edit/delete)
+  # flows freely — the runner captures the whole change set with git at the turn
+  # boundary and gates it per-file for review. A gitignored path is invisible to
+  # that git snapshot: a non-secret gitignored WRITE was already handled above
+  # (staged + allowed, or hard-blocked) when captureIgnored is on; here it only
+  # reaches the deny-gate when captureIgnored is off (no artifact storage) or it is
+  # a gitignored DELETE (no CAS capture path, parity with deep-agent). shell
+  # (category "shell") never takes this branch and stays gated as always. In a
+  # NON-GIT workspace this arm is skipped entirely (there is no git diff): writes
+  # were CAS-staged above and a delete falls through to the deny-gate.
+  if [ "$CAPTURE_MODE" = "true" ] && [ "$GIT_WORKSPACE" = "true" ] && { [ "$CATEGORY" = "write" ] || [ "$CATEGORY" = "delete" ]; }; then
+    if ! __stigmer_is_gitignored "$SALIENT"; then
+      echo '{"permission":"allow"}'
+      exit 0
+    fi
+  fi
+  # Reinvocation grant: allow when the CONTENT-exact token (a file edit approved
+  # earlier with this exact content) OR the COARSE token (a shell/delete, or the
+  # content-less degrade) is in approvedGrantTokens. A sibling edit to the same
+  # file has a different content token and no coarse grant, so it re-gates.
+  if { [ -n "$CONTENT_TOKEN" ] && echo "$STATE" | grep -qF "\\"$CONTENT_TOKEN\\""; } || echo "$STATE" | grep -qF "\\"$TOKEN\\""; then
     echo '{"permission":"allow"}'
     exit 0
   fi
-  record_denial "$TOKEN"
+  # Run-lifetime category lease: the user chose "approve all <category>" earlier
+  # in this run (the scoped successor to autoApproveAll), so every built-in of
+  # this category is allowed for the rest of the run. Matched within the extracted
+  # leasedCategories array so a category word elsewhere in the state can't grant.
+  LEASED_CATEGORIES=$(echo "$STATE" | grep -o '"leasedCategories":\\[[^]]*\\]' | head -1 || true)
+  if [ -n "$LEASED_CATEGORIES" ] && echo "$LEASED_CATEGORIES" | grep -q "\\"$CATEGORY\\""; then
+    echo '{"permission":"allow"}'
+    exit 0
+  fi
+  # Record the PRIMARY token (content-exact when available, else coarse) so the
+  # runner's denial correlation keys on the SAME identity it grants on approval.
+  if [ -n "$CONTENT_TOKEN" ]; then
+    record_denial "$CONTENT_TOKEN"
+  else
+    record_denial "$TOKEN"
+  fi
   echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"Tool requires approval: '"$TOOL_NAME"'"}'
   exit 0
 fi