@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-cursor/approval-state.js

@@ -0,0 +1,682 @@
+/**
+ * Approval state management for the hook-deny + reinvoke HITL model.
+ *
+ * Before starting a Cursor Agent run, the cursor-runner writes a state file
+ * into the session's runner-owned HITL directory (outside the user's
+ * workspace). The preToolUse hook script reads this file to decide whether to
+ * allow or deny each tool call.
+ *
+ * State file format (JSON):
+ * {
+ *   "autoApproveAll": false,
+ *   "leasedCategories": ["shell"],
+ *   "mcpDestructiveTools": {
+ *     "planton/apply_cloud_resource": { "message": "Execute apply_cloud_resource" }
+ *   },
+ *   "mcpUnlistedServers": ["plugin_linear_linear"],
+ *   "toolListsRestricted": true,
+ *   "toolScope": "<base64(JSON)>",
+ *   "approvedGrants": [{ "toolName": "edit", "mcpServerSlug": "", "key": "write", "salient": "a.txt", "contentDigest": "<sha256>" }],
+ *   "approvedGrantTokens": ["<base64(key\nsalient[\ncontentDigest])>"]
+ * }
+ *
+ * A grant token is the action's PRIMARY token: base64(key \n salient \n digest)
+ * for a content-identified file edit (so a DIFFERENT edit to the same file does
+ * not match), or base64(key \n salient) for shell/delete/MCP and the rare
+ * content-less fallback. See {@link primaryToken}.
+ *
+ * Two questions, answered in this order. First, may this agent call the tool
+ * at all (`toolScope`, its tool lists compiled by `hook-scope.ts`)? A tool out
+ * of scope is refused whatever the approval posture. Then, does the call ask
+ * first? The hook gates the dangerous built-in set and the MCP tools whose
+ * server marks them destructive (`mcpDestructiveTools`, keyed by server and
+ * tool), and every tool of a server whose tools could not be listed at turn
+ * start (`mcpUnlistedServers`); 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
+ * live here. Both halves are computed by the runner from the turn's one
+ * source each (`TurnMcp.mcpDefault`, `TurnMcp.toolScope`), so this file adds
+ * no rule of its own.
+ *
+ * Approval leases (the scoped successor to autoApproveAll): `autoApproveAll` is
+ * ONLY the pre-armed spec.auto_approve_all global bypass. An interactive
+ * "approve all" of a given class becomes a run-lifetime lease: a built-in
+ * category lease is listed in `leasedCategories` (the hook allows any built-in of
+ * that category), and an MCP-server lease leaves the server's tools out of
+ * mcpDestructiveTools and the server out of mcpUnlistedServers, so the hook
+ * lets them through.
+ *
+ * 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 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
+ * each grant that the hook matches by simple string membership. The structured
+ * `approvedGrants` is retained for readability, debugging, and tests; the two
+ * are always generated together from the same source.
+ *
+ * Denial ledger (hook → runner):
+ * The state file is the runner's INPUT to the hook. Its symmetric OUTPUT is the
+ * denial ledger (denials.jsonl): EVERY deny the hook issues appends the call's
+ * identity token to this file, tagged with a `kind` (see {@link DenialKind}) —
+ * so the ledger is the complete, authoritative record of what THIS hook blocked
+ * this turn (the cursor analog of the native harness's LangGraph interrupts).
+ * The kinds split by consumer semantics:
+ *
+ * - Only APPROVAL-kind entries pause the run (the first-denial stop and
+ *   reconcileDeniedToolCalls filter to them via {@link approvalDenials}); a
+ *   secret hard-block or a fail-closed deny must never surface an approval the
+ *   user cannot meaningfully grant.
+ * - The FULL ledger (all kinds) means "these actions did NOT execute": it feeds
+ *   capture stamping and approved-command provenance, and it is the ATTRIBUTION set for
+ *   issue #205 — a hook-blocked tool call with NO ledger entry of any kind was
+ *   blocked by a FOREIGN hook (or a failed ledger append), an invariant
+ *   violation the turn boundary surfaces instead of completing silently.
+ *
+ * The token uses the SAME identity space as approvedGrantTokens, so a denial
+ * token approved this turn becomes a grant token next turn.
+ */
+import { createHash } from "node:crypto";
+import { watch } from "node:fs";
+import { writeFile, readFile, mkdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { extractArgKey, approvalCategory, resolveApprovalMessage, POLICY_ENGINE_VERSION } from "./approval-policy.js";
+import { DESTRUCTIVE_MCP_APPROVAL_MESSAGE } from "../../shared/approval-policy.js";
+import { encodeHookToolScope, SCOPE_KEY_PREFIX, UNRESTRICTED_HOOK_SCOPE } from "./hook-scope.js";
+import { contentDigest } from "../../shared/file-tools.js";
+import { toolUseEventId } from "../../harness/events/ids.js";
+import { fingerprintCoarseIdentity, } from "../../shared/approval-fingerprint.js";
+import { PendingApprovalSchema, } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalAction, ToolCallStatus } from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+export function toolIdentity(toolName, mcpServerSlug, args) {
+    if (mcpServerSlug) {
+        return { key: `${mcpServerSlug}/${toolName}`, salient: "" };
+    }
+    const category = approvalCategory(toolName);
+    // A gated built-in keys on its category; any other built-in on the hook's
+    // name for it, the one a hook asked under.
+    return { key: category ?? STREAM_TO_HOOK_NAME.get(toolName) ?? toolName, salient: extractArgKey(args) };
+}
+/**
+ * The hook's name for each built-in the stream names otherwise and that has
+ * no approval category: what a hook's ask on it is keyed by on both sides
+ * (`@cursor/sdk` 1.0.31, live: a read streams as `read`, a search as `grep`,
+ * a glob as `glob`, and the hook sees `Read`, `Grep`, and `Grep` with an
+ * empty pattern; from its bundle and tool vocabulary: a directory listing
+ * streams as `ls` and a lint read as `readLints`, and the hook sees `List`
+ * and `ReadLints`). `hook-views.ts` `rowNameOf` is the inverse.
+ */
+const STREAM_TO_HOOK_NAME = new Map([
+    ["read", "Read"],
+    ["grep", "Grep"],
+    ["glob", "Grep"],
+    ["ls", "List"],
+    ["readLints", "ReadLints"],
+]);
+/**
+ * Compute the flat token the bash hook matches on. The hook recomputes the same
+ * 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(key, salient) {
+    return Buffer.from(`${key}\n${salient}`, "utf-8").toString("base64");
+}
+/**
+ * The ledger token of a scope refusal: the TOOL (`key`: the stream name's
+ * `scopeKey`, `hook-scope.ts`, or `mcpToolKey(server, tool)` for an MCP call),
+ * plus, for a tool the lists may exclude only in part (`READ_SCOPE_KEY`,
+ * `AGENT_SCOPE_KEY`), the call's discriminator: the path as given, or the
+ * normalized sub-agent type. An empty discriminator names the whole tool.
+ * The hook records the same bytes (`grantToken` of the prefixed key and the
+ * discriminator); the turn boundary decodes them (`decodeIdentityToken`).
+ */
+export function scopeRefusalToken(key, discriminator = "") {
+    return grantToken(`${SCOPE_KEY_PREFIX}${key}`, discriminator);
+}
+/**
+ * The content-exact wire token: `base64(key \n salient \n contentDigest)`. This
+ * is the exact-identity grant the hook matches for a file-mutating tool, so an
+ * approval of one edit does NOT authorize a DIFFERENT edit to the same file (a
+ * different digest yields a different token). The hook recomputes the identical
+ * token from `tool_input` (it appends the same `\n<digest>` only when the digest
+ * is non-empty — see hook-script.ts), so this encoding must stay byte-identical
+ * to the hook's, exactly as {@link grantToken} already is.
+ */
+export function contentToken(key, salient, contentDigest) {
+    return Buffer.from(`${key}\n${salient}\n${contentDigest}`, "utf-8").toString("base64");
+}
+/**
+ * The single token a tool call authorizes (as a grant) and is recorded under (as
+ * a denial): the {@link contentToken} when a content digest is present (file
+ * edits/writes), else the coarse {@link grantToken} (shell, delete, MCP, or a
+ * content-less grep-fallback). One definition, used by the runner for both grant
+ * building and denial correlation and mirrored by the hook, so the deny-time and
+ * reinvoke-time identities can never drift.
+ */
+export function primaryToken(key, salient, contentDigest) {
+    return contentDigest ? contentToken(key, salient, contentDigest) : grantToken(key, salient);
+}
+/**
+ * Compute a streamed tool call's identity token in the same canonical space the
+ * preToolUse hook records denials in (see {@link toolIdentity} / primaryToken).
+ * The token keys on the cross-taxonomy category + salient resource PLUS, for a
+ * file edit/write, the {@link contentDigest} of the edit content — so a stream
+ * `edit` correlates to the hook's `Write` deny for the same path AND content,
+ * and an approval of one edit does not match a DIFFERENT edit to the same file.
+ *
+ * The digest is read from the persisted `approval_content_digest` field when
+ * present (a seeded gate carries it, stable even if `args` was elided), and is
+ * recomputed from the call's args otherwise (a freshly-streamed call). For a
+ * shell/delete/MCP call (no content) it falls back to the coarse token, exactly
+ * as before — so those identities are unchanged.
+ *
+ * Exported so the resume-grant round-trip can be locked against it: the grant a
+ * resume mints for an approved tool (buildApprovalGrants -> primaryToken) must
+ * equal THIS denial/overlay identity, or the re-issued call is re-gated forever
+ * (the dual-path drift the approval-state round-trip suite guards against).
+ */
+export function toolCallIdentityToken(tc) {
+    const id = toolIdentity(tc.name, tc.mcpServerSlug, toolCallArgs(tc));
+    // A hook ask's digest binds the grant, not the row's identity: the model's
+    // retry streams with the coarse identity and resumes onto this row.
+    const persisted = tc.approvalContentDigest.startsWith(HOOK_ASK_DIGEST_PREFIX) ? "" : tc.approvalContentDigest;
+    const digest = persisted || contentDigest(toolCallArgs(tc));
+    return primaryToken(id.key, id.salient, digest);
+}
+/** Marks a {@link hookAskDigest}, apart from a file edit's content digest. */
+export const HOOK_ASK_DIGEST_PREFIX = "args:";
+/**
+ * What a hook's ask is approved under when the call carries no file content
+ * (an MCP tool, a shell command, a read or a search): the whole input as the
+ * hook saw it. The native engine asks for every call a hook asks on; here an
+ * approval leaves a grant, and keyed to the tool alone it would let through
+ * the same tool with any arguments. The gate's script computes the same
+ * digest from the payload (`hook-script.ts`, the hook arm's grant check), so
+ * the two must stay byte-identical: SHA-256 of the input's JSON, prefixed.
+ */
+export function hookAskDigest(input) {
+    return HOOK_ASK_DIGEST_PREFIX + createHash("sha256").update(JSON.stringify(input), "utf8").digest("hex");
+}
+/**
+ * Decode a primary token back into its (key, salient, digest) for the synthesis
+ * fallback. The token is `base64(key \n salient)` (coarse) or
+ * `base64(key \n salient \n digest)` (content-exact); the digest is the optional
+ * third segment. salient never contains a newline (a path or shell command), so
+ * splitting on the first two newlines is unambiguous.
+ */
+export function decodeIdentityToken(token) {
+    try {
+        const decoded = Buffer.from(token, "base64").toString("utf-8");
+        const first = decoded.indexOf("\n");
+        if (first < 0)
+            return undefined;
+        const key = decoded.slice(0, first);
+        const rest = decoded.slice(first + 1);
+        const second = rest.indexOf("\n");
+        if (second < 0)
+            return { key, salient: rest, digest: "" };
+        return { key, salient: rest.slice(0, second), digest: rest.slice(second + 1) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Best-effort args record for a tool call (proto struct, else parsed preview). */
+export function toolCallArgs(tc) {
+    if (tc.args && typeof tc.args === "object") {
+        return tc.args;
+    }
+    if (tc.argsPreview) {
+        try {
+            const parsed = JSON.parse(tc.argsPreview);
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch {
+            // fall through
+        }
+    }
+    return {};
+}
+/**
+ * The shared HMAC coarse fingerprint of an approval grant.
+ *
+ * This is the SAME canonical coarse identity the wire token (grantToken) encodes
+ * — `(key, salient)` plus the MCP slug — run through the one shared HMAC+canonical
+ * path ({@link fingerprintCoarseIdentity}). It is NOT the hook's wire-match value:
+ * the hook matches on the mechanically-reproducible base64 token (a bash script
+ * can recompute base64 but not a keyed HMAC over a workspace-root-normalized
+ * salient). This fingerprint is the cross-substrate, anti-forgery identity used
+ * for the runner-side shadow receipt today and as the successor wire token once a
+ * lease becomes a server-issued bearer token. Because it shares the
+ * exact category + salient the token uses, the hook-side and stream-side
+ * fingerprints of one action are equal by construction (see the parity tests).
+ */
+export function grantFingerprint(key, grant) {
+    return fingerprintCoarseIdentity(key, {
+        // An MCP grant's `key` is `server/tool`; the fingerprint names the tool
+        // and the server apart, as the native engine's does.
+        tool: grant.mcpServerSlug ? grant.toolName : grant.key,
+        mcpServerSlug: grant.mcpServerSlug,
+        salient: grant.salient,
+    });
+}
+/**
+ * Emit a best-effort shadow ExecutionReceipt for each grant the runner issues
+ * this turn (the mirror of the deep-agent gateway's receipt).
+ *
+ * Cursor executes tools out-of-process, so unlike the in-process deep-agent
+ * gateway the runner cannot observe the actual side effect — the receipt is
+ * issued when the authorization GRANT is written (best-effort, `verified:false`),
+ * not at execution. Structured log only: never persisted, no proto. Shares the
+ * one HMAC+canonical fingerprint path so the value matches the deep-agent and
+ * cross-language corpus definitions.
+ */
+export function emitCursorGrantReceipts(grants, fingerprintKey, executionId) {
+    for (const g of grants) {
+        console.log("[hitl-gateway] receipt " +
+            JSON.stringify({
+                executionId,
+                toolName: g.toolName,
+                mcpServerSlug: g.mcpServerSlug,
+                category: g.mcpServerSlug ? "" : g.key,
+                authorization: "approval",
+                policyEngineVersion: POLICY_ENGINE_VERSION,
+                fingerprint: grantFingerprint(fingerprintKey, g),
+                substrate: "cursor",
+                verified: false,
+            }));
+    }
+}
+/**
+ * Build approval grants from the pending approvals the user adjudicated and
+ * 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, decisions, contentDigests) {
+    const grants = [];
+    for (const pa of pendingApprovals) {
+        // Both APPROVE and APPROVE_ALL allow the adjudicated tool through on the
+        // resumed turn. APPROVE_ALL additionally grants a run-lifetime lease for the
+        // clicked action's class (handled by the caller via deriveActiveLeases ->
+        // leasedCategories / dropped MCP server), but we still emit a grant here so
+        // the clicked tool itself is allowed regardless of how the hook reads state.
+        const decision = decisions.get(pa.toolCallId);
+        if (decision !== ApprovalAction.APPROVE && decision !== ApprovalAction.APPROVE_ALL)
+            continue;
+        const id = toolIdentity(pa.toolName, pa.mcpServerSlug, parseArgs(pa.argsPreview));
+        grants.push({
+            toolName: pa.toolName,
+            mcpServerSlug: pa.mcpServerSlug,
+            key: id.key,
+            salient: id.salient,
+            // The content digest comes from the gate's authoritative captured input
+            // (carried on the tool call, see reconstructAdjudicatedApprovals) — NOT
+            // from argsPreview, which elides heavy edit content. Empty when the gate
+            // had no content (shell/delete/MCP) or it was unrecoverable, in which case
+            // the grant degrades to the coarse token (a same-file sibling can ride it,
+            // the documented bounded residual).
+            contentDigest: contentDigests?.get(pa.toolCallId) ?? "",
+            sourceToolCallId: pa.toolCallId,
+        });
+    }
+    return grants;
+}
+/**
+ * The calls a person skipped or rejected (SKIP / REJECT), by identity token
+ * (the primary one, and the coarse one a content-less retry of the same
+ * resource carries), so a hook's allow or ask never runs one of them again:
+ * the person's refusal binds on the model's retry, as it does on the native
+ * engine (`middleware/approval-gate.ts`). Only a hook's deny comes before
+ * it (`hook-server.ts`).
+ */
+export function buildPersonRefusals(pendingApprovals, decisions, contentDigests, hookAsked = new Set(), denyMessages = new Map()) {
+    const refusals = new Map();
+    for (const pa of pendingApprovals) {
+        const decision = decisions.get(pa.toolCallId);
+        if (decision !== ApprovalAction.REJECT && decision !== ApprovalAction.SKIP)
+            continue;
+        const refusal = {
+            action: decision === ApprovalAction.SKIP ? "skip" : "reject",
+            toolName: pa.toolName,
+            comment: denyMessages.get(pa.toolCallId) ?? "",
+        };
+        const id = toolIdentity(pa.toolName, pa.mcpServerSlug, parseArgs(pa.argsPreview));
+        const digest = contentDigests?.get(pa.toolCallId) ?? "";
+        refusals.set(primaryToken(id.key, id.salient, digest), refusal);
+        // A hook's ask was refused for that exact call, as it is granted for one.
+        if (!hookAsked.has(pa.toolCallId) && !digest.startsWith(HOOK_ASK_DIGEST_PREFIX))
+            refusals.set(grantToken(id.key, id.salient), refusal);
+    }
+    return refusals;
+}
+function parseArgs(argsPreview) {
+    if (!argsPreview)
+        return undefined;
+    try {
+        const parsed = JSON.parse(argsPreview);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the approval state file content from the turn's approval default, its
+ * tool scope and any approval grants from a previous HITL cycle.
+ *
+ * The state file carries the hook script's DYNAMIC inputs:
+ * - globalBypass: the pre-armed spec.auto_approve_all (written as autoApproveAll)
+ * - leasedCategories: built-in categories with a run-lifetime lease
+ * - mcpDestructiveTools: the MCP tools that ask, keyed by server and tool,
+ *   leased servers left out
+ * - mcpUnlistedServers: the servers whose every tool asks because their tools
+ *   could not be listed, leased servers left out
+ * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
+ *   cycle, allowed through on reinvocation
+ * - toolScope: the agent's tool lists, compiled (`hook-scope.ts`)
+ * - captureMode / fileReview / captureIgnored / gitWorkspace: how file edits
+ *   flow this turn (captured for review, flowing unreviewed, or gated)
+ *
+ * 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(mcpDefault, globalBypass, leasedCategories, grants, captureMode = false, captureIgnored = false, gitWorkspace = true, unattendedSkip = false, toolScope = UNRESTRICTED_HOOK_SCOPE, fileReview = true) {
+    const approvedGrants = grants ?? [];
+    const mcpDestructiveTools = {};
+    for (const key of mcpDefault.destructive) {
+        // `mcpToolKey` joins a slug (no "/") and a tool name, so the first "/" splits them.
+        const sep = key.indexOf("/");
+        const server = key.slice(0, sep);
+        if (mcpDefault.leasedServers.has(server))
+            continue;
+        const tool = key.slice(sep + 1);
+        mcpDestructiveTools[key] = { message: resolveApprovalMessage(DESTRUCTIVE_MCP_APPROVAL_MESSAGE, tool, {}) };
+    }
+    const mcpUnlistedServers = [...mcpDefault.unlisted].filter((server) => !mcpDefault.leasedServers.has(server));
+    return {
+        autoApproveAll: globalBypass,
+        leasedCategories: [...leasedCategories],
+        mcpDestructiveTools,
+        mcpUnlistedServers,
+        toolListsRestricted: toolScope.restricted,
+        toolScope: encodeHookToolScope(toolScope),
+        approvedGrants,
+        // The hook matches a tool call's PRIMARY token (content when it can compute a
+        // digest from tool_input, else coarse). A content-identified grant authorizes
+        // only its exact content; a content-less grant authorizes the coarse token.
+        approvedGrantTokens: approvedGrants.map((g) => primaryToken(g.key, g.salient, g.contentDigest)),
+        captureMode,
+        fileReview,
+        captureIgnored,
+        gitWorkspace,
+        unattendedSkip,
+    };
+}
+const STATE_FILE_NAME = "approval-state.json";
+/**
+ * Write the approval state file into the session's HITL directory for the hook
+ * script to read.
+ *
+ * The HITL directory is runner-owned and lives outside the user's workspace
+ * (`~/.stigmer/sessions/{id}/hitl/`), so this file never lands in the attached
+ * repo — only a minimal `.cursor/hooks.json` pointing here by absolute path does
+ * (see issue #173). The hook reads this file fresh on every tool call, so its
+ * dynamic policy is always current even if the SDK caches `hooks.json`.
+ *
+ * Written as COMPACT JSON (no indentation): the bash hook parses it with
+ * line-oriented grep patterns that assume `"key":value` with no spaces or
+ * newlines (e.g. `"autoApproveAll":true`, `"name":{...}`). Pretty-printing
+ * would break every lookup.
+ */
+export async function writeApprovalStateFile(hitlDir, state) {
+    await mkdir(hitlDir, { recursive: true });
+    const filePath = join(hitlDir, STATE_FILE_NAME);
+    await writeFile(filePath, JSON.stringify(state), "utf-8");
+    return filePath;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Denial ledger (hook → runner): the authoritative record of what the hook gated
+// ─────────────────────────────────────────────────────────────────────────────
+const DENIAL_LEDGER_FILE = "denials.jsonl";
+/** The one kind that pauses the run for user approval. */
+export const APPROVAL_DENIAL_KIND = "approval";
+/** The unattended-mode resolution kind (non-pausing; stamped SKIPPED). */
+export const UNATTENDED_DENIAL_KIND = "unattended";
+/** The tool-list refusal kind (non-pausing, permanent for the run). */
+export const DISABLED_DENIAL_KIND = "disabled";
+/** The hook-layer refusal kind (non-pausing). */
+export const HOOK_DENIAL_KIND = "hook";
+/** The effective kind of a ledger entry (absent → approval, the pre-kind format). */
+export function denialKindOf(entry) {
+    return entry.kind || APPROVAL_DENIAL_KIND;
+}
+/**
+ * The entries that pause the run for user approval — the ONLY kind
+ * reconcileDeniedToolCalls may turn into WAITING_APPROVAL gates and the only
+ * kind the first-denial stop may cancel the run for. Every other consumer
+ * (capture stamping, approved-command provenance, foreign-hook attribution)
+ * wants the FULL
+ * ledger: all kinds mean "this action did not execute".
+ */
+export function approvalDenials(entries) {
+    return entries.filter((e) => denialKindOf(e) === APPROVAL_DENIAL_KIND);
+}
+/**
+ * The entries the UNATTENDED approval mode resolved — never pausing,
+ * consumed by the turn boundary's `stampUnattendedSkippedToolCalls` to
+ * terminalize the corresponding streamed tool calls as TOOL_CALL_SKIPPED with
+ * UNATTENDED_SKIP provenance, so both harnesses persist the same honest shape.
+ */
+export function unattendedDenials(entries) {
+    return entries.filter((e) => denialKindOf(e) === UNATTENDED_DENIAL_KIND);
+}
+/**
+ * Absolute path of the per-turn denial ledger the hook appends to, inside the
+ * session's runner-owned HITL directory (never the user's workspace).
+ */
+export function denialLedgerPath(hitlDir) {
+    return join(hitlDir, DENIAL_LEDGER_FILE);
+}
+/**
+ * Truncate the denial ledger to empty for a fresh turn, returning its path.
+ *
+ * Called every turn alongside writeApprovalStateFile (the HITL directory is
+ * durable and reused across HITL reinvocations), so the runner only ever reads
+ * denials produced by the current run. A Temporal activity retry re-runs this
+ * reset before re-running the agent, so the read stays deterministic under
+ * retries.
+ */
+export async function resetDenialLedger(hitlDir) {
+    await mkdir(hitlDir, { recursive: true });
+    const filePath = denialLedgerPath(hitlDir);
+    await writeFile(filePath, "", "utf-8");
+    return filePath;
+}
+/**
+ * Watch the denial ledger so the stream loop learns about a hook denial the
+ * moment it is written — not on the next tool_call event.
+ *
+ * The hook appends to denials.jsonl BEFORE Cursor surfaces the failure to the
+ * model, so a filesystem notification is the earliest possible signal that a
+ * turn must pause. The watcher deliberately does NOT read the file itself: it
+ * only flips the caller's dirty flag, and the stream loop confirms with a
+ * readDenialLedger() — a notification can fire for the per-turn reset
+ * truncation too, and only a read distinguishes "reset to empty" from "denial
+ * appended". Watching the DIRECTORY (not the file) survives the file being
+ * replaced/truncated between turns.
+ *
+ * fs.watch is best-effort by platform contract, so this is an accelerator,
+ * never the only trigger: the stream loop keeps its tool_call-event read as
+ * the backstop. On any watcher error we fall back to that backstop silently.
+ *
+ * Returns a close function, idempotent and safe to call on every exit path.
+ */
+export function watchDenialLedger(hitlDir, onDirty) {
+    try {
+        const watcher = watch(hitlDir, (_eventType, filename) => {
+            if (!filename || filename === DENIAL_LEDGER_FILE)
+                onDirty();
+        });
+        // Without an error listener a watcher error crashes the process; with one,
+        // the watcher just goes quiet and the tool_call backstop takes over.
+        watcher.on("error", () => { });
+        return () => {
+            try {
+                watcher.close();
+            }
+            catch {
+                // Already closed — nothing to release.
+            }
+        };
+    }
+    catch {
+        // Watch unsupported on this platform/filesystem — backstop only.
+        return () => { };
+    }
+}
+/**
+ * Read the denial ledger written by the hook during the turn. Missing file →
+ * no denials. Blank or partially-written lines are tolerated (the hook appends
+ * line-by-line and a run can be interrupted), so a malformed tail never hides
+ * the valid denials before it.
+ */
+export async function readDenialLedger(hitlDir) {
+    let raw;
+    try {
+        raw = await readFile(denialLedgerPath(hitlDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj.token === "string" && obj.token) {
+                entries.push({
+                    toolName: typeof obj.toolName === "string" ? obj.toolName : "",
+                    token: obj.token,
+                    // A garbled/missing kind degrades to undefined → approval (the
+                    // pre-kind format); see denialKindOf.
+                    kind: typeof obj.kind === "string" && obj.kind ? obj.kind : undefined,
+                    input: decodeLedgerInput(obj.input),
+                    ...(typeof obj.message === "string" && obj.message
+                        ? { message: Buffer.from(obj.message, "base64").toString("utf-8") }
+                        : {}),
+                    // base64 of the plugin's slug; "" (the agent's own block) is written as a lone "=" sentinel.
+                    ...(typeof obj.hook === "string" && obj.hook
+                        ? { hook: obj.hook === "=" ? "" : Buffer.from(obj.hook, "base64").toString("utf-8") }
+                        : {}),
+                });
+            }
+        }
+        catch {
+            // Tolerate a partial trailing line from an interrupted hook append.
+        }
+    }
+    return entries;
+}
+/**
+ * Decode the hook's base64(JSON(tool_input)) into the authoritative args object,
+ * or undefined when absent/garbage. Tolerant by construction: a bad capture must
+ * never drop the denial it rides on — the gate still surfaces, just without the
+ * richer preview.
+ */
+function decodeLedgerInput(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    try {
+        const json = Buffer.from(raw, "base64").toString("utf-8");
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Active-turn pointer (runner → stable hook): the per-turn indirection that makes
+// a single, process-cached hook script resolve the CURRENT execution's artifacts
+// ─────────────────────────────────────────────────────────────────────────────
+const ACTIVE_POINTER_FILE = "active.json";
+/** Absolute path of the active-turn pointer inside a workspace's gate directory. */
+export function activePointerPath(gateDir) {
+    return join(gateDir, ACTIVE_POINTER_FILE);
+}
+/**
+ * Atomically point the workspace's stable hook at the current turn's artifacts.
+ *
+ * Written compactly (the hook's grep fallback parses `"key":"value"` with no
+ * spaces) and atomically (write a temp sibling, then rename) so a hook firing
+ * concurrently with the write never reads a half-written pointer. Returns the
+ * pointer path.
+ */
+export async function writeActiveTurnPointer(gateDir, pointer) {
+    await mkdir(gateDir, { recursive: true });
+    const filePath = activePointerPath(gateDir);
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    await writeFile(tmpPath, JSON.stringify(pointer), "utf-8");
+    await rename(tmpPath, filePath);
+    return filePath;
+}
+/**
+ * Remove the active-turn pointer on teardown so the gate is INERT between turns:
+ * a hook that fires when no turn is active (a leftover cached hooks.json, the
+ * user's own IDE) reads no pointer and allows immediately. Best-effort — a
+ * teardown failure must never fail the execution, and a stale pointer is itself
+ * inert once its runnerPid is gone (the scope guard fails closed to allow).
+ */
+export async function removeActiveTurnPointer(gateDir) {
+    try {
+        await rm(activePointerPath(gateDir), { force: true });
+    }
+    catch {
+        // Already gone or unwritable — nothing to clean.
+    }
+}
+/** The ask's policy source word when a hook asked (`harness/events/emitter.ts` `POLICY_SOURCE_WORDS`, the contract's `policy_source` word). */
+const HOOK_POLICY_SOURCE_WORD = "hook";
+export function reconstructAdjudicatedApprovals(messages, logged) {
+    const pendingApprovals = [];
+    const decisions = new Map();
+    const contentDigests = new Map();
+    const hookAsked = new Set();
+    for (const msg of messages) {
+        for (const tc of msg.toolCalls) {
+            if (tc.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL)
+                continue;
+            const decision = logged.decisions.get(tc.id);
+            if (decision === undefined || decision === ApprovalAction.UNSPECIFIED)
+                continue;
+            decisions.set(tc.id, decision);
+            const ask = logged.asks.get(toolUseEventId(logged.runId, tc.id));
+            if (ask?.policySource === HOOK_POLICY_SOURCE_WORD)
+                hookAsked.add(tc.id);
+            contentDigests.set(tc.id, ask?.contentDigest ?? "");
+            pendingApprovals.push(create(PendingApprovalSchema, {
+                toolCallId: tc.id,
+                toolName: tc.name,
+                message: tc.approvalMessage,
+                argsPreview: tc.argsPreview,
+                mcpServerSlug: tc.mcpServerSlug,
+                requestedAt: tc.approvalRequestedAt,
+            }));
+        }
+    }
+    return { pendingApprovals, decisions, contentDigests, hookAsked };
+}
+//# sourceMappingURL=approval-state.js.map