@stigmer/runner 3.1.6 → 3.1.8

package/src/activities/execute-cursor/message-translator.ts

@@ -45,7 +45,14 @@ import {
   resolveApprovalProvenance,
   toProtoPolicySource,
 } from "../../shared/approval-policy.js";
-import { grantToken, primaryToken, toolIdentity, type DeniedLedgerEntry } from "./approval-state.js";
+import {
+  approvalDenials,
+  denialKindOf,
+  grantToken,
+  primaryToken,
+  toolIdentity,
+  type DeniedLedgerEntry,
+} from "./approval-state.js";
 import { utcTimestamp } from "../../shared/status.js";
 import { hideToolCallRow, isToolCallRowHidden } from "../../shared/tool-row.js";
 import { classifyTool, toolApprovalCategory, type ToolApprovalCategory } from "../../shared/tool-kind.js";
@@ -316,6 +323,19 @@ function mapSubAgentStatus(cursorStatus: string): SubAgentStatus {
   }
 }
 
+/**
+ * Terminal for the MONOTONIC status guard in {@link mergeToolCallEvent}: once a
+ * row reaches one of these, a later event re-emit must not regress it.
+ *
+ * TOOL_CALL_INTERRUPTED is deliberately NOT here, even though it is terminal
+ * everywhere else (server, clients, provenance scoping — see the shared
+ * TERMINAL_TOOL_CALL_STATUSES in tool-row.ts). INTERRUPTED is server-authored
+ * when an execution terminalizes with the call in flight; if that FAILED
+ * execution is later RECOVERED, the harness checkpoint can re-execute the call
+ * under its original call id — and live execution evidence outranks the
+ * interruption marker, so the replayed event must advance the row to its true
+ * outcome (the enum's documented recovery supersede rule).
+ */
 function isTerminalToolStatus(status: ToolCallStatus): boolean {
   return (
     status === ToolCallStatus.TOOL_CALL_COMPLETED ||
@@ -1217,6 +1237,13 @@ export async function reconcileDeniedToolCalls(
   mergedPolicies?: Map<string, MergedToolPolicy>,
   workspaceBackend?: WorkspaceBackend,
 ): Promise<ToolCall[]> {
+  // Defense-in-depth: only APPROVAL-kind denials may become approval gates.
+  // The turn boundary already passes the filtered subset; re-filtering here
+  // makes it structurally impossible for a secret/capture-error/fail-closed
+  // entry to manufacture a pause the user cannot meaningfully grant, no matter
+  // what a future caller passes (an absent kind is the pre-kind format and
+  // counts as approval).
+  ledger = approvalDenials(ledger);
   if (ledger.length === 0) return [];
 
   // The workspace the gated files live in; its rootDir normalizes paths for the
@@ -1793,6 +1820,102 @@ export function clearProvisionalPostDenialNarration(
   return redacted;
 }
 
+/**
+ * Substrings of the error text Cursor stamps onto a tool call blocked by a
+ * `preToolUse`/`beforeMCPExecution` hook (its generic replacement for the
+ * hook's own agent_message — confirmed by the Phase 0 ground-truth capture in
+ * cursor_hitl_test.go). The SDK has NO structured "denied by hook" signal, so
+ * this marker family is the only stream-side trace of a hook block and is
+ * single-sourced here for every consumer (the issue #205 attribution detector
+ * below; tests). Matched case-insensitively against the FAILED call's error.
+ */
+export const HOOK_BLOCK_ERROR_MARKERS: readonly string[] = ["blocked by a hook"];
+
+/** True when a tool call's error text reads as a hook block. */
+function isHookBlockError(errorText: string): boolean {
+  if (!errorText) return false;
+  const lowered = errorText.toLowerCase();
+  return HOOK_BLOCK_ERROR_MARKERS.some((marker) => lowered.includes(marker));
+}
+
+/** One hook-blocked tool call that no ledger entry accounts for (issue #205). */
+export interface UnattributedHookBlock {
+  toolCallId: string;
+  toolName: string;
+  /** The hook-block error text Cursor stamped on the call. */
+  error: string;
+}
+
+/**
+ * Detect tool calls blocked by a hook that STIGMER'S OWN hook did not deny —
+ * the issue #205 invariant check "a blocked tool must never silently complete".
+ *
+ * Cursor runs EVERY hook registered in the workspace's `.cursor/hooks.json`
+ * and a deny from any of them blocks the tool. Our hook records every deny it
+ * issues to the denial ledger (all kinds — see {@link DeniedLedgerEntry}), so a
+ * FAILED tool call carrying Cursor's hook-block error text with NO matching
+ * ledger entry was blocked by a FOREIGN hook (a user/team `preToolUse` policy
+ * hook the merge deliberately preserves) — or, equally fatally, by our own
+ * hook whose best-effort ledger append failed. Either way the runner cannot
+ * pause for approval (an approval grants a token only OUR hook reads; the
+ * foreign hook would deny the re-attempt forever), so the caller surfaces an
+ * explicit failure instead of completing with the work silently undone.
+ *
+ * Attribution, in order:
+ *  1. Any `fail-closed` ledger entry → the gate itself was broken this turn and
+ *     denied EVERYTHING it saw; per-call correlation is meaningless, so every
+ *     hook block is attributed to our own (broken) gate. Nothing is reported.
+ *  2. Exact identity: the call's {@link toolCallIdentityToken} appears in the
+ *     ledger (any kind — approval gates were overlaid to WAITING_APPROVAL or
+ *     collapsed by the reconcile that runs first, so a still-FAILED row here is
+ *     typically a secret/capture-error deny, correctly attributed as ours).
+ *  3. Normalized-path fallback: the same abs-vs-rel drift the reconcile's
+ *     second pass handles — a FILE call matches a ledger entry by (category,
+ *     workspace-normalized path) even when the raw tokens differ.
+ *
+ * Scoped to THIS turn's messages (from `turnStartMessageIndex`): seeded
+ * prior-turn rows were already adjudicated and must never re-trigger.
+ * Deliberately conservative: an ordinary tool failure (no hook-block text)
+ * is never reported, and a foreign hook denying with fully custom text evades
+ * the marker match (the documented residual — the install-time
+ * foreignGatingHooks warning still fires for diagnosability).
+ */
+export function detectUnattributedHookBlocks(
+  messages: readonly AgentMessage[],
+  turnStartMessageIndex: number,
+  ledger: readonly DeniedLedgerEntry[],
+  workspaceRoot?: string,
+): UnattributedHookBlock[] {
+  if (ledger.some((e) => denialKindOf(e) === "fail-closed")) return [];
+
+  const ledgerTokens = new Set(ledger.map((e) => e.token));
+  const ledgerNormalizedSalients = new Set<string>();
+  if (workspaceRoot) {
+    for (const entry of ledger) {
+      const decoded = decodeIdentityToken(entry.token);
+      if (!decoded) continue;
+      const normalized = normalizedFileSalient(decoded.key, decoded.salient, workspaceRoot);
+      if (normalized) ledgerNormalizedSalients.add(normalized);
+    }
+  }
+
+  const blocks: UnattributedHookBlock[] = [];
+  for (const msg of messages.slice(Math.max(0, turnStartMessageIndex))) {
+    for (const tc of msg.toolCalls) {
+      if (tc.status !== ToolCallStatus.TOOL_CALL_FAILED) continue;
+      if (!isHookBlockError(tc.error)) continue;
+      if (ledgerTokens.has(toolCallIdentityToken(tc))) continue;
+      if (workspaceRoot) {
+        const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
+        const normalized = normalizedFileSalient(id.key, id.salient, workspaceRoot);
+        if (normalized && ledgerNormalizedSalients.has(normalized)) continue;
+      }
+      blocks.push({ toolCallId: tc.id, toolName: tc.name, error: tc.error });
+    }
+  }
+  return blocks;
+}
+
 /**
  * Compute a streamed tool call's identity token in the same canonical space the
  * preToolUse hook records denials in (see {@link toolIdentity} / primaryToken).

package/src/activities/execute-cursor/turn-boundary.ts

@@ -2,12 +2,17 @@
  * The Cursor harness's turn boundary — the single post-run pipeline that turns
  * a finished agent run into the durable review surfaces:
  *
- *  1. read the denial ledger the preToolUse hook appended this turn;
+ *  1. read the denial ledger the preToolUse hook appended this turn (ALL
+ *     kinds — every entry means "this action did not execute"; only the
+ *     approval-kind subset may pause, see approval-state.ts);
  *  2. derive the approved-command provenance (DD-28 auto-keep facts);
  *  3. capture the turn's net file change set to the file_review ledger
  *     (CANDIDATE_CAPTURED) and stamp the flowed edit rows;
- *  4. reconcile denied tool calls to WAITING_APPROVAL gate rows and redact the
- *     model's provisional post-denial narration.
+ *  4. reconcile denied (approval-kind) tool calls to WAITING_APPROVAL gate rows
+ *     and redact the model's provisional post-denial narration;
+ *  5. detect UNATTRIBUTED hook blocks (issue #205) — a tool blocked by a hook
+ *     with no ledger entry of any kind was denied by a FOREIGN hook the merge
+ *     preserved, and the caller fails the run rather than completing silently.
  *
  * Extracted from the activity entry point (index.ts Phase 12) so it is directly
  * unit-testable AND re-enterable: the poisoned-handle / transport-timeout
@@ -32,12 +37,20 @@ import { collectSubAgentToolCallIds } from "../../shared/tool-row.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
 import type { MergedToolPolicy } from "../../shared/approval-policy.js";
-import { primaryToken, readDenialLedger, type ApprovalGrant } from "./approval-state.js";
+import {
+  approvalDenials,
+  denialKindOf,
+  primaryToken,
+  readDenialLedger,
+  type ApprovalGrant,
+} from "./approval-state.js";
 import { deriveTurnCommandProvenance } from "./command-provenance.js";
 import { captureTurnToLedger } from "./capture-flow.js";
 import {
   clearProvisionalPostDenialNarration,
+  detectUnattributedHookBlocks,
   reconcileDeniedToolCalls,
+  type UnattributedHookBlock,
 } from "./message-translator.js";
 
 // How long the boundary waits for the first-denial-stop's run.cancel() to
@@ -96,6 +109,13 @@ export interface TurnBoundaryOptions {
    * normal completion path and the recovery retries, which have no early stop).
    */
   readonly denialCancelSettled?: Promise<void>;
+  /**
+   * Foreign (non-Stigmer) hook commands the gate install preserved on the
+   * gating events (see HitlGateHandle.foreignGatingHooks). Used only for
+   * diagnostics: when an unattributed hook block is detected, these name the
+   * likely culprit in the logs and the caller's failure message.
+   */
+  readonly foreignGatingHooks?: readonly string[];
 }
 
 export interface TurnBoundaryResult {
@@ -109,6 +129,15 @@ export interface TurnBoundaryResult {
   readonly capturedChangeCount: number;
   /** Denied tool calls reconciled to WAITING_APPROVAL gate rows this call. */
   readonly deniedToolCallCount: number;
+  /**
+   * Hook-blocked tool calls this turn that NO denial-ledger entry accounts for
+   * (issue #205): a foreign `.cursor/hooks.json` hook — or our own hook with a
+   * failed ledger append — denied them, and Stigmer cannot approve on its
+   * behalf. When the turn is not otherwise pausing, the caller must surface an
+   * explicit EXECUTION_FAILED instead of completing with the work silently
+   * undone (a pausing turn is not silent — the caller logs and pauses as usual).
+   */
+  readonly unattributedHookBlocks: readonly UnattributedHookBlock[];
 }
 
 /**
@@ -140,6 +169,7 @@ export async function runTurnBoundary(opts: TurnBoundaryOptions): Promise<TurnBo
     artifactStorage,
     mergedPolicies,
     denialCancelSettled,
+    foreignGatingHooks,
   } = opts;
 
   // The timebox keeps a wedged cancel from hanging the pause; the reconcile
@@ -153,7 +183,13 @@ export async function runTurnBoundary(opts: TurnBoundaryOptions): Promise<TurnBo
       }),
     ]);
   }
+  // The FULL ledger (all kinds) vs its APPROVAL subset — the kind split:
+  // every ledger entry means "this action did NOT execute", so the full set
+  // feeds capture stamping, DD-28 provenance, and foreign-hook attribution;
+  // only approval-kind entries may become WAITING_APPROVAL gates (a secret
+  // hard-block or fail-closed deny is attributable but never pausable).
   const deniedLedger = await readDenialLedger(hitlDir ?? "");
+  const approvalLedger = approvalDenials(deniedLedger);
 
   // Capture mode: author the net change set to the file_review ledger as the
   // CANDIDATE_CAPTURED event (projected server-side to a file_change_set
@@ -230,7 +266,7 @@ export async function runTurnBoundary(opts: TurnBoundaryOptions): Promise<TurnBo
   const gateWorkspaceBackend = new LocalWorkspaceBackend(primaryWorkspaceDir);
   const deniedToolCalls = await reconcileDeniedToolCalls(
     status.messages,
-    deniedLedger,
+    approvalLedger,
     mergedPolicies,
     gateWorkspaceBackend,
   );
@@ -266,9 +302,46 @@ export async function runTurnBoundary(opts: TurnBoundaryOptions): Promise<TurnBo
     }
   }
 
+  // Issue #205 invariant: a blocked tool must never silently complete. Match
+  // this turn's hook-blocked FAILED rows against the FULL ledger (all kinds) —
+  // anything left over was denied by a hook that is not ours (or by our hook
+  // with a failed ledger append). The reconcile above ran first, so our own
+  // approval gates are already WAITING_APPROVAL/collapsed and cannot appear
+  // here as false positives.
+  const unattributedHookBlocks = detectUnattributedHookBlocks(
+    status.messages,
+    turnStartMessageIndex,
+    deniedLedger,
+    primaryWorkspaceDir,
+  );
+  const waiting = deniedToolCalls.length > 0 || capturedChangeCount > 0;
+  if (unattributedHookBlocks.length > 0) {
+    const culprits = (foreignGatingHooks?.length ?? 0) > 0
+      ? ` — likely foreign workspace hook(s): ${foreignGatingHooks!.join(", ")}`
+      : "";
+    console.warn(
+      `ExecuteCursor turn boundary: ${unattributedHookBlocks.length} tool call(s) blocked ` +
+      `by a hook with NO matching denial-ledger entry ` +
+      `[${unattributedHookBlocks.map((b) => b.toolName).join(", ")}]${culprits} ` +
+      `(execution=${executionId})${waiting ? " — turn pauses anyway; not failing" : ""}`,
+    );
+  }
+  // Diagnosability for the broken-gate shape: fail-closed entries mean the
+  // approval state file was missing and the gate denied everything it saw.
+  // Attribution treats those blocks as ours (never a foreign-hook failure),
+  // but the condition itself deserves a loud log.
+  if (deniedLedger.some((e) => denialKindOf(e) === "fail-closed")) {
+    console.warn(
+      `ExecuteCursor turn boundary: fail-closed denial(s) in the ledger — the approval ` +
+      `state file was missing during this turn and gated tools were denied ` +
+      `(execution=${executionId})`,
+    );
+  }
+
   return {
-    waiting: deniedToolCalls.length > 0 || capturedChangeCount > 0,
+    waiting,
     capturedChangeCount,
     deniedToolCallCount: deniedToolCalls.length,
+    unattributedHookBlocks,
   };
 }

package/src/activities/execute-cursor/turn-stream.ts

@@ -33,7 +33,7 @@ import {
   type StallWatchdog,
 } from "../../shared/stall-watchdog.js";
 import { shouldPersistStreamingStatus } from "./persist-decision.js";
-import { readDenialLedger } from "./approval-state.js";
+import { approvalDenials, readDenialLedger } from "./approval-state.js";
 import {
   captureFileChangeProgress,
   type ProgressCaptureState,
@@ -305,7 +305,11 @@ export async function consumeCursorTurnStream(
       // anchor's own row is always present for the turn-boundary gate overlay.
       if (!state.firstDenialDetected && hitlDir && (state.denialLedgerDirty || event.type === "tool_call")) {
         state.denialLedgerDirty = false;
-        const denials = await readDenialLedger(hitlDir);
+        // APPROVAL-kind denials only: a secret hard-block or fail-closed deny
+        // also lands in the (kinded) ledger for attribution, but must never
+        // stop the run — the agent is told to continue past those, and there
+        // is no approval the user could meaningfully grant.
+        const denials = approvalDenials(await readDenialLedger(hitlDir));
         if (denials.length > 0) {
           state.firstDenialDetected = true;
           console.log(

package/src/activities/execute-cursor/workspace-setup.ts

@@ -103,6 +103,19 @@ export interface HitlGateHandle {
    * gate is inert between turns.
    */
   gateDir: string;
+  /**
+   * Commands of FOREIGN (non-Stigmer) hooks registered on the gating events
+   * (preToolUse/beforeMCPExecution) in the workspace's pre-existing hooks.json.
+   * The merge deliberately PRESERVES them (they are the user's own config), but
+   * because Cursor runs every configured hook and a deny from ANY of them blocks
+   * the tool, a foreign hook can deny the runner's tools without writing our
+   * denial ledger — the issue #205 silent-failure trigger. Surfaced here so the
+   * runner can log the exposure at install and name the likely culprit when the
+   * turn boundary detects an unattributed hook block. Empty when the workspace
+   * had no hooks.json, only Stigmer entries, or an unparseable file (which is
+   * REPLACED for the turn, so its hooks cannot run against us).
+   */
+  foreignGatingHooks: readonly string[];
 }
 
 /** Absolute path + restore target for a single workspace file the gate manages. */
@@ -334,12 +347,12 @@ async function installWorkspaceHook(
     originalRaw = null;
   }
 
-  const { merged, restoreTo } = buildMergedConfig(originalRaw, registrations);
+  const { merged, restoreTo, foreignGatingHooks } = buildMergedConfig(originalRaw, registrations);
 
   await mkdir(cursorDir, { recursive: true });
   await writeFile(hooksJsonPath, merged, "utf-8");
 
-  return { hooksJsonPath, restoreTo };
+  return { hooksJsonPath, restoreTo, foreignGatingHooks };
 }
 
 /**
@@ -406,21 +419,35 @@ const STANDALONE_CONFIG = (registrations: HookRegistration[]): string =>
 /**
  * Merge our registrations into a hooks object: for each event, drop any stale
  * Stigmer entry, then append our fresh one. Returns the merged hooks object, the
- * cleaned (Stigmer-free) hooks for restore, and whether anything was stripped.
+ * cleaned (Stigmer-free) hooks for restore, whether anything was stripped, and
+ * the FOREIGN commands preserved on the gating events (see
+ * {@link HitlGateHandle.foreignGatingHooks} for why they matter).
  */
 function mergeHooks(
   existingHooks: Record<string, unknown>,
   registrations: HookRegistration[],
-): { hooks: Record<string, unknown>; cleaned: Record<string, unknown>; strippedStale: boolean } {
+): {
+  hooks: Record<string, unknown>;
+  cleaned: Record<string, unknown>;
+  strippedStale: boolean;
+  foreignGatingHooks: string[];
+} {
   const hooks: Record<string, unknown> = { ...existingHooks };
   const cleaned: Record<string, unknown> = { ...existingHooks };
   let strippedStale = false;
+  const foreignGatingHooks: string[] = [];
 
   for (const { event, scriptPath } of registrations) {
     const hadEvent = Array.isArray(existingHooks[event]);
     const existing = hadEvent ? (existingHooks[event] as unknown[]) : [];
     const userEntries = existing.filter((e) => !isStigmerHookEntry(e));
     if (userEntries.length !== existing.length) strippedStale = true;
+    // The user entries surviving on a GATING event are exactly the hooks that
+    // can deny the runner's tools without touching our denial ledger.
+    for (const entry of userEntries) {
+      const command = (entry as { command?: unknown } | null)?.command;
+      if (typeof command === "string" && command) foreignGatingHooks.push(command);
+    }
 
     hooks[event] = [...userEntries, buildHookEntry(scriptPath)];
     // Restore target keeps the event key only if the user originally had it, so
@@ -428,12 +455,12 @@ function mergeHooks(
     if (hadEvent) cleaned[event] = userEntries;
   }
 
-  return { hooks, cleaned, strippedStale };
+  return { hooks, cleaned, strippedStale, foreignGatingHooks };
 }
 
 /**
- * Compute the merged hooks.json to write for this turn and the content to
- * restore afterward.
+ * Compute the merged hooks.json to write for this turn, the content to restore
+ * afterward, and the foreign gating hooks the merge preserved.
  *
  * - No existing file → write our standalone config; restore by deleting (null).
  * - Existing, parseable file → append our entry to each registered event array,
@@ -448,19 +475,19 @@ function mergeHooks(
 export function buildMergedConfig(
   originalRaw: string | null,
   registrations: HookRegistration[],
-): { merged: string; restoreTo: string | null } {
+): { merged: string; restoreTo: string | null; foreignGatingHooks: string[] } {
   if (originalRaw === null) {
-    return { merged: STANDALONE_CONFIG(registrations), restoreTo: null };
+    return { merged: STANDALONE_CONFIG(registrations), restoreTo: null, foreignGatingHooks: [] };
   }
 
   let parsed: unknown;
   try {
     parsed = JSON.parse(originalRaw);
   } catch {
-    return { merged: STANDALONE_CONFIG(registrations), restoreTo: originalRaw };
+    return { merged: STANDALONE_CONFIG(registrations), restoreTo: originalRaw, foreignGatingHooks: [] };
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return { merged: STANDALONE_CONFIG(registrations), restoreTo: originalRaw };
+    return { merged: STANDALONE_CONFIG(registrations), restoreTo: originalRaw, foreignGatingHooks: [] };
   }
 
   const root = parsed as Record<string, unknown>;
@@ -470,13 +497,14 @@ export function buildMergedConfig(
       : {};
   const version = typeof root.version === "number" ? root.version : 1;
 
-  const { hooks: mergedHooks, cleaned, strippedStale } = mergeHooks(hooks, registrations);
+  const { hooks: mergedHooks, cleaned, strippedStale, foreignGatingHooks } =
+    mergeHooks(hooks, registrations);
 
   const merged = JSON.stringify({ ...root, version, hooks: mergedHooks }, null, 2);
 
   // No stale Stigmer entry → restore the user's exact original bytes.
   if (!strippedStale) {
-    return { merged, restoreTo: originalRaw };
+    return { merged, restoreTo: originalRaw, foreignGatingHooks };
   }
 
   // We stripped a stale Stigmer entry, so never restore the original bytes (that
@@ -495,5 +523,5 @@ export function buildMergedConfig(
     ? null
     : JSON.stringify({ ...root, version, hooks: cleaned }, null, 2);
 
-  return { merged, restoreTo };
+  return { merged, restoreTo, foreignGatingHooks };
 }

package/src/activities/execute-deep-agent/__tests__/environment.test.ts

@@ -3,12 +3,15 @@ import { resolveEnvironment } from "../environment.js";
 
 function createMockClient(execContext: any) {
   return {
+    // No scoped token — the OSS/local shape (no runner credential to exchange).
+    acquireScopedRunnerToken: vi.fn().mockResolvedValue(undefined),
     getExecutionContextByExecutionId: vi.fn().mockResolvedValue(execContext),
   } as any;
 }
 
 function createNotFoundClient() {
   return {
+    acquireScopedRunnerToken: vi.fn().mockResolvedValue(undefined),
     getExecutionContextByExecutionId: vi.fn().mockRejectedValue(
       Object.assign(new Error("not found"), { code: 5 }),
     ),
@@ -81,6 +84,7 @@ describe("resolveEnvironment", () => {
 
   it("propagates non-NOT_FOUND errors", async () => {
     const client = {
+      acquireScopedRunnerToken: vi.fn().mockResolvedValue(undefined),
       getExecutionContextByExecutionId: vi.fn().mockRejectedValue(
         new Error("connection refused"),
       ),
@@ -92,6 +96,7 @@ describe("resolveEnvironment", () => {
 
   it("handles NOT_FOUND with lowercase code", async () => {
     const client = {
+      acquireScopedRunnerToken: vi.fn().mockResolvedValue(undefined),
       getExecutionContextByExecutionId: vi.fn().mockRejectedValue(
         Object.assign(new Error("not found"), { code: "not_found" }),
       ),