@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-cursor/__test-utils__/contract-subject.js

@@ -0,0 +1,392 @@
+/**
+ * The Cursor harness as a `HarnessContractSubject` — the REAL `createCursorAdapter()`
+ * driven through the harness contract kit, with the kit's engine-neutral
+ * scenario vocabulary translated onto the scripted `@cursor/sdk` double (#1048).
+ *
+ * The sibling of `gateway-substrate.ts` (the Cursor side of the approval
+ * contract kit): the kit owns the invariants and the runtime stand-in, this
+ * module owns the ENGINE — what the next turn of a session's agent will do —
+ * and reports what the double observed. The adapter under test is the
+ * production one, untouched; it imports no `@temporalio/*` (the fence test
+ * pins that), which is what lets the kit run it outside any activity
+ * context.
+ *
+ * ── The engine is per session ───────────────────────────────────────────────
+ * One scripted agent per session, minted when the kit first arranges a turn
+ * for it and handed out by the double's `Agent.create` for THAT session (keyed
+ * by the SDK's `platform.workspaceRef`, computed the way the adapter computes
+ * it), then parked by the real session cache across turns exactly as in a live
+ * worker. Arranging a turn REPLACES the agent's next script, so a turn the
+ * adapter interrupts before its `send()` leaves no stale script for the
+ * session's next turn. Every session also gets the workspace directory the
+ * runtime's provisioner would give it (`<workspaceRootDir>/sessions/<id>`), so
+ * both halves of the kit gate in the same directory shape; the hook's
+ * active-turn pointer is per workspace, so concurrent sessions cannot repoint
+ * each other's hook.
+ *
+ * ── The translation, one rule per word ──────────────────────────────────────
+ *  - `say(text)`      → an `assistant` event. A first send opens with the
+ *                       `system/init` event; a resumed send does not (the
+ *                       `deny-and-retry` turn-2 script is the precedent).
+ *  - `propose(id, a)` → the STREAM tool call (`edit` / `shell` / `delete`, the
+ *                       kits' shared translation in `cursor-hook-harness.ts`),
+ *                       an `effect` that runs the REAL preToolUse hook the
+ *                       adapter installed against the session's workspace,
+ *                       and the call's completion event. `executionCount(id)`
+ *                       is the hook's `allow` answers for `id` — the SDK
+ *                       executes a tool iff the hook allows it, so this is the
+ *                       safety-critical observable. WHETHER the call is
+ *                       emitted is decided from the kit's view and this
+ *                       subject's own memory, as the model and the SDK would
+ *                       decide it (see {@link CursorContractSubject.proposeSteps}).
+ *  - `read(id, path)` → the `read` tool call, the REAL hook (which allows it —
+ *                       a read is never gated) and the completion; counted as
+ *                       run. The discrete event the adapter's loop flushes a
+ *                       persist on.
+ *  - `usage(delta)`   → a `turn-ended` delta; the adapter prices it.
+ *  - `hang`           → an `effect` parked on the run's own `cancelled`
+ *                       status, which the adapter's stop-signal listener
+ *                       (`turn-stream.ts` `cancelOnStop`) produces. Never a
+ *                       timer. Resolves `whenHanging`.
+ *  - `fail(msg, s)`   → `engine`: the run ends `{ status: "error" }` and
+ *                       `run.wait()` carries the message; `internal`: an
+ *                       `effect` throws mid-stream (the adapter's catch
+ *                       classifies it). `actionable` is refused as a test bug:
+ *                       only the unattributed-hook-block path produces that
+ *                       surface, and the kit's invariants do not ask for it.
+ *  - `cancelled`      → an `effect` calling `run.cancel()` from the SDK side
+ *                       (the `run-cancelled` golden's shape).
+ * Every script that does not end in `fail`, `cancelled` or `hang` closes with
+ * `finished({ result: <last say> })` so `run.wait()` has an answer.
+ *
+ * ── Two modelling decisions (#1070) ─────────────────────────────────────────
+ * A `propose` for an id this subject has already seen the hook ALLOW emits
+ * nothing: the real SDK does not re-run a completed tool on resume — the parked
+ * agent's conversation already holds the tool's result. A `propose` whose id
+ * carries a SKIP or REJECT decision emits nothing either: the resume prompt
+ * tells the model the user declined the action and an obedient model moves
+ * on. Both are what "the engine re-reaches the same call" and "the turn
+ * continues" MEAN for a deny-and-retry harness; neither hides anything from
+ * the safety observable, because a fresh identical command from a
+ * disobedient model IS a new gated act and Cursor re-gates it — the subject
+ * file proves that with {@link CursorContractSubject.forceReissue}.
+ *
+ * The completion event a `propose` emits is scripted from the answer the hook
+ * is EXPECTED to give (deny for an undecided proposal, allow for an approved
+ * re-issue); the hook's actual answer is recorded at effect time and any
+ * disagreement is kept in {@link CursorContractSubject.hookDisagreements} for
+ * the subject file to assert empty — a hook that allows an undecided action
+ * would show up there AND in `executionCount`, never be papered over.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ServiceTier, ThinkingMode } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { loopbackHostedRow } from "../../../__test-utils__/loopback-host.js";
+import { createCursorAdapter } from "../adapter.js";
+import { resolveSessionStoreLocation } from "../session-store.js";
+import { hookInputFor, streamArgsFor, STREAM_NAME } from "./cursor-hook-harness.js";
+import { FIXTURE, SDK_CATALOG, hermeticCursorConfig, runWorkspaceHook } from "./hermetic-cursor.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "./scripted-agent.js";
+import { ScriptedCursorSdk, bindScriptedSdk } from "./scripted-sdk.js";
+import { ApprovalAction } from "../../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/** The user's message every kit turn asks; the prompt builder needs one and the kit has none to give. */
+const KIT_USER_MESSAGE = "Do what the scenario says.";
+/** What the double records the SDK "returning" for an allowed tool call. */
+const ALLOWED_RESULT = "ok (kit)";
+/** The error the SDK surfaces on a hook-denied call, as the goldens script it. */
+const HOOK_BLOCKED_RESULT = "Blocked by hook";
+/**
+ * Build the subject over one hermetic environment (the temp `HOME` the gate's
+ * per-session HITL artifacts land under, the temp workspace root). The
+ * environment is the caller's to create before and dispose after; the SDK
+ * double is bound for the module here, so a file holds one subject.
+ */
+export function createCursorContractSubject(env) {
+    return new CursorSubject(env);
+}
+class CursorSubject {
+    env;
+    name = "cursor";
+    harness = "cursor";
+    adapter;
+    config;
+    sdk;
+    hookDisagreements = [];
+    agents = new Map();
+    agentsByWorkspaceRef = new Map();
+    proposals = new Map();
+    forcedReissues = new Set();
+    hangWaiters = [];
+    mintCounter = 0;
+    constructor(env) {
+        this.env = env;
+        this.config = hermeticCursorConfig(env);
+        // Hosted, as production runs it: the remote adapter in front, the real one behind the pipe.
+        this.adapter = loopbackHostedRow({ harness: "cursor", adapter: createCursorAdapter() }).adapter;
+        this.sdk = new ScriptedCursorSdk({
+            agents: [],
+            catalog: SDK_CATALOG,
+            agentForWorkspaceRef: (ref) => this.agentsByWorkspaceRef.get(ref),
+        });
+        bindScriptedSdk(this.sdk);
+    }
+    // ── HarnessContractSubject ────────────────────────────────────────────────
+    arrange(turn, view) {
+        const agent = this.agents.get(view.sessionId) ?? this.mintAgent(view.sessionId);
+        mkdirSync(this.workspaceRootOf(view.sessionId), { recursive: true });
+        agent.arrangeNextTurn(this.translate(turn, view, agent));
+    }
+    inputOverrides(view) {
+        return {
+            // The adapter validates the name against its catalog and prices against
+            // the registry fixture; both know exactly this model.
+            model: { requested: FIXTURE.model, serviceTier: ServiceTier.STANDARD, thinkingMode: ThinkingMode.DISABLED },
+            workspaceDir: this.workspaceRootOf(view.sessionId),
+            message: KIT_USER_MESSAGE,
+        };
+    }
+    whenHanging() {
+        return new Promise((resolve) => this.hangWaiters.push(resolve));
+    }
+    executionCount(toolCallId) {
+        return this.proposals.get(toolCallId)?.allowed ?? 0;
+    }
+    // ── The subject file's observations ──────────────────────────────────────
+    agentFor(sessionId) {
+        return this.agents.get(sessionId);
+    }
+    forceReissue(toolCallId) {
+        this.forcedReissues.add(toolCallId);
+    }
+    // ── The engine ────────────────────────────────────────────────────────────
+    /** The directory the runtime's provisioner gives a session with no workspace entries (`session-root.ts`). */
+    workspaceRootOf(sessionId) {
+        return join(this.env.workspaceRootDir, "sessions", sessionId);
+    }
+    mintAgent(sessionId) {
+        const agent = new ScriptedCursorAgent({ agentId: `agent-kit-${++this.mintCounter}`, turns: [] });
+        this.agents.set(sessionId, agent);
+        // The adapter asks the SDK to create an agent for the session over a store
+        // opened under this ref; the double answers with this agent.
+        const { workspaceRef } = resolveSessionStoreLocation(sessionId, this.config.workspaceRootDir);
+        this.agentsByWorkspaceRef.set(workspaceRef, agent);
+        return agent;
+    }
+    translate(turn, view, agent) {
+        const ev = sdkEvents(agent.agentId, agent.nextRunId);
+        const script = [];
+        if (agent.sends.length === 0)
+            script.push(step.event(ev.init()));
+        let lastSay = "";
+        let ended = false;
+        for (const s of turn) {
+            switch (s.kind) {
+                case "say":
+                    script.push(step.event(ev.assistant(s.text)));
+                    lastSay = s.text;
+                    break;
+                case "propose":
+                    script.push(...(s.flows
+                        ? this.flowingWriteSteps(s.toolCallId, s.action, view, ev)
+                        : this.proposeSteps(s.toolCallId, s.action, view, ev)));
+                    break;
+                case "read":
+                    script.push(...this.readSteps(s.toolCallId, s.path, view, ev));
+                    break;
+                case "usage":
+                    script.push(
+                    // The kit's delta leaves a count optional; the SDK's `turn-ended`
+                    // states all four, and an absent count is zero, as the pricer reads it.
+                    step.turnEnded({
+                        inputTokens: s.delta.inputTokens ?? 0,
+                        outputTokens: s.delta.outputTokens ?? 0,
+                        cacheReadTokens: s.delta.cacheReadTokens ?? 0,
+                        cacheWriteTokens: s.delta.cacheWriteTokens ?? 0,
+                    }));
+                    break;
+                case "hang":
+                    script.push(step.effect("kit: hang until the adapter cancels the run", ({ run }) => this.park(run)));
+                    ended = true;
+                    break;
+                case "fail":
+                    switch (s.surface) {
+                        case "engine":
+                            script.push(step.errored({ result: s.message }));
+                            break;
+                        case "internal":
+                            script.push(step.effect("kit: the transport breaks mid-stream", () => {
+                                throw new Error(s.message);
+                            }));
+                            break;
+                        case "actionable":
+                            throw new Error(`${this.name}: fail(..., "actionable") is not producible by this subject (only the unattributed hook block reaches that surface); test bug`);
+                        default: {
+                            const exhaustive = s.surface;
+                            throw new Error(`${this.name}: unknown failure surface ${String(exhaustive)}`);
+                        }
+                    }
+                    ended = true;
+                    break;
+                case "cancelled":
+                    script.push(step.effect("kit: the SDK cancels its own run", ({ run }) => run.cancel()));
+                    ended = true;
+                    break;
+                case "limit":
+                    throw new Error(`${this.name}: limit() is not producible by this subject (the Cursor SDK has no tool-round budget; the runtime arm is declared off for it); test bug`);
+                default: {
+                    const exhaustive = s;
+                    throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
+                }
+            }
+        }
+        if (!ended)
+            script.push(step.finished({ result: lastSay, model: { id: FIXTURE.model, params: [] } }));
+        return script;
+    }
+    /**
+     * Whether the model emits the gated call this turn, and what the hook is
+     * expected to answer — one rule per case (see the header). `undefined`
+     * means "nothing is emitted".
+     */
+    emissionFor(toolCallId, view) {
+        if (this.forcedReissues.delete(toolCallId)) {
+            // The disobedient model: emitted regardless; the hook decides on its own
+            // (a grant exists only for an APPROVE), so what to expect is the grant.
+            return { expectAllow: view.approvalDecisions.get(toolCallId) === ApprovalAction.APPROVE };
+        }
+        if ((this.proposals.get(toolCallId)?.allowed ?? 0) > 0)
+            return undefined;
+        const decision = view.approvalDecisions.get(toolCallId) ?? ApprovalAction.UNSPECIFIED;
+        switch (decision) {
+            case ApprovalAction.UNSPECIFIED:
+                return { expectAllow: false };
+            case ApprovalAction.APPROVE:
+            case ApprovalAction.APPROVE_ALL:
+                return { expectAllow: true };
+            case ApprovalAction.SKIP:
+            case ApprovalAction.REJECT:
+                return undefined;
+            default: {
+                const exhaustive = decision;
+                throw new Error(`${this.name}: unknown approval action ${String(exhaustive)}`);
+            }
+        }
+    }
+    proposeSteps(toolCallId, action, view, ev) {
+        const emission = this.emissionFor(toolCallId, view);
+        if (!emission)
+            return [];
+        if (action.kind === "read" || action.kind === "mcp") {
+            throw new Error(`${this.name}: propose(${action.kind}) is not a gated built-in on this harness; test bug`);
+        }
+        const gated = { ...action, kind: action.kind };
+        const memory = this.proposals.get(toolCallId) ?? { emitted: 0, allowed: 0 };
+        this.proposals.set(toolCallId, memory);
+        // The first emission carries the kit's id (the WAITING row the kit looks
+        // up); a re-issue carries a fresh call id, as the resumed SDK agent does,
+        // and the adapter reconciles it onto the committed row by identity.
+        const callId = memory.emitted === 0 ? toolCallId : `${toolCallId}#${memory.emitted}`;
+        memory.emitted += 1;
+        const name = STREAM_NAME[gated.kind];
+        const args = streamArgsFor(gated);
+        const workspaceRoot = this.workspaceRootOf(view.sessionId);
+        return [
+            step.event(ev.toolCall(callId, name, "running", args)),
+            step.effect(`kit: the real hook judges ${name} ${gated.resource}`, () => {
+                const { permission } = runWorkspaceHook(workspaceRoot, hookInputFor(gated));
+                if (permission === "allow")
+                    memory.allowed += 1;
+                if ((permission === "allow") !== emission.expectAllow) {
+                    this.hookDisagreements.push(`${toolCallId}: expected ${emission.expectAllow ? "allow" : "deny"}, hook answered ${permission}`);
+                }
+            }),
+            emission.expectAllow
+                ? step.event(ev.toolCall(callId, name, "completed", args, ALLOWED_RESULT))
+                : step.event(ev.toolCall(callId, name, "error", args, HOOK_BLOCKED_RESULT)),
+        ];
+    }
+    /**
+     * A write the arm expects to FLOW under apply-then-review capture: the
+     * stream tool call, the REAL hook (which allows a git-capturable write in
+     * capture mode — asserted through the disagreement record like every other
+     * hook answer), the write itself as the SDK would perform it once allowed
+     * (the bytes are this double's own: the tool-call id, one line, appended),
+     * and the completion. The runtime captures the change after the turn; the
+     * hook's sidecar is what this adapter binds as its CAS observations, so a
+     * gitignored path here would reach the review that way.
+     */
+    flowingWriteSteps(toolCallId, action, view, ev) {
+        if (action.kind !== "write") {
+            throw new Error(`${this.name}: only a write flows under capture (got ${action.kind}); test bug`);
+        }
+        const memory = this.proposals.get(toolCallId) ?? { emitted: 0, allowed: 0 };
+        this.proposals.set(toolCallId, memory);
+        if (memory.allowed > 0)
+            return [];
+        memory.emitted += 1;
+        const gated = { ...action, kind: "write" };
+        const args = streamArgsFor(gated);
+        const workspaceRoot = this.workspaceRootOf(view.sessionId);
+        const file = join(workspaceRoot, action.resource);
+        return [
+            step.event(ev.toolCall(toolCallId, STREAM_NAME.write, "running", args)),
+            step.effect(`kit: the real hook lets ${action.resource} flow under capture`, () => {
+                const { permission } = runWorkspaceHook(workspaceRoot, hookInputFor(gated));
+                if (permission !== "allow") {
+                    this.hookDisagreements.push(`${toolCallId}: expected a flowing write to be allowed, hook answered ${permission}`);
+                    return;
+                }
+                memory.allowed += 1;
+                mkdirSync(dirname(file), { recursive: true });
+                appendFileSync(file, `${toolCallId}\n`);
+            }),
+            step.event(ev.toolCall(toolCallId, STREAM_NAME.write, "completed", args, ALLOWED_RESULT)),
+        ];
+    }
+    /**
+     * An ungated read: the stream tool call, the REAL hook (which allows every
+     * read — the gate's baked-in category set has no arm for it; asserted
+     * through the disagreement record like every other hook answer), and the
+     * completion with contents. The SDK executes what the hook allows, so the
+     * read counts as run.
+     */
+    readSteps(toolCallId, path, view, ev) {
+        const memory = this.proposals.get(toolCallId) ?? { emitted: 0, allowed: 0 };
+        this.proposals.set(toolCallId, memory);
+        memory.emitted += 1;
+        const args = { path };
+        const workspaceRoot = this.workspaceRootOf(view.sessionId);
+        return [
+            step.event(ev.toolCall(toolCallId, "read", "running", args)),
+            step.effect(`kit: the real hook judges read ${path}`, () => {
+                const { permission } = runWorkspaceHook(workspaceRoot, hookInputFor({ kind: "read", resource: path }));
+                if (permission === "allow")
+                    memory.allowed += 1;
+                else
+                    this.hookDisagreements.push(`${toolCallId}: expected allow for a read, hook answered ${permission}`);
+            }),
+            step.event(ev.toolCall(toolCallId, "read", "completed", args, `contents of ${path}`)),
+        ];
+    }
+    /**
+     * Park until the adapter cancels the run — the real shape of "the engine
+     * makes no progress until told to stop": the adapter's stop-signal listener
+     * calls `run.cancel()`, the double's status flips, and its stream breaks at
+     * the next step.
+     */
+    park(run) {
+        for (const waiter of this.hangWaiters.splice(0))
+            waiter();
+        if (run.status === "cancelled")
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const unsubscribe = run.onDidChangeStatus((status) => {
+                if (status !== "cancelled")
+                    return;
+                unsubscribe();
+                resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=contract-subject.js.map

package/dist/activities/execute-cursor/__test-utils__/contract-subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-subject.js","sourceRoot":"","sources":["../../../../src/activities/execute-cursor/__test-utils__/contract-subject.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/__test-utils__/cursor-hook-harness.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Test harness for the generated Cursor preToolUse bash hook.
+ *
+ * Runs the ACTUAL bash script the runner writes into the workspace, feeding it
+ * the REAL hook-input shapes captured from `@cursor/sdk`. It is the out-of-process
+ * deny-oracle's only honest test surface: write the runner-owned state file (with
+ * any approval grants), invoke the hook, and read back its allow/deny decision
+ * and the denial ledger.
+ *
+ * Extracted from `__tests__/hook-script.test.ts` so it is shared by both that
+ * behavior suite and the deny-oracle adapter in the gateway Contract Test Kit
+ * (`__test-utils__/gateway-substrate.ts`) — one harness, no drift.
+ *
+ * Each harness owns a throwaway workspace under the OS temp dir and self-cleans
+ * via `onTestFinished`, so it must be called from within a running test.
+ */
+import { type ApprovalGrant } from "../approval-state.js";
+import type { ApprovalCategory, McpApprovalDefault } from "../approval-policy.js";
+import { type ToolLists } from "../../../shared/tool-lists.js";
+import type { McpToolListing } from "../../../shared/mcp-tool-listing.js";
+import { type CasObservations } from "../cas-observations.js";
+import type { ProposedAction } from "../../../__test-utils__/approval-contract/types.js";
+/**
+ * Whether `bash` is available on this machine. Hook tests must be skipped where
+ * it is not — use `const d = hasBash ? describe : describe.skip`.
+ */
+export declare const hasBash: boolean;
+export interface CursorHookHarness {
+    /** The throwaway workspace root (git repo when capture mode is on). */
+    readonly root: string;
+    /** The throwaway platform dir (outside the workspace) the `platform` link points at. */
+    readonly platformDir: string;
+    /** Run the hook against a single hook-input payload and report its decision. */
+    decide(input: object): {
+        permission: string;
+        raw: string;
+    };
+    /**
+     * {@link decide} without blocking the event loop: the script asks the hook
+     * server, which answers in this process (`hookServer`).
+     */
+    decideAsync(input: object): Promise<{
+        permission: string;
+        raw: string;
+    }>;
+    /**
+     * The denial ledger entries the hook has appended this turn, raw. `kind` is
+     * the attribution taxonomy (approval/secret/capture-error/fail-closed/
+     * disabled); `input` is the base64(JSON(tool_input)) the hook captures on
+     * APPROVAL-kind entries only; `message` the base64 refusal text on a
+     * tool-list refusal.
+     */
+    ledger(): Array<{
+        toolName: string;
+        token: string;
+        kind?: string;
+        input?: string;
+        message?: string;
+        hook?: string;
+    }>;
+    /** The hook's directory, the harness's `hitlDir` analog: `readDenialLedger(h.hitlDir)` reads what the runner reads. */
+    readonly hitlDir: string;
+    /** Truncate the denial ledger (a fresh turn). */
+    resetLedger(): void;
+    /**
+     * The cas-observations the hook staged this turn (captured gitignored writes +
+     * secret-blocked paths), read back through the real sidecar reader. Empty when
+     * captureIgnored is off / nothing was staged.
+     */
+    observations(): Promise<CasObservations>;
+}
+export interface CursorHookHarnessOptions {
+    /** Pre-armed spec.auto_approve_all (the whole-run global bypass). */
+    autoApproveAll?: boolean;
+    /** Built-in categories with a run-lifetime scoped lease. */
+    leasedCategories?: ApprovalCategory[];
+    grants?: ApprovalGrant[];
+    /** Tools of the MCP server "srv" (the one {@link hookMcp} names) that its server marks destructive. */
+    destructiveMcpTools?: string[];
+    /** The server {@link destructiveMcpTools} belong to; "srv" (the one {@link hookMcp} names by default) when absent. */
+    destructiveMcpServer?: string;
+    /** MCP servers with a run-lifetime lease. */
+    leasedMcpServers?: string[];
+    /** Omit the state file to exercise the fail-closed (deny) path. */
+    noStateFile?: boolean;
+    /**
+     * Process the hook treats as "the runner". Defaults to this test process,
+     * which is an ancestor of the bash child `execFileSync` spawns — so the scope
+     * guard sees the call as the runner's own agent and applies the gate. Pass a
+     * non-ancestor PID to exercise the foreign-client path (issue #173).
+     */
+    runnerPid?: number;
+    /**
+     * Capture mode (git workspaces): the hook ALLOWS write/edit/delete to flow,
+     * gating only gitignored paths, shell, and MCP. When set, the harness baked
+     * workspace root is the throwaway workspace so `git check-ignore` resolves.
+     */
+    captureMode?: boolean;
+    /**
+     * The turn's file review (default on). Off, the hook ALLOWS a built-in
+     * write or delete to flow unreviewed; the secret-like write block still
+     * applies, keyed on the git substrate.
+     */
+    fileReview?: boolean;
+    /**
+     * Initialize the throwaway workspace as a git repo with these gitignore
+     * patterns, so capture mode's `git check-ignore` has a real repo to consult.
+     */
+    gitignored?: string[];
+    /**
+     * CAS capture of gitignored writes (deep-agent parity). When true, the hook
+     * stages a non-secret gitignored write's before-bytes into the cas-observations
+     * sidecar and ALLOWS it, and hard-blocks a secret-like gitignored write —
+     * instead of denying every gitignored write. Requires a git repo (set via
+     * {@link captureMode} or {@link gitignored}).
+     */
+    captureIgnored?: boolean;
+    /**
+     * Whether the workspace is a git tree. Default true. When false the
+     * throwaway workspace is NOT git-initialized and the state's `gitWorkspace` flag
+     * is false, so the hook CAS-stages EVERY write (not only gitignored ones) and
+     * skips the git-tracked flow arm.
+     */
+    gitWorkspace?: boolean;
+    /**
+     * Unattended approval mode: approval denies are recorded with the
+     * non-pausing "unattended" kind and the adapt-and-explain agent message.
+     */
+    unattendedSkip?: boolean;
+    /**
+     * The main agent's tool lists. Compiled into the state exactly as the
+     * runner compiles them (`hook-scope.ts`).
+     */
+    lists?: ToolLists;
+    /**
+     * What the workspace's `.stigmer` is this turn (default: the platform link
+     * when `lists` is set, else nothing): `platform`, the runner's link to the
+     * harness's throwaway platform dir; `repo`, a repository's own symlink to a
+     * real directory inside the workspace (an unlinked turn); `none`. The read
+     * root is derived from it as `turn-setup.ts` `platformReadRoot` derives it.
+     */
+    stigmerLink?: "platform" | "repo" | "none";
+    /** The turn's MCP servers and the tools the turn start listed of each (null: its listing failed). */
+    mcpServers?: Array<{
+        slug: string;
+        listedTools: string[] | null;
+    }>;
+    /** Plugin servers whose tools could not be listed this turn: every one of their tools asks. */
+    unlistedMcpServers?: string[];
+    /** The platform's synthesized attachment slugs (always in scope). */
+    platformServerSlugs?: string[];
+    /** The custom sub-agent types registered with the SDK. */
+    subAgentTypes?: string[];
+    /** The turn's hook server, named in the active-turn pointer as the runner names it. */
+    hookServer?: {
+        socketPath: string;
+        token: string;
+    };
+}
+/** The turn start's listing of the harness's servers: a `null` tool list is a server whose listing failed. */
+export declare function listingOf(servers: readonly {
+    slug: string;
+    listedTools: readonly string[] | null;
+}[]): McpToolListing;
+/** The approval default of a turn whose servers mark nothing destructive and hold no lease. */
+export declare const NO_MCP_DEFAULT: McpApprovalDefault;
+/**
+ * Build a throwaway workspace, write the generated hook + (optionally) the
+ * approval state file, and return a driver for the real bash hook.
+ */
+export declare function setupCursorHookHarness(opts?: CursorHookHarnessOptions): CursorHookHarness;
+export declare const hookWrite: (filePath: string, content?: string) => {
+    tool_name: string;
+    tool_input: {
+        file_path: string;
+        content: string;
+    };
+};
+export declare const hookEdit: (filePath: string, oldString?: string, newString?: string) => {
+    tool_name: string;
+    tool_input: {
+        file_path: string;
+        old_string: string;
+        new_string: string;
+    };
+};
+export declare const hookShell: (command: string) => {
+    tool_name: string;
+    tool_input: {
+        command: string;
+        cwd: string;
+        timeout: number;
+    };
+};
+export declare const hookDelete: (filePath: string) => {
+    tool_name: string;
+    tool_input: {
+        file_path: string;
+    };
+};
+export declare const hookRead: (filePath: string) => {
+    tool_name: string;
+    tool_input: {
+        file_path: string;
+    };
+};
+export declare const hookMcp: (name: string, input?: Record<string, unknown>, server?: string) => {
+    tool_name: string;
+    tool_input: string;
+    mcp_server_name: string;
+    command: string;
+    hook_event_name: string;
+};
+export declare const hookMcpPreToolUse: (name: string) => {
+    tool_name: string;
+    tool_input: {};
+    hook_event_name: string;
+};
+export declare const hookSubagentStart: (subagentType: string) => {
+    subagent_id: string;
+    subagent_type: string;
+    task: string;
+    parent_conversation_id: string;
+    tool_call_id: string;
+    hook_event_name: string;
+};
+export declare const hookBuiltin: (toolName: string, toolInput: Record<string, unknown>, cwd?: string) => {
+    hook_event_name: string;
+    cwd?: string | undefined;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+};
+/** Build the real preToolUse hook-input payload for an abstract action. */
+export declare function hookInputFor(action: ProposedAction): object;
+/** The gated built-in categories: the only action kinds a grant is ever minted for. */
+export type GatedActionKind = "write" | "shell" | "delete";
+/**
+ * Stream-side (SDK) tool name per gated category — deliberately the OTHER
+ * taxonomy from the hook input, so a grant minted from the stream matches a
+ * hook-named call only via the canonical category, not the raw name.
+ */
+export declare const STREAM_NAME: Record<GatedActionKind, string>;
+/**
+ * The stream-side args of a gated action, mirroring {@link hookInputFor}: a
+ * write carries whole-file content (so its digest is content-exact and matches
+ * the hook's), a delete carries only a path, and a shell carries its command
+ * (the salient is already exact). The shapes the goldens' `edit` events use.
+ */
+export declare function streamArgsFor(action: ProposedAction & {
+    kind: GatedActionKind;
+}): Record<string, unknown>;