@sema-ai/core 1.275.1

package/dist/core/types.d.ts

@@ -0,0 +1,2828 @@
+import type { TSchema } from "typebox";
+import type { AgentTool, ThinkingLevel } from "../internal/harness.js";
+import type { DocumentContent, ImageContent, Model, ResilienceOptions, StreamFn, TextContent } from "../internal/llm.js";
+import type { TaskNotificationPayload } from "./task-notification.js";
+/** A model reference: either a fully-formed Model, or a `"provider/id"` ref resolved via a catalog. */
+export type ModelRef = string | Model;
+/**
+ * Logical model roles, so a deployment declares its models once and every subsystem asks for its
+ * role instead of repeating a model name. Resolved against `RunnerDeps.roles` / `TaskSpec.roles`
+ * with a fallback chain (e.g. `summarize → default`, `synthesize → team → default`).
+ * - `default` — the main task model when `TaskSpec.model` is omitted.
+ * - `summarize` — between-turn compaction/summarization (aider's "weak model"); a cheap tier.
+ * - `subagent` — delegated sub-runs (`createSubagentTool` without an explicit model).
+ * - `team` / `synthesize` — team members / the neutral synthesizer.
+ * - `advisor` — the strong "teacher" a cheap student escalates to (`runWithTeacher`).
+ */
+export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier";
+/**
+ * A role's model: a `ModelRef`, or a config object that pins a `model`, **selects** one by
+ * capability/price (`select`, design/11 Layer 2), and/or sets a default `thinking` level.
+ */
+export type RoleSpec = ModelRef | {
+    model?: ModelRef;
+    select?: import("./select-model.js").ModelCriteria;
+    thinking?: ThinkingLevel;
+    /**
+     * Optional preset system prompt for this role (e.g. {@link CODE_AGENT_PROMPT} for a dev role).
+     * Used only when the task does not supply its own `TaskSpec.systemPrompt`. Lets coding roles run
+     * a coding prompt while other roles keep the neutral default — without touching the global default.
+     */
+    systemPrompt?: string;
+};
+/** Map of role → model. `TaskSpec.roles` overrides `RunnerDeps.roles` per task/scenario. */
+export type ModelRoles = Partial<Record<ModelRole, RoleSpec>>;
+/** The "external brain": a streaming completion function plus a non-streaming one (auto-derived if omitted). */
+export interface Brain {
+    /** Streaming completion. Must follow the AssistantMessageEvent stream contract (never throw post-invocation).
+     *
+     * NOTE: the return type is a union — `Stream | Promise<Stream>`. Third-party direct callers must
+     * normalize first (`const s = await brain.stream(...)`) before iterating or reading `.result()`,
+     * otherwise TS reports TS2339 on the union. The Runner already handles this internally. */
+    stream: StreamFn;
+    /**
+     * Optional non-streaming completion used by compaction/summarization.
+     * If omitted, it is derived from `stream` by consuming the stream to its final result.
+     *
+     * CONTRACT: a custom implementation must return the AssistantMessage with ALL fields intact —
+     * including `errorKind` (the compaction summary path keys its budget-escalation recovery on it)
+     * and `errorMessage`. Rebuilding the message with a field whitelist silently disables recovery.
+     */
+    complete?: (model: Model, context: {
+        systemPrompt?: string;
+        messages: unknown[];
+    }, options?: unknown) => Promise<unknown>;
+}
+/**
+ * Side-effect class of a tool. Used by wake/resume reconciliation: when a call was interrupted
+ * before its result was recorded, the outcome is unknown, so core must decide whether re-doing it
+ * is safe. See {@link reconcileInterruptedSession}.
+ * - `read` — no side effects (a query/lookup). Safe to call again.
+ * - `idempotent` — has a side effect, but repeating it with the same args is equivalent to doing it
+ *   once (e.g. `PUT` a known key, set-to-value). Safe to call again.
+ * - `write` — a non-idempotent side effect (delete, append, charge, send). **Unsafe to repeat
+ *   blindly.** This is the conservative default when `effect` is omitted.
+ */
+export type ToolEffect = "read" | "write" | "idempotent";
+/** A native tool the model can call. `parameters` is a typebox schema; `execute` does the work. */
+export interface ToolSpec<TParams extends TSchema = TSchema> {
+    /**
+     * Model-facing tool name. MUST NOT contain `__` — that separator is reserved for the MCP namespace
+     * (`mcp__<server>__<tool>`); a caller tool name with `__` is rejected at prepare-time (`config.tool_name_invalid`)
+     * because the durable-resume name shim ({@link canonicalToolName}) would mis-namespace it across an upgrade.
+    */
+    name: string;
+    /**
+     * Backward-compatible model-facing names that should dispatch to this tool. New transcripts and tool rosters
+     * should use {@link name}; aliases exist only so old model calls / SDK payloads / resumed sessions don't strand
+     * across a canonical rename.
+     */
+    aliases?: string[];
+    description: string;
+    /**
+     * Human label for UIs. Defaults to `name`.
+     *
+     * ⚠️ Currently INERT (design/71 liveness sweep, 2026-06-12): mapped onto the tool object but no
+     * runtime path or emitted event reads it — the model and TaskStream consumers only ever see
+     * `name`. Kept for API stability; wire it into tool events or drop it before building on it.
+     */
+    label?: string;
+    /**
+     * G1 通告层 (CC `agent_listing_delta` parity): the delegation tool's agent-type roster (name + one-line
+     * description), filled by `createSubagentTool` so the Runner's turn-boundary announcer can surface the
+     * "Available agent types" reminder without reaching into the tool's closure. Deployment-authored tools
+     * normally leave it unset; the announcer only runs when `TaskSpec.attachments.agentListing` opts in.
+     */
+    agentListing?: ReadonlyArray<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * design/136 §2.1.c — OPTIONAL pre-validation compatibility shim for raw tool-call arguments (mirrors the
+     * engine `AgentTool.prepareArguments` seam it is forwarded onto): map a LEGACY argument shape onto the
+     * current schema BEFORE schema validation, so a persisted old-shape call (a pre-rename durable checkpoint's
+     * pendingAction replayed via {@link canonicalToolName}) doesn't fail the declared-schema check. MUST be
+     * idempotent and identity for already-canonical args (the engine path applies it before validation AND the
+     * defineTool wrapper applies it again before its own check). Consumer example: the Agent tool maps the
+     * retired Fork tool's `{directive}` onto `{prompt, subagent_type:"fork"}`.
+     */
+    prepareArguments?: (args: unknown) => unknown;
+    /**
+     * Side-effect class for wake/resume safety. Defaults to `write` (conservative) when omitted:
+     * an interrupted call of unknown effect is treated as possibly-applied and never auto-repeated.
+     */
+    effect?: ToolEffect;
+    /**
+     * design/70: marks a tool whose execution is an EXTERNAL write (egress) — an outward-visible,
+     * effectively-irreversible action (open a PR, push a branch, send) as opposed to an internal side
+     * effect. **Orthogonal to {@link effect}**: `effect` is the repeat-safety axis (wake/resume
+     * reconciliation), `egress` is the blast-radius axis (the design/37 gate); reconcile/wake ignore it.
+     * The gate NEVER auto-allows an egress tool: a surviving `allow` (default or policy) is tightened to
+     * `ask`, so execution always passes an explicit ask-resolution — synchronous `onAsk`, a durable
+     * suspend (design/45), or a deployment-authored approver. Headless stays deny (an external write
+     * never happens without explicit confirmation). An egress tool must be repeat-unsafe: declaring
+     * `effect: "read"`/`"idempotent"` with `egress: true` is a configuration error (fail-fast at
+     * prepare) — omitting `effect` is fine (the default IS `write`).
+     */
+    egress?: true;
+    /**
+     * design/77 §4 (Gate 4 — irreversibility axis): how reversible this tool's effect is. A THIRD axis,
+     * orthogonal to {@link effect} (repeat-safety) and {@link egress} (blast-radius). For office/finance
+     * primitives (send money, file a return, send an email) where a wrong action cannot be undone, this
+     * forces a durable human-approval suspend BEFORE the tool runs:
+     *  - `"never"` — fully reversible; the gate leaves a surviving `allow` untouched (no ask).
+     *  - `"maybe"` — reversibility depends on the args; the gate calls {@link reversibilityProbe} (when one is
+     *     declared) on a surviving `allow` and tightens to `ask` UNLESS the probe reports reversible. A tool
+     *     that declares a `reversibilityProbe` but omits `irreversibility` defaults to `"maybe"` (so it always
+     *     enters the activation set and is gated).
+     *  - `"always"` — irreversible; the gate ALWAYS tightens a surviving `allow` to `ask` (like {@link egress}).
+     *
+     * The tighten mirrors the egress tighten (it only ever tightens allow→ask; a `deny`/`ask` is untouched),
+     * runs immediately AFTER it, and routes through the SAME ask-resolution: synchronous `onAsk`, a durable
+     * suspend (a new `{kind:"irreversible_ask"}` checkpoint → `status:"suspended"`), or a deployment approver.
+     * Headless with no approver SUSPENDS durably (never a model-facing deny — that would be a reward-hack
+     * retry surface), so an irreversible action never runs unattended without explicit confirmation.
+     *
+     * **Note (deliberate redundancy):** `egress` already means "effectively-irreversible external write"; an
+     * `egress:true` + `irreversibility:"always"` tool is DOUBLE-tightened. Harmless (allow→ask is idempotent
+     * under the deny>ask fold) — the two axes overlap on purpose, they are NOT strictly disjoint.
+     */
+    irreversibility?: "never" | "maybe" | "always";
+    /**
+     * design/77 §4: optional deployment-injected probe for an `irreversibility:"maybe"` tool. Given the call's
+     * (post-hook) args, it reports whether THIS specific call is reversible. The gate calls it ONLY when the
+     * surviving decision is `allow` and `irreversibility` resolves to `"maybe"`; it is time-bounded (the
+     * approval timeout) and **fail-closed**: a non-`reversible` verdict, a timeout, or a throw all tighten to
+     * `ask`. Declaring this probe defaults `irreversibility` to `"maybe"`. It is read from the spec at
+     * prepare-time and captured in a closure — NOT a tool argument — so the model cannot monkey-patch it.
+     */
+    reversibilityProbe?: (args: unknown) => {
+        reversible: boolean;
+    } | Promise<{
+        reversible: boolean;
+    }>;
+    /**
+     * Batch execution mode (design/64 §1 P1, CC reads-parallel/writes-sequential partition). When omitted,
+     * `defineTool` derives it FAIL-CLOSED from `effect` (CC 2.1.206 `TOOL_DEFAULTS.isConcurrencySafe → false`):
+     * `read` → `"parallel"`; `write`/`idempotent`/UNDECLARED → `"sequential"` — an unannotated tool never
+     * silently rides a parallel batch, and two writes in one batch never race. Set explicitly to override.
+     */
+    executionMode?: "sequential" | "parallel";
+    /**
+     * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): input-level concurrency
+     * refinement for a non-`"parallel"` tool — return `true` to let THIS CALL run in a parallel batch
+     * (and, under `streamingToolExecution`, start in-stream). An explicit `executionMode:"parallel"`
+     * needs no refinement (always safe); a throw = false (fail-closed). In the batch/stream paths the
+     * hook receives schema-VALIDATED (coerced) args — CC 206 `parsed.data` parity; a schema-invalid
+     * call is judged unsafe before the hook runs. Still treat defensively (direct callers may pass raw).
+     * The one real consumer is Bash's read-only classifier.
+     */
+    isConcurrencySafe?: (args: unknown) => boolean;
+    /** typebox schema for the tool arguments. */
+    parameters: TParams;
+    /**
+     * Large-result offload (design/30): set `false` to NEVER offload this tool's output (e.g. a file-read
+     * tool whose output IS the deliverable — offloading then immediately re-reading would just churn).
+     * Default: offload when the result exceeds the resolved threshold.
+     */
+    offload?: boolean;
+    /** Per-tool offload threshold (chars), overriding the global {@link RunnerDeps.toolResultThresholdChars}. */
+    offloadThresholdChars?: number;
+    /**
+     * Deferred disclosure (design/36): when `true`, this tool is NOT inlined with its full JSON Schema in
+     * every request. It appears as a lightweight placeholder (`{name, one-line hint, empty params}`) so
+     * the model knows it exists; the model must call the injected `tool_search` to activate it, at which
+     * point core materializes its full schema into the next request's `tools[]` (without disturbing the
+     * cache prefix). Use for large/MCP tool sets where inlining hundreds of schemas blows up turn-1 tokens
+     * and risks prefix-cache breakage. Default: not deferred (full schema inlined). See {@link RunnerDeps.deferMode}.
+     */
+    defer?: boolean;
+    /**
+     * Execute the tool. Return a string (becomes text content) or a structured result.
+     * Throw to signal failure (the loop encodes it as an error tool result).
+     */
+    execute: (args: unknown, ctx: ToolExecuteContext) => Promise<ToolReturn> | ToolReturn;
+}
+/** What a tool's execute may return. */
+export type ToolReturn = string | {
+    content: Array<TextContent | ImageContent | DocumentContent> | string;
+    /** Arbitrary structured details for logs/UI (not shown to the model unless put in content).
+     *  Producer side of the tool-result 双面契约: `content` is the MODEL face (may carry model-directed
+     *  framing/trailers), `details` is the HOST face (per-tool structured Output). Hosts render from the
+     *  structured face and never re-parse the model face — see the `tool_end.structured` JSDoc
+     *  (CC 2.1.207 @765495, CC207-CORE-SWEEP P2-3) for the full contract. */
+    details?: unknown;
+    /** Hint the agent to stop after this tool batch. */
+    terminate?: boolean;
+};
+export interface ToolExecuteContext {
+    toolCallId: string;
+    signal?: AbortSignal;
+    /**
+     * The RUNNING task's effective working root (worktree-aware), Runner-filled — read-only context a
+     * delegation tool threads into its child's trusted internals so the child's env can inherit the
+     * parent's cwd (CC parity: a Task sub-agent works in the main session's directory). Undefined when
+     * the tool runs outside a Runner task.
+     */
+    parentCwd?: string;
+    /**
+     * Report usage spent in a nested run this tool spawned (e.g. a sub-agent). The Runner accumulates
+     * it into the parent task's `TaskResult.stats.nested`, so delegated cost — the multi-agent "~15×"
+     * — is visible at the top level. `createSubagentTool` calls this automatically.
+     */
+    reportUsage?: (usage: {
+        tokens: number;
+        turns: number;
+        tasks: number;
+        costUsd?: number;
+        costMicroUsd?: number;
+    }) => void;
+    /**
+     * The model the PARENT task is currently running on, **snapshotted at the moment this tool is called**
+     * (design/38 1B). A delegation tool reads it to let a sub-agent `inherit` the caller's model. If the
+     * parent later degrades, an already-started child is unaffected (it kept the snapshot). Undefined when
+     * the tool runs outside a Runner task.
+     */
+    model?: Model;
+    /**
+     * The PARENT task's current thinking level, snapshotted at call time — the {@link model} companion.
+     * A delegation tool threads it into the child so a sub-agent inherits the caller's thinking depth by
+     * default (an explicit agent-definition/script `thinking` wins). Undefined outside a Runner task.
+     */
+    thinkingLevel?: ThinkingLevel;
+    /**
+     * The running task's authenticated end-user {@link TaskSpec.principal} (design/62), **read-only** — the
+     * Runner fills it; a tool cannot change it. A delegation tool (`createSubagentTool`) propagates it
+     * verbatim to its child task so the end-user identity is inherited down the delegation tree (the worker
+     * cannot substitute a different principal — it is not a tool argument). Undefined when the task has no
+     * principal or the tool runs outside a Runner task.
+     */
+    principal?: string;
+    /**
+     * design/112 C1/C5 — read-only SNAPSHOT of the parent task's client-supplied USER facts (timeZone/userEmail),
+     * inherited verbatim down the delegation tree like `principal`, so a subagent/fork child's
+     * `# Environment` block localizes "today" to the SAME user zone (not the container's UTC) and names the same
+     * user. Runner-filled (NOT a tool argument). Undefined when the task carries no clientContext.
+     */
+    clientContext?: TaskSpec["clientContext"];
+    /**
+     * 🔴 design/77 §3 / §7 — read-only SNAPSHOT of the parent task's ACTIVE skill-manifest frames (the
+     * Gate-3 deny-narrowing scope, see {@link SkillManifest}), filled by the Runner. A delegation tool
+     * (`createSubagentTool`) reads it AT SPAWN TIME and propagates it into the child task so the child
+     * inherits the parent skill's tool/path restrictions (a child of a manifested skill is at most as
+     * capable as the manifest). Returns an opaque, frozen array of frames; an empty array = no manifest is
+     * active (the common case). The model/worker can neither read nor set it (it is not a tool argument).
+     * Undefined when the tool runs outside a Runner task. The returned frame objects are intentionally
+     * opaque to callers other than the Runner internals that re-seed them.
+     */
+    activeSkillScope?: () => readonly unknown[];
+    /**
+     * design/99 (nested-subagent live observability): the host run's stable taskId (`spec.taskId ?? sessionId`),
+     * filled by the Runner. A delegation tool (`createSubagentTool`) reads it AT SPAWN TIME and threads it into the
+     * child as the child's `parentTaskId`, so a UI can build the live nested-agent tree (child.parentTaskId === this
+     * taskId). Undefined when the tool runs outside a Runner task.
+     */
+    taskId?: string;
+    /** design/129: the host run's SESSION id (Runner-filled, read-only) — a session-scoped background child
+     *  registers under it so later turns (fresh taskId) still reach the entry. */
+    sessionId?: string;
+    /** design/129: the host spec's `backgroundScope`, threaded read-only so delegation tools apply the
+     *  deployment's background-lifetime policy (never a model argument). */
+    backgroundScope?: "task" | "session";
+    /** design/129-B: the process-level background-child observer ({@link RunnerDeps.onBackgroundChildEvent}),
+     *  threaded read-only so the Agent tool's background lane reports spawn/tick/terminal for the child's
+     *  whole lifetime (a per-leg sink goes stale when the leg settles; this one never does). */
+    onBackgroundChildEvent?: (event: BackgroundChildEvent) => void;
+    /**
+     * design/115 P3 — the run-local task-notification sink (the SAME lane runtask wires for workflow/bash
+     * completions). Injected by prepare-task's spec.tools wrapper so a caller-mounted delegation tool can
+     * fire background-agent completion notifications into the SOURCE task's next turn. TRUSTED, run-scoped.
+     */
+    onTaskNotification?: (n: import("./task-notification.js").TaskNotificationPayload, opts?: {
+        priority?: import("./task-notification.js").SystemInjectionPriority;
+    }) => void;
+    /**
+     * design/99 (nested-subagent live observability): the host run's OPT-IN display sink — a deployment sets it (via
+     * `RunInternals.onForwardEvent`) to receive a SUBAGENT's live `task_progress` ticks that otherwise stay in the
+     * child's ISOLATED stream. A delegation tool threads it to the child so nested progress bubbles to one sink. This
+     * is a DISPLAY channel ONLY — the child stream is NEVER merged into the parent's MODEL context, and nothing
+     * security-relevant consumes a forwarded event. Present ONLY when the deployment opted in; the Runner filters it
+     * to `task_progress` (a tool cannot push other event types). ⚠️ Forwarded ticks are UNTRUSTED display hints — any
+     * tool holding this ctx could forge one, so a consumer validates `parentTaskId` against its known runs.
+     */
+    forwardEvent?: (event: TaskEvent) => void;
+    /**
+     * Blackboard 2026-07-03 (subagent steer verb): the host run's opt-in SUBAGENT-STEER-HANDLE sink
+     * (threaded from `RunInternals.onSubagentSpawn`). When present, `createSubagentTool` runs each sync
+     * child via `runTaskStream` and emits a steer handle here; the deployment routes a human steer into
+     * the running child. The handle never reaches the model. Absent ⇒ children run non-steerable.
+     */
+    onSubagentSpawn?: (handle: import("../agents/subagent.js").SubagentSteerHandle) => void;
+    /**
+     * design/122 D1 — the parent run's subagent-retain LEDGER, present ONLY when the parent's
+     * {@link TaskSpec.retainSubagentSessions} is enabled. TRUSTED run-scoped state the Runner fills (never a
+     * tool argument): `createSubagentTool` registers each retained child here (pre-minted sessionId + a
+     * FROZEN plain spec snapshot — never the live ctx/spec-builder closures, r1-m5) and the Runner disposes
+     * the whole ledger (abort in-flight resumes + unpin + release every retained session) when the parent
+     * run ends (D4).
+     */
+    subagentRetain?: import("../agents/subagent.js").SubagentRetainLedger;
+    /**
+     * design/135 §0 — the TRUSTED per-call worktree-isolation lane for the Agent tool (CC
+     * `isolation: "worktree"`). The Runner fills it (prepare-task builds it over the run's ExecutionEnv +
+     * task root via `createSubagentWorktreeHelper`) for write-capable runs; a tool cannot forge it and the
+     * model only REQUESTS isolation via the Agent tool's `isolation` parameter — the capability itself is
+     * never a model argument. Absent ⇒ the deployment cannot mint worktrees (read-only run / outside a
+     * Runner) and the Agent tool reports isolation as honestly unavailable.
+     */
+    worktreeIsolation?: import("../agents/subagent.js").SubagentWorktreeIsolation;
+    /**
+     * design/135 §0 — TRUE when THIS run is itself a forked child ({@link RunInternals.insideFork}),
+     * threaded read-only so the Agent tool's built-in `subagent_type:"fork"` route can refuse nested forks
+     * (CC: "fork is not available inside a forked worker") even for a deployment-mounted Agent tool that
+     * flowed into the forked child via its tool list. Runner-filled; never a model argument.
+     */
+    insideFork?: boolean;
+    /**
+     * OBS-2 (CC 2.1.206 observer parity) — present iff this run's principal resolved
+     * {@link RuntimeCaps.allowObservers}` === true` (EXPLICIT opt-in, default OFF — see the polarity
+     * note there). The delegation tool honors {@link AgentDefinition.observer} declarations only under
+     * this flag; absent ⇒ declarations resolve to unobserved with NO warn (the gate, not a mistake).
+     * Runner-filled at call time (same closure posture as `forkAccess`); never a model argument.
+     */
+    observersAllowed?: true;
+    /**
+     * design/136 §6 盲点① — the Runner-computed fork-GOVERNANCE verdict for THIS run (from
+     * `forkGovernanceDenial(spec.enableFork, runtimeCaps.allowFork)`), threaded read-only so the Agent
+     * tool's built-in `subagent_type:"fork"` route enforces the SAME per-task/per-principal authorization
+     * as the standalone Fork tool's mount gate (pre-1.256, `allowFork:false` only prevented mounting Fork
+     * while Agent-fork ran ungoverned). Present ONLY when governance DENIES (`denied:"task"` =
+     * `enableFork:false`; `denied:"principal"` = `runtimeCaps.allowFork:false`) — absent means governance
+     * does not object (or the tool runs outside a Runner ⇒ capability checks only). Runner-filled; never a
+     * model argument.
+     */
+    forkAccess?: {
+        denied: "task" | "principal";
+    };
+    /**
+     * design/80 D-B — the general "a tool yields to a HUMAN review gate" primitive. A tool calls this to request
+     * that, at the next SAFE turn boundary, the engine pause with a durable `plan_review` checkpoint
+     * (`status:"needs_review"`) so a human approves/edits/rejects before the run continues. The tool still returns
+     * its `content` normally first (the plan/diff lives there → reaches the reviewer via the transcript). HONORED
+     * only when the deployment can actually pause (a `checkpointStore` is wired); otherwise the request is a silent
+     * no-op (read-only/headless degrade). The first-party `present_plan` tool (CC `ExitPlanMode` parity) is a thin
+     * caller of this; any tool may use it to gate a high-blast step on human review. Idempotent within a batch (the
+     * first request wins; the suspend fires once at the boundary). The Runner fills it; not a tool arg.
+     */
+    requestReview?: (opts?: {
+        reason?: string;
+    }) => void;
+    /**
+     * design/105 — request a CLEAN stop of THIS run after the current turn (NOT an abort: the loop finishes the
+     * turn, then exits gracefully — no orphan-[INTERRUPTED] reconcile). A thin binding to the harness's existing
+     * one-way `requestStopAfterTurn` flag (the same the human-suspend saga uses). Typical use: a tool that
+     * persisted a delayed self-wake intent (e.g. CronCreate with kind:"delay") ends the run cleanly so the
+     * daemon owns the re-wake ("end now, re-wake" — NOT "suspend-continue", see design/105 §3.4). Idempotent
+     * one-way flag; a no-op for tools that don't call it. The Runner fills it; not a tool arg. Absent outside a Runner.
+     */
+    requestStopAfterTurn?: () => void;
+    /**
+     * design/108 — enter mid-run READ-ONLY plan mode: the rest of THIS run rejects write-effect tool calls
+     * (`effect !== "read"`), while read/research tools and `present_plan` still run. A run-local one-way flag
+     * (NOT durable — a later approve-resume re-prepares with it clear, so the approved plan can write). The
+     * first-party `enter_plan_mode` tool (CC `EnterPlanMode` parity) is the only caller; the engine enforces the
+     * read-only restriction in a dedicated plan-mode tool-call check (separate from the safety gate — plan mode
+     * is a FIDELITY mode, not a security boundary; the real safety gates apply independently). Idempotent; a
+     * no-op for tools that don't call it. The Runner fills it; not a tool arg. Absent outside a Runner.
+     */
+    enterPlanMode?: () => void;
+}
+/**
+ * design/138 S2-C — the hands band's write-time CONTENT hook (single source; `src/tools/fs` re-exports
+ * these so its import surface is unchanged — moved here by design/141 件2 because `RunnerDeps.hands`
+ * carries the deployment-composable half of the hook). Called before EVERY `env.writeFile` in
+ * Write/Edit/NotebookEdit with the resolved containment key and the exact final text; `{ ok:false }`
+ * fails the tool with a structured error and NOTHING is written. A THROWING hook fails CLOSED.
+ */
+export interface BeforeWriteRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — what the hook should judge. */
+    key: string;
+    /** The FINAL full text about to be written (Edit/NotebookEdit: after application). */
+    content: string;
+}
+export type BeforeWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type BeforeWriteHook = (req: BeforeWriteRequest) => BeforeWriteResult | undefined | Promise<BeforeWriteResult | undefined>;
+/**
+ * design/141 件2 — the SAFE deployment-configurable subset of the hands toolkit ({@link RunnerDeps.hands}).
+ * Only fields whose injection is purely additive for a deployment are here; Runner-internal orchestration
+ * state (taskRegistry/detachHub/execClamp/cwdRef/mount coordination) is deliberately NOT configurable.
+ */
+export interface HandsBandOptions {
+    /** Override the `bash_readonly` command allowlist (read-only band). Default: the built-in read-only set. */
+    bashReadonlyAllow?: readonly string[];
+    /** Co-Authored-By trailer for the bash git protocol; `false` disables it. Default: the built-in trailer. */
+    commitCoAuthor?: string | false;
+    /** Read-tool image downsampler: inject your own, or `false` to force-disable (deterministic no-sharp).
+     *  Omitted ⇒ auto-detect sharp. Same contract as the MCP-side {@link import("./mcp.js").ImageDownsampler}. */
+    readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
+    /** Deployment write gate — COMPOSED with (never replacing) the engine's MemoryEngine write-scan gate:
+     *  this hook judges first (a rejection short-circuits), the engine gate then still runs in full. */
+    beforeWrite?: BeforeWriteHook;
+}
+/**
+ * A declarative, reusable named sub-agent (design/38 1B). Hand a set to {@link createSubagentTool} and the
+ * model picks one (by `whenToUse`) to delegate to; the chosen definition's config builds the child task.
+ *
+ * **Deployment-side config, NOT user input** — `systemPrompt`/`allowTools` shape what the sub-agent can do
+ * and see, so they must be set by the deployment, never taken from an end-user message.
+ */
+export interface AgentDefinition {
+    /** Stable identifier + the value the delegation tool's `agent` parameter selects. Must be unique. */
+    name: string;
+    /** Guidance shown to the model for WHEN to pick this agent (listed in the delegation tool's description). */
+    whenToUse?: string;
+    /**
+     * F4 (CC 2.1.198 parity, `whenToUseLean` — 锚 pretty.js:409174 `rbm` + selection `tIl` :453029
+     * `(lean && e.whenToUseLean) || e.whenToUse`): a SHORT variant of {@link whenToUse} preferred on
+     * lean-prompt surfaces. sema posture: the engine runs the CC lean-prompt arm wholesale (web.ts
+     * lean-card precedent), so roster listings/descriptions prefer this text whenever present;
+     * {@link whenToUse} remains the fallback. Optional — a single-text agent behaves exactly as before.
+     */
+    whenToUseLean?: string;
+    /** Tool allowlist over the delegation pool (`["*"]` = all). Replaces (does not merge with) the tool's
+     *  own `allowTools`/`denyTools` when this agent is selected. F1 (CC parity): unlike the TOOL-level
+     *  allow/deny (which never filters the nested delegation tool — that stays `maxDepth`-governed), a
+     *  PER-AGENT allow/deny ALSO governs the nested delegation tool: an agent whose allow/deny excludes
+     *  the delegation tool's name cannot re-delegate (CC Explore/Plan `disallowedTools` include Agent,
+     *  pretty.js:409189/486948). */
+    allowTools?: string[];
+    /** Tool denylist (a deny always wins). See {@link allowTools} for the per-agent delegation-tool note. */
+    denyTools?: string[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `skills` — 锚 pretty.js:422126 `e.skills ?? []`, GA/ungated in 198:
+     * CC preloads each named skill's prompt content into the child's opening messages, warning on misses).
+     * sema shape: full {@link SkillSpec} objects (sema has no ambient skill registry to resolve bare names
+     * against) threaded into the chosen child's `TaskSpec.skills` — disclosed in its `<skills>` block +
+     * invocable via the `skill` tool. Deployment-trusted, same trust tier as `systemPrompt`.
+     */
+    skills?: SkillSpec[];
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `background` — 锚 pretty.js:453611 `H.background===!0` OR-ed into
+     * the background predicate, GA/ungated): `true` = this agent ALWAYS launches on the background lane
+     * (an omitted `run_in_background` no longer means sync, and the per-call parameter cannot force sync —
+     * CC-same OR semantics). Requires the delegation tool's `background` surface; without one the child
+     * runs synchronously (CC-same quiet fallback — CC's env kill-switch arm, :453611 `&& !sJt`).
+     */
+    background?: boolean;
+    /**
+     * F7 (CC 2.1.198 parity, per-agent `isolation` — 锚 pretty.js:453599 `z = a ?? H.isolation`, GA):
+     * default isolation for this agent; an explicit per-call `isolation` argument wins. sema supports
+     * `"worktree"` (CC's `"remote"` arm is a claude.ai-session concern, not ported).
+     */
+    isolation?: "worktree";
+    /** Model for this agent. **Omit to INHERIT the caller's current model** (design/38 1B finding 7) — the
+     *  recommended default; a concrete `ModelRef` pins it instead. */
+    model?: ModelRef;
+    /** Thinking level for this agent. **Omit to INHERIT the caller's current thinking level** (the model
+     *  companion above — a mid-run degrade/boost on the parent carries into new children); a concrete
+     *  level pins it instead. */
+    thinking?: ThinkingLevel;
+    /** System prompt / persona for this agent. Falls back to the delegation tool's `systemPrompt`. */
+    systemPrompt?: string;
+    /** Per-agent turn cap. Falls back to the delegation tool's `limits.maxTurns`. */
+    maxTurns?: number;
+    /** Long-term memory scope for this agent (same shape as {@link TaskSpec.memory}). */
+    memory?: TaskSpec["memory"];
+    /**
+     * Observer agents (CC 2.1.206 parity — 逐字锚 docs/CC206-OBSERVER-ANCHORS-2026-07-11.md, schema
+     * 面 C @28385708): "Agent type auto-spawned as a background observer whenever this agent runs.
+     * The observer receives read-only activity digests and reports via the ObserverReport tool; it
+     * never participates in the task." Resolution is warn-and-unobserved on an unknown type and
+     * refuses chaining (an observer's own `observer` declaration is ignored). Gated by
+     * {@link RuntimeCaps.allowObservers} — EXPLICIT opt-in, default OFF (the sema seat of CC's
+     * default-unset env `CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS` + default-true statsig pair).
+     */
+    observer?: string;
+    /**
+     * CC 面 C: "Supplemental postamble appended (after the harness-owned default) to each activity
+     * digest sent to the observer. Blank values are ignored."
+     */
+    observerMessage?: string;
+}
+/** Definition of an MCP server to connect to for the duration of one task, then discard. */
+export interface McpServerSpec {
+    /** Stable name; tool names are namespaced as `<name>__<tool>` to avoid collisions. */
+    name: string;
+    transport: {
+        kind: "stdio";
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    } | {
+        kind: "http";
+        url: string;
+        /** Static headers sent on every request (e.g. an auth bearer for the MCP server itself). */
+        headers?: Record<string, string>;
+        /**
+         * Per-task **end-user principal** header (design/62). When set, the Runner injects the running task's
+         * authenticated {@link TaskSpec.principal} as this header (e.g. `"X-Agent-Principal"`) on every call to
+         * this server's tools, so the MCP server can enforce per-user RBAC. Absent {@link TaskSpec.principal}
+         * ⇒ the header is **not** sent (the MCP server must default to deny/public, never admin). Overrides any
+         * same-named static `headers` entry. The principal is Runner-held and the model/worker can neither read
+         * nor set it (it is not a tool argument) — see {@link TaskSpec.principal}.
+         */
+        principalHeader?: string;
+    };
+    /** Optional allowlist of tool names to expose (others are dropped). */
+    allowTools?: string[];
+    /**
+     * design/99 §E23 — opt in to INBOUND elicitation for THIS server: when `true` AND a {@link RunnerDeps.onElicit}
+     * seam is wired, core advertises the `elicitation` capability to this server and registers a handler, so the
+     * server may send an `elicitation/create` request to ask the END USER for input mid-tool-call. **Default OFF
+     * (fail-closed)**: never advertise unless explicitly wired, so a hostile/over-eager server cannot pull a human
+     * into the loop. v1 is LIVE-ONLY — `onElicit` answers synchronously on the open connection (no durable
+     * suspend; a durable/cross-replica elicitation needs the deferred E22 longer-lived connection).
+     */
+    elicitation?: boolean;
+    /**
+     * Caller-side per-tool safety-axis overrides, keyed by the server's REMOTE (un-namespaced) tool name. The
+     * CALLER is the trust root: unlike a server's self-declared annotations (which may only TIGHTEN), a caller
+     * override is AUTHORITATIVE and may LOWER an effect (vouch a tool is `read`/`idempotent`) as well as raise it
+     * (`egress` / irreversible). This is the ONLY trusted way to drop an MCP tool below the fail-closed `write`
+     * default (design F). Folds over the server hints in prepare-task (caller > server hint > fail-closed write).
+     */
+    toolAxes?: Record<string, {
+        effect?: ToolEffect;
+        egress?: boolean;
+        irreversibility?: "always" | "never";
+    }>;
+}
+/**
+ * design/99 §E23 — an INBOUND MCP elicitation request (a connected server asking the END USER for input
+ * mid-tool-call). Handed to the deployment's {@link RunnerDeps.onElicit} seam. **UNTRUSTED**: `message` /
+ * `requestedSchema` / `url` are SERVER-controlled — core never interprets `requestedSchema`; a consumer that
+ * shows `message` to a human MUST fence it (`delimitUntrusted`).
+ */
+export interface McpElicitRequest {
+    /** The {@link McpServerSpec.name} of the server that issued the request. */
+    server: string;
+    /** The server's human-facing prompt (UNTRUSTED — fence before display). */
+    message: string;
+    /** Form mode: the server's requested input schema (a flat object of scalars). OPAQUE to core. */
+    requestedSchema?: unknown;
+    /**
+     * URL mode: a server-controlled URL the user is asked to visit (UNTRUSTED — a phishing/social-engineering
+     * surface; a consumer MUST scrutinize/fence it before showing it). **Inactive in v1**: core advertises
+     * FORM mode only, so the SDK rejects url-mode requests before this seam — this field is reserved for a
+     * future url-mode opt-in and is never populated today.
+     */
+    url?: string;
+    /** The running task's authenticated end-user (design/62), if any — for routing the prompt to the right human. */
+    principal?: string;
+}
+/** design/99 §E23 — the deployment's answer to an {@link McpElicitRequest} (returned to the MCP server). */
+export interface McpElicitResponse {
+    action: "accept" | "decline" | "cancel";
+    /** Submitted values (accept only); core passes them through opaquely, never validated against the schema. */
+    content?: Record<string, string | number | boolean | string[]>;
+}
+/**
+ * design/99 §E23 — the LIVE-ONLY inbound-elicitation seam. A deployment provides it (e.g. the sema shell
+ * prompts the user at the terminal) and returns the answer SYNCHRONOUSLY; core replies to the server on the
+ * still-open connection. Absent ⇒ no server is advertised the elicitation capability (fail-closed). Not a
+ * durable suspend — a crash/replica-change loses an in-flight elicitation (acceptable for an interactive shell).
+ *
+ * 🔴 THROTTLING IS THE DEPLOYMENT'S JOB: once a server is opted in, it may issue elicitations at any frequency
+ * (one per tool call, or many) — core imposes NO rate/count limit (an elicitation is not a tool call and does
+ * not ride the policy gate). `onElicit` is the choke point: throttle, aggregate, or `decline`/`cancel` an
+ * over-eager or hostile server here (the request's `AbortSignal` is forwarded so a deadline can cancel it).
+ */
+export type OnElicit = (req: McpElicitRequest, signal?: AbortSignal) => Promise<McpElicitResponse>;
+/**
+ * A per-skill runtime capability manifest (design/77 §3 Gate-3). When present, loading the skill
+ * SCOPES the rest of the invocation to ONLY these tools/paths via runtime deny-narrowing: a tool call
+ * not in `allowTools` (intersected across nested skill frames) is DENIED, and a write whose canonical
+ * target falls outside `allowPaths` is DENIED — regardless of how permissive the task policy is.
+ *
+ * 🔴 **Safe-by-construction:** a manifest can only SUBTRACT capability. The narrowing composes via the
+ * `deny > ask > allow` fold (`combinePolicies`) where `deny` short-circuits, so a manifest can never
+ * *grant* a tool the task policy withheld — an attacker who sets a manifest can only restrict further.
+ * Worst case (the model never pops the frame) = no narrowing, never widening — still ⊆ task policy.
+ *
+ * The manifest is CALLER-provided here (same trust level as the rest of `SkillSpec`); deriving it
+ * automatically (the auto-promote pipeline) is a separate, deferred concern (design/77 §5).
+ */
+export interface SkillManifest {
+    /** The ONLY tool names the invocation may call while this skill's frame is active. */
+    allowTools: string[];
+    /**
+     * Optional path allowlist for WRITE tools (`write_file`/`edit_file`): a write whose canonicalized
+     * target is not inside one of these (path-segment-aware) prefixes is DENIED. Omit = no path narrowing
+     * (only `allowTools` applies). Reads are never path-narrowed (this gate restricts capability, not visibility).
+     *
+     * 🔴 **Fail-closed (MAJOR-2):** `allowPaths` can only confine tools whose write target is a parseable `path`
+     * argument (`write_file`/`edit_file`). While an `allowPaths` constraint is active, any OTHER mutating
+     * (effect:write/idempotent) allowlisted tool — notably `bash`, whose command can write anywhere — is DENIED
+     * outright, because its target cannot be path-confined. So a manifest that lists `bash` together with
+     * `allowPaths` does NOT let bash write/egress anywhere: bash is denied while the path constraint is active.
+     * Confine writes to specific paths via `write_file`/`edit_file` only.
+     */
+    allowPaths?: string[];
+    /** Reserved (design/77 §3): whether egress is permitted under this manifest. Carried through; v1 does
+     *  not act on it beyond the allowTools intersection (egress tools must also be in `allowTools`). */
+    egress?: boolean;
+    /** Stable lineage id of the artifact this manifest came from — used in deny reasons + as the scope key. */
+    lineageId: string;
+}
+/** A skill made available to this task (passed as an object; not loaded from disk). */
+export interface SkillSpec {
+    name: string;
+    description: string;
+    content: string;
+    /** Optional Gate-3 runtime capability manifest (design/77 §3) — see {@link SkillManifest}. */
+    manifest?: SkillManifest;
+}
+/** An image attached to the task's user message: either inline base64 or a URL to fetch. */
+export type ImageInput = {
+    /** Base64-encoded image bytes (no data: prefix). */
+    data: string;
+    /** MIME type, e.g. "image/png" / "image/jpeg". */
+    mimeType: string;
+} | {
+    /** URL the runner will fetch and inline as base64 before sending to the model. */
+    url: string;
+};
+/** A single self-contained task with its full configuration. */
+export interface TaskSpec {
+    taskId?: string;
+    /** The instruction / latest user message for this turn. */
+    objective: string;
+    /**
+     * Authenticated **end-user principal** this task runs on behalf of (design/62) — an opaque identity string
+     * (user id, email, tenant-scoped subject) the **trusted caller** sets at task creation. The Runner holds it
+     * for the whole run and injects it into MCP requests for any server with a `principalHeader`
+     * ({@link McpServerSpec}), enabling per-user RBAC in the MCP server. Delegated child tasks (sub-agent / team /
+     * fan-out) inherit it.
+     *
+     * 🔴 **Trust contract (design/53 — authority stays in the control plane):** this is a control-plane value,
+     * **NOT model/worker input.** Set it only from the authenticated task-submission context; it is not exposed
+     * as a tool argument and the model cannot read or change it (a worker filling its own principal = a privilege
+     * bypass). Treat it as write-once for the run. The MCP server MUST trust this header only on the Runner's
+     * authenticated/TLS channel and default to deny/public when it is absent — never default-admin.
+     *
+     * 🔴🔴 **This is the GOVERNANCE key.** Per-principal entitlements are resolved off this value:
+     * {@link RunnerDeps.runtimeCapsResolver}`(spec.principal)` decides `allowWorkflows` (and thus whether
+     * self-orchestration / `RunWorkflow` is permitted). So a caller MUST set `spec.principal` to a
+     * **cryptographically VERIFIED** identity — **never a raw, spoofable request header**. A deployment that holds
+     * both an unverified header value AND a verified one (e.g. a "direct-door" path) MUST pass the VERIFIED one
+     * here: keying a gate on a spoofable principal is a multi-tenant governance BYPASS (a forged header would
+     * inherit another tenant's entitlements). Core cannot verify identity itself (no crypto context) — it trusts
+     * this value by contract; getting it wrong is a privilege-escalation hole, not a core bug.
+     */
+    principal?: string;
+    /** Optional images attached to this turn's user message (model must support vision). */
+    images?: ImageInput[];
+    /** Reuse an existing in-memory session for chat continuity; omit to start fresh. */
+    sessionId?: string;
+    /**
+     * design/114 Phase3 — with `sessionId` set, REQUIRE that session to already exist: if it is gone (e.g. a
+     * non-durable store lost it across a restart, or a typo'd id), the run FAILS LOUD (`resume.session_not_found`)
+     * instead of silently creating a fresh empty session and running with NO warm context. Use this for a
+     * reuse-style warm-resume (`runTask({sessionId, requireExistingSession: true})`) so "looks warm, actually
+     * fresh" can never happen. (The `fork`-first path via `warmResume` is already fail-loud without this flag.)
+     * Ignored when `sessionId` is absent. Default `false` = today's create-on-miss behavior.
+     */
+    requireExistingSession?: boolean;
+    /**
+     * design/112 C1/C5 — CLIENT-supplied USER facts (distinct from execution-env/container facts). In TOB the
+     * worker container runs UTC and has no idea who the user is or where they are; the client/REPL/gateway knows.
+     * It threads these so the `# Environment` block localizes "today" to the user's zone (else it annotates UTC)
+     * and names who the agent acts for. All optional; absent ⇒ current behavior (UTC date, no user line). This is
+     * the USER half of the env block — the WORKSPACE half (cwd/git/platform/shell) is probed THROUGH the
+     * ExecutionEnv (the container), never from here.
+     */
+    clientContext?: {
+        /** IANA time zone of the user (e.g. `Asia/Tokyo`) — localizes the env block's date. Invalid zones fall back
+         *  to UTC (date AND annotation) rather than mislabeling — see `isValidTimeZone`. */
+        timeZone?: string;
+        /** The user's identity (e.g. email) — surfaced in the env block so the agent knows who it acts for. */
+        userEmail?: string;
+    };
+    /**
+     * design/99 §E18 (resume-at) — BRANCH the session at this prior entry BEFORE the turn: replay root→here,
+     * then run the new `objective` as the next turn (the shell's "rewind to this message, ask differently").
+     * Requires `sessionId`. **The id is a core `SessionTreeEntry.id`** — a persisted session-entry id — **NOT a
+     * live {@link TaskEventIdentity.eventId}** (eventIds are never persisted; a deployment that holds eventIds
+     * owns the eventId→entryId map). Must reference a `message`/`custom_message` entry, and NOT an assistant
+     * message that ends mid-tool-call (a SETTLED turn boundary — else the replay would orphan-close a done call).
+     * Non-destructive: recorded as a branch `leaf` entry, so prior leaves stay in the tree (re-resume any time).
+     * Mutually exclusive with a durable `runner.resume(...)` (the Runner rejects both at once).
+     */
+    resumeAt?: string;
+    /**
+     * Which model to run on. If omitted, resolved from the `modelRole` (default `"default"`) against
+     * `roles` / `RunnerDeps.roles`. Either `model` or a resolvable role must be available.
+     */
+    model?: ModelRef;
+    /** Which role to resolve when `model` is omitted. Default `"default"`. */
+    modelRole?: ModelRole;
+    /** Per-task/scenario role→model overrides (merged over `RunnerDeps.roles`, task wins). */
+    roles?: ModelRoles;
+    /** Optional cheaper model for compaction/summarization. Falls back to the `summarize` role if set. */
+    compactionModel?: ModelRef;
+    /** Thinking level. If omitted, a default from the resolved role's `RoleSpec.thinking` applies. */
+    thinking?: ThinkingLevel;
+    /** Preset system prompt for this task. */
+    systemPrompt?: string;
+    /**
+     * APPEND a caller block to the assembled system prompt, keeping the engine's base + harness/safety blocks
+     * (unlike `systemPrompt`, which REPLACES the base, and `promptProvider`, which rewrites the whole assembly).
+     * The lightweight user/scenario-extension seam (≈ CC `--append-system-prompt`): add task-specific rules,
+     * domain context, or a persona tweak without losing the neutral base, cyber/url safety, harness context, or
+     * memory discipline. CALLER-TRUSTED (same trust level as `systemPrompt`/`skills` — NOT user input). Composed
+     * as a STABLE block (prepare-time) at the END of the stable prefix, before the volatile `<user_memory>` tail,
+     * so it never breaks prefix-cache friendliness. Composes WITH `systemPrompt` (appended after it).
+     */
+    appendSystemPrompt?: string;
+    /**
+     * Per-task ROLE-LAYER prompt provider (overrides `RunnerDeps.promptProvider`). Lets one Runner serve
+     * different scenarios with different role prompts. 提示词主权批: `stableSystem` supplies the role base
+     * only — core appends the constitution (harness/safety/mode/memory blocks) structurally, so a provider
+     * cannot drop it by accident; `replaceAll: true` is the explicit full-replacement escape hatch.
+     * TRUST BOUNDARY: a provider is function-valued and therefore CODE — it can only be set by in-process
+     * deployment code, never by a wire-level (JSON) task submission; untrusted self-orchestration specs
+     * additionally have this field stripped by workflow governance. The `prompt.assembled` trace records
+     * which mode ran, so a `replaceAll` is always observable.
+     */
+    promptProvider?: import("../prompts/default.js").PromptProvider;
+    /**
+     * Enable long-term memory for this task. **design/138 S4 (BREAKING): requires `RunnerDeps.memoryBackend`**
+     * (the injection-first memory engine — materialize → file ops → harvest). With a backend configured the
+     * task gets the CC-verbatim `# Memory` instruction + fenced derived index and works memory through its
+     * ordinary file tools. WITHOUT a backend this field is INERT: the legacy `RunnerDeps.memoryStore` fallback
+     * (remember/recall tools + legacy `<user_memory>` injection) was retired — the task runs memory-less and
+     * one deprecation warning is emitted via `onError` (phase `"config"`).
+     *
+     * **design/84 Seam A** — single opaque scope → an **ordered, opaque scope list + a single writeScope**.
+     * The engine only does read-side **layered injection** (one `<user_memory>` block, a `<scope …>` subsection
+     * per scope, ordered by priority — the LAST scope is highest-priority and lands at the prompt TAIL) and
+     * write-side **single-point routing** (remember/consolidation only ever write `writeScope`; the model never
+     * picks a layer). Scope strings stay OPAQUE — the client/profile derives them (TOC: managed/user/project/
+     * agent/local; TOB: tenant hierarchy). All three fields are normalized to one canonical shape
+     * ({@link import("./memory.js").normalizeMemorySpec}) — `scope` → `[scope]`, `writeScope` defaults to the
+     * LAST scope — so the consumer side reads one array with zero narrowing.
+     *
+     * Cache discipline (§5, implemented in prepare-task): the scopes are injected in list order, so the
+     * caller places STABLE layers (managed/user/org — rarely change) FIRST (cacheable prefix) and VOLATILE
+     * layers (project/agent/local) LAST (only the tail re-computes). The stable prefix is byte-stable.
+     *
+     * Backward compatible: a plain `{ scope: "user:42" }` is unchanged (normalizes to `scopes:["user:42"]`,
+     * `writeScope:"user:42"`).
+     *
+     * The accepted shape is {@link import("./memory.js").MemorySpecInput} (the SAME type
+     * {@link import("./memory.js").normalizeMemorySpec} consumes) — DESIGN-2 (council): typed by import rather
+     * than re-declared inline so the input contract and its normalizer can never silently diverge. Per-field
+     * semantics: `scope` = single opaque LEGACY scope (`scopes` wins when both present); `scopes` = ordered
+     * opaque layering (STABLE first / VOLATILE last; last = highest priority); `writeScope` = the single layer
+     * all writes land in (default = last scope; explicit `null` = read-only — no `remember` tool, consolidation
+     * off); `enabled` = master switch (default true).
+     */
+    memory?: import("./memory.js").MemorySpecInput;
+    /**
+     * @deprecated design/138 S4 — legacy memory consolidation (design/41) rode the retired memoryStore
+     * path and no longer runs; this field is ignored. (The engine plane's consolidation re-mount is a
+     * separate design — see design/138 §7.) Type kept one major; removal is the next major.
+     */
+    memoryConsolidation?: MemoryConsolidationConfig;
+    /**
+     * design/100 §E12 — after the task COMPLETES, run ONE extra opt-in LLM pass to propose "next prompts" the
+     * user might send (the shell's follow-up suggestions). OFF/omitted = zero extra LLM calls, behavior unchanged.
+     * Fire-and-forget (never blocks the result); the suggestions are surfaced via {@link TaskStream.suggestions}
+     * and the (budget-excluded) cost via {@link TaskStats.suggestions}. `count` default 3, `role` default
+     * `"summarize"` (a cheap tier → falls back to the task model). The output is UNTRUSTED model text for the
+     * shell UI ONLY — never re-feed it to a model.
+     */
+    suggestNextPrompts?: boolean | {
+        count?: number;
+        role?: ModelRole;
+    };
+    /**
+     * design/101 §E19 — opt-in working-tree **rewind**: when this task uses {@link resumeAt} to branch at a prior
+     * message AND a snapshot was captured for that message, RESTORE the files to how they were at that message
+     * (pairs with E18: branch the session + restore the tree). Also makes every COMPLETED turn capture a
+     * snapshot keyed by its leaf `SessionTreeEntry.id`. Requires `RunnerDeps.fileSnapshotStore`. **v1 is
+     * LOCAL-only** — a remote ({@link RunnerDeps.executionEnvFactory}) env defers rewind to its own VM-snapshot
+     * backend behind the same seam. OFF/omitted = zero snapshot/restore work.
+     */
+    rewindFiles?: boolean;
+    /**
+     * design/101 §E19 + R8 (CC Rewind `code`-only mode) — restore the working tree to the snapshot captured at
+     * this prior message entryId WITHOUT forking the conversation (no {@link resumeAt} leaf-branch). This is CC's
+     * "Restore code" mode (vs "Restore code and conversation" = {@link resumeAt}+{@link rewindFiles}, and "Restore
+     * conversation" = {@link resumeAt} alone). Honored ONLY when {@link resumeAt} is ABSENT (with `resumeAt` set,
+     * that branch's own `rewindFiles` governs — they are different operations); a no-snapshot target is an
+     * expected no-op (same as `rewindFiles`). Requires `RunnerDeps.fileSnapshotStore`. The session leaf is
+     * untouched — the next turn continues the CURRENT conversation, only the files moved.
+     */
+    rewindFilesTo?: string;
+    /** Native tools available to this task. */
+    tools?: ToolSpec[];
+    /** Gate tool calls before they run (allow/deny/approval). Overrides `RunnerDeps.toolPolicy`. */
+    toolPolicy?: import("./tool-policy.js").ToolPolicy;
+    /** How `ask` decisions resolve for this task (headless auto-deny by default). Overrides `RunnerDeps.onAsk`. */
+    onAsk?: import("./tool-policy.js").OnAsk;
+    /** Content-ask seam (design/64 §5): routes an AskUserQuestion tool call to a real human/UI. When set, the
+     *  AskUserQuestion tool is mounted. Overrides `RunnerDeps.onQuestion`. Distinct from `onAsk` (permission). */
+    onQuestion?: import("./ask-question.js").OnQuestion;
+    /** LSP code-intelligence seam (design/64 §13.1): when set, the `lsp` tool is mounted and routed to this
+     *  manager. Overrides `RunnerDeps.lspManager`. Unset ⇒ no `lsp` tool (the model uses grep/read_file). */
+    lspManager?: import("./lsp.js").LspServerManager;
+    /**
+     * design/121 (CC 198 parity): after the agent edits a file, NEW language-server diagnostics are
+     * injected into the model (`<new-diagnostics>` context message, 10/file · 30 total · 4000-char cap)
+     * and emitted as a structured `diagnostics` event for the shell. **Default ON** whenever the
+     * preconditions hold — an LSP manager with a diagnostics registry is wired AND the roster has
+     * write-capable fs tools (CC's same gate); zero cost/behavior change otherwise. `false` opts out.
+     */
+    lspDiagnostics?: boolean;
+    /** In-process hooks (PreToolUse/PostToolUse/UserPromptSubmit) for this task. Overrides `RunnerDeps.hooks`. */
+    hooks?: import("./hooks.js").Hooks;
+    /**
+     * design/45 **durable suspend-on-approval** (F4). When set AND a `CheckpointStore` is wired
+     * (`checkpointStore` here or on `RunnerDeps`), a tool-policy `ask` is **persisted as a checkpoint** and
+     * the task ends `status:"suspended"` + `checkpointToken` instead of resolving synchronously through
+     * `onAsk` — resume later with `runner.resume(token, outcome)`. This is the cross-process / long /
+     * headless version of the `onAsk` gate. **opt-in, default-off**: unset → the 1.63 synchronous `onAsk`
+     * path (unchanged). Only safe at the top-level `runTask` (orchestrators fail-fast, §11 Q6).
+     */
+    durableApproval?: {
+        /** Multi-tenant isolation key, forced into the checkpoint + `resolve`/`reap` WHERE. Required. */
+        scope: string;
+        /** Optional awaiting-human TTL (ms). Past it a reaper CAS-expires the checkpoint (≈ deny). */
+        ttlMs?: number;
+    };
+    /**
+     * design/74: opt into resource-slice suspend. When a resource limit (maxTurns / budget / walltime) is hit
+     * AND the task is eligible (a `checkpointStore` + a remote, suspendable `executionEnvFactory` env), suspend
+     * as a resumable `resource_limit` checkpoint instead of failing (clay's "失败≠没做完" third state) — resume
+     * continues the run with the next slice's allowance. `scope` is the multi-tenant isolation key (like
+     * `durableApproval.scope`). Absent ⇒ a limit hit still FAILS (backward compatible). Independent of
+     * `durableApproval` (a run can have one, both, or neither).
+     */
+    resourceSuspend?: {
+        /** Multi-tenant isolation key, forced into the checkpoint + `resolve`/`reap` WHERE. Required. */
+        scope: string;
+        /**
+         * design/74 Slice 4: the task's TOTAL $ budget (USD) across the whole resume→re-suspend chain — the
+         * human's allocation, distinct from `maxCostUsd` (the per-SLICE window). Each slice may spend
+         * `min(maxCostUsd, total − alreadySpent)`; the ledger (carried on the checkpoint) accumulates spend so a
+         * resume can't refresh the budget. `undefined` ⇒ no $ ceiling on the whole task (each slice is bounded
+         * only by its own `maxCostUsd` / walltime). Set ONLY on the FIRST slice; later slices read the frozen
+         * total from the ledger. (Walltime has a sibling `totalWalltimeSec` on the ledger; not yet enforced.)
+         */
+        totalBudgetUsd?: number;
+        /**
+         * design/74 (search [136] HIGH-1): max resource SLICES (resume legs) before the run fails with
+         * `"suspend.loop"`. The resource-slice analogue of `maxSuspends`, but counted on the ledger's
+         * `sliceCount` and INDEPENDENT of the restart-loop `maxSuspends`: a legitimate long resource run must
+         * not be capped by the (low) restart-loop safety, and restart-loop suspends must not consume the slice
+         * allowance (the bug: both shared one `suspendCount` + `maxSuspends`). The cross-slice $ budget
+         * (`totalBudgetUsd`) is the PRIMARY bound; this is a backstop against a $0-progress slice loop. Default
+         * `DEFAULT_MAX_SLICES` (100, the design/74 spec's worker-suspend ceiling). The leader sizes it to budget/slice.
+         */
+        maxSlices?: number;
+        /**
+         * design/74 (search [136] HIGH-2): retention TTL (ms) stamped onto the resource checkpoint's `deadline`
+         * so the durable reaper can GC an orphaned (never-resumed) resource suspend. WITHOUT it the checkpoint
+         * has no `deadline`, both reapers filter on `deadline`, and the `pending` row (+ in-memory pin) leaks
+         * forever. Default `DEFAULT_RESOURCE_TTL_MS` (30 days, the spec `RESOURCE_SUSPEND_TTL_SEC`). A legitimate
+         * resume happens long before this; the deadline only reaps abandonment.
+         */
+        ttlMs?: number;
+    };
+    /**
+     * design/80 Seam #2 (external preempt/yield): the SCHEDULER raises this `AbortSignal` to PREEMPT this task —
+     * a graceful, RESUMABLE durable yield (free resources for a higher-priority task), NOT an abort (abort kills
+     * the run and loses its state). When raised, the task durably suspends at the next CLEAN turn boundary as a
+     * `resource_limit` checkpoint with reason `"preempt"` (the SAME mechanism as a budget/turns/walltime resource
+     * suspend — only the trigger differs), and is resumed later via `runner.resume(token, {gate:"resource_limit",
+     * decision:"continue"}, …)` exactly like any resource-limit resume (continue the work, no decision).
+     *
+     * **Eligibility (v1 reuses the resource-suspend opt-in):** preempt only fires when the task is eligible for
+     * durable suspend — i.e. it opted into {@link resourceSuspend} AND a durable `checkpointStore` is wired AND
+     * tool-results are durable AND the per-task env is a remote (suspendable) `RemoteExecutionEnv`. This is
+     * correct: a non-durable task cannot be preempted-AND-resumed anyway. If `preemptSignal` is raised on a task
+     * that is NOT resource-suspend-eligible, preempt is a SILENT NO-OP (the run continues normally to its natural
+     * end) — decoupling preempt's own opt-in from `resourceSuspend` is a future enhancement, not built here.
+     *
+     * **Re-supply on resume:** like `resourceSuspend`/`durableApproval`, this is part of the resume task config —
+     * a long task that is resumed may need re-preemption, so supply a FRESH `preemptSignal` (a new
+     * `AbortController.signal`) in the resume `taskConfig` to make the resumed leg preempt-able again.
+     */
+    preemptSignal?: AbortSignal;
+    /**
+     * design/131 (service [404] 拍) — per-task resilience overrides, INTENT-ONLY (no decorator
+     * topology on the spec; the deployment's brain stack stays the single owner). For bench/eval or
+     * critical tasks that need the provider's TRUE failure shape instead of a silent fallback:
+     *  - `allowDegrade:false` — reactive model degrade is off for this task (failure passes through).
+     *  - `allowFailover:false` — cross-gateway failover is off (only the primary brain is tried).
+     *  - `bypassBreaker:true` — an open circuit breaker's fast-fail is waived for THIS task; outcomes
+     *    are still recorded (shared observation undiminished). Operator-facing — deployments SHOULD
+     *    NOT expose this to wire users directly (it defeats provider protection).
+     * All absent ⇒ exactly today's behavior. Threaded per-call as `StreamOptions.resilience`; the
+     * first-party degrading/failover/breaker decorators honor it, custom brains may ignore it.
+     */
+    resilience?: ResilienceOptions;
+    /**
+     * design/132 — final-verification gate (OPT-IN: `true` enables). When a task is about to end
+     * NATURALLY (inside budget) and this run made at least one non-`read` tool call, the engine
+     * injects a reminder to re-verify the final deliverable through its REAL entry point
+     * (execute it directly; don't trust earlier self-tests or shell redirections) before finishing.
+     * Oracle-grounding upgrade (docs/DESIGN-ORACLE-GROUNDING-GATE-2026-07-10.md §3.A): if the run's
+     * tool-call record carried a deterministic verifiable-structure signal (raw-byte read /
+     * structural parse / digest-reconciliation word-faces in shell commands — never a semantic scan
+     * of closing text) and the model ends AGAIN without headroom concerns, ONE grounding re-entry
+     * reminder is injected; total injections are hard-capped at 2, then the run always ends. A
+     * submitted structured output and the maxTurns-1 boundary always pass through un-gated.
+     * Evidence: TB full-run autopsy — the biggest shell-gap bucket (7-8 tasks) finished convinced by
+     * their own fake self-check; prompt discipline alone (1.242) had a low landing rate. Opt-in
+     * because the evidence is from AUTONOMOUS legs — turn it on for autonomous/benchmark scenarios
+     * (sema-tb defaults it ON); interactive deployments choose per scenario. Read-only / Q&A runs
+     * never trigger it. Telemetry: `stats.mechanisms.finalVerifyInjected`.
+     */
+    finalVerification?: boolean;
+    /**
+     * design/72 §2.2 (B): max times this task may durably suspend before the run fails with
+     * `"suspend.loop"` instead of minting another checkpoint. Caps a resume/restart loop (a model that
+     * re-issues the gated/egress call every resume, re-suspending forever). Counted across resume chains.
+     * Default 5 (loose — a real human-approval flow re-suspends rarely, so 5 separates a normal resume from a
+     * pathological loop; a deployment that genuinely needs more sets this). Overrides `RunnerDeps.maxSuspends`.
+     */
+    maxSuspends?: number;
+    /** Per-task {@link import("./checkpoint-store.js").CheckpointStore} for durable suspend/resume
+     *  (design/45). Overrides `RunnerDeps.checkpointStore`. Needed (with `durableApproval`) to suspend. */
+    checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
+    /**
+     * Restrict the injected "hand" band (design/44) to its effect:read tools for this task — read_file /
+     * grep / glob (+ `bash_readonly` when a shell is available); edit_file / write_file / `bash` are not
+     * mounted. This is the verifier read-only boundary (§6): an adversarial verifier inspects but must not
+     * modify the project. No effect unless an `executionEnv` is injected. Default false.
+     */
+    handsReadOnly?: boolean;
+    /**
+     * design/119 (CC --add-dir parity): extra directories the FILE tools may access in addition to the
+     * containment root — each is canonicalized into the containment allowlist and listed in the
+     * `# Environment` block so the model knows they're available. Same defense-in-depth caveat as the
+     * root: this bounds the file tools, not `bash` (OS-level containment is the env's job).
+     */
+    additionalDirectories?: string[];
+    /**
+     * design/80 D-B — opt in to PLAN MODE: mount the first-party `present_plan` tool (CC `ExitPlanMode` parity).
+     * The model calls it to present a plan; the engine then pauses with a durable `plan_review` checkpoint
+     * (`status:"needs_review"`) so a human approves/edits/rejects before any action. Typically paired with
+     * `handsReadOnly:true` (research read-only until the plan is approved, then the resume drops it). Default
+     * false — when unset the tool is NOT mounted, NOT disclosed, and a `ToolReturn.requestReview` is ignored, so
+     * a non-plan-mode task is byte-identical. Needs a `checkpointStore` wired to actually pause (else a
+     * `requestReview` is a no-op). The tool is a thin composition over the general `requestReview` primitive.
+     */
+    enablePlanMode?: boolean;
+    /**
+     * design/110 / design/136 §2.1.a (⚠️ BREAKING semantics change) — the per-task FORK governance gate for
+     * `Agent(subagent_type:"fork")` (the standalone `Fork` tool was retired; the capability lives in the Agent
+     * tool's `subagent_type` value domain — CC-exact shape). The fork spawns a child that INHERITS this
+     * conversation's full context (vs the clean-context delegation) and shares the prompt-cache prefix.
+     *
+     * OPT-OUT default (flipped from the pre-136 opt-IN): `undefined`/`true` = fork is AVAILABLE, bounded by the
+     * session capability (`hasSessionFork` durable store + a session id + not inside a fork — honest refusal
+     * otherwise); an EXPLICIT `false` = fork is DENIED for this task with the honest `fork.disabled` result
+     * (never a silent downgrade). Multi-tenant deployments that previously relied on `undefined` being OFF must
+     * now send `enableFork: false` explicitly (or deny per-principal via `RuntimeCaps.allowFork`).
+     */
+    enableFork?: boolean;
+    /**
+     * design/80 D-2 (part-1): gate the injected `bash` hand tool, since a full shell can run egress (`curl`,
+     * `git push`) and irreversible (`rm`) commands that the per-tool egress/irreversibility marks otherwise miss.
+     * The §4-OQ4 doctrine: shell-in-presence ⇒ always-gate UNLESS a real parsed classifier is wired.
+     *  - `"off"` (default): `bash` is unmarked — the current behavior (subject only to the deployment's policy).
+     *  - `"always"`: every `bash` command tightens to an `irreversible_ask` durable suspend (fail-closed; the
+     *    correct default for an unattended/supervisor deployment with no classifier).
+     *  - `"classify"`: mark `bash` `irreversibility:"maybe"` with {@link import("../tools/fs/index.js").bashReversibilityProbe}
+     *    — a provably-benign single allowlisted read-only command (no operators) auto-allows; everything else
+     *    (writes, egress, pipes, unknown commands) tightens to ask. An egress command (e.g. `curl`) suspends under
+     *    the IRREVERSIBLE axis (the shell mark is irreversibility, not egress) — the kind is non-budgetable either
+     *    way, so the budget resolver still never auto-approves it; the axis label is informational.
+     * No effect under `handsReadOnly` (that mounts `bash_readonly`, already allowlisted) or with no execution env.
+     * **Re-supply on resume:** like `toolPolicy`/`tools`/`durableApproval`, `shellGate` is part of the resume
+     * task config — a resume that omits it leaves the resumed run's SUBSEQUENT `bash` calls ungated (the approved
+     * pending call itself runs once, having been adjudicated). Re-pass the same value the original task used.
+     */
+    shellGate?: "off" | "always" | "classify";
+    /** Task-scoped MCP servers, materialized into tools then disposed. */
+    mcp?: McpServerSpec[];
+    /**
+     * Task-scoped skills (object form). Two first-party halves (design/71 黑盒#5 fix): a stable
+     * `<skills>` system-prompt block disclosing name+description (deterministic order, capped), and an
+     * injected `skill` tool (effect:read) that returns the skill's full content as a tool result
+     * (per-skill body cap with an honest truncation marker). Duplicate names: first wins. The name
+     * `skill` becomes reserved when this field is non-empty (`config.reserved_tool_name`).
+     *
+     * Skill content is CALLER-trusted — same trust level as `systemPrompt`. Callers forwarding
+     * end-user-authored skills are responsible for vetting them: a skill IS instructions by design.
+     */
+    skills?: SkillSpec[];
+    /**
+     * design/129 — lifetime scope for BACKGROUND children (Agent/Fork `run_in_background`). Default `"task"`:
+     * the parent runTask's terminal reaps them (design/115 — no orphans burning tokens; [431] turn-end killed
+     * frame). `"session"`: children OUTLIVE the turn (CC Backgrounded semantics) — registered under the
+     * SESSION owner (cross-turn TaskOutput poll works), skipped by the parent-teardown reap, force-capped by
+     * a default child timeout when none is given, and finally reapable via
+     * `TaskRegistry.reapSessionBackground(sessionId, scope)` (call it from your session release/sweep).
+     * CALLER-trusted (systemPrompt tier): never a model-facing parameter, never on the governed workflow
+     * whitelist — a child's lifetime crossing the turn boundary is an isolation-contract surface.
+     */
+    backgroundScope?: "task" | "session";
+    /**
+     * 黑板 [435]/[442] A1 — structured SANDBOX facts for the `# Environment` block, so the agent knows what
+     * toolchains the environment already carries (no blind reinstall), which package source installs go
+     * through, and whether the network is reachable at all (egress=none ⇒ don't burn budget on downloads).
+     * DEPLOYMENT-trusted (systemPrompt tier — the deployment knows its own sandbox binding): rendered
+     * sanitized+bounded by prepare-task; never a model-facing parameter, never on the governed workflow
+     * whitelist. All fields optional; absent ⇒ block unchanged.
+     */
+    envFacts?: {
+        /** The bound sandbox image profile (e.g. `dev-mobile`). */
+        profile?: string;
+        /** Toolchains/capabilities the image carries (e.g. `android-sdk`, `gradle`). Rendered bounded. */
+        capabilities?: readonly string[];
+        /** Which package-source lane installs go through (e.g. `cn` | `global` | `custom`). */
+        pkgSource?: string;
+        /** Outbound-network posture. `none` renders an explicit "downloads will fail" caveat. */
+        egress?: "none" | "allowlist" | "full";
+        /** Session-specific scratch directory for temporary files (CC Scratchpad parity, 1.257.3): when set,
+         *  the environment block instructs the model to use this dir instead of `/tmp` — prevents parallel
+         *  tasks trampling each other's temp files and project-dir pollution. Unset ⇒ no section rendered. */
+        scratchpadDir?: string;
+    };
+    limits?: {
+        maxTurns?: number;
+        timeoutSec?: number;
+        /**
+         * design/119 #2: per-REQUEST output-token cap (the provider `max_tokens` / `max_completion_tokens`
+         * field). Distinct from `maxTokens` (the cumulative BUDGET cap): this bounds each model reply.
+         * Unset ⇒ prior behavior (Anthropic: model.maxTokens; OpenAI family: provider default). A reply
+         * that hits it stops with `length` and the loop's truncated-output auto-continue takes over.
+         * HARD bound on Anthropic budget-thinking models too: a cap too small to host a legal thinking
+         * budget (< 2048) skips thinking for the request rather than silently raising the cap.
+         */
+        maxOutputTokens?: number;
+        /**
+         * design/128 T1-2 — deadline awareness for `timeoutSec` (default ON). At each turn boundary the run
+         * loop checks elapsed wall-clock against the budget and injects at most TWO one-shot
+         * `<system-reminder>` nudges (at ~80%: "start converging"; at ~95% or budget−2min, whichever is
+         * earlier: "deliver NOW") so the model converges BEFORE the hard abort instead of losing unfinished
+         * work to it. `false` disables; `{at:[a,b]}` overrides the two ratios (0<a<b<1). No effect without
+         * `timeoutSec`. Resource-suspend-eligible tasks never nudge (their timeoutSec is a SLICE boundary —
+         * the clean suspend already is the convergence). Cost: at most two tail transcript reminders; the
+         * stable system prefix (and thus the prompt cache) is untouched. Known limit: the check runs only at
+         * turn boundaries — a single very long turn can sail past a threshold and see the nudge one boundary
+         * late.
+         */
+        deadlineNudge?: false | {
+            at?: [number, number];
+        };
+        /**
+         * design/130 P1 — wall-clock-aware per-CALL output cap (default ON when `timeoutSec` is set).
+         * Before each model call the runner shrinks the request's `max_tokens` to what the remaining
+         * wall-clock can actually absorb (`remainingSec × measured-throughput × 0.5 safety`, EWMA from
+         * this run's completed calls; a conservative prior before the first sample), clamped to
+         * [1024, `maxOutputTokens` ?? model default]. SHRINK-ONLY: never raises the static ceiling.
+         * Thinking contract (codex ①): a cap that lands in [1024, 2047] is raised to 2048 iff the
+         * remaining budget can absorb it WITHOUT the safety margin; otherwise the cap stands and an
+         * Anthropic budget-thinking call skips thinking for that request (design/119 semantics) — the
+         * `brain.call` trace carries `callCap`/`capThinkingSkipped` either way. `false` disables.
+         * Resource-suspend-eligible tasks never shrink (their timeoutSec is a SLICE boundary; a
+         * per-slice opt-in is deferred). No effect without `timeoutSec`.
+         */
+        callCapByDeadline?: false;
+        /**
+         * design/130 P2 — graceful-finalize turn (default ON when `timeoutSec` is set). At a turn
+         * boundary where the remaining wall-clock no longer fits one more full model-call + tool cycle
+         * (EWMA of this run's call latencies + tool durations, ×1.25 headroom), the runner injects a
+         * ONE-SHOT finalize instruction — "write your best current answer to the deliverable path NOW,
+         * open no new work" — and suppresses any still-pending deadline nudges (one deadline-class
+         * message per boundary, finalize wins — codex ②). The turn after finalize still runs under the
+         * P1 cap with its floor raised to 2048 so the write-out isn't starved. `false` disables.
+         * Resource-suspend-eligible tasks never finalize (clean slice suspend outranks it — codex ⑤).
+         * v1 is instruction-only: the finalize turn's tool face is NOT narrowed (deferred; needs a
+         * mid-run setTools surgery whose cache cost outweighs v1 value).
+         *
+         * design/130 P2b — deadline EXECUTION hardening (rides this same switch; the family is one
+         * discipline). With finalize on, the runner additionally reserves a fixed write-out CUSHION
+         * (15% of the budget, clamped to [10s, 75s]) and enforces a soft execution deadline
+         * (`deadline − cushion`; the finalize turn itself gets `deadline − 5s`):
+         *  - the finalize boundary condition becomes `remaining < est + cushion` (the last work cycle
+         *    can no longer eat the write-out window), with a TAIL-AWARE est (decayed peak ∨ EWMA);
+         *  - first-party brains CUT a model call whose stream crosses the soft deadline (prefix
+         *    salvaged, one bounded write-out turn follows; exhausted ⇒ `timeout` + salvagedOutput);
+         *  - foreground shell timeouts are CLAMPED to the soft deadline (a long command times out
+         *    cleanly instead of riding into the hard abort).
+         * `stats.mechanisms.callCutoffs`/`toolClamps` count the engagements. `false` disables all of it.
+         */
+        gracefulFinalize?: false;
+    };
+    /**
+     * Blackboard 2026-07-03 (subagent viewing pane, clay dogfood): widen the opt-in display sink
+     * (`RunInternals.onForwardEvent`) from `task_progress`-only to a SUBAGENT's live CONTENT events
+     * (`text_delta` / `reasoning_delta` / `tool_start` / `tool_end`), so a UI can render a delegated
+     * child's transcript live. Default OFF (progress-only, prior behavior). The child stream is still
+     * NEVER merged into the parent's model context — this is purely a render channel; forwarded events
+     * carry `parentToolCallId` (attribution) and the same UNTRUSTED-RAW contract as the main stream's
+     * `tool_start.args`/`tool_end.output` (consumer MUST redact — design/99 §E1). Single-level: each
+     * delegation level opts in for ITS direct children.
+     */
+    forwardSubagentEvents?: boolean;
+    /**
+     * design/122 D1 — RETAIN sync sub-agent sessions after they settle so an operator can RESUME (revive) a
+     * finished child with a new prompt via {@link import("../agents/subagent.js").SubagentSteerHandle}'s
+     * `resume` verb (CC `dfe` resumeAgentBackground parity). Default OFF = prior behavior byte-for-byte:
+     * child sessions are throwaway (released eagerly after the delegation returns).
+     *
+     * ON (`true` or a config object): each SYNC delegation spawned while the deployment's
+     * `RunInternals.onSubagentSpawn` sink is wired (the handle-emitting path — without a handle there is no
+     * resume capability, so retaining would be a pure leak) pre-mints the child's sessionId, PINS it against
+     * the store's idle sweep, and SKIPS the eager release. The session is retained in a parent-run-scoped
+     * ledger until `ttlMs` after settle (default 30 min), eviction past `max` retained children (default 16),
+     * or the PARENT run reaching a terminal state — whichever comes first; then it is unpinned + explicitly
+     * released (throwaway semantics restored — a retained session never dangles to the store's 7-day TTL).
+     * `run_in_background` children are OUT OF SCOPE (no handle, no retain — r1-M3; the bg lane's resume needs
+     * durable support and is a separate item). Resume is reachable only while the parent run lives (the
+     * ledger is run-scoped, not a durable registry — codex-B3).
+     */
+    retainSubagentSessions?: boolean | {
+        ttlMs?: number;
+        max?: number;
+    };
+    /**
+     * design/120 P2: opt in to in-stream tool execution — safe tool calls start while the model is
+     * still streaming its response instead of waiting for the full reply. Default OFF. Forwarded to
+     * the harness, which additionally withholds it whenever a `tool_call` gate handler is registered
+     * (policy / approval / egress runs — a gate could durably suspend, which is impossible
+     * mid-stream), so setting this on a gated task is safe and simply has no effect. A run whose only
+     * gate concern is resource-suspend does NOT register that handler (it stops at clean turn
+     * boundaries), so in-stream execution stays available there.
+     *
+     * Known limitation (documented): with this ON, a tool's side effect can complete BEFORE the
+     * assistant message persists; a hard process crash in that window leaves no transcript trace of
+     * the call (wake reconcile cannot see an orphan that was never written). Prefer OFF for
+     * deployments where crash-exactly-once accounting of tool effects matters more than latency.
+     */
+    streamingToolExecution?: boolean;
+    /**
+     * Hard cost ceiling in USD for this task (requires `model.cost` or `RunnerDeps.pricing`). Checked
+     * pre-call and at each turn boundary; exceeding ends the task `failed` with `errorCode="budget.precall"`
+     * (estimate rejected, nothing spent) or `"budget.exceeded"` (after spend). When set, `budgetStreamCancel`
+     * defaults to `true`.
+     *
+     * NOTE: the pre-call check is **best-effort** — it estimates the first call's input from the objective
+     * length only (it cannot see the assembled system prompt / history / memory), so it may under-estimate
+     * and let an oversized first turn run; the turn-boundary gate then catches it as `budget.exceeded`.
+     * Treat `budget.precall` as a fast-fail optimization, not a hard guarantee that no single call exceeds.
+     */
+    maxCostUsd?: number;
+    /** Hard cap on cumulative prompt+completion tokens; exceeding ends `failed` + `"budget.exceeded"`. */
+    maxTokens?: number;
+    /** Cancel an in-flight stream the moment cumulative cost crosses `maxCostUsd`. Defaults to `true`
+     *  when `maxCostUsd` is set (hard control), `false` otherwise. */
+    budgetStreamCancel?: boolean;
+    /**
+     * **Near-budget degradation** (1.39 v2, design/21 §5C). When cumulative cost reaches `atCostFraction`
+     * of `maxCostUsd`, **switch the active model to the cheaper `to`** for the rest of the task to stretch
+     * the remaining budget — accepting lower quality instead of stopping at `maxCostUsd`. One-way (never
+     * switches back); sets `TaskResult.degraded = { …, reason: "budget" }`. Requires `maxCostUsd` (the
+     * fraction is of it); ignored otherwise. This is the proactive, Runner-level complement to the
+     * reactive brain-level `createDegradingBrain` (rate_limit / breaker-open).
+     */
+    degrade?: {
+        to: ModelRef;
+        atCostFraction: number;
+    };
+    /**
+     * **Structured output** (1.41): constrain the task's FINAL result to this JSON schema (a typebox
+     * object schema). Injects a built-in `submit_output` tool whose parameters ARE this schema; the model
+     * calls it to finish, the validated object is surfaced as `TaskResult.structuredOutput`, and the task
+     * ends. Provider-agnostic (it's just a tool). If the model can't produce a valid object within a few
+     * tries the task fails with `errorCode="output.invalid"`. A caller tool named `submit_output` is
+     * rejected (reserved). The model may still answer in prose (then `structuredOutput` is undefined) or
+     * `report_blocked`. Cast the result with `Static<typeof yourSchema>`.
+     */
+    outputSchema?: TSchema;
+    /**
+     * How many times the model may **retry** a rejected `submit_output` before the task fails with
+     * `errorCode="output.invalid"` (only meaningful when {@link outputSchema} is set). `0` = fail on the
+     * first invalid submit (no in-loop retry); the caller decides whether to re-run. Default `2`
+     * (3 total attempts). Clamped to a non-negative integer. This bounds only the *in-task* retry of a
+     * malformed object — it is not an auto-fixer; pair it with a caller-side retry on `output.invalid`.
+     */
+    outputRetries?: number;
+    /** Best-effort fire-and-forget trace sink (task/turn/brain/tool). Overrides `RunnerDeps.tracer`. */
+    tracer?: import("./trace.js").TracerHook;
+    /** Per-task override of the large-tool-result offload threshold (chars); see `RunnerDeps.toolResultThresholdChars`. */
+    toolResultThresholdChars?: number;
+    /**
+     * Override auto-compaction thresholds for this task's session. Compaction (LLM summary, persisted
+     * to the session) runs in two places sharing these settings: at every within-task turn boundary
+     * (design/64 §25 (A) — the long-single-task case) and once at task end (the between-task case).
+     * Defaults: enabled, reserveTokens 16384, keepRecentTokens 20000 — repaired automatically when
+     * pathological for the model's window: threshold ≤ 0, keepRecent ≥ threshold, or a threshold above
+     * the clearStale point (0.7×window — the prefix-cache "death band", design/64 §26.4) is clamped
+     * down to it. The clamp applies to explicit values too (the clearStale point is not configurable,
+     * so a threshold above it cannot express consistent intent); explicit values below all three
+     * bounds are never overridden (see `sanitizeCompactionSettings`).
+     * `instructions` is appended to the summarization prompt — use it to guarantee critical
+     * facts survive (e.g. "preserve verbatim any codes, IDs, names, and explicit user instructions").
+     * Scope caveat (design/141 examples 批实测): `instructions` rides the WHOLE-TURN summarization
+     * request only; a split-turn cut point (mid-turn prefix summarization) uses the engine-owned
+     * turn-prefix prompt and does not carry it (same A2 boundary as `RunnerDeps.summaryProvider`).
+     * `withinTask: false` keeps end-of-task compaction but disables the within-task (turn-boundary)
+     * trigger — the escape hatch for the §25 (A) control-flow change; the system prompt then stops
+     * claiming mid-task summarization (§6.3 honesty).
+     * `attachWorkingFiles` (LONGRUN-2; **default ON since 2026-07-03** — CC 198 hard-codes its
+     * post-compact file restore, and LONGRUN-2 measured ≈2.3 extra read round-trips per compaction
+     * without it): after each compaction, re-read the task's most recently READ files (CC
+     * readFileState semantics; falls back to modified-by-recency when read tracking is absent) and
+     * append their current contents to the summary (bounded: `maxFiles` default 3,
+     * `maxCharsPerFile` default 16k chars ≈ 4k tokens, plus a total cap that self-scales to ~15% of
+     * the model window). The `compacted` wire event carries the attached list as `attachedFiles`
+     * (shell renders CC's post-compact Read cards). `false` opts out; an object customizes caps;
+     * no-op when the task has no execution env (no hands, nothing to re-read).
+     */
+    compaction?: {
+        enabled?: boolean;
+        withinTask?: boolean;
+        reserveTokens?: number;
+        keepRecentTokens?: number;
+        instructions?: string;
+        attachWorkingFiles?: boolean | {
+            maxFiles?: number;
+            maxCharsPerFile?: number;
+        };
+    };
+    /**
+     * design/133 §R3 — turn-boundary attachment producers (CC `getContextAttachments` parity), ALL
+     * OPT-IN. Same default-face judgment as design/132 `finalVerification` (B2/H2): the evidence for
+     * these reminders comes from AUTONOMOUS long-task legs (weak-model drift safety net — CC's own
+     * trigger counts proved unreproducible: the observed CC runs never mounted TodoWrite), so the
+     * autonomy entrypoints (sema-tb) turn them on and interactive deployments stay byte-identical
+     * until a behavior leg proves them neutral. At most ONE coalesced `<system-reminder>` steer per
+     * clean turn boundary, lowest lane: finalize/deadline-nudge/diagnostics at the same boundary — and
+     * the design/130 P2 / design/132 end-game latches — all suppress it.
+     *
+     *  - `todoReminder`: CC 10/10 cadence — when TodoWrite (or the task tools; both mounted ⇒ the
+     *    task family wins, CC isTodoV2) hasn't been used for 10 assistant turns, re-surface the list
+     *    (thin projection; an all-completed list is cleared, never regurgitated). No tools mounted ⇒
+     *    permanently silent.
+     *  - `changedFiles`: boundary-time stat of ≤20 (or `maxFiles`) most-recently-READ files; a file
+     *    whose mtime moved past the recorded read time (+2s epsilon) is listed (path-only v1, "do not
+     *    blindly revert — re-read"). OFF ⇒ zero stat calls. Self-edits are immune (write-back
+     *    refreshes the read stamp); mtime skew on exotic fs remains a documented false-positive source.
+     *  - `planModeReminder`: while `enter_plan_mode` is active, re-surface the read-only constraint
+     *    every 5 assistant turns (full copy every 5th, sparse between) so a long plan phase doesn't
+     *    drift into write-deny thrash. Exiting plan mode stops it.
+     *  - `backgroundTasks` (G1 通告层, 黑板 [482] — CC /compact parity): after a compaction LANDS, the
+     *    next boundary announces this run's still pending/running background tasks (task registry
+     *    snapshot: id/description/status, CC three-state copy). ONE-SHOT per compaction — never
+     *    per-boundary nagging; no compaction ⇒ permanently silent.
+     *  - `toolsDelta` (G1 — CC deferred-tools boundary notice): when design/36 `tool_search`
+     *    materializes deferred tools mid-task (setTools + fingerprint refresh), the next boundary
+     *    announces the NEWLY available names once. Already-active and resume-reseeded tools are never
+     *    (re)announced; no deferred tools ⇒ permanently silent.
+     *  - `agentListing` (G1 续批 — CC `agent_listing_delta` parity): when a delegation tool built by
+     *    `createSubagentTool` is mounted, the FIRST collected boundary announces the full agent-type
+     *    roster ("Available agent types for the Agent tool:", CC-verbatim; + the concurrency note when
+     *    more than one type). Later boundaries announce only roster drift (adds/removals — static in
+     *    practice; the delta lane serves dynamic-registration deployments). A durable resume leg is
+     *    seeded as already-announced (the prior leg's listing is in the transcript — never replayed).
+     *  - `mcpInstructions` (G1 续批 — CC `mcp_instructions_delta` parity): the INITIAL server
+     *    instructions stay in the stable system prompt (`# MCP Server Instructions`, design/64 §17.3 —
+     *    deliberate CC deviation: CC injects them as reminders, sema's stable-prompt carrier is
+     *    prefix-cache-correct). This member announces only DELTAS: a mid-task disconnect of an
+     *    instruction-bearing server ("The following MCP servers have disconnected…", CC-verbatim), and
+     *    the add lane for a future dynamic-connect face. Added instruction text is UNTRUSTED server
+     *    text → fenced with `delimitUntrusted` (deliberate CC deviation: CC injects it raw).
+     *
+     * Telemetry: `steering_injected` (source `todo_reminder`/`task_reminder`/`changed_files`/
+     * `plan_mode`/`background_tasks`/`tools_delta`/`agent_listing`/`mcp_instructions`) +
+     * `stats.mechanisms.attachmentsInjected`.
+     */
+    attachments?: {
+        todoReminder?: true;
+        /**
+         * task #51 口径③ — CC `r2o()` kill-switch parity (CC 198 pretty.js:479167-479171; both reminder
+         * producers consume it as `if (r2o() === "off") return []`, :480232/:480268). `"off"` silences the
+         * todo/task reminder lane even when `todoReminder` is wired on (the other attachment producers are
+         * untouched — CC's nudge gate is lane-scoped); any other value (or absence) = CC `"baseline"`.
+         * CC resolves this from env `CLAUDE_CODE_TODO_REMINDER_MODE` / the `tengu_soft_slate_nudge` gate;
+         * sema keeps env resolution at the deployment shell (sema-tb: `TB_TODOREMIND=off`) — core reads no env.
+         */
+        todoReminderMode?: "baseline" | "off";
+        changedFiles?: true | {
+            maxFiles?: number;
+        };
+        planModeReminder?: true;
+        /**
+         * SR-3 (CC 198 `budget_usd` lane, producer QFm pretty.js:480424-480428 + renderer :600225): the
+         * progressive $-budget readout `USD budget: $used/$total; $remaining remaining` (CC-verbatim
+         * template). CC-exact activation: live ONLY while the task carries an effective cost ceiling
+         * (`maxCostUsd`, or a resource-slice ledger remaining — CC `options.maxBudgetUsd`); no ceiling ⇒
+         * permanently silent even when opted in. CC-exact cadence: NO threshold ladder and NO throttle —
+         * CC mounts it on every main-agent attachment cycle (:479243-479245, gated `d = !t.agentId`), so
+         * sema emits one line at every collected clean turn boundary; the "progression" is the numbers
+         * advancing with spend. Recorded deviation (continuation gate): CC attaches at request assembly
+         * and can never EXTEND a run, while a sema boundary steer revives an idle harness — so this lane
+         * only rides boundaries whose turn resolved ≥1 tool call (a next request is already guaranteed);
+         * a text-only final turn is never dragged past its natural end. Numbers ride the enforcement
+         * coordinate (`stats.costMicroUsd` vs the effective ceiling, ÷1e6 → USD) so the readout never
+         * disagrees with `budget.exceeded`.
+         * NOTE: this deliberately relaxes the design/74 "no budget language reaches the model" default —
+         * that judgment shaped the DEFAULT-OFF posture; an opted-in deployment chooses CC parity.
+         */
+        budgetUsd?: true;
+        backgroundTasks?: true;
+        toolsDelta?: true;
+        agentListing?: true;
+        mcpInstructions?: true;
+    };
+    /**
+     * Inject a built-in `report_blocked` tool the agent can call when it cannot finish
+     * (missing info, permission, ambiguity). When called, the task ends with status "blocked".
+     * Default: true.
+     */
+    enableBlockedReport?: boolean;
+    /**
+     * **LLM self-orchestration** (design/98, S8). Allow THIS task's model to AUTHOR + RUN its own workflow
+     * (a deterministic JS orchestration script) via the `run_workflow` tool. Default `false`.
+     *
+     * 🔴 REQUIRES a deployment-provided HARD sandbox AND a governance baseline:
+     * `RunnerDeps.workflowScriptRunner.safeForUntrustedScripts === true` (an isolated-vm / separate-process
+     * runner — the Node `vm` dev runner is NOT a security boundary) AND `RunnerDeps.workflowGovernanceBaseline`
+     * (the deployment-trusted governance every spawned sub-agent inherits, tighten-only). With EITHER missing
+     * the tool is NOT mounted and the orchestration prompt is NOT injected (FAIL-CLOSED) — core never runs an
+     * LLM-authored script in the dev `vm`, and never lets a script-spawned agent run with no governed baseline.
+     *
+     * Recommended ONLY for strong models; weak models default-off (force-enableable, but the hard-sandbox +
+     * baseline bar still applies — the gate is the deployment's sandbox/governance, NOT the model id). NOT
+     * enforced by model id.
+     */
+    selfOrchestration?: boolean;
+    /** Per-model auth. Returns the api key (and optional headers) for a given provider/model. */
+    getApiKeyAndHeaders?: (model: Model) => Promise<{
+        apiKey: string;
+        headers?: Record<string, string>;
+    } | undefined>;
+    /**
+     * External cancellation. When it aborts, the task aborts (the brain request is cancelled and any
+     * pending tool-policy gate releases). Pass a parent tool's `ToolExecuteContext.signal` here so a
+     * nested `runTask` stops the instant the parent does instead of running to its own `timeoutSec`.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * `"suspended"` (design/45) is a **non-terminal** outcome: the task hit a durable tool-policy gate
+ * (`ask` with a `CheckpointStore` wired) and persisted a checkpoint instead of finishing — resume it
+ * with `runner.resume(checkpointToken, outcome)`. v1 contract: it is only safe at the **top-level
+ * `runTask` boundary**; the orchestrators (cascade/teacher/verify/team) map an unexpected `suspended`
+ * to `failed` + `errorCode:"unexpected.suspended"` and pass the token up (§11 Q6, hard boundary).
+ *
+ * `"needs_review"` (design/76 §2.5, dry-run / shadow; design/80 D-B, plan-gate) is also a **non-terminal,
+ * resumable** outcome, but a DISTINCT one: it is the REVIEW-PAUSE terminal a human/judge must clear. Two
+ * disjoint gate kinds share it (carrying a `reviewRef`, errorCode `"review.pending"`): a `{kind:"needs_review"}`
+ * checkpoint — a profile's dry-run interception produced a predicted state-diff to REVIEW before it is applied,
+ * resumed with a `dry_run_review` outcome — and a `{kind:"plan_review"}` checkpoint (design/80 D-B) — a
+ * profile's plan-gate produced a proposed PLAN a human must approve/edit/reject BEFORE any step runs, resumed
+ * with a `plan_review` outcome. Both are DISJOINT from `"suspended"`: that is a PRE-ACTION approval of a TOOL
+ * CALL (resumed with `policy_ask`); these are human REVIEWS (the distinct gate.kind picks the resume outcome).
+ * Orchestrators that map an unexpected `suspended` should map an unexpected `needs_review` the same
+ * hard-boundary way (it is, like `suspended`, only safe at the top-level `runTask` boundary).
+ */
+export type TaskStatus = "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review";
+/** Result returned when a task finishes or gets stuck. Designed to be machine-readable for an external AI. */
+export interface TaskResult {
+    taskId: string;
+    /** Use this to continue the same conversation on the next call. */
+    sessionId: string;
+    status: TaskStatus;
+    /** design/99 MF-25: the EFFECTIVE model id that served this task — the RESOLVED `Model.id`, not the requested
+     *  `TaskSpec.model` ref (which may be a role / name / `@mention`). Lets a UI echo "served by X" instead of the
+     *  requested ref. A mid-run degradation is observed separately (see the degraded-model fields). */
+    model?: string;
+    /** Final assistant text. */
+    result: string;
+    /**
+     * Best-effort salvaged assistant text from a terminal FAILURE (design/39). Lets a caller recover work
+     * a task produced before it failed at the very end, instead of discarding a `failed` result wholesale:
+     * `const out = r.status === "completed" ? r.result : r.salvagedOutput;`. Its interpretation depends on
+     * `errorCode` — for `"output.degenerate"` it is the model's text up to (and currently including) the
+     * looped tail. **v1 fills it only on degenerate repetition**; a follow-up generalizes it to
+     * timeout/max_turns and trims the degenerate tail. Undefined when there was nothing to salvage.
+     */
+    salvagedOutput?: string;
+    /** Set when status is "blocked": why the agent could not finish. */
+    blockedReason?: string;
+    /**
+     * Set when `status === "suspended"` (design/45) OR `status === "needs_review"` (design/76 §2.5 dry-run /
+     * design/80 D-B plan-gate): the durable-checkpoint token to resume this task with via
+     * `runner.resume(checkpointToken, outcome)` (a `policy_ask` outcome for `suspended`; for `needs_review`, a
+     * `dry_run_review` outcome on a `needs_review` gate or a `plan_review` outcome on a `plan_review` gate —
+     * read `checkpointGate.kind` to pick). Also passed up by an
+     * orchestrator that mapped an unexpected `suspended` to `failed` (errorCode `"unexpected.suspended"`) so the
+     * top-level caller can still resume. Branded `CheckpointToken`; **never log it or put it in a URL** (it is
+     * the resume capability, §6). Undefined for every other status.
+     */
+    checkpointToken?: import("./checkpoint-store.js").CheckpointToken;
+    /** Set with `checkpointToken`: who/what must resume (e.g. `{kind:"human", reason, toolName}`), so the
+     *  caller knows what decision the suspension is awaiting. */
+    checkpointGate?: import("./checkpoint-store.js").CheckpointGate;
+    /** Set when status is "failed"/"timeout". Human-readable. */
+    errorMessage?: string;
+    /**
+     * Machine-readable failure code when the failure carried one — e.g. a `SessionError.code` such as
+     * `"conflict"` (a cross-instance write lost the optimistic lock), or a Node error code. Lets a
+     * caller branch programmatically (e.g. evict a stale cache + retry on `"conflict"`) instead of
+     * matching `errorMessage` strings. Undefined when no code is available.
+     *
+     * 1.37+ terminal codes use a **dotted namespace** so a caller can prefix-match a whole class:
+     * `"budget.precall"` / `"budget.exceeded"` / `"limit.max_turns"` / `"limit.timeout"`
+     * (e.g. `errorCode.startsWith("budget.")`). 1.36 brain codes (`auth`/`network`/`rate_limit`/…)
+     * and `"conflict"` remain flat (unchanged, to avoid breaking existing consumers).
+     */
+    errorCode?: string;
+    /**
+     * Present when the task was served — at least once — by a **degraded** (cheaper/different) model
+     * because the primary was rate-limited, its circuit breaker was open, or — design/126 chain form —
+     * it failed with a `server_error`/`last_resort` class error (1.39 + design/126, opt-in via
+     * `createDegradingBrain`). Lets a caller know the result was produced at reduced quality and alert/
+     * track it. Records the **first** degradation only (degradation is one-way within a task). Set even
+     * when the fallback also failed — so `status:"failed"` + `degraded` means "primary down, fallback
+     * down too". `reason="budget"` is reserved for the v2 near-budget trigger.
+     */
+    degraded?: {
+        from: string;
+        to: string;
+        /** design/126 widens the union: `server_error` (5xx/529 escaped the retry budget) and `last_resort`
+         *  (404/other non-retryable statuses) — the CC 批 β fallback-chain triggers. Additive on this
+         *  OUTPUT field; consumers switching exhaustively should add the two arms. */
+        reason: "breaker_open" | "rate_limit" | "budget" | "server_error" | "last_resort";
+        /** design/126 — the fallback-chain model ids attempted after the primary, in order (absent on the
+         *  single-hop legacy path's pre-126 markers and on the budget path). */
+        chain?: string[];
+        /** 1-based turn during which degradation was triggered. Reactive (rate_limit/breaker): the turn the
+         *  cheaper model first served. Budget: the turn whose cumulative cost crossed the threshold (the
+         *  switch takes effect from the next turn). */
+        atTurn: number;
+    };
+    /** The validated object the model submitted via `submit_output` when `TaskSpec.outputSchema` was set
+     *  (1.41). Undefined if the model answered in prose instead, or the task didn't finish via the output
+     *  tool. Cast it with `Static<typeof yourSchema>`. (Exhausting the output-retry cap → `failed` +
+     *  `errorCode="output.invalid"`, and this stays undefined.) */
+    structuredOutput?: unknown;
+    /**
+     * `turns`/`tokens`/`costUsd` are this task's OWN model usage. `nested` is the summed usage of any
+     * delegated sub-runs (sub-agents) it spawned — present only when it delegated. The true total
+     * cost is `tokens + (nested?.tokens ?? 0)`; a large `nested` is the multi-agent "~15×" made visible.
+     */
+    stats: {
+        turns: number;
+        tokens: number;
+        /** design/97 CORE-8 (②): total TOOL CALLS executed (one per `tool_start`) — distinct from `turns` (model
+         * rounds; a turn may issue several parallel tool calls). For a CC-style "N tool calls" per-agent row.
+         * **v1 fidelity (audit MINOR)**: counted in THIS run leg via the harness dispatch path, so on a DURABLE
+         * RESUME it under-reports — the resumed gated call (executed by the resume engine, not the harness) and any
+         * cross-slice resource-suspend legs are not folded (turns/tokens/cost ARE folded; toolCalls is per-leg, like
+         * the compaction subtotal). OBSERVE-ONLY (never gates budget). The workflow display is unaffected (its agents
+         * fail-on-suspend, never durably resume). A `spentToolCalls` ledger fold is a follow-on. */
+        toolCalls?: number;
+        /** Total prompt (input) tokens presented across the task's turns, normalized across providers
+         * (Anthropic reports input excluding cache; OpenAI/vLLM include it). The denominator for
+         * `cacheHitRate`. */
+        promptTokens?: number;
+        /** Prompt tokens served from the model's prefix cache (a cache HIT), summed over the task's
+         * turns — when the gateway reports it (vLLM/OpenAI `prompt_tokens_details.cached_tokens`,
+         * DeepSeek `prompt_cache_hit_tokens`, Anthropic `cache_read_input_tokens`). */
+        cachedTokens?: number;
+        /** Prompt tokens written to the cache (Anthropic `cache_creation_input_tokens`); 0 elsewhere. */
+        cacheWriteTokens?: number;
+        /** `cachedTokens / promptTokens` ∈ [0,1] — the prefix-cache hit rate for this task. Cost-critical;
+         * a low value on a multi-turn task means the cacheable prefix is unstable (see `design/09`).
+         * Track it per task and trend it per session. Undefined when the gateway reports no usage. */
+        cacheHitRate?: number;
+        /** Alias of `promptTokens` (the normalized total input incl. cache), named to match OTel
+         *  `gen_ai.usage.input_tokens`. Cost is computed from this. (Not a bug fix — `promptTokens` was
+         *  already the normalized total; this is the OTel-aligned name. See design/17 §11.5.) */
+        totalInputTokens?: number;
+        /** Completion (output) tokens summed over the task's turns. */
+        outputTokens?: number;
+        /** Cache-write tokens at the 1-hour TTL (Anthropic); 0 unless 1h caching is in use. */
+        cacheWriteTokensLong?: number;
+        /** Authoritative cost in **integer micro-USD** (1e-6 USD), computed in core from injected pricing
+         *  — integer to avoid float-accumulation error in billing. Prefer this over the float `costUsd`. */
+        costMicroUsd?: number;
+        /** @deprecated Float USD — accumulation error, and pre-1.37 overstated cache cost. Use
+         *  `costMicroUsd`. Kept for back-compat; removed in a later minor. */
+        costUsd?: number;
+        nested?: {
+            tokens: number;
+            turns: number;
+            tasks: number;
+            costUsd?: number;
+            costMicroUsd?: number;
+        };
+        /**
+         * Post-task memory-consolidation usage (design/41), when consolidation ran. Its own line item —
+         * **kept out of `tokens`/`costMicroUsd` and excluded from the budget gate** — so a completed task is
+         * never retroactively flipped to `budget.exceeded` by reconcile cost. `tokens` is 0 when every note
+         * took a cheap (no-LLM) path; `applied` counts store mutations the pass made (cheap-path
+         * UPDATE/DELETE + applied LLM decisions) so callers can observe reconcile efficacy without re-reading
+         * the store. Absent when consolidation was disabled / no-op / produced no notes. Populated
+         * asynchronously (consolidation is fire-and-forget) — see {@link TaskStream.consolidation}.
+         */
+        memory?: {
+            tokens: number;
+            costMicroUsd: number;
+            applied: number;
+        };
+        /**
+         * design/100 §E12 — the prompt-suggestion pass's usage, when it ran. Same budget-excluded side-observable
+         * treatment as {@link memory}: **kept out of `tokens`/`costMicroUsd` and excluded from the budget gate**, so
+         * the (fire-and-forget, post-completion) suggestion pass can never retroactively flip a done task to
+         * `budget.exceeded`. Absent when `suggestNextPrompts` was off / produced nothing. Populated asynchronously —
+         * see {@link TaskStream.suggestions}.
+         */
+        suggestions?: {
+            tokens: number;
+            costMicroUsd: number;
+        };
+        /**
+         * TB telemetry B2 (service [397]): counters for the engine's wall-clock/deadline mechanisms, so a
+         * bench/monitoring consumer can judge from the RESULT whether they actually engaged (refute-130
+         * lesson: "did P1/P2 fire" was unanswerable from artifacts). Present only when at least one
+         * mechanism engaged this leg; absent = none did (byte-compatible).
+         */
+        mechanisms?: {
+            /** design/130 P2: the graceful-finalize instruction was injected this run. */
+            finalizeInjected?: true;
+            /** design/128 T1-2: number of deadline nudges dispatched at turn boundaries. */
+            nudgesSent?: number;
+            /** design/130 P1: number of model calls whose max_tokens was SHRUNK by the wall-clock cap. */
+            capShrinks?: number;
+            /** design/130 P2b: number of model calls the brain CUT at the soft wall-clock deadline
+             *  (deliberate stream cancel + prefix salvage — the pre-P2b shape was a mid-call hard kill). */
+            callCutoffs?: number;
+            /** design/130 P2b: number of foreground shell timeouts CLAMPED to the soft tool deadline
+             *  (a long command times out cleanly before the write-out window instead of riding past it). */
+            toolClamps?: number;
+            /** design/132: the natural-end final-verification reminder was injected this run. */
+            finalVerifyInjected?: true;
+            /** oracle-grounding gate (opus LOW 复审, additive): HOW MANY final-verification injections
+             *  fired this run — 1 = the R9 one-shot only, 2 = R9 + the grounding re-entry (hard cap).
+             *  Present iff `finalVerifyInjected` is (the boolean stays for compatibility). */
+            finalVerifyInjections?: number;
+            /** design/133: number of turn-boundary attachments injected this run (todo/task reminders,
+             *  changed-files notes, plan-mode re-reminders — each bundled block counts once). */
+            attachmentsInjected?: number;
+            /** Repetition telemetry (clay 2026-07-10, 2e1c161 observability): brain-side degenerate-repetition
+             *  stream CUTS this run (each pairs with an `output.degenerate`-classified turn). */
+            repetitionCuts?: number;
+            /** Repetitions that landed in a detection window but were SPARED by a 2e1c161 structural
+             *  allowance (code-line shape / divider run) — the raw material for judging the allowance. */
+            repetitionSpared?: number;
+            /** Per-event details (turn + rule + period/reps + a ≤120-char segment sample), capped at 20
+             *  entries — `repetitionCuts`/`repetitionSpared` keep the true totals past the cap. */
+            repetitionEvents?: Array<{
+                turn: number;
+                action: "cut" | "spared";
+                rule: "char-run" | "unit-loop";
+                period: number;
+                reps: number;
+                segment: string;
+            }>;
+        };
+        /**
+         * design/91 — **human-review burden** (design/89 §2.4 C2 axis). The wall-clock time a task spent waiting
+         * on a human at an approval gate, plus the count, bucketed by `gate.kind`. Both human-review paths are
+         * captured: the **synchronous** `onAsk`/`resolveAsk` await (`t_return − t_call`) and the **durable**
+         * suspend→resume wait (`resumedAt − checkpoint.suspendedAt`, including the human's offline time); a
+         * multi-leg suspend/resume chain **accumulates across legs**. All timestamps come from {@link RunnerDeps.now}.
+         *
+         * **NOT an LLM cost (load-bearing, design/91 §1):** human-review time is wall-clock latency, not token
+         * spend — it is **NEVER folded into `costMicroUsd`, `costBreakdown`, or the budget gate** (the same
+         * budget-excluded side-observable treatment as {@link memory}). Adding human seconds to token µUSD is the
+         * design/89 §2.1 "apples + oranges" trap; the supervisor Pareto frontier keeps `(token cost, human seconds,
+         * correctness)` as three SEPARATE axes. Absent (`undefined`) when the task hit no approval gate OR no clock
+         * is injectable to measure — byte-compatible with a task that never paused for a human.
+         */
+        humanReview?: {
+            /** Number of human decisions awaited (each synchronous `resolveAsk` return + each durable resume of an
+             *  approval suspend). Equals `gates.length`. */
+            count: number;
+            /** Cumulative wall-clock the approval gates were alive (ms), summed across all legs. Equals `Σ gates[].waitMs`. */
+            totalWaitMs: number;
+            /** One entry per human decision, in order. `kind` = the gate's discriminant (`human` /
+             *  `irreversible_ask` for durable; `human` for a synchronous ask). `decision` = the adjudication when
+             *  known (`allow`/`deny`). design/99 MF-24 (Service AI [297]): `toolName` = the gated tool; `toolArg` = a
+             *  SHORT, SECRET-SCRUBBED one-line summary of its input (the same `primaryActivityArg` boundary as the MF-W
+             *  activity arg) — the permission-denial ledger's "denied: Bash(rm …)" display. `toolArg` is set on the
+             *  SYNCHRONOUS-ask path (the input is in scope); a durable-resume gate carries `toolName` only (its input is
+             *  not threaded onto the persisted gate — a documented follow-on). */
+            gates: Array<{
+                kind: string;
+                waitMs: number;
+                decision?: string;
+                toolName?: string;
+                toolArg?: string;
+            }>;
+        };
+        /**
+         * design/80 D-E-core: a thin FINANCE TAXONOMY of the LLM-derived costs the engine actually prices,
+         * decomposing the task's spend into report categories (derived from existing cost sources — no new
+         * persisted structure). **CORE = LLM-token-derived ONLY** — the deployment SERVICE adds the infra axes it
+         * owns (tool-call / sandbox-walltime / egress; it has the k8s cost data) and composes them with this for
+         * the supervisor surface. Each category is ≥ 0 and the LLM parts reconcile to the independently-summed
+         * LLM total: `llmRootMicroUsd + nestedSubagentMicroUsd + compactionMicroUsd === costMicroUsd`
+         * (`memoryConsolidationMicroUsd` is a separate, budget-excluded line — see `memory` — filled
+         * asynchronously after consolidation, so it is NOT part of that identity). Present whenever stats are
+         * assembled.
+         */
+        costBreakdown?: {
+            /** Root-agent LLM cost (micro-USD) = `costMicroUsd − compactionMicroUsd` (the sub-category folded into
+             *  it). NOT minus nested — nested cost is never folded into `costMicroUsd` (it lands in `nested`).
+             *  ⚠️ APPROXIMATE on a multi-slice `resource_limit` RESUME (design/80 D-E-core, codex review #3): the
+             *  durable resource ledger persists only the AGGREGATE prior spend, not its compaction subtotal, so
+             *  prior slices' compaction folds in HERE rather than into `compactionMicroUsd`. The TOTAL (`costMicroUsd`)
+             *  stays exact; only this llmRoot-vs-compaction split is per-leg-approximate across resource slices. */
+            llmRootMicroUsd: number;
+            /** Delegated sub-agent (nested) LLM cost (micro-USD) = `nested?.costMicroUsd ?? 0`. */
+            nestedSubagentMicroUsd: number;
+            /** Post-task memory-consolidation LLM cost (micro-USD) = `memory?.costMicroUsd ?? 0`; filled
+             *  asynchronously after the consolidation pass (0 until then). A separate, budget-excluded line. */
+            memoryConsolidationMicroUsd: number;
+            /** design/100 §E12 — prompt-suggestion pass LLM cost (micro-USD) = `suggestions?.costMicroUsd ?? 0`; filled
+             *  asynchronously after the (post-completion) pass (0 until then). A separate, budget-excluded line. */
+            suggestionsMicroUsd?: number;
+            /** Within-task compaction LLM cost (micro-USD) — part of `costMicroUsd`, so subtracted from root.
+             *  ⚠️ See {@link llmRootMicroUsd}: under-reports prior slices' compaction on a multi-slice resource resume. */
+            compactionMicroUsd: number;
+        };
+    };
+}
+/**
+ * Identity fields carried by every CONTENT event of a task stream (design/99 §E2 — lightweight message
+ * identity, service [241]/[242]). Both are OPTIONAL and ADDITIVE; a consumer that ignores them is unchanged.
+ *
+ * - `eventId` — a core-minted, time-sortable (uuidv7) unique id stamped on each emitted content event. Gives
+ *   a live UI a stable handle to correlate/dedup streamed events and to map its own client-side message ids
+ *   back to a core anchor. (The durable-anchor mapping for resume-at — which eventIds are restartable
+ *   transcript positions — is finalized by the E18 `resumeAt` seam; this field is the stable handle it builds on.)
+ * - `parentToolCallId` — present ONLY when this task runs as a sub-agent spawned under a parent task's tool
+ *   call (threaded via the trusted `RunInternals.parentToolCallId`, sourced from the spawning tool's
+ *   `ToolExecuteContext.toolCallId`). Lets a consumer attribute streamed content to the delegation subtree it
+ *   belongs to WITHOUT core physically merging the child stream into the parent (the child's RESULT still
+ *   re-enters the parent MODEL context only through the `delimitUntrusted` fence — observability threading and
+ *   model-context isolation are kept separate, so prompt-cache and the injection boundary are untouched).
+ */
+export interface TaskEventIdentity {
+    eventId?: string;
+    parentToolCallId?: string;
+    /**
+     * design/122 S2 (codex-M4 name: the `WorkflowRun.sourceTaskId` family, NOT a second `taskId` — that
+     * field already exists on `task_progress` and a duplicate would bite consumers) — the ORIGINATING task's
+     * canonical id (`spec.taskId ?? sessionId`), stamped ONLY on the content events of a task running AS A
+     * SUB-AGENT (same condition as {@link parentToolCallId}). A consumer of the C1 forward channel
+     * (`forwardSubagentEvents`) can key a child's content events by the child task directly, without an
+     * alias table. A TOP-LEVEL task's own events carry NO `sourceTaskId` (absent = the consumer's current
+     * task). Additive; a consumer that ignores it is unchanged.
+     */
+    sourceTaskId?: string;
+}
+/**
+ * design/99 §E3/§E10 (service [241]/[242]) — a BRAIN-LAYER liveness phase, surfaced so a UI can show why a
+ * turn is stalled (the brain otherwise absorbs these silently in its connect/retry loop). Provider-NEUTRAL:
+ * carries only the graduated phase + a neutral hint, NEVER an HTTP status / provider taxonomy / stop_reason.
+ * A CLOSED union (type-safe) covering the core brain layer; a deployment that surfaces its OWN states
+ * (e.g. E25 token-refresh `authenticating`) does so on its own channel, not by widening this.
+ */
+export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "circuit_open";
+/** design/99 §E3/§E10 — the payload of a {@link TaskEvent} `status` event (and the brain→runner signal). */
+export interface BrainStatus {
+    phase: BrainStatusPhase;
+    /** Optional neutral, human-readable hint (NO provider/HTTP detail). */
+    detail?: string;
+    /** Seconds until the brain's next retry attempt (from the honored backoff / `Retry-After`), when known. */
+    retryInSec?: number;
+}
+/**
+ * design/97 CORE-8 (③): one lightweight TOOL-ACTIVITY beat surfaced from a running task, for a per-agent live
+ * "last N tool calls" drill-down. A trusted run-scoped sink ({@link RunInternals.onActivity}) receives one at
+ * each tool start + end. Structural (name/phase/ids) + a SHORT redacted primary `arg` for display — NOT the full
+ * ARGS or OUTPUT (those carry untrusted/host data; the workflow layer surfaces redacted prompt/output separately).
+ */
+export interface ToolActivity {
+    phase: "start" | "end";
+    toolCallId: string;
+    toolName: string;
+    /** design/99 MF-W: a SHORT primary-arg summary for the monitor's `Read(path)` / `Bash(grep …)` display — the
+     *  single most salient input ABBREVIATED (command→name, path→basename, url→origin+path) + SECRET-SCRUBBED +
+     *  truncated (~80 code points). Set on `phase: "start"`. NOT the full args object, and NOT `redactHostLeaks`
+     *  (that over-redacts the path the monitor needs); the abbreviation + scrub is the leak boundary since the value
+     *  is persisted + SSE-forwarded (codex-reviewed). See `primaryActivityArg`. */
+    arg?: string;
+    /** Set on `phase: "end"` — whether the tool call errored. */
+    isError?: boolean;
+}
+/** Streaming events surfaced from a running task (for live UIs). */
+export type TaskEvent = ({
+    type: "text_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    type: "reasoning_delta";
+    delta: string;
+} & TaskEventIdentity) | ({
+    type: "tool_start";
+    toolCallId: string;
+    toolName: string; /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    label?: string;
+    args: unknown;
+} & TaskEventIdentity) | ({
+    type: "tool_end";
+    toolCallId: string;
+    toolName: string;
+    /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    label?: string;
+    isError: boolean;
+    /**
+     * design/99 §E1 (service [241]/[242]) — the tool's MODEL-FACING result content, surfaced for a live UI
+     * that renders tool output. It is the harness `AgentToolResult.content` the mapper already produced
+     * (previously dropped here); the internal `details` payload is NOT exposed (e.g. a sub-agent tool's
+     * `details` is the entire child `TaskResult`).
+     *
+     * **Type is `unknown` and intentionally non-uniform** — within size it passes through AS-IS to keep
+     * structure a UI wants (a `string`, or `(TextContent|ImageContent)[]` blocks); when the serialized body
+     * exceeds the core size cap it degrades to a single TRUNCATED STRING (see {@link truncated}). A consumer
+     * must handle both shapes.
+     *
+     * **UNTRUSTED RAW + for OBSERVABILITY ONLY**: it is external tool output (file reads, shell stderr, API
+     * bodies) and may carry secrets/paths/PII — core bounds only its SIZE; a consumer MUST redact and MAY
+     * further bound before it persists or displays it (same contract as `tool_start.args`). It is for a live
+     * UI / trace, NOT for re-feeding to a model: a truncated body would mislead an LLM, and the model already
+     * has the full, untruncated result in its own context — build model prompts from the session, never by
+     * replaying this field. Absent when the tool produced no content body.
+     */
+    output?: unknown;
+    /**
+     * design/116 [363] channel (b) — the tool's CC-shaped `toolUseResult` facts (`details.type` ∈ the
+     * known card set: edit/create/update/bash/text/grep/glob/notebook-edit/mcp/multiedit), surfaced on
+     * the live wire so a CC-faithful shell renders rich cards (red/green diff, stdout panes, file cards)
+     * without re-parsing the model-facing string. Absent when the tool carries no CC card shape (a
+     * subagent's child TaskResult is deliberately NOT exposed — the allowlist is the leak boundary) or
+     * when the serialized card exceeds the size bound (omitted whole; a consumer falls back to `output`).
+     * UNTRUSTED RAW like {@link output}: a consumer MUST redact before persisting or forwarding.
+     *
+     * **双面契约(CC 2.1.207 @765495 成文,`tool_use_result` describe;CC207-CORE-SWEEP P2-3)** — a tool
+     * result has TWO faces that never substitute for each other:
+     * - **模型面** = {@link output} / the tool_result text: the string the MODEL reads. It may carry
+     *   model-directed framing — e.g. a delegation tool's trailer (agentId / usage lines the model uses to
+     *   address SendMessage or budget itself). That framing is FOR THE MODEL; it is not a host data format.
+     * - **宿主面** = this field: the tool's structured Output object, per-tool shaped, keyed by the matching
+     *   tool call's name. For a delegation/Agent-family tool the completed shape is the subagent's final
+     *   report WITHOUT the model-directed trailer, plus run totals (CC names it `AgentToolCompletedOutput`).
+     * A host/shell MUST render from `structured` and MUST NOT parse the model-facing text back into data
+     * (trailer wording is model-audience prose and may change without notice); symmetrically, core never
+     * strips the trailer from the model face just because the structured face exists — the model still needs
+     * it in-context. When `structured` is absent, the honest fallback is to display `output` as opaque text,
+     * not to scrape it.
+     */
+    structured?: unknown;
+    /**
+     * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
+     * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of
+     * parsing the `…[+N chars truncated]` marker out of the string. Absent/false = `output` is the complete
+     * content body. (The full untruncated result still lives in the model's context / `ToolResultStore`.)
+     */
+    truncated?: boolean;
+} & TaskEventIdentity) | ({
+    type: "turn_end";
+    /**
+     * Per-turn token usage + cost (the turn that just ended), for live per-turn accounting / a trace UI
+     * (service [41]). Re-priced in core from injected pricing (authoritative, like `TaskResult.stats`).
+     * `inputTokens` is the normalized total input incl. cache (matches `stats.promptTokens` / the tracer's
+     * `brain.call.promptTokens`). Absent only if the turn produced no assistant usage.
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        costMicroUsd: number;
+    };
+    /** TB 尸检 T1-5: set when the turn ended WITHOUT a provider usage frame (e.g. a degenerate-repetition
+     *  cutoff cancelled the stream before usage arrived). Consumers must treat the missing usage as
+     *  UNKNOWN — not zero (the provider still served the request; `stats` under-counts it honestly rather
+     *  than polluting the single-source accounting with an estimate). */
+    usageMissing?: true;
+    /** TB telemetry B1 (service [397]): the NORMALIZED finish reason of the turn's LAST model call —
+     *  the engine's `AssistantMessage.stopReason` (`StopReason`: `"stop"`/`"length"`/`"toolUse"`/
+     *  `"error"`/`"aborted"`). This is post-normalization: e.g. Anthropic `end_turn`/`stop_sequence`
+     *  both fold to `"stop"`, `max_tokens`→`"length"`; the raw provider reason is NOT preserved here.
+     *  The machine signal for "was this turn cut by max_tokens" (`"length"`) — previously stream+trace
+     *  double-blind, which made P1 cap-binding unjudgeable from artifacts. Absent when the turn produced
+     *  no assistant message. Typed `string` (not the internal `StopReason`) to keep the engine's union
+     *  private, but the value set is exactly those five tokens. */
+    stopReason?: string;
+} & TaskEventIdentity) | {
+    /** design/99 MF-18: a compaction boundary (or, since design/119 #1, mid-turn when the prompt-too-long recovery force-compacts between a failed request and its retry). `trigger` = what caused it: `"auto"` (the context-threshold
+     *  auto-compaction) or `"manual"` (the `TaskStream.compact` / `/compact` path). `tokensBefore` = the
+     *  pre-compaction context size. CC parity = `SDKCompactBoundary{trigger, pre_tokens, preserved_segment}`. */
+    type: "compacted";
+    trigger: "auto" | "manual";
+    tokensBefore: number;
+    /** TB telemetry B4 (service [397]): post-compaction context size in the TRIGGER-GATE coordinate
+     *  (`postTriggerTokens` = estimate + anchor-less overhead). Pairs with {@link triggerTokensBefore}
+     *  — NOT with `tokensBefore` (which is the CC `pre_tokens` value in prepareCompaction's coordinate,
+     *  lacking the overhead term; subtracting across the two coordinates would mis-state the delta,
+     *  the audit-B-1 / P-13 class). Absent when the post measurement failed (best-effort, never fails a
+     *  successful compaction). */
+    tokensAfter?: number;
+    /** TB telemetry B4: pre-compaction size in the SAME trigger-gate coordinate as {@link tokensAfter}
+     *  (`triggerTokens` — the exact quantity the compaction gate compared). `triggerTokensBefore −
+     *  tokensAfter` is the self-consistent freed delta. Absent on the legacy emitter. */
+    triggerTokensBefore?: number;
+    /** TB telemetry B4: wall time of the whole compaction pass (summary call included) — what the
+     *  boundary pause actually cost. Absent on legacy emitters. */
+    durationMs?: number;
+    /** CC `SDKCompactBoundary.preserved_segment` parity: `firstKeptEntryId` is the session-tree entry id where
+     *  the surviving KEPT TAIL begins after this compaction. A consumer maps it to a wire message via the
+     *  `entryId` carried on `message_committed` (message-identity Phase 1) — render the compaction divider just
+     *  before that message + relink the preserved tail. (The eventId↔entryId side map service keeps for resumeAt
+     *  also resolves it, but is no longer required.) Absent on a compaction that reported no kept-tail floor. */
+    preserved_segment?: {
+        firstKeptEntryId: string;
+    };
+    /** Blackboard 2026-07-03 (CC post-compact file-restore parity): the working files the engine
+     *  re-read into the summary (attachWorkingFiles), attachment order. A shell renders CC's
+     *  `Read {path} (…)` cards under the compaction divider from this. Absent when the feature is
+     *  off or nothing was attached. `truncated` = the content was clipped at the per-file cap. */
+    attachedFiles?: Array<{
+        path: string;
+        chars: number;
+        truncated: boolean;
+    }>;
+} | ({
+    /**
+     * TB telemetry B3 (service [397]): the engine injected a SYSTEM steering message (a deadline nudge
+     * or the design/130 P2 graceful-finalize instruction) into the model's next turn. Previously these
+     * went through `harness.steer()` with no stream echo — a consumer literally could not tell whether
+     * the finalize fired (the refute-130 attribution blind spot). Echo only; the model-facing message
+     * is unchanged. `preview` is the injected text clipped to a display bound.
+     *
+     * design/133 (LOW-11/F11): the turn-boundary attachment producers ride the same echo — sources
+     * `todo_reminder` / `task_reminder` / `changed_files` / `plan_mode` and the G1 [482]/续批 members
+     * `background_tasks` / `tools_delta` / `agent_listing` / `mcp_instructions` (one event per
+     * attachment; a multi-attachment boundary still coalesces into ONE steer message on the model lane).
+     */
+    type: "steering_injected";
+    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "changed_files" | "plan_mode" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "mcp_instructions";
+    preview: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/121 (CC 198 `<new-diagnostics>` parity): NEW LSP diagnostics that appeared after the
+     * agent's edits, drained at a turn boundary. The SAME data was injected into the model as a
+     * `<new-diagnostics>` context message; this frame is the shell's render source (CC's collapsed
+     * `Found N new diagnostic issues in M files (ctrl+o to expand)` row). UNTRUSTED RAW (language-
+     * server output over workspace files) — a consumer redacts/bounds before persisting (§E1).
+     */
+    type: "diagnostics";
+    files: Array<{
+        uri: string;
+        diagnostics: Array<{
+            message: string;
+            /** LSP severity: 1=Error 2=Warning 3=Information 4=Hint. */
+            severity?: number;
+            range?: {
+                start: {
+                    line: number;
+                    character: number;
+                };
+                end?: {
+                    line: number;
+                    character: number;
+                };
+            };
+            code?: string | number;
+            source?: string;
+        }>;
+    }>;
+    isNew: true;
+} & TaskEventIdentity) | ({
+    /**
+     * message-identity Phase 1 (the CC `SDKCompactBoundary` parity enabler): a persisted session-tree entry was
+     * just COMMITTED for a RENDERABLE message the consumer has already streamed. `entryId` = `SessionTreeEntry.id`
+     * (uuidv7, persisted, replica-stable) — the SAME id space as `compacted.preserved_segment.firstKeptEntryId`,
+     * E18 `resumeAt`, and E19 `rewindFiles`. `role` + (for a tool result) `toolCallId` let a consumer bind it to
+     * the message it rendered: a tool result by its `toolCallId`; an assistant/user message by stream order (this
+     * is the terminal boundary for the content just streamed, after its deltas and before its tool results). A
+     * consumer builds its own `entryId → message` map from these to resolve `preserved_segment` WITHOUT the
+     * eventId↔entryId side map. Terminal per-message boundary; additive + ignorable. ABSENT for a message that did
+     * not persist (an empty-failure assistant) and for non-message entries (a compaction summary / model_change —
+     * never a `message_committed`). The engine still holds no eventId→entryId map (the deployment owns it); this
+     * only pushes the persisted id onto the wire, the constitution's primitive/profile split (cf. §E2 `eventId`).
+     */
+    type: "message_committed";
+    entryId: string;
+    role: "user" | "assistant" | "toolResult";
+    /** Present iff `role === "toolResult"`: the exact join key to the `tool_start`/`tool_end` already rendered. */
+    toolCallId?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 §E3/§E10 (service [241]/[242]) — a live BRAIN-LAYER status the brain would otherwise absorb
+     * silently (a 429 rate-limit / a 5xx or network retry / a reconnect / an open circuit breaker). Emitted
+     * the moment the brain decides to wait/retry, carrying the graduated {@link BrainStatusPhase} + an
+     * optional `retryInSec` so a UI can show "rate limited, retrying in Ns". EPHEMERAL — a pure liveness
+     * signal, never persisted or replayed on resume. Provider-neutral (no HTTP status / stop_reason).
+     * SCOPE: reflects THIS task's own (top-level) brain calls. A delegated sub-agent's brain liveness routes
+     * to the SUB-AGENT's own stream (isolated, like every child event — §E2); a background internal brain
+     * call (memory recall/consolidation) is intentionally not surfaced.
+     */
+    type: "status";
+} & BrainStatus & TaskEventIdentity) | ({
+    /**
+     * design/115 P2 core slice — SDK-side projection of a background task terminal notification. The model-facing
+     * projection is the sibling `<task-notification>` XML injected through the runner's system-injection lane when
+     * the originating harness is still running; durable idle wake/resume is a deployment transport concern.
+     */
+    type: "task_notification";
+    notification: TaskNotificationPayload;
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 MF-10 (Service AI [297]) — a SUBAGENT PROGRESS TICK: the delegated sub-run's usage ACCRUING
+     * over time, emitted at each turn boundary WHILE it runs, so a parent UI animates the Task card's rollup
+     * (tokens/tool-uses climbing). Emitted ONLY for a subagent (a task with `parentToolCallId`); a top-level
+     * run's own usage is the consumer's own. `status:"running"` mid-run; the terminal usage is the `done` result.
+     * Live/ephemeral — NOT persisted (a resumable trace re-derives usage from the result), like `status`.
+     * Maps to CC `SDKTaskProgress` (camelCase here → snake_case `task_id`/`total_tokens`/`tool_uses`/`duration_ms`
+     * at the SDK/service projection, the same convention as `toolCallId`→`tool_use_id`).
+     */
+    type: "task_progress";
+    taskId: string;
+    /** design/99 (nested-subagent live tree): the spawning run's taskId — present on a DEEPER-than-1 subagent tick
+     *  (a subagent spawned by another subagent), forwarded via `RunInternals.onForwardEvent` so a UI nests the
+     *  node directly (this.taskId under parentTaskId) without mapping `parentToolCallId` → owner. The top-level
+     *  run is known to the consumer; its direct children carry the top's taskId here. Absent on a top-level tick. */
+    parentTaskId?: string;
+    /** design/99 BC-2 (Service AI [§I]): a short, single-line HUMAN display name for the subagent — its explicit
+     *  `taskName` or the selected agent-type. So a Fleet child row shows a readable label instead of the raw
+     *  `taskId` (the stable row identity stays the taskId). ABSENT when the subagent carries neither a taskName
+     *  nor an agent-type — the child then keeps its taskId (NOT the raw objective, which could leak a delegated
+     *  secret to a progress-scoped consumer — dual-review Q2). Sanitized (control-char-stripped, length-capped). */
+    name?: string;
+    /** 黑板 [583] (#64 接线实证): the child's most recent tool intent as one human line ("Bash npm test",
+     *  "Edit src/x.ts") — the SAME source/value as the registry sink tick's `currentAction` (黑板 [558] B),
+     *  attached to the FORWARDED frame because every client wire projects this TaskEvent, not the sink
+     *  (service's three projection legs saw a permanently-absent field before this). UNTRUSTED display
+     *  hint — redact at the projection boundary (service [579]②). Absent until the child runs a tool. */
+    currentAction?: string;
+    usage: {
+        totalTokens: number;
+        toolUses: number;
+        durationMs: number;
+    };
+    status: "running";
+} & TaskEventIdentity) | ({
+    /**
+     * design/99 §E13 (service [241]/[242]) — the task's tracked working directory CHANGED mid-run (a `bash`
+     * `cd` moved it). Emitted live after the tool that moved it, carrying the new logical cwd, so a shell UI
+     * can update its prompt/path display. The tracked cwd is the RAW logical path (a `cd` through a symlink
+     * reports the raw path navigated, not the resolved target). Only fires when a real shell is mounted
+     * (absent under `handsReadOnly` / no-exec). The initial cwd is NOT announced (it is the known root); only
+     * subsequent changes are. A live observability signal — not persisted, and the tracked cwd RESETS to the
+     * root across a suspend/resume (the per-leg execution cwd is not durable today — a pre-existing limitation
+     * tracked with the E18/E19 execution-state durability work); within a leg, every `cd` move is reported.
+     */
+    type: "workspace_changed";
+    cwd: string;
+} & TaskEventIdentity) | {
+    type: "done";
+    result: TaskResult;
+};
+/**
+ * Outcome of a manual {@link TaskStream.compact} request (blackboard [496]③ — the enum names align with
+ * the diagnosis decision tree's drain exits, so a consumer can tell "202 processed" states apart):
+ * - `"compacted"` — a compaction landed at the boundary (the `compacted{trigger:"manual"}` event fired).
+ * - `"failed"` — the attempt ran and threw (summarizer failure / empty summary / oversized summary;
+ *   `compaction.failed` trace frame + `Runner.onError(phase:"compaction")`), or the §17.4 breaker was
+ *   already open so the request was drained without an attempt (`compaction.failed` frame, no attempt).
+ * - `"mooted"` — the request was processed but the run could no longer compact (dying loop: abort /
+ *   durable suspend / plan review in flight), or the task settled before any boundary arrived.
+ * - `"noop"` — the attempt ran but there was nothing to compact (no valid cut point / empty history).
+ * - `"blocked"` — a `preCompact` hook deliberately blocked this compaction (not a failure).
+ * - `"disabled"` — compaction is disabled by the task spec (`compaction.enabled: false`).
+ */
+export type CompactOutcome = "compacted" | "failed" | "mooted" | "noop" | "blocked" | "disabled";
+/** A running task you can iterate for live events and await for the final result. */
+export interface TaskStream extends AsyncIterable<TaskEvent> {
+    result(): Promise<TaskResult>;
+    /**
+     * Resolves when the post-task memory-consolidation pass (design/41) settles — or immediately when none
+     * ran. Consolidation is **fire-and-forget**: `result()`/`runTask()` never wait for it (result-first).
+     * Await this ONLY when you need `stats.memory` populated (tests/metrics) or to know the background
+     * reconcile finished. Best-effort: it never rejects (failures route to `onError(phase:"memory")`).
+     */
+    consolidation(): Promise<void>;
+    /**
+     * design/100 §E12 — resolves to the post-completion prompt **suggestions** (the shell's follow-up prompts),
+     * or `[]` when `suggestNextPrompts` was off / the task did not complete / the pass produced nothing / it
+     * failed. Like {@link consolidation}, the pass is **fire-and-forget**: `result()` never waits for it, so a
+     * shell does `await stream.result()` THEN `await stream.suggestions()`. **Never rejects.** The strings are
+     * UNTRUSTED model output for display ONLY — never re-feed them to a model.
+     */
+    suggestions(): Promise<string[]>;
+    /**
+     * Inject a mid-task **steering** message (design/47) that the running task sees at the start of its
+     * next turn (delivered via the harness steering queue). Resolves once queued; **throws** (code
+     * `steering.not_running`) if the task hasn't started yet or has already finished — never silently
+     * dropped. By default the text enters as a normal **user** message (in an orchestration the caller IS
+     * the task's user). Pass `trusted: true` ONLY for operator/system-level guidance: it is wrapped as a
+     * `<system-reminder>` (elevated authority) — do NOT use it for caller/third-party content that could
+     * carry a prompt injection. The seam gives the channel; the caller owns the judgement (design/43 §6).
+     */
+    steer(text: string, options?: {
+        trusted?: boolean;
+    }): Promise<void>;
+    /**
+     * Request a manual context **compaction** (design/99 MF-18 — the shell `/compact` button). Forces a
+     * compaction at the NEXT safe turn boundary regardless of the auto-threshold (the only safe point — never
+     * mid-turn, which would rewrite the session under an in-flight request); a `compacted` event with
+     * `trigger:"manual"` is emitted when it actually compacts. Resolves once the request has been PROCESSED at
+     * a boundary, or when the task ends first (whichever comes first — it never hangs). **Throws**
+     * (`steering.not_running`) if the task hasn't started or has already finished. Idempotent-ish: concurrent
+     * calls coalesce onto the next boundary (all waiters get the same outcome).
+     *
+     * ⚠️ BREAKING (blackboard [496]③, MF-18 processed-无-compacted): resolves with a {@link CompactOutcome}
+     * instead of `void` — "processed" alone told a consumer nothing when the attempt failed or was mooted
+     * (the 202-then-silence fingerprint). Every outcome also has a stream/trace counterpart:
+     * `"compacted"` → the `compacted` event; `"failed"` → `compaction.failed` trace (+ `onError(phase:
+     * "compaction")` when an attempt was burned); `"blocked"` → `compaction.blocked` trace; `"noop"` →
+     * `compaction.noop` trace; `"disabled"` → `compaction.disabled` trace; `"mooted"` →
+     * `compaction.mooted` trace — or the task simply settled before any boundary processed the request
+     * (the run-end backstop resolves "mooted" without a frame; the task's terminal events are the signal).
+     */
+    compact(): Promise<CompactOutcome>;
+    /**
+     * design/116 detach(飞轮 [C],CC mid-flight ctrl+b)— move a RUNNING tool call to the background.
+     * Today only a detach-capable Bash honors it (the env adopts the child as a background shell; the tool
+     * settles early with "moved to background; task_id=b*", and the G2b completion notification takes over).
+     * Fire-and-forget and race-safe: a request landing before the tool reads its signal still detaches; one
+     * landing after the tool finished is a no-op. Unknown toolCallIds are a no-op (nothing to detach).
+     */
+    detach(toolCallId: string): void;
+    /**
+     * Hard-**interrupt** the running task — a real abort (not a best-effort hint), equivalent to firing the
+     * task's `signal` (design/47). No-op if the task already finished. For a SOFT redirect that lets the
+     * task keep running and adjust, use {@link steer} instead.
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Reap this task's resources — **callable after it finished**, idempotent, never throws (design/50 §3,
+     * design/51). The fan-out (v2) cancel primitive: an orchestrator's `cancelAll` is the shared
+     * `AbortController.abort()` then `Promise.all(streams.map((s) => s.destroy()))`.
+     *
+     *  - **still running** → hard-interrupts it; the run's own `finish()` tears down its execution env.
+     *  - **suspended** (`status:"suspended"`) → `finish()` SKIPPED env teardown (the remote env was
+     *    `suspendVM`-paused for a durable resume) and the checkpoint is committed → `destroy()` reaps BOTH:
+     *    it CAS-**expires** the checkpoint (`CheckpointStore.expire`, fencing any concurrent resume) and —
+     *    **only if it won that CAS** — destroys the paused env. So a cancelled fan-out worker never leaks a
+     *    paused container + orphan checkpoint, and is never resumed onto an env `destroy()` already tore down
+     *    (the expire/resolve CAS on the one `pending` row is mutually exclusive: exactly one of reap/resume
+     *    wins). If `expire` itself fails, the env is left intact (checkpoint + paused env stay a consistent,
+     *    still-resumable pair; the failure surfaces via `RunnerDeps.onError`, not a throw).
+     *  - **already completed / failed / already destroyed** → no-op.
+     *
+     * Idempotent at the promise level (repeat/concurrent calls await the same settled work).
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Memory write-side consolidation (design/41 B-full): after a task ends, optionally make **one** LLM
+ * call to reconcile the notes the model wrote this task against existing memory — Mem0-style
+ * ADD/UPDATE/DELETE/NONE — so memory stays "few and accurate". **Opt-in, off by default**: the object's
+ * mere presence does NOT enable it; `enabled` must be set `true` explicitly (so a config object can sit
+ * in place pre-wired and be flipped on). Requires `RunnerDeps.memoryStore` to implement the
+ * id-addressable trio (`searchScored`/`update`/`delete`); otherwise consolidation is a safe no-op.
+ *
+ * Cost lands in `TaskResult.stats.memory` (NOT in the task's own `tokens`/`cost`, and excluded from the
+ * budget gate). Failures are best-effort: the notes the model already saved are kept, and the failure is
+ * reported via `onError(phase:"memory")`.
+ *
+ * @deprecated design/138 S4 — the runner-integrated consolidation pass rode the retired legacy memoryStore
+ * path and no longer runs (the config is ignored by the Runner). The standalone helpers
+ * (`runMemoryConsolidation`/`consolidateScope`) still accept it for direct store-level use.
+ */
+export interface MemoryConsolidationConfig {
+    /** Master switch. `false`/omitted = no consolidation (zero extra LLM calls), unchanged behavior. */
+    enabled: boolean;
+    /** Model role for the reconcile LLM call. Default `"summarize"` (a cheap tier; falls back to `default`). */
+    role?: ModelRole;
+    /**
+     * Vector-distance reconcile band over `searchScored` candidates (see {@link ScoredMemory} — cosine
+     * distance ∈ [0, 2], 0 = identical). A new note's NEAREST existing candidate decides its path:
+     * `< lo` = near-duplicate → cheap UPDATE, no LLM; `[lo, hi]` = possibly refines/contradicts → batched
+     * into the LLM call; `> hi` = genuinely new → kept as-is, no LLM. Default `{ lo: 0.05, hi: 0.30 }`.
+     *
+     * These defaults are effectively the **5th / 95th percentile** of a typical embedding model's distance
+     * distribution — **calibrate them per embedding model**: a different model's distances live on a
+     * different scale, and an un-recalibrated band silently degrades to pass-through (everything ADDs) or
+     * over-merges (everything reconciles).
+     */
+    band?: {
+        lo: number;
+        hi: number;
+    };
+    /** Top-k candidates `searchScored` fetches per new note. Default 20 (bounds the LLM input). */
+    searchLimit?: number;
+    /** Cap on this-task notes consolidated in one batch (bounds the LLM input). Default 50. */
+    maxNotesPerTask?: number;
+    /** Independent wall-clock timeout (seconds) for the whole consolidation pass. Default 30. */
+    timeoutSec?: number;
+}
+/**
+ * design/98 §E.2 / §2.5 (S8b) — the deployment-trusted governance that EVERY sub-agent an LLM-authored
+ * workflow script spawns INHERITS (tighten-only). The child spec is BUILT from this baseline + a strict
+ * WHITELIST of safe work-fields the script may set — `{ ...base, ...pick(scriptSpec, WHITELIST_KEYS) }` then
+ * `tightenTaskSpec(base, child)` (codex BLOCKER2: default-deny / complete-by-construction, NOT a blacklist
+ * strip — a missed control-plane field would otherwise leak). It is captured from `RunnerDeps` (trusted,
+ * never LLM-influenced), NEVER from the LLM-influenced initiating task spec.
+ *
+ * Why an EXPLICIT field (codex Q1/Q2 arbitration): `RunnerDeps` has no `tools`/`mcp`/`skills`/`principal`
+ * (those are TaskSpec-only), so the capability a workflow child gets cannot be auto-derived from deps —
+ * the deployment must DECLARE it here. Unset ⇒ self-orchestration is FAIL-CLOSED (the `run_workflow` tool is
+ * not mounted, same hard deploy gate as a missing sandbox): a script-spawned agent must never run without a
+ * governed baseline.
+ */
+export interface WorkflowGovernanceBaseline {
+    /**
+     * The deployment's trusted control-plane the child inherits — toolPolicy / onAsk / onQuestion / hooks /
+     * principal / tools / mcp / skills / lspManager / checkpointStore / getApiKeyAndHeaders / promptProvider /
+     * handsReadOnly / shellGate / limits / maxCostUsd / maxTokens, etc. Snapshotted into each child spec FIRST,
+     * so every governance field comes from here; only whitelisted work-fields overlay it.
+     */
+    base: Partial<TaskSpec>;
+    /**
+     * The allowed model NAMES an LLM-authored script may pick (design/98 §2.5, codex 新洞2). A script gives a
+     * `modelName` string (never a `Model` object — that carries `baseUrl`/`headers` = exfil); the engine
+     * resolves it against this list to a deploy-configured `Model` (the script never sees the object).
+     * **FAIL-CLOSED**: `undefined`/empty ⇒ the script CANNOT pick a model (its `modelName` is rejected → the
+     * child falls back to the workflow's default role). NEVER fail-open to the whole `models` catalog for an
+     * LLM-authored workflow.
+     */
+    workflowModelAllowlist?: string[];
+}
+/**
+ * design/99 §K — the per-principal runtime ENTITLEMENTS the engine enforces server-side, resolved by a
+ * deployment via {@link RunnerDeps.runtimeCapsResolver} from center's `GET /api/config/effective?principal=`.
+ * Every field is TIGHTEN-ONLY (a cap only ever DENIES or FORCES; `undefined` = no per-principal restriction).
+ * Only the two caps the ENGINE can enforce live here; `allowUltracode`/`allowBypassPermissions` are
+ * shell-UX / service-settings-layer concerns (see {@link RunnerDeps.runtimeCapsResolver}).
+ */
+export interface RuntimeCaps {
+    /** `false` DENIES workflow self-orchestration for this principal server-side — even on a deployment that is
+     *  capable ({@link RunnerDeps.workflowScriptRunner} + governance). The third stage of the workflows gate.
+     *  `undefined`/`true` = no per-principal restriction (the deployment capability still governs). */
+    allowWorkflows?: boolean;
+    /** `false` DENIES fork (`Agent(subagent_type:"fork")` — design/136: the only fork face since the standalone
+     *  tool was retired; the deny is the honest `fork.disabled` result, and since 1.256 it binds the Agent-fork
+     *  route too, closing the 1.254 governance bypass) for this principal server-side — even on a fork-capable
+     *  (durable-store) deployment. Fork is a compute-amplification primitive (a principal spawns
+     *  context-inheriting children, each spending on its own quota), so a multi-tenant operator gates it
+     *  per-principal the SAME way as {@link allowWorkflows}. `undefined`/`true` = no per-principal restriction
+     *  (the task `enableFork` + durable-store capability still govern). Tighten-only: it can DENY a capable
+     *  deployment, never GRANT beyond it. */
+    allowFork?: boolean;
+    /**
+     * Observer agents (CC 2.1.206 parity, docs/CC206-OBSERVER-ANCHORS-2026-07-11.md §6): honor
+     * {@link AgentDefinition.observer} auto-spawn declarations. **POLARITY NOTE — unlike
+     * `allowWorkflows`/`allowFork` (`undefined` = unrestricted), this one is `=== true` EXPLICIT
+     * opt-in, default OFF**: CC's gate pair is a default-UNSET experimental env var
+     * (`CLAUDE_CODE_EXPERIMENTAL_OBSERVER_AGENTS`) ANDed with a default-true statsig gate — the
+     * composite ships dark. `undefined`/`false` ⇒ declarations resolve to unobserved (no warn: the
+     * gate, not a config mistake).
+     */
+    allowObservers?: boolean;
+    /** `true` FORCES this principal's run onto the durable-approval path: the engine synthesizes a
+     *  `durableApproval{scope: principal}` so a policy `ask` suspends to the wire (a per-tool CC-faithful gate)
+     *  even when the caller did not opt in — center's fleet-wide "interactive runs gate" mandate. A
+     *  caller-supplied `TaskSpec.durableApproval` always wins (it may carry a tighter scope/ttl). */
+    forceDurableGate?: boolean;
+}
+/**
+ * design/129-B(黑板 [444])— one lifecycle event of a BACKGROUND delegation child, delivered to the
+ * process-level {@link RunnerDeps.onBackgroundChildEvent} observer. Keys: `taskId` is the registry handle
+ * (`a*` domain — the TaskOutput/TaskStop key); `progressTaskId`/`sessionId` are the child RUN's id (uuid
+ * domain — the same key `task_progress` frames carry, [434] anchor).
+ */
+export interface BackgroundChildEvent {
+    kind: "spawn" | "tick" | "terminal";
+    /** Registry handle id (`a*` domain). Stable across all three kinds — the row key. */
+    taskId: string;
+    /** design/129: `true` when the child outlives its parent turn (session-scoped). */
+    sessionScoped: boolean;
+    /** Registry owner key (task-scoped: the host taskId; session-scoped: the sessionId). */
+    owner?: string;
+    /** Registry scope (tenant/principal isolation key). */
+    scope?: string;
+    /** spawn: the child's short description (bounded, display-safe). */
+    description?: string;
+    /** spawn: the HOST task's canonical taskId (parent attribution). */
+    parentTaskId?: string;
+    /** tick: the forwarded `task_progress` frame's own taskId (uuid domain; nested children carry theirs). */
+    progressTaskId?: string;
+    /** tick: the forwarded frame's parentTaskId (nested attribution) · terminal: absent. */
+    progressParentTaskId?: string;
+    /** tick: the child's display name, when the frame carried one. */
+    name?: string;
+    /**
+     * tick (黑板 [558] B): the child's most recent tool intent as one human line ("Bash npm test",
+     * "Edit src/x.ts") — derived from the last `tool_start` on the child's stream, so a parent can show
+     * "what is it doing right now" with zero polling of the child. Absent until the child runs a tool.
+     */
+    currentAction?: string;
+    /** terminal: the child RUN's session id (uuid domain) when known. */
+    sessionId?: string;
+    /**
+     * terminal (黑板 [558] C): a handle to the child's persisted transcript — the child RUN's session id
+     * (uuid domain). A parent reads the last N steps on demand via the `AgentTranscript` tool (pull model:
+     * it does NOT inflate the parent's context). Mirror of {@link sessionId} for terminal events; named
+     * distinctly so a consumer keys "how do I read this child's history" without conflating it with routing.
+     */
+    transcriptId?: string;
+    /**
+     * terminal (黑板 [558] A): the child's last ≤10 completed tool steps ({tool, target, outcome}) — the
+     * residual a parent needs to write a PRECISE resume prompt ("you stopped at file X, step Y") for a
+     * child that was stopped/killed mid-flight, WITHOUT reading the transcript. Bounded; absent if the
+     * child ran no tools.
+     */
+    recentSteps?: import("../agents/subagent-steps.js").SubagentStep[];
+    /**
+     * terminal (黑板 [558] D — core half): files the child mutated (Write/Edit/MultiEdit/NotebookEdit)
+     * with edit counts. The LSP-aggregated `<new-diagnostics>` projection is the shell's half; core
+     * supplies only the edited-file list. Bounded; absent if the child edited nothing.
+     */
+    editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
+    /**
+     * terminal (黑板 [558] E): `true` when the child can be revived with `SendMessage` (its session is
+     * retained and it was not stopped by the user); `false` for a user-stopped / non-resumable child.
+     * Lets a parent's orchestration logic decide "continue it" vs "start fresh" without trial-and-error.
+     */
+    resumable?: boolean;
+    /** terminal: the settled status. */
+    status?: "completed" | "killed" | "failed";
+    /** terminal, killed only (design/134 §3.3): who stopped it. MIRROR of task-registry `StopSource`
+     *  (the single source; inlined to avoid an import cycle — task-registry imports types.ts; third
+     *  mirror: task-notification.ts `TaskNotificationPayload.stoppedBy` — keep all three in sync).
+     *  OPEN ENUM: consumers must tolerate unknown values (a future "timeout" is not breaking). */
+    stoppedBy?: "user" | "parent" | "system" | (string & {});
+    /** terminal: bounded human summary (same text the task_notification carries). */
+    summary?: string;
+    /** tick: live rollup (`task_progress.usage`) · terminal: final `{tokens, turns, costMicroUsd}`. */
+    usage?: {
+        totalTokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+        tokens?: number;
+        turns?: number;
+        costMicroUsd?: number;
+    };
+}
+/**
+ * parity-204 — structured `RunnerDeps.loadProjectMemory` return (backward-compatible: a bare
+ * `string | null` keeps its exact historical meaning). Adds the CC 2.1.204 `seededFromContext`
+ * seam (cc204-bundle @17917159: CC preloads readFileState for CLAUDE.md/nested-memory files it
+ * placed in context, and a DEFAULT whole-file Read of an unchanged seeded file answers with the
+ * already-in-context reminder instead of re-transmitting the body — token economy, GA in 204).
+ */
+export interface ProjectMemoryLoad {
+    /** The project-context text to inject — same semantics as returning a bare string (null/blank ⇒ no injection). */
+    content: string | null;
+    /**
+     * Files whose FULL, disk-verbatim text the deployment has placed in the model's context (e.g. the
+     * CLAUDE.md that `content` embeds). The Runner pre-seeds the hands' read state (through the same
+     * resolveKey containment as a real Read — an out-of-root path is silently skipped), so a default
+     * whole-file Read of an UNCHANGED seeded file returns the CC-verbatim reminder
+     * (`This file is already in your context (see "Contents of <path>" above) and has not changed on
+     * disk…`) instead of the body. `content` here MUST be the file's exact disk text at load time —
+     * the unchanged check hashes it; never declare a truncated/annotated variant (CC's `isPartialView`
+     * exemption). A file that later changes on disk always reads normally (hash mismatch bypasses the
+     * dedup and disarms it). Requires hands (an executionEnv); ignored on a hands-less task.
+     */
+    seededFiles?: ReadonlyArray<{
+        path: string;
+        content: string;
+    }>;
+}
+/** Runtime dependencies shared across tasks. */
+export interface RunnerDeps {
+    brain: Brain;
+    /** Catalog used to resolve string ModelRefs to Model objects. */
+    models?: Record<string, Model>;
+    /**
+     * 模型档位绑定(clay 拍 2026-07-11):sema 档位词(`max`/`pro`/`flash`/`lite`,`ultra` 预留)→ 具体模型
+     * (catalog 名或 Model)。Runner 构造时经 `expandTiers` 增广进 catalog,使档位词与 CC alias
+     * (`fable`/`mythos`/`opus`/`sonnet`/`haiku`,内置固定映射)在全部模型寻址面直接可用(TaskSpec.model /
+     * roles / Agent 工具 model / workflow agent() / `@model` mention)。无绑定档沿 DEFAULT_TIER_ORDER 降档;
+     * 与部署 catalog 同名键时 catalog WINS(SHADOW)。center 经配置域下发/覆写此表。
+     */
+    tiers?: Record<string, ModelRef>;
+    /**
+     * F4 agentType 注册表(2026-07-11):部署声明的 {@link AgentDefinition} 集,workflow `agent(…,{agentType})`
+     * 经此解析(内置 Explore/Plan 之上 SHADOW)。design/141 件A:Agent 工具 lane(`createSubagentTool`)未显式
+     * 传 `agents` 时经 `Runner.agentCatalog` 自动取此表——同一 Runner 两 lane 单源;显式传参仍 WINS。
+     */
+    agents?: AgentDefinition[];
+    /** `false` 从 workflow agentType 注册表移除内置 Explore/Plan(镜像 createSubagentTool 同名开关)。 */
+    builtinAgents?: boolean;
+    /**
+     * design/141 件2 — hands 工具带(Read/Write/Edit/Bash…)的部署方窄配置面。刻意不导出
+     * `createHandsToolkit` 整厂(部署自装配塞 `spec.tools` 会被 Runner 的自动装配同名覆盖=反模式;
+     * CC 亦无 options-bag 开放面,走单例+hook)。只开放安全子集,Runner 装配时合成:
+     * - `beforeWrite` 与引擎的 MemoryEngine 写扫描门 **COMPOSE 而非替换**(部署 hook 先判,拒即拒;
+     *   放行后引擎门仍全量生效——写保护不可能被部署配置绕过)。
+     * Runner 私有编排字段(taskRegistry/detachHub/execClamp/cwdRef/…)不在此面,永不开放。
+     */
+    hands?: HandsBandOptions;
+    /**
+     * design/96 §20 (P1a) — DEPLOYMENT-DECLARED training knowledge cutoff per model id (e.g.
+     * `{ "qwen-3.5-35b": "2025-01", "deepseek-pro": "2024-07" }`). When the resolved model id is present, the
+     * `# Environment` block shows `Knowledge cutoff: <value>` so the agent reasons about what it may not know.
+     * Deployment-owned ON PURPOSE: core hardcodes no model→date map (a stale cutoff = a §25 honesty breach, and
+     * the model catalog is a deployment/profile concern). Omitted ⇒ no cutoff line (honest absence). Optional.
+     */
+    modelKnowledgeCutoffs?: Record<string, string>;
+    /**
+     * Default model roles: declare your models once and let every subsystem (main task, compaction,
+     * subagent, team) resolve its role instead of repeating a model name. `TaskSpec.roles` overrides
+     * per task/scenario. e.g. `{ default: "strong", summarize: "cheap", subagent: "cheap" }`.
+     */
+    roles?: ModelRoles;
+    /**
+     * Session lifecycle/persistence backend. Defaults to `TtlSessionStore` (in-memory, 7-day idle TTL
+     * — lost on restart). For **durable** sessions (a "session center" that survives restarts and is
+     * shared across stateless replicas), supply a `TtlSessionStore` over a durable `SessionRepo`
+     * (e.g. TiDB-backed), or a fully custom `SessionStore`. See `design/10-会话持久化与会话中心.md`.
+     */
+    sessionStore?: import("./session.js").SessionStore;
+    /**
+     * Durable-checkpoint backend for suspend/resume (design/45). A task with `durableApproval` set
+     * persists its awaiting-human checkpoints here and ends `status:"suspended"`; `runner.resume()` reads
+     * them back — cross-replica when this is durable (service's approval/run-store). A task's own
+     * `checkpointStore` overrides this. Omitted → no durable suspension (policy `ask` stays synchronous).
+     */
+    checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
+    /**
+     * design/101 §E19 — working-tree snapshot backend for {@link TaskSpec.rewindFiles}. A task with
+     * `rewindFiles` captures a snapshot per completed turn (keyed by the leaf `SessionTreeEntry.id`) and, when it
+     * also branches via {@link TaskSpec.resumeAt}, restores the snapshot for that entry. Omitted ⇒ rewind is OFF
+     * (no snapshot/restore work). The default reference impl is {@link InMemoryFileSnapshotStore}; a deployment
+     * supplies a durable / git / VM-snapshot backend behind the same seam (v1 restore is LOCAL-only).
+     */
+    fileSnapshotStore?: import("./file-snapshot-store.js").FileSnapshotStore;
+    /**
+     * design/99 §E6 — DURABLE per-session permission rules (a deny-narrowing folded into the task-time tool
+     * policy). Omitted ⇒ the feature is OFF (no rules read, zero behavior change). A deployment supplies a
+     * cross-replica backend whose CAS-rev + tighten-only semantics match the core
+     * {@link import("./session-policy-store.js").InMemorySessionPolicyStore}. Rules are read at prepare time for a
+     * task carrying its own `sessionId` (a delegated subagent inherits none) and composed BEFORE the caller
+     * policy, so they can only SUBTRACT capability. core does NOT verify owner/operator identity — the store
+     * honors the `operator` flag the (service) caller freezes from a verified principal.
+     */
+    sessionPolicyStore?: import("./session-policy-store.js").SessionPolicyStore;
+    /**
+     * design/99 §K (service [305]/center [318]) — resolve the **per-principal runtime ENTITLEMENTS** the engine
+     * ENFORCES server-side, keyed by `spec.principal`. A deployment (the SERVICE) implements it over center's
+     * `GET /api/config/effective?principal=` `runtimeCaps`. Resolved once at prepare time.
+     *
+     * 🔐 This is a TRUSTED deployment seam, NOT a caller-facing `TaskSpec` field: entitlements are purely
+     * server-governed — an untrusted caller must never be able to self-grant a capability. `undefined` (no
+     * resolver, or an unset cap) = NO per-principal restriction (TIGHTEN-ONLY: a cap can only ever DENY or
+     * FORCE; absence falls back to the deployment-level default). Symmetric with {@link sessionPolicyStore}.
+     *
+     * core enforces only the caps it CAN enforce in the engine: `allowWorkflows` (the third stage of the
+     * workflows gate — task opt-in ∧ deployment capability ∧ this) and `forceDurableGate` (forces a run onto
+     * the durable-approval path so a policy `ask` suspends to the wire). `allowUltracode` is a shell/UX concern
+     * (reasoning-tier, not a core primitive); `allowBypassPermissions` is enforced at the service settings-
+     * resolution layer (the engine sees only a resolved policy, never a "this allow came from bypass" signal).
+     */
+    runtimeCapsResolver?: (principal: string | undefined) => RuntimeCaps | undefined | Promise<RuntimeCaps | undefined>;
+    /**
+     * design/129-B(黑板 [444])— PROCESS-level observer for background delegation children (Agent/Fork
+     * `run_in_background`): `spawn` (at registry registration) / `tick` (every forwarded `task_progress`)
+     * / `terminal` (after the registry settle), for the child's WHOLE lifetime. Motivation: every per-leg
+     * sink (`RunInternals.onForwardEvent` etc.) carries the SPAWNING turn's lifecycle — correct for sync
+     * children, structurally wrong for a session-scoped background child that outlives the turn (the
+     * deployment rightly freezes per-leg publishers at leg settle, which silences the child). This seam is
+     * keyed to nothing but the process: wire it once at Runner construction and publish fleet rows /
+     * completion pushes from it. Observability only — a throwing observer is swallowed, never faults a run.
+     */
+    onBackgroundChildEvent?: (event: BackgroundChildEvent) => void;
+    /**
+     * design/98 (S8) — the HARD sandbox seam for LLM-AUTHORED workflow scripts (`TaskSpec.selfOrchestration`).
+     * A deployment supplies an isolated-vm / separate-process runner whose `safeForUntrustedScripts === true`;
+     * core does NOT ship one (the Node `vm` dev runner is NOT a security boundary). With this unset (or
+     * `safeForUntrustedScripts:false`), `selfOrchestration` is FAIL-CLOSED: the `run_workflow` tool is not
+     * mounted and the orchestration prompt is not injected. See {@link WorkflowGovernanceBaseline}.
+     */
+    workflowScriptRunner?: import("../orchestration/workflow-script-runner.js").WorkflowScriptRunner;
+    /**
+     * design/98 §2.5 (S8b) — the deployment-trusted governance every workflow-spawned sub-agent inherits
+     * (tighten-only). REQUIRED (alongside a hard `workflowScriptRunner`) for `selfOrchestration` to activate:
+     * unset ⇒ FAIL-CLOSED (the `run_workflow` tool is not mounted — a script-spawned agent must never run
+     * without a governed baseline). See {@link WorkflowGovernanceBaseline}.
+     */
+    workflowGovernanceBaseline?: WorkflowGovernanceBaseline;
+    /** design/98 §D.6 (S8c) — deployment hard CEILINGS for an LLM-authored workflow (script length / agent
+     *  count / timeouts / per-child cost+token caps / budget / result+log size). Defaults bound a runaway. */
+    workflowLimits?: import("../orchestration/run-workflow-tool.js").WorkflowLimits;
+    /** design/98 §D.5 (S8c) — re-invoke seam: called once when an LLM-authored workflow completes, with a
+     *  redacted, bounded summary. Unset ⇒ the run still completes + is queryable; the originator just isn't
+     *  pushed a notification. */
+    workflowCompletionNotifier?: import("../orchestration/run-workflow-tool.js").WorkflowCompletionNotifier;
+    /** design/97 S1b / design/98 §D.5 — persist LLM-authored workflow runs here for cross-replica `/workflows`
+     *  history (opt-in; in-process runs are still subscribable without it). */
+    workflowRunStore?: import("./workflow-run-store.js").WorkflowRunStore;
+    /** design/97 CORE-9 (Part A) — the LOAD-BEARING resume journal for LLM-authored (`run_workflow` tool) workflows
+     *  (the twin of `workflowRunStore`; service ships a durable Postgres/TiDB one). Wired into the auto-mounted
+     *  run_workflow tool so a tool-launched workflow can durably RESUME across a replica crash. Opt-in. */
+    workflowJournalStore?: import("./workflow-journal-store.js").WorkflowJournalStore;
+    /** B5/F2 + design/140 §6 1a — the script-persistence / named-registry seam, threaded into the auto-mounted
+     *  run_workflow tool: every invocation's resolved script is persisted (iterate via `{scriptPath}`), `{name}`
+     *  resolves a saved workflow, and a registration's `defaultArgs` merge under the call-time args. Opt-in
+     *  (absent ⇒ inline `script` + built-in names only). */
+    workflowScriptStore?: import("../orchestration/workflow-script-store.js").WorkflowScriptStore;
+    /** design/140 §6 1c — `false` removes the BUILT-IN named workflows (`team-discussion`, …) from the
+     *  auto-mounted run_workflow tool (the `builtinAgents:false` analog; default ON). A deployment
+     *  `workflowScriptStore` registration of the same name shadows a built-in regardless. */
+    builtinWorkflows?: boolean;
+    /**
+     * design/97 CORE-9 (Part B) — a TRUSTED deployment sink for the steerable handle of every agent an LLM-authored
+     * (`run_workflow` tool) workflow spawns. When set, the tool's `agent()` primitive runs each agent STEERABLE and
+     * emits its {@link import("../orchestration/workflow.js").WorkflowAgentHandle} here (the script never receives
+     * the handle — no host-context leak into the runner); the deployment registers it by `runId`+`label` to route a
+     * human/cross-replica steer to `handle.steer(...)`. Unset ⇒ agents run non-steerable (no overhead). Opt-in.
+     *
+     * **Interaction with {@link workflowJournalStore} (audit note)**: a steerable agent runs via `agentStream`,
+     * which is NOT journaled (a finished result can't be steered). So with BOTH set, a steerable workflow's
+     * `resumeFromRunId` finds an empty journal and re-runs all agents LIVE — correct, but with no caching benefit
+     * (durable resume re-executes rather than skips). Journal-able steerable agents are a follow-on.
+     */
+    onWorkflowAgentSpawn?: (handle: import("../orchestration/workflow.js").WorkflowAgentHandle) => void;
+    /** design/72 §2.2 (B): deployment default for the suspend-loop cap (see `TaskSpec.maxSuspends`).
+     *  Default 5 (loose — human-approval flows re-suspend rarely). A task's own `maxSuspends` overrides. */
+    maxSuspends?: number;
+    /**
+     * design/91: injectable wall-clock source for **human-review timing** (and `Checkpoint.suspendedAt`).
+     * Defaults to `Date.now`. The Runner reads EVERY human-time timestamp through this — the synchronous
+     * `resolveAsk` wait (`t1 − t0`), the durable suspend's `suspendedAt`, and the resume's derived human
+     * latency (`now() − suspendedAt`) — so a test can inject a controllable clock (`let t = 0; now = () => t`)
+     * and assert `stats.humanReview` deterministically (design/87 §4.3 flaky-guard: no bare `Date.now()` in a
+     * hard-gate test). **Scope = human-time only**: this is NOT a general clock for token/cost/turn accounting
+     * (those keep `Date.now`); `humanReview` is a budget-EXCLUDED side observable, never folded into cost. */
+    now?: () => number;
+    /** @deprecated design/138 S4 (BREAKING) — the legacy MemoryStore runner path is RETIRED: with this set,
+     *  the Runner mounts NO remember/recall tools, injects NO `<user_memory>` block, and runs NO legacy
+     *  consolidation/selective/dynamic recall — it only emits a one-shot deprecation warning per prepared
+     *  task (`onError`, phase `"config"`). Migrate to {@link memoryBackend} (the injection-first memory
+     *  engine). The TYPE and the store implementations (InMemory/File/Pg) remain exported — a FileBackend
+     *  等 store 仍可独立使用; this dep just no longer drives the runner. Field removal is the next major. */
+    memoryStore?: import("./memory.js").MemoryStore;
+    /**
+     * design/138 S1 — the NEW-ARCHITECTURE memory seam (MemoryEngine over a {@link import("./memory-engine/types.js").MemoryBackend}).
+     * When set AND `spec.memory.enabled`, the task runs the INJECTION-FIRST file-based memory lifecycle
+     * (materialize → session file ops → harvest with the full gate set), the CC-verbatim `# Memory`
+     * instruction + fenced derived index replace the legacy `<user_memory>` block, and NO remember/recall
+     * tools are mounted (memory = the model's ordinary file skills). **S4 (codex 1.258 F6 doc fix): unset ⇒
+     * the task runs MEMORY-LESS** — the legacy `memoryStore` runtime path was retired (one deprecation
+     * warning via `onError` phase `"config"`); this field is the ONLY live memory seam.
+     */
+    memoryBackend?: import("./memory-engine/types.js").MemoryBackend;
+    /**
+     * design/138 §2.7 — the memory-engine directory CONFIG ROOT used when {@link memoryBackend} does not
+     * pin its own directory (a {@link import("./memory-engine/file-backend.js").FileMemoryEngineBackend}
+     * exposes `directoryRoot` and wins). The per-repo memory dir derives as `<root>/<repoKey>/memory`
+     * (repoKey = CC-style slug of the task root). Default: `AGENT_DATA_DIR` env or `~/.ai-agent`.
+     * Location is PURE CONFIG (§2.7 r2.1): a deployment may equally construct the FileBackend over an
+     * IN-REPO git-tracked directory for a project scope.
+     */
+    memoryEngineDir?: string;
+    /**
+     * design/138 S2-B (O-F7/C-F3) — the Runner-owned harvest-report sink. Both harvest boundaries
+     * (the checkpoint mint inside commitSuspendSaga, `phase: "checkpoint"`, and the task terminal in
+     * runtask, `phase: "terminal"`) deliver their {@link import("./memory-engine/types.js").HarvestReport}
+     * here instead of dropping it — trace/accounting/alerting is the deployment's call. Swallow-guarded:
+     * a throwing consumer never fails the boundary. (The model-facing announcement lane is separate:
+     * the engine enqueues gate events at its harvest tail; the NEXT session's first injection drains
+     * them — 时机①.) Optional; unset ⇒ no behavior change beyond the report no longer being discarded.
+     */
+    onMemoryHarvestReport?: (report: import("./memory-engine/types.js").HarvestReport, info: {
+        sessionId: string;
+        phase: "checkpoint" | "terminal";
+    }) => void;
+    /**
+     * design/113 C4 — proactive project startup. The Runner calls this once during `prepareTask` (every prepare,
+     * incl. durable resume — design/113 §4 H8) and injects the returned text as a READ-ONLY, FENCED, virtual
+     * `"project"` memory layer at the TAIL (so the agent "sees" what project it is in from turn 1, like CC's
+     * CLAUDE.md/git injection — the cure for "say hi → only greets"). The deployment/profile owns the CONTENT
+     * (read CLAUDE.md / `.claude/` + fold in `git log -5`/status + a byte budget); core owns the seam + fence +
+     * cache placement and NEVER hardcodes a filename (same trust posture as {@link executionEnvFactory}/
+     * {@link promptProvider}/{@link modelKnowledgeCutoffs}). A RunnerDeps FUNCTION, not a `TaskSpec` field: it is
+     * unserializable (durable resume) and reading files for an UNTRUSTED caller would be a confused-deputy hole
+     * (design/44 §7 Q4). DECOUPLED from `memoryStore` — injects even with NO long-term memory configured (H5).
+     *
+     * `undefined` (default) ⇒ the whole path is skipped = byte-identical to today (full parity, H3). Returning
+     * `null`/blank ⇒ no injection (also byte-identical). The content is fenced/sanitized like every other memory
+     * layer (repo-controlled CLAUDE.md is UNTRUSTED data, not an instruction — H2). The ctx lets a profile tailor
+     * or suppress: `handsEnabled:false` = a hands-less chat with no real project (return null); `isSubagent` =
+     * a delegated child (a profile may trim CLAUDE.md for a cheap "grep this" subagent — H7).
+     */
+    loadProjectMemory?: (ctx: {
+        /** The task's working directory (= the execution env's cwd; a worktree task = its worktree root). */
+        cwd: string;
+        /** False ⇒ a hands-less chat (no real filesystem/project) — a profile typically returns null. */
+        handsEnabled: boolean;
+        /** True ⇒ a delegated subagent run (a profile may trim/suppress project content to control cost). */
+        isSubagent: boolean;
+        /** The subagent's type name, when `isSubagent` — lets a profile tailor content per agent type. */
+        agentName?: string;
+    }) => Promise<string | null | ProjectMemoryLoad> | string | null | ProjectMemoryLoad;
+    /**
+     * design/77 §2 Gate-2: the profile-injected predicate that decides whether a promotable artifact's
+     * (opaque) outcome statistics clear the promotion bar. Core enforces the gate's *presence* (a promotable
+     * write needs a verdict); this predicate supplies the *positivity* definition (the taxonomy/threshold
+     * stays in the profile). **Unwired ⇒ promotable writes fail closed** (an absent gate never auto-passes).
+     */
+    utilityGate?: import("./memory.js").UtilityGate;
+    /**
+     * @deprecated design/138 S4 — legacy memory consolidation (design/41) rode the retired memoryStore path
+     * and no longer runs; ignored. (Engine-plane consolidation re-mount = design/138 §7, another稿.)
+     * Type kept one major; removal is the next major.
+     */
+    memoryConsolidation?: MemoryConsolidationConfig;
+    /**
+     * @deprecated design/138 S4 — selective recall (design/65 §2.2) served ONLY the retired legacy
+     * `<user_memory>` injection path; ignored. The memory engine injects a bounded derived index instead
+     * (MEMORY.md, CC parameters) and the model reads topic files on demand. Removal is the next major.
+     */
+    memoryRecall?: {
+        enabled?: boolean;
+        /** Memory size (bytes) above which selective recall activates. Default 8000. */
+        thresholdBytes?: number;
+        /** Override the side-query selector; default = main-brain sub-query. */
+        select?: import("./memory-recall.js").MemorySelector;
+        /** Model for the default selector (default = the task's model). */
+        selectorModel?: ModelRef;
+        /** Max notes the side-query may select (default 5). */
+        maxSelected?: number;
+        /** Max 1-hop `[[name]]` link-followed notes appended after the selected ones (design/65 P3).
+         *  `0` disables link-following. Default 3. */
+        maxLinked?: number;
+        /** Side-query hard timeout (ms, default 5000). */
+        timeoutMs?: number;
+    };
+    /** Override system-prompt assembly. Defaults to `defaultPromptProvider`. */
+    promptProvider?: import("../prompts/default.js").PromptProvider;
+    /**
+     * design/99 §E23 — the LIVE-ONLY inbound-elicitation seam (an MCP server asking the END USER for input
+     * mid-tool-call). Wired ONLY for servers that opted in via {@link McpServerSpec.elicitation}; absent ⇒ core
+     * advertises no elicitation capability (fail-closed). The deployment answers synchronously (e.g. prompts the
+     * terminal user); core replies to the server on the open connection.
+     */
+    onElicit?: OnElicit;
+    /**
+     * design/116 CONFIRM-1 (clay 拍 加 seam 保体验): resize an over-limit MCP image so the model still SEES a
+     * degraded image instead of a spill-to-disk note. Absent ⇒ core auto-detects `sharp` (dynamic import;
+     * turnkey deployments with sharp installed get the CC experience with zero config) and otherwise spills.
+     */
+    mcpImageResizer?: import("./mcp.js").McpImageResizer;
+    /** Default tool-call gate for all tasks (a task's own `toolPolicy` overrides this). */
+    toolPolicy?: import("./tool-policy.js").ToolPolicy;
+    /**
+     * How `ask` decisions resolve when a policy/hook requests human confirmation (design/37). Default
+     * (omitted) = `"deny"`: **headless auto-deny** — no approver, so `ask` resolves deterministically to
+     * deny with a model-readable reason (the safe default for stateless automation). `"allow"` to
+     * auto-approve, or a fail-closed approver function. A task's own `onAsk` overrides this.
+     */
+    onAsk?: import("./tool-policy.js").OnAsk;
+    /** Content-ask seam (design/64 §5): when set, every task mounts an AskUserQuestion tool that routes a
+     *  model-issued question to this callback (a real human/UI). Distinct from `onAsk` (permission). A task's
+     *  own `onQuestion` overrides this. Unset ⇒ the tool is not mounted (the model can't ask). */
+    onQuestion?: import("./ask-question.js").OnQuestion;
+    /** LSP code-intelligence seam (design/64 §13.1): when set, every task mounts an `lsp` tool routed to this
+     *  manager (a deployment-provided language-server bridge, e.g. an E2B LSP sidecar). The manager returns
+     *  `undefined` for a file whose language has no server, and the tool degrades to "fall back to grep". A
+     *  task's own `lspManager` overrides this. Unset ⇒ no `lsp` tool. */
+    lspManager?: import("./lsp.js").LspServerManager;
+    /**
+     * Default in-process hooks for all tasks (design/37): PreToolUse (rewrite/restrict args + inject
+     * context), PostToolUse (rewrite output + inject context), UserPromptSubmit (block/inject before the
+     * objective becomes a message). A task's own `hooks` overrides this. A PreToolUse hook's `allow`
+     * never bypasses `toolPolicy` — the policy is always the final say.
+     */
+    hooks?: import("./hooks.js").Hooks;
+    /**
+     * Policy for remote image URLs (`TaskSpec.images[].url`). Return false to reject. When set it
+     * **replaces** the built-in SSRF guard (https-only + private/reserved-host block) — e.g. supply a
+     * CDN allowlist, or a stricter resolve-and-pin check. Omit to use the safe default.
+     */
+    allowImageUrl?: (url: string) => boolean;
+    /**
+     * Optional sink for best-effort background errors/warnings that are otherwise swallowed:
+     * - `"compaction"` — a compaction failure (F8); a persistently failing one (flaky gateway, empty
+     *   summaries) is invisible without this and lets a session grow until it tops the window.
+     * - `"prompt-cache"` — a legacy `PromptProvider.system` assembled a cache-hostile prompt (volatile
+     *   memory not at the tail); the prefix cache will miss every turn. Log/alert on both.
+     * - `"prompt-constitution"` — a `stableSystem` provider returned an ALREADY-assembled prompt
+     *   (constitution anchor found); core passed it through un-doubled. Upgrade the provider to return
+     *   only the role base (or set `replaceAll: true` to own the whole base).
+     * - `"memory"` — a post-task memory-consolidation pass failed or skipped a malformed reconcile
+     *   decision (design/41). Best-effort: the notes the model saved are kept; the task still succeeds.
+     * - `"mcp"` — an MCP server failed to connect / list its tools and was skipped (fail-open, design/29);
+     *   the task runs with the remaining servers' tools. One call per failed server.
+     */
+    onError?: (err: unknown, context: {
+        phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
+        sessionId: string;
+        /**
+         * Machine-readable sub-classification when the phase has one — currently the design/31
+         * cache-break detector's root cause (`"model-switch" | "tool-schema" | "tool-set" |
+         * "system-prefix" | "server-or-ttl"`). Lets the host pick its own log level: `"server-or-ttl"`
+         * is usually benign in agentic tasks (slow tools ⇒ 5min+ request gaps expire provider caches —
+         * service[64] flag②) and warrants info/warn, while the prefix-bug causes warrant attention.
+         */
+        classification?: string;
+    }) => void;
+    /** Best-effort fire-and-forget trace sink (task/turn/brain/tool); `TaskSpec.tracer` overrides per task. */
+    tracer?: import("./trace.js").TracerHook;
+    /**
+     * design/73 §1 v1 — fire-and-forget sink for {@link import("./task-outcome.js").TaskOutcome} facts
+     * (the feedback ledger's core seam; tracer/onError posture — swallow-guarded, a throwing sink never
+     * affects the run). 🔴 Red lines: core emits ONLY the `mechanical` tier (objective-oracle results —
+     * llm_assisted/self-report never enter v1); every outcome carries `oracleHadRedRun`; ONE emission
+     * point — `runGoal`'s terminal state (goal `doneCheck` = the natural mechanical oracle) plus explicit
+     * `emitTaskOutcome` from harnesses that own a real oracle. Plain `runTask` never auto-emits (no
+     * objective oracle → no fact). core emits facts only; aggregation/policy live in the service ledger.
+     */
+    onTaskOutcome?: (outcome: import("./task-outcome.js").TaskOutcome) => void;
+    /** Per-model pricing (per-1M absolute USD) keyed by model id; falls back to each `Model.cost`. */
+    pricing?: Record<string, import("./pricing.js").ModelPricing>;
+    /**
+     * The execution environment the agent's "hand" acts on (design/44) — file system + shell. Default:
+     * `StubExecutionEnv` (no real I/O, current behavior). Inject `NodeExecutionEnv` for local fs/shell, or
+     * a sandboxed/remote impl for multi-tenant isolation. **Injecting a non-stub env is the opt-in** that
+     * activates the file tool band. ⚠️ A bare `NodeExecutionEnv` is unsandboxed — a multi-tenant deployment
+     * MUST inject a chroot/container/per-principal-scoped impl; do not expose raw `NodeExecutionEnv`.
+     */
+    executionEnv?: import("../internal/harness.js").ExecutionEnv;
+    /**
+     * design/48 remote seam — a **trusted control-plane** factory that mints a FRESH execution env per
+     * task (e.g. one isolated container per task in the remote model). Called once at task start; the env
+     * it returns is owned by that task and released on task end. **Wins over** the shared static
+     * `executionEnv`. Injecting it also activates the hand tool band (design/44), exactly like
+     * `executionEnv`. This is the ONLY per-task env injection point — `TaskSpec` deliberately has no
+     * `executionEnv`, so an untrusted caller can't swap the sandbox (design/44 §7 Q4); the trusted
+     * deployment wires the factory.
+     */
+    executionEnvFactory?: import("./remote-env.js").ExecutionEnvFactory;
+    /**
+     * design/77 §1 Gate-1 (oracleIsolation) — a **DISTINCT** trusted control-plane factory that mints the
+     * ISOLATED grader env an out-of-process oracle grades in (the 4th auto-promote gate). It is a SIBLING of
+     * {@link executionEnvFactory}, never the same env: the worker runs in `executionEnvFactory`'s env, the
+     * grader in `graderEnvFactory`'s — so a worker can't corrupt the env that judges it. It inherits the exact
+     * same trust contract: `TaskSpec` deliberately has NO env field (design/44 §7 Q4), so an untrusted caller
+     * can never inject/swap a grader env and grade itself; only the trusted deployment wires this factory. The
+     * env it mints is wrapped in a {@link import("./oracle-isolation.js").GraderEnv} (with the control-plane
+     * `provenance` brand) at the call site, and asserted via
+     * {@link import("./oracle-isolation.js").assertOracleIsolation} before any positive oracle verdict.
+     * **Auto-promote stays mandate-OFF until the four gates are implemented + verified end-to-end** (design/77
+     * §7); this seam only makes auto-accept implementable — it does not turn it on.
+     */
+    graderEnvFactory?: import("./remote-env.js").ExecutionEnvFactory;
+    /**
+     * Containment root for the file tools (design/44 §4 invariant 7): every path must resolve within it,
+     * else the tool rejects (`PathNotInRoot`). Default `process.cwd()`. A defense-in-depth guard rail at the
+     * tool layer — NOT a sandbox (it does not constrain `bash`; that needs OS-level containment) and not a
+     * substitute for an isolated `executionEnv`.
+     */
+    rootPath?: string;
+    /**
+     * Backing store for offloaded large tool results (design/30). Default: a task-scoped
+     * `InMemoryToolResultStore` (no cross-wake durability). Inject a durable store (keyed by ref) so an
+     * offloaded result survives wake/resume.
+     */
+    toolResultStore?: import("./tool-result-store.js").ToolResultStore;
+    /**
+     * Offload a tool result to the store + leave a preview when its text exceeds this many chars. Default
+     * ~20000; set `0` or `Infinity` to disable offloading. Per-tool override via `ToolSpec.offloadThresholdChars`.
+     */
+    toolResultThresholdChars?: number;
+    /**
+     * Two-phase prefix-cache-break detection (design/31): per turn, fingerprint the prefix and, on a
+     * confirmed `cacheRead` drop, emit a root-cause finding via `onError(phase:"prompt-cache")`. Cheap
+     * (hashes only) and only fires on a detected break. Default **on**; set `false` to disable.
+     */
+    cacheBreakDetection?: boolean;
+    /**
+     * Aggregate inline-MEDIA (image) byte budget for the request (batch-C/§17.2 sibling of the text budget;
+     * CC 2.1.196 `tengu_media_byte_cap` parity). Image reads (`Read` → ImageContent) are per-image-capped but
+     * accumulate across turns; this bounds the SUM in the request by stripping the OLDEST images (replaced with a
+     * marker) — request-only, non-destructive (the durable session keeps the image; the model can re-Read it).
+     * Default {@link AGGREGATE_MEDIA_BUDGET_BYTES}; set `Infinity`/`0` to disable.
+     */
+    mediaByteCapBytes?: number;
+    /** Optional telemetry fired when {@link mediaByteCapBytes} strips media in a request (CC's
+     *  `tengu_media_byte_cap_stripped` fields). Pure observability — no effect on the request. */
+    onMediaStripped?: (info: {
+        totalBytes: number;
+        limitBytes: number;
+        removedCount: number;
+        removedBytes: number;
+    }) => void;
+    /**
+     * Deferred-tool disclosure policy (design/36). Default (omitted): deterministic per-tool — only tools
+     * with `ToolSpec.defer === true` (and MCP tools, which default to deferred) are deferred, so the same
+     * `TaskSpec` always yields the same `tools[]`. `"auto"`: additionally auto-defer tools when the total
+     * inlined schema size would exceed a fraction of the model's context window. Auto is an explicit opt-in
+     * (council minor #6) because an implicit threshold makes `tools[]` depend on the model/context, which
+     * callers find hard to predict; explicit `defer` flags always win regardless of this setting.
+     */
+    deferMode?: "auto";
+    /**
+     * design/84 Seam C — compact-boundary COST optimization (data-gated, default OFF). A FUNCTION seam (a
+     * trusted control-plane injection), so it lives on `RunnerDeps` — NOT `TaskSpec`: `TaskSpec` is the
+     * serializable, untrusted-caller, durable-resume-round-trippable per-task config (a function can be
+     * neither serialized nor durably checkpointed, and the sandbox/env-class injections deliberately sit on
+     * `RunnerDeps` for the same trust reason). Same placement as `memoryRecall.select` / `promptProvider` /
+     * `executionEnvFactory`.
+     *
+     * When `summaryProvider` is set, BOTH compaction call sites (the within-task turn boundary AND `finish()`
+     * at task end) consult it: a NON-EMPTY string is reused verbatim (the real `generateSummary` LLM call is
+     * skipped); `null`/`undefined`/blank falls back to the existing LLM path (byte-identical to today).
+     * `onCompaction` is a pure post-compaction observer. `maxConsecutiveProviderReuse` (default 3, CC parity)
+     * forces a real summary after N consecutive reuses to bound drift; the Runner OWNS the consecutive-reuse
+     * counter across both call sites for the task (reset on a real summary, incremented on a reused one), so
+     * the caller does not have to thread it back. **Absent (default) ⇒ no behavior change whatsoever.**
+     *
+     * SCOPE (design/141 examples 批实测): the seam covers the whole-turn compaction sites only. A
+     * SPLIT-TURN cut point (mid-turn prefix summarization — the common shape inside a long single-user-
+     * message tool loop) bypasses the provider by design (A2 algorithm sovereignty): the turn-prefix
+     * summary is engine-owned. Deployments needing a clean provider-visible boundary should shape work
+     * as separate tasks sharing `sessionId`.
+     */
+    summaryProvider?: import("./auto-compaction.js").MaybeCompactOptions["summaryProvider"];
+    /** design/84 Seam C — pure post-compaction observer (fires only on a real compaction, never a no-op).
+     *  Consumed ONLY when `summaryProvider` is also set (the Seam C options early-return otherwise) — a
+     *  pure-observer deployment passes a provider that always returns `null` (keeps the LLM path intact). */
+    onCompaction?: import("./auto-compaction.js").MaybeCompactOptions["onCompaction"];
+    /** design/84 Seam C — force a real `generateSummary` after this many consecutive provider reuses (default
+     *  3, CC parity). The Runner tracks the consecutive-reuse counter per task across both compaction sites. */
+    maxConsecutiveProviderReuse?: number;
+    /**
+     * design/86 §3 缺口 A — DYNAMIC memory re-recall (CC `processSessionStartHooks('compact')` parity),
+     * **opt-in & default OFF** (data-gated, like Seam C `summaryProvider`). Absent/`enabled:false` ⇒ NO behavior
+     * change whatsoever: memory is the one-shot snapshot taken at task start (the stable prefix), exactly as today.
+     *
+     * When enabled, AFTER each REAL within-task compaction the Runner re-runs the EXISTING memory selector against
+     * the CURRENT conversation (the most-recent messages), de-dups against everything already surfaced (the same
+     * `priorSurfacedIds`/`priorSurfacedKeys` machinery the initial recall uses, seeded from the initial recall),
+     * and injects any NEW relevant notes as a TAIL attachment user message (`harness.steer` → next request's tail).
+     * It NEVER touches the stable system prefix (the prefix-cache the whole design rests on) and NEVER re-injects
+     * an already-shown note. It needs a selective-capable store (`listStructuredNotes`/`getByIds`) + a selector
+     * (the `memoryRecall.select` override, else the default brain sub-query); on selector failure/timeout it injects
+     * nothing (no inject-all fallback mid-task). A FUNCTION/observer seam, so it lives on `RunnerDeps`, NOT `TaskSpec`
+     * (the same trust placement as `memoryRecall.select` / `summaryProvider` / `executionEnvFactory`).
+     *
+     * Why compaction-triggered (not every turn): compaction is when fine detail is actually lost (the highest-value
+     * moment to reground, CC parity); firing only post-compaction also bounds the extra selector LLM call (whether
+     * the cost is worth it is a design/82 cost-per-truly-correct data-gated question — this is a THIN seam, no
+     * provider/policy beyond the trigger is built in).
+     *
+     * @deprecated design/138 S4 — the dynamic re-recall seam served ONLY the retired legacy memoryStore
+     * injection path; ignored (prepareTask never wires the seam state anymore). Removal is the next major.
+     */
+    dynamicRecall?: import("./dynamic-recall.js").DynamicRecallConfig;
+}
+export type { AgentTool, Model, StreamFn, ThinkingLevel };
+//# sourceMappingURL=types.d.ts.map