@sema-agent/core 5.19.0 → 5.21.0

package/dist/internal/harness-types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Pure-type re-exports split out of harness.ts (S1, design/157) — see harness.ts for the full
+ * design/33 + design/118 facade narrative. This file exists to break an engine-import SCC: consumers
+ * that only need harness types (not the NodeExecutionEnv value export) import from here instead, so
+ * their compile-time dependency graph never has to reach the value side of the facade.
+ */
 export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/compaction/compaction.js";
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";

package/dist/internal/harness.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Internal boundary to the engine's harness layer (design/33; de-vendored by design/118). Everything
+ * in `src/` (outside `src/internal/`) imports these symbols from HERE, never via a deep
+ * `../engine/...` path — one auditable coupling point (CI-guarded by test/vendor-insulation.test.ts).
+ * The vendored tree this facade used to front is fully retired (design/118 ⓪-⑤); the facade stays so
+ * consumers never notice which module a symbol lives in.
+ *
+ * Pure-type re-exports live in ./harness-types.js (S1, design/157) — split out to break an
+ * engine-import SCC for type-only consumers. Re-exported here too so existing `harness.js` imports
+ * keep working unchanged.
+ */
 export * from "./harness-types.js";
 export { AgentHarness } from "../engine/harness/agent-harness.js";
 export { CompactionError, ExecutionError, FileError, ok, err } from "../engine/harness/types.js";

package/dist/internal/llm.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Internal boundary to the llm layer (design/33). Everything in `src/` (outside `src/internal/`)
+ * imports these symbols from HERE, never via a deep path — one auditable coupling point (CI-guarded).
+ * design/118 ①②: the layer is now first-party (`src/engine/llm/`, naturalized out of the vendored
+ * llm-core); the facade stays so consumers never notice which side a symbol lives on.
+ */
 export { createAssistantMessageEventStream, snapshotActorAssertion, stripEngineMetadata } from "../engine/llm/index.js";
 export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";

package/dist/orchestration/builtin-workflows.d.ts

@@ -1,10 +1,63 @@
+/**
+ * design/140 §6 1c — BUILT-IN named workflows offered by the `Workflow` tool's `{name}` calling surface,
+ * mirroring the built-in agents precedent (src/agents/builtin-agents.ts: GA default-on, opt out via a
+ * deployment config flag, same-name deployment registration SHADOWS the built-in):
+ *  - `RunWorkflowToolDeps.builtinWorkflows: false` (threaded from `RunnerDeps.builtinWorkflows`) removes
+ *    them wholesale;
+ *  - a deployment `WorkflowScriptStore.resolveName` hit for the SAME NAME wins (the built-in is consulted
+ *    only when the deployment registry does not resolve the name).
+ *
+ * The first built-in is `team-discussion` — the round-based collab profile design/140 §1 verified live
+ * (docs/DESIGN-140-VERIFICATION-2026-07-11.md B 面: 2 members × 2 rounds + finalizer, 8.2s/10.5K tokens,
+ * round 2 genuinely responding to round 1). It is pure SCRIPT CONTENT over the existing primitives — zero
+ * new runtime mechanism:
+ *  - args schema (ALL optional — zero-config must run): `{ topic, members?: [{ role, prompt?, model? }],
+ *    rounds?, finalizer?: { prompt?, model? } }`; a bare STRING args is accepted as the topic.
+ *  - budget: reuses the workflow `budget` hard ceiling + DETERMINISTIC in-script truncation (a rounds/member
+ *    cap and a `budget.remaining()` early-stop — never an evaluator agent; design/140 §1 "预算" row).
+ *  - `meta.whenToUse` carries the REQUIRED negative boundary (when-NOT-to-use: single factual question /
+ *    budget-sensitive runs — design/140 §4 "两投影").
+ */
 import type { NamedWorkflowListing } from "./workflow-script-store.js";
+/** The built-in round-based team-discussion workflow's registered name. */
 export declare const TEAM_DISCUSSION_WORKFLOW_NAME = "team-discussion";
+/**
+ * The `team-discussion` script source (design/140 §1 table row 1, live-verified shape: for-loop rounds +
+ * `agent()` members with transcript re-feed + a schema'd finalizer). Deterministic by construction — no
+ * clock/randomness reads (locked by test against `workflowScriptReadsClockOrRandom`).
+ */
 export declare const TEAM_DISCUSSION_SCRIPT = "export const meta = {\n  name: \"team-discussion\",\n  description: \"Round-based team discussion: configurable members debate a topic across rounds (each member sees the transcript so far), then a finalizer synthesizes a structured verdict.\",\n  whenToUse: \"Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }. Hard ceilings: members is capped at 6 and rounds is capped at 5 regardless of what you pass; the run reports it via log() and a capped field on the result when a request exceeds either.\",\n  phases: [\n    { title: \"Discussion\" },\n    { title: \"Synthesis\" },\n  ],\n};\n// Zero-config runnable (design/140 \u00A76 1c): every arg has an opinionated fallback.\nconst raw = args;\nconst a = raw !== null && typeof raw === \"object\" && !Array.isArray(raw) ? raw : {};\nconst topic =\n  typeof a.topic === \"string\" && a.topic.trim() !== \"\"\n    ? a.topic\n    : typeof raw === \"string\" && raw.trim() !== \"\"\n      ? raw // ergonomic form: a bare string args IS the topic\n      : \"No topic was provided. Discuss: what information should a caller supply to make a team discussion like this productive, and when should they NOT convene one?\";\nconst defaultMembers = [\n  { role: \"advocate\", prompt: \"Make the strongest constructive case. Propose concrete options and argue their benefits with specifics.\" },\n  { role: \"skeptic\", prompt: \"Stress-test every claim made so far. Surface risks, hidden costs, failure modes, and cheaper alternatives.\" },\n];\nconst rawMembers = Array.isArray(a.members) && a.members.length > 0 ? a.members : defaultMembers;\nconst members = rawMembers.slice(0, 6).map((m, i) => {\n  const mm = m !== null && typeof m === \"object\" ? m : {};\n  const member = {\n    role: typeof mm.role === \"string\" && mm.role.trim() !== \"\" ? mm.role : \"member-\" + (i + 1),\n    prompt: typeof mm.prompt === \"string\" && mm.prompt.trim() !== \"\" ? mm.prompt : \"Contribute your own distinct perspective: be concrete, give reasons, and engage with what others said.\",\n  };\n  if (typeof mm.model === \"string\" && mm.model.trim() !== \"\") member.model = mm.model;\n  // Slot-tools carrier (design/140 \u2461-3 + F4): a member may BE a registered agent type ({agent:\"reviewer\"}) \u2014\n  // persona/tools/model then come from the deployment's AgentDefinition (role library), args stay thin.\n  if (typeof mm.agent === \"string\" && mm.agent.trim() !== \"\") member.agent = mm.agent;\n  return member;\n});\n// Deterministic budget truncation (design/140 \u00A71 \u9884\u7B97 row): a HARD rounds ceiling + member cap \u2014 never an\n// evaluator agent. The engine's budget/maxAgents hard stops remain the backstop.\nconst requestedRounds = Math.floor(Number(a.rounds));\nconst normalizedRounds = Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2;\nconst rounds = Math.min(normalizedRounds, 5);\n// RB-380 disclosure: the member/round slices above are silent by construction (Array.prototype.slice /\n// Math.min just drop the excess) \u2014 record + surface it instead of a caller finding out only by counting\n// transcript entries. Fires only when a request actually exceeded a ceiling (never on the common path).\nconst capNotes = [];\nif (rawMembers.length > 6) capNotes.push(\"requested \" + rawMembers.length + \" members, capped at 6\");\nif (normalizedRounds > 5) capNotes.push(\"requested \" + normalizedRounds + \" rounds, capped at 5\");\nfor (const note of capNotes) log(\"team-discussion: \" + note);\nconst fin = a.finalizer !== null && typeof a.finalizer === \"object\" && !Array.isArray(a.finalizer) ? a.finalizer : {};\nconst finalizerPrompt = typeof fin.prompt === \"string\" && fin.prompt.trim() !== \"\"\n  ? fin.prompt\n  : \"You are the synthesis lead. Read the full discussion transcript and produce the final verdict: the decision/answer, the key supporting points, and the strongest unresolved dissent (if any). Do not introduce new arguments of your own.\";\nconst clip = (s) => { const t = String(s); return t.length > 4000 ? t.slice(0, 4000) + \" ...[truncated]\" : t; };\nconst isBudgetStop = (e) => e !== null && typeof e === \"object\" && e.code === \"workflow.budget_exceeded\";\n\nphase(\"Discussion\");\nconst transcript = [];\nlet truncated = null;\nfor (let r = 1; r <= rounds && truncated === null; r++) {\n  // Deterministic early stop on an exhausted budget (a live read of the engine budget; the engine's\n  // hard WorkflowBudgetExceededError remains the backstop if a member call itself crosses the line).\n  if (budget.total !== null && budget.remaining() <= 0) { truncated = \"budget exhausted before round \" + r; break; }\n  for (const m of members) {\n    const history = transcript.length === 0 ? \"(none yet - you open the discussion)\" : transcript.join(\"\\n\\n\");\n    const spec = {\n      objective:\n        \"Team discussion on: \" + topic + \"\\n\\n\" +\n        'You are \"' + m.role + '\" in round ' + r + \" of \" + rounds + \".\\n\" +\n        \"Your brief: \" + m.prompt + \"\\n\\n\" +\n        \"Transcript so far:\\n\" + history + \"\\n\\n\" +\n        \"Respond to the strongest points others made (do not repeat yourself), then advance your own position. Be concise: a few tight paragraphs at most.\",\n    };\n    if (m.model !== undefined) spec.modelName = m.model;\n    let res;\n    try {\n      res = await agent(spec, m.agent !== undefined ? { label: m.role + \"-r\" + r, phase: \"Discussion\", agentType: m.agent } : { label: m.role + \"-r\" + r, phase: \"Discussion\" });\n    } catch (e) {\n      // The engine's budget hard stop: keep what the discussion already produced instead of failing the run.\n      if (isBudgetStop(e)) { truncated = \"budget exhausted at \" + m.role + \", round \" + r; break; }\n      throw e;\n    }\n    const text = res && res.status === \"completed\" ? clip(res.result) : \"(no contribution - agent ended \" + (res ? res.status : \"unknown\") + \")\";\n    transcript.push(m.role + \" (round \" + r + \"): \" + text);\n  }\n}\n\nphase(\"Synthesis\");\nconst finalSpec = {\n  objective:\n    finalizerPrompt + \"\\n\\nTopic: \" + topic + \"\\n\\nFull transcript:\\n\" +\n    (transcript.length === 0 ? \"(the discussion produced no contributions)\" : transcript.join(\"\\n\\n\")) +\n    (truncated ? \"\\n\\nNote: the discussion was cut short (\" + truncated + \").\" : \"\"),\n};\nif (typeof fin.model === \"string\" && fin.model.trim() !== \"\") finalSpec.modelName = fin.model;\nlet verdict = null;\ntry {\n  verdict = await agent(finalSpec, {\n    label: \"finalizer\",\n    phase: \"Synthesis\",\n    schema: {\n      type: \"object\",\n      properties: {\n        decision: { type: \"string\", description: \"The final answer/decision, one paragraph.\" },\n        keyPoints: { type: \"array\", items: { type: \"string\" }, description: \"The strongest supporting points from the discussion.\" },\n        dissent: { type: \"string\", description: \"The strongest unresolved counter-position, if any.\" },\n      },\n      required: [\"decision\", \"keyPoints\"],\n    },\n  });\n} catch (e) {\n  // Budget died before synthesis: return the transcript honestly rather than failing the whole run.\n  if (!isBudgetStop(e)) throw e;\n  truncated = truncated === null ? \"budget exhausted before synthesis\" : truncated;\n}\n\nreturn {\n  topic,\n  rounds,\n  members: members.map((m) => m.role),\n  ...(capNotes.length > 0 ? { capped: capNotes } : {}),\n  ...(truncated ? { truncated } : {}),\n  transcript,\n  verdict: verdict && verdict.structuredOutput !== undefined ? verdict.structuredOutput : (verdict ? verdict.result : null),\n};\n";
+/** One built-in named workflow: the registered name + its self-contained script source. The name is the
+ *  routing key of the `{name}` calling surface; the script's `meta.name` matches it (locked by test). */
 export interface BuiltinWorkflowDefinition {
     name: string;
     script: string;
 }
+/**
+ * The built-in named-workflow registry. Order = card listing order.
+ *
+ * RB-342 (2026-07-29): the previous note called this a "CC `HCe`-analog shape". `HCe` is not a workflow
+ * symbol in the 220 corpus at all (it is a memoized JSX local in a renderer, pretty220 885850+) — the name
+ * came from an older bundle and drifted, the standing hazard with minified identifiers. The real 220
+ * counterpart is the built-in workflow list behind `Rsn()` / `Dft()` (451216 / 454626), and the shape
+ * matches only PARTLY:
+ *
+ *  - **Registry, not literal.** 220's backing array is initialised EMPTY (`kSd = []`, 451221) and filled at
+ *    startup by feature-gated registrars (`DRo`, 451207 — two callers, `code-review` @496716 and
+ *    `deep-research` @497127, each behind its own enablement check); `Rsn()` additionally returns `[]`
+ *    wholesale when its gate is off. sema's list is a compile-time literal with no gating. Same role,
+ *    different lifecycle — do not read "CC ships these built-ins unconditionally" out of this function.
+ *  - **Shadowing holds; ordering does not transfer.** 220 resolves by concatenating
+ *    `[...builtins.filter(name not taken), ...userLevel, ...projectLevel]` (454641-454647): a
+ *    deployment-defined workflow of the same name REMOVES the built-in, which is the same net rule as
+ *    {@link resolveBuiltinWorkflow} being the second lookup. But 220 lists built-ins FIRST and enforces the
+ *    shadow by filtering, while sema enforces it by lookup order — so the listing order here is sema's own
+ *    choice, not a parity constraint.
+ */
 export declare function builtinWorkflowDefinitions(): BuiltinWorkflowDefinition[];
+/** Resolve a built-in workflow by name (the `{name}` surface's SECOND lookup — a deployment
+ *  `scriptStore.resolveName` hit for the same name shadows this, design/140 §6 1c). */
 export declare function resolveBuiltinWorkflow(name: string): BuiltinWorkflowDefinition | undefined;
+/** design/140 §6 1b — the built-ins' listing projection rows (name + description + whenToUse, parsed from
+ *  each script's static meta). Consumed by the Workflow tool card renderer. */
 export declare function builtinWorkflowListings(): NamedWorkflowListing[];

package/dist/orchestration/dev-vm-script-runner.d.ts

@@ -1,3 +1,22 @@
+/**
+ * design/98 §2.2 (S8b) — a `WorkflowScriptRunner` backed by Node's `vm`, for TRUSTED, DEVELOPER-authored
+ * workflow scripts ONLY.
+ *
+ * 🔴🔴 NOT A SECURITY BOUNDARY. Node `vm` does NOT isolate untrusted code: a script can reach the host realm
+ * through the prototype chain of ANY injected host object —
+ *   `agent.constructor.constructor("return process")()`
+ * yields the host `process` (the injected `agent` is a host function; its `.constructor.constructor` is the
+ * HOST `Function`, evaluated in the host realm where code-generation is unrestricted). The
+ * `codeGeneration:{strings:false}` below hardens the vm context's OWN eval/Function but CANNOT close that
+ * constructor-chain escape — see `test/workflow-vm-escape.test.ts`, which PROVES the escape so no one ever
+ * mistakes this for a sandbox.
+ *
+ * Therefore `safeForUntrustedScripts === false`: the S8 self-orchestration gate (design/98 §C) refuses to
+ * mount `run_workflow` with this runner. An LLM-authored script REQUIRES a runner whose
+ * `safeForUntrustedScripts === true` (isolated-vm / separate process + container), supplied by the deployment
+ * or a separate `@ai-only/workflow-sandbox` package. Core ships this dev runner + the conformance contract a
+ * hard runner must pass ({@link import("./workflow-sandbox-conformance.js").assertWorkflowSandboxConformance}).
+ */
 import type { WorkflowScriptRunner } from "./workflow-script-runner.js";
 export declare const WORKFLOW_DATE_ERR = "Date.now() / new Date() are unavailable in workflow scripts (breaks resume). Stamp results after the workflow returns, or pass timestamps via args.";
 export declare const WORKFLOW_RANDOM_ERR = "Math.random() is unavailable in workflow scripts (breaks resume). For N independent samples, include the index in the agent label or prompt.";

package/dist/orchestration/goal.d.ts

@@ -1,39 +1,96 @@
+/**
+ * design/96 §C (S2) — **Goal 模式**:LLM 自报完成 + core 校验续跑(CC goal 对标:目标 + 完成判定 + 续跑)。
+ * `runGoal` 是 `runRepairLoop`/`verifyCompleted` 的 SIBLING —— thin composition over `runner.runTask`,零
+ * Runner core 改动。详 `design/96-references/GOAL-IMPLEMENTER-SPEC.md`(v3,codex r1+r2 异源对抗收敛)。
+ *
+ * 🔴 **完成判定双闸(reward-hack 红线)**:① LLM 自报完成 = 调内置 `declare_done` 工具(或 `submit_output`,有
+ * outputSchema 时)= **机器信号**,非泛化 `completed`;② core `doneCheck`(机械/oracle 校验)。**AND**:仅二者
+ * 都满足才停 —— LLM 自报但 doneCheck 否决 → 续跑(把 reason 围栏喂回),这是防"模型说我完成了就算数"的核心。
+ *
+ * 🔴 **G1 脱钩(不可绕)**:`status:"achieved"` = 双闸过 → **停迭代 + SURFACE**,`accepted` 恒 false。runGoal
+ * **无任何 commit/accept 副作用**(纯 loop,同 runRepairLoop SAFE-tier 永不 `fixed`)。要 accept,caller 自走
+ * design/77 Gate-1 out-of-process oracle 隔离边界,不在 goal helper 开后门。
+ */
 import type { Runner } from "../core/runner/runtask.js";
 import type { CheckpointToken } from "../core/checkpoint-store.js";
 import type { TaskResult, TaskSpec } from "../core/types.js";
+/** Read-only snapshot a `doneCheck` sees after one iteration. */
 export interface GoalTurnState {
+    /** This iteration's full {@link TaskResult}. */
     readonly result: TaskResult;
+    /** 1-based iteration index. */
     readonly iteration: number;
+    /** The session threaded through the whole goal (so a doneCheck can read the session/working tree). */
     readonly sessionId: string;
+    /** Cumulative tokens (own + nested) across iterations — observe-only (the budget gate is in the engine). */
     readonly cumulativeTokens: number;
 }
 export interface GoalVerdict {
+    /** core verification passed? (AND-ed with the LLM self-report — the double gate). */
     readonly done: boolean;
+    /** When not done: the specific feedback fed back to the LLM (fenced as untrusted data). */
     readonly reason: string;
 }
+/** The caller's HONEST declaration of how `doneCheck` verifies — surfaced on the result so a
+ *  `self_report_only` "achieved" is never mistaken for a mechanically-verified one (G1, reward-hack honesty). */
 export type GoalVerificationKind = "mechanical" | "self_report_only";
 export interface GoalSpec {
+    /** The goal (injected as iteration 1's objective + GOAL_COMPLETION_GUIDANCE via the trusted goalMode flag). */
     objective: string;
+    /**
+     * 🔴 The CORE completion gate (REQUIRED). The LLM self-report (gate 1) is necessary but NOT sufficient: the
+     * goal stops as `achieved` only when gate 1 AND `doneCheck.done`. Provide a PURE read-check (it may read the
+     * session/working tree but must have no side effects — it can be cancelled/timed out). A throw/reject
+     * fail-closes to `failed`/`goal.donecheck_error` (never treated as achieved). Core ships no default —
+     * supplying it forces the caller to confront the reward-hack red line.
+     */
     doneCheck: (state: GoalTurnState, signal: AbortSignal) => Promise<GoalVerdict>;
+    /** Honest declaration of `doneCheck`'s substance (§3.2). `self_report_only` ⇒ surfaced on the result. */
     verificationKind: GoalVerificationKind;
+    /** Hard iteration cap (≥1) — exceeding without the double gate → `max_iterations` (NOT achieved). */
     maxIterations: number;
+    /** Per-iteration base spec (model/tools/toolPolicy/principal/env/outputSchema/…). `objective` is overridden
+     *  per iteration; `sessionId` is minted to thread the whole goal if absent; `signal` is set by the engine. */
     taskSpec: Omit<TaskSpec, "objective">;
+    /** Cumulative token ceiling (own + nested); reaching it stops with `budget`. */
     budgetTokens?: number;
+    /** Whole-goal wall-clock ceiling (ms); reaching it stops with `budget`. */
     totalTimeoutMs?: number;
+    /** Cancels the whole goal (folded into each iteration's signal + the doneCheck). */
     signal?: AbortSignal;
+    /**
+     * design/73 §1 — aggregation key of the `TaskOutcome` emitted at the goal's terminal state (only when
+     * `verificationKind:"mechanical"` — the red line). Default: `goal:<sha256(objective) first 16 hex>`,
+     * deterministic per objective. Set it when the "same task" spans differently-worded objectives.
+     */
     taskSignature?: string;
 }
 export type GoalStatus = "achieved" | "max_iterations" | "budget" | "blocked" | "suspended" | "needs_review" | "failed" | "aborted";
 export interface GoalResult {
     readonly status: GoalStatus;
+    /** Last iteration's result; absent on a preflight-terminate (a stop BEFORE iteration 1 ran). */
     readonly result?: TaskResult;
     readonly iterations: number;
+    /** The last `doneCheck` verdict (present once a doneCheck ran). */
     readonly lastVerdict?: GoalVerdict;
+    /** The caller's declared verification kind (always present — replaces the ambiguous "verifiedBy"). */
     readonly verificationKind: GoalVerificationKind;
+    /** 🔴 G1 explicit: runGoal NEVER accepts the artifact. Always false. `achieved` = "stopped + awaiting
+     *  review"; the caller decides acceptance (via a Gate-1 boundary), never runGoal. */
     readonly accepted: false;
     readonly cumulativeTokens: number;
+    /** Carried up on suspended/needs_review so the caller can resume the underlying task. */
     readonly checkpointToken?: CheckpointToken;
+    /** Set on `failed` (incl. `goal.donecheck_error`). */
     readonly errorCode?: string;
 }
+/** Reserved name of the goal-completion signal tool (injected by `runGoal` when there is no outputSchema). */
 export declare const DECLARE_DONE_TOOL_NAME = "DeclareDone";
+/**
+ * Run a goal to a double-gated completion (or a bound). Iterates `runner.runTask` on ONE session: each
+ * iteration the LLM works and signals completion (declare_done / submit_output); `doneCheck` then verifies.
+ * Only `declare_done` AND `doneCheck.done` → `achieved` (surfaced, NEVER auto-accepted, G1). A rejected
+ * doneCheck feeds its reason back (fenced) and continues. Bounded by maxIterations / budget / wall-clock /
+ * cancel; a durable pause (suspended/needs_review) is a hard boundary that surfaces the checkpointToken.
+ */
 export declare function runGoal(runner: Runner, spec: GoalSpec): Promise<GoalResult>;

package/dist/orchestration/goal.js

@@ -60,6 +60,9 @@ export async function runGoal(runner, spec) {
     if (!Number.isFinite(spec.maxIterations) || spec.maxIterations < 1) {
         throw new Error(`runGoal: maxIterations must be a finite number ≥ 1 (got ${spec.maxIterations})`);
     }
+    if (spec.totalTimeoutMs !== undefined && (!Number.isFinite(spec.totalTimeoutMs) || spec.totalTimeoutMs < 0 || spec.totalTimeoutMs > 2_147_483_647)) {
+        throw new Error(`runGoal: totalTimeoutMs must be a finite number in [0, 2147483647] (got ${spec.totalTimeoutMs}) — a host timer clamps anything else and fires immediately. Omit it for no deadline.`);
+    }
     const hasOutputSchema = spec.taskSpec.outputSchema !== undefined;
     if (!hasOutputSchema && (spec.taskSpec.tools ?? []).some((t) => t.name === DECLARE_DONE_TOOL_NAME)) {
         const e = new Error(`Tool name "${DECLARE_DONE_TOOL_NAME}" is reserved in goal mode.`);

package/dist/orchestration/run-spec.d.ts

@@ -1,20 +1,62 @@
+/**
+ * design/125 D2 — **`runSpec`**:SpecContract 的 thin 装配器(形态定死 = `runTask` + Stop hook;裁决
+ * 议题#1:不组合 runGoal —— doneCheck 只在模型自报后跑不适合外部强制,且 mechanical goal 终态自己发射
+ * TaskOutcome,组合 = 同 taskSignature 双发射,违反 design/73 红线③)。
+ *
+ * 装配五步(全部**组合而非覆盖**,codex-B1=fable-M4):
+ *  1. preflight:frozenPaths 校验+字节快照;亲跑三值 oracle;requireRedStart(默认 true)⇒ 必须 red
+ *     (green→`spec.not_red`、error→`spec.oracle_error`,均 fail-loud);捕获 baseline 计数。
+ *  2. frozen deny policy 经 {@link combinePolicies} 合入部署基线(deny 短路不可被顶);绝不裸赋顶掉
+ *     `taskSpec.toolPolicy`(TRAP #1)。
+ *  3. Hooks 多路复用:runSpec 的 stop gate 先跑(guard-restore → oracle 判)——red ⇒ block 短路(失败
+ *     尾部经 `delimitUntrusted` 围栏后置入:oracle 输出是模型可影响面);green ⇒ **链式调用**用户 stop
+ *     (不吞其否决权);error ⇒ block 一次并注明 oracle 基础设施故障,**连续 2 次 error 放弃把关**走终态
+ *     判定(防 oracle 自坏死循环)。其它 hook 槽原样透传。
+ *  4. 收口:终态亲跑 oracle = 最终判定;`emitTaskOutcome`(mechanical):`oracleHadRedRun` = 任一
+ *     「真跑过且判 red」的观察(preflight ∨ stop-gate ∨ 终态;error 永不置位)。durable pause
+ *     (suspended/needs_review)非终态,不发射(同 goal.ts 先例:无半事实、resume 不重复计数)。
+ *  5. objective 框架:spec 文本围栏置入 + frozenPaths 只读声明(框架 = 可信第一方,spec = DATA)。
+ *
+ * 已知两代价(fable,写明):① stop cap=8 引擎硬常量 —— >8 次红反馈的超长修复需拆任务;② stop gate 只在
+ * 自然结束点咨询,maxTurns/timeout/abort 结束不咨询 —— 终态亲跑兜住**判定**但不兜**续命**(预算配比
+ * 参考 harness 实战:maxTurns=60 / 自限 6)。
+ *
+ * runSpec **不接**的 harness 职责(fable-MIN1,显式留给使用方):JSONL 事件账本、不变量检查器、workcopy
+ * 生命周期(调用方保证起点是干净树 —— preflight 红才有意义)、模型/Runner 装配、chaos 包装。frozen 写入
+ * 面:policy 只挡 Write/Edit 族 = belt;bash 写入由快照恢复兜(suspenders);危险 bash deny 仍是使用方纪律。
+ */
 import type { Runner } from "../core/runner/runtask.js";
 import type { TaskResult, TaskSpec } from "../core/types.js";
 import type { TaskOutcome } from "../core/task-outcome.js";
 import { type OracleBaseline, type OracleGateResult, type OracleVerdict, type SpecContract } from "../core/spec-contract.js";
 export interface RunSpecOptions {
+    /** Workcopy root — the containment root for frozenPaths, oracle cwd, and `spec.path` resolution. */
     rootDir: string;
+    /** Per-run base spec (model/tools/toolPolicy/hooks/limits/…). `objective` is owned by runSpec (the
+     *  spec framing); `toolPolicy` and `hooks` are COMPOSED with runSpec's, never replaced. */
     taskSpec: Omit<TaskSpec, "objective">;
 }
 export interface RunSpecOracleReport {
+    /** Terminal adjudication (the authoritative bit — the stop gate only advises mid-run). */
     final: OracleVerdict;
     perGate: OracleGateResult[];
+    /** Preflight counts backing `minPass:"baseline"` (empty when no gate parses counts). */
     baseline: OracleBaseline;
 }
 export interface RunSpecResult {
     result: TaskResult;
     oracle: RunSpecOracleReport;
+    /** The emitted outcome fact. Undefined on a durable pause (suspended/needs_review — not a terminal). */
     outcome?: TaskOutcome;
+    /** How many frozen files were byte-restored after tampering (stop gates + terminal sweep). */
     guardRestores: number;
 }
+/**
+ * Run one task under a {@link SpecContract}. 🔴 CODE-tier input contract (fable-M3): `contract` must come
+ * from the deployment author / a trusted code path — its oracle commands are executed verbatim.
+ *
+ * Throws coded errors on contract violations before any model turn runs: `spec.no_oracle`,
+ * `spec.frozen_path_invalid`, `spec.frozen_missing`, `spec.spec_unreadable`, `spec.not_red`,
+ * `spec.oracle_error`.
+ */
 export declare function runSpec(runner: Pick<Runner, "runTask"> & Partial<Pick<Runner, "emitTaskOutcome" | "gateBaseline">>, contract: SpecContract, opts: RunSpecOptions): Promise<RunSpecResult>;

package/dist/orchestration/run-spec.js

@@ -102,6 +102,9 @@ export async function runSpec(runner, contract, opts) {
     const userHooks = opts.taskSpec.hooks && deployBaseline?.hooks
         ? {
             preToolUse: (opts.taskSpec.hooks.preToolUse ?? deployBaseline.hooks.preToolUse)?.bind(opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
+            ...((opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks).preToolUseObservational === true
+                ? { preToolUseObservational: true }
+                : {}),
             postToolUse: (opts.taskSpec.hooks.postToolUse ?? deployBaseline.hooks.postToolUse)?.bind(opts.taskSpec.hooks.postToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
             userPromptSubmit: (opts.taskSpec.hooks.userPromptSubmit ?? deployBaseline.hooks.userPromptSubmit)?.bind(opts.taskSpec.hooks.userPromptSubmit ? opts.taskSpec.hooks : deployBaseline.hooks),
             stop: (opts.taskSpec.hooks.stop ?? deployBaseline.hooks.stop)?.bind(opts.taskSpec.hooks.stop ? opts.taskSpec.hooks : deployBaseline.hooks),
@@ -118,6 +121,7 @@ export async function runSpec(runner, contract, opts) {
     let gateAbandoned = false;
     const hooks = {
         ...(userHooks?.preToolUse && { preToolUse: userHooks.preToolUse.bind(userHooks) }),
+        ...(userHooks?.preToolUse && userHooks.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
         ...(userHooks?.postToolUse && { postToolUse: userHooks.postToolUse.bind(userHooks) }),
         ...(userHooks?.userPromptSubmit && { userPromptSubmit: userHooks.userPromptSubmit.bind(userHooks) }),
         ...(userHooks?.postToolUseFailure && { postToolUseFailure: userHooks.postToolUseFailure.bind(userHooks) }),

package/dist/orchestration/run-workflow-tool.d.ts

@@ -1,3 +1,14 @@
+/**
+ * design/98 §3.1 (S8c) — the `run_workflow` TOOL an LLM calls to author + run its own workflow. Mounted ONLY
+ * when self-orchestration is active (design/98 §1.2: opt-in + a HARD `WorkflowScriptRunner` + a governance
+ * baseline). Params are ONLY `{ script, args }` — it NEVER accepts `depth` (the nesting depth is a trusted
+ * internal channel, design/98 §0.1). `effect: "write"` (spawning agents is an irreversible side effect → it
+ * passes the design/37 policy gate; each spawned agent then passes its OWN governed gate).
+ *
+ * Flow: size-cap the script → statically validate `meta` (no eval) → `startWorkflow` with the GOVERNED
+ * primitives + hard caps → return `{ runId }` IMMEDIATELY → on completion, notify the originator via the
+ * {@link WorkflowCompletionNotifier} seam.
+ */
 import type { AgentTool } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
 import type { Runner } from "../core/runner/runtask.js";
@@ -10,7 +21,17 @@ import type { WorkflowAgentHandle } from "./workflow.js";
 import type { WorkflowScriptRunner } from "./workflow-script-runner.js";
 import { type NamedWorkflowListing, type WorkflowScriptStore } from "./workflow-script-store.js";
 import { type WorkflowSizeGuideline } from "./workflow-size-guideline.js";
+/** Reserved name of the injected self-orchestration tool. Audit 2026-07-07: CC's primary
+ *  name is `Workflow` with `RunWorkflow` as the alias — CC-trained prompts address "Workflow", so the
+ *  primary flipped to match. #181-F2 订正: since RB-476-A retired alias resolution, `RunWorkflow`/
+ *  `run_workflow` are NOT callable — they live in RETIRED_TOOL_NAMES as validation data only (a call
+ *  under either gets a loud roster miss), so every model-visible mention must use THIS constant. */
 export declare const RUN_WORKFLOW_TOOL_NAME = "Workflow";
+/**
+ * design/98 §D.5 — the seam the deployment implements to RE-INVOKE the originating LLM when its workflow
+ * finishes. Core calls `notify` once per run (at most once — `runId` dedup) with a REDACTED, BOUNDED summary;
+ * the service routes it back through its task-notification path (cross-replica via the WorkflowRunStore).
+ */
 export interface WorkflowCompletionNotifier {
     notify(input: {
         runId: string;
@@ -18,15 +39,34 @@ export interface WorkflowCompletionNotifier {
         task_type?: "workflow";
         toolUseId?: string;
         sourceTaskId?: string;
+        /** The ORIGINATING session id (the run that spawned this workflow), threaded from the
+         *  Runner so a deployment's completion inbox resolves the target session lookup-free. */
         originatingSessionId?: string;
         principal?: string;
         status: "completed" | "failed";
+        /** Redacted + length-bounded — never the host's internal paths/tokens. */
         summary: string;
         result?: string;
         usage?: unknown;
+        /** [1630]-sweep A-①: the diagnosis route (per-agent rows / journal locator / resumeFromRunId guidance).
+         *  Added 1.353 on the payload but silently dropped at this hand-written subset seam until 1.404 —
+         *  keep this interface in lockstep with the payload fields the settle legs mint. */
         diagnostics?: string;
+        /** P1-3(黑板 [1920]/[1921]/[1924]/[1925]) — see {@link "../core/task-notification.js".TaskNotificationPayload.completionId}.
+         *  This CROSS-REPLICA seam is exactly one of the read faces the cross-channel correlation contract
+         *  promises the same value on — added here in the same car specifically so this interface does not
+         *  repeat the diagnostics field's own drift history (the comment right above this one). */
         completionId?: string;
     }): Promise<void> | void;
+    /**
+     * Poll-then-also-notify dedup: the ORIGINATING session was served this run's TERMINAL
+     * state IN-BAND (a `TaskOutput` poll through the task registry returned a non-running snapshot) —
+     * the deployment should ack/drop any still-pending completion-inbox entry for (originatingSessionId,
+     * runId), so a later stream-open doesn't re-deliver a `workflow_complete` the model already
+     * consumed. Fired at most once per run, AFTER `notify` may already have enqueued (the whole point:
+     * the poll usually wins the race in-turn). Optional; errors are swallowed. The shell-side same-process
+     * seed dedup remains the belt — this is the durable/cross-restart half.
+     */
     ackServed?(input: {
         runId: string;
         originatingSessionId?: string;
@@ -34,63 +74,192 @@ export interface WorkflowCompletionNotifier {
         principal?: string;
     }): Promise<void> | void;
 }
+/** design/98 §D.6 — the deployment's hard CEILINGS for an LLM-authored workflow (the tool forces them; a
+ *  script may only tighten). All optional; sensible defaults bound a runaway script. */
 export interface WorkflowLimits {
+    /** Max script source length (chars). Default 100_000. */
     maxScriptChars?: number;
+    /** Max cumulative agents. Default 50. */
     maxAgents?: number;
+    /** Whole-workflow wall-clock cap (ms). Default 600_000 (10 min). */
     totalTimeoutMs?: number;
+    /** design/164 — per-child wall-clock ceiling (ms). No default: unset means the children are not
+     *  wall-clock bounded (state a ceiling to get one). */
     perAgentMaxWalltimeMs?: number;
+    /** Per-child cost ceiling (USD). Forced onto every child. */
     childMaxCostUsd?: number;
+    /** Per-child token ceiling. Forced onto every child. */
     childMaxTokens?: number;
+    /** Per-child turn ceiling. */
     childMaxTurns?: number;
+    /** Workflow token budget (`ctx.agent` throws once reached). */
     budget?: number;
+    /** Max returned-result size (chars). Default 100_000. */
     maxResultChars?: number;
+    /** Max single log-line length (chars). Default 10_000. */
     maxLogChars?: number;
+    /**
+     * CC 2.1.202+ config key `workflowSizeGuideline`: ADVISORY workflow size guidance
+     * (NOT a cap — the hard ceiling stays `maxAgents`). small/medium/large append CC's verbatim
+     * "keep workflows under N agents … guideline, not a hard limit" section to the Workflow tool card
+     * (matching observed CC behavior); an EXPLICIT "unrestricted" injects nothing, while unset resolves
+     * to the medium DEFAULT arm (RB-339 rebaseline — see workflow-size-guideline.ts).
+     * Lives on the limits object so it rides the EXISTING `RunnerDeps.workflowLimits` threading —
+     * deployments configure it as `workflowLimits: { sizeGuideline }` with no new prepare-task seam.
+     * `RunWorkflowToolDeps.sizeGuideline` (direct construction) takes precedence when both are set.
+     */
     sizeGuideline?: WorkflowSizeGuideline;
 }
+/**
+ * design/140 §6 1b — pick the LLM-facing guidance text for one named workflow: `whenToUse` when declared,
+ * else the description (the agents-side `agentWhenToUseText`/CC `tIl` selection shape, workflows arm —
+ * workflows have no lean variant, so the fallback chain is just whenToUse → description).
+ */
 export declare function workflowWhenToUseText(m: {
     description?: string;
     whenToUse?: string;
 }): string | undefined;
+/**
+ * design/140 §6 1b — render the named-workflow roster block appended to the Workflow tool card (the
+ * consumption face `meta.whenToUse` previously lacked). Line shape mirrors the agent roster (CC `tIl`,
+ * subagent.ts precedent): `- name: whenToUse-or-description`. Returns undefined when nothing is registered
+ * (the card stays byte-identical to the pre-140 form).
+ */
 export declare function renderNamedWorkflowListing(entries: ReadonlyArray<NamedWorkflowListing>): string | undefined;
 export interface RunWorkflowToolDeps {
+    /** The Runner that executes child tasks (the workflow's `ctx.agent` → `runner.runTask`). */
     runner: Runner;
+    /** The HARD sandbox (asserted `safeForUntrustedScripts:true`). */
     scriptRunner: WorkflowScriptRunner;
+    /** Deployment-trusted governance every spawned agent inherits (design/98 §2.5). */
     governanceBaseline: WorkflowGovernanceBaseline;
+    /** codex F6 (tool-face round 5): the HOST task's tool-face controls (prepare-time snapshot) — a
+     *  scenario roster must survive the workflow delegation path exactly like the Agent path. Merged
+     *  (union — tighten-only) into the baseline base for every child spec this workflow spawns. */
     parentExcludeTools?: readonly string[];
     parentDeferTools?: readonly string[];
+    /** DD-3 (RB-422): the defer face's subtract valve rides the same snapshot — a pin the operator
+     *  declared for the tree must survive this direct-mount lane exactly like the deferral it exempts
+     *  from. Union (widen-the-exemption never tightens the child beyond the parent's own face). */
     parentAlwaysLoadTools?: readonly string[];
+    /** R2 双形轴 — the HOST task's resolved prompt profile, inherited by every workflow-spawned child
+     *  (base spec seat; the child's own explicit promptProfile would win in prepare, but workflow
+     *  scripts cannot name this field, so in practice the tree speaks the host's profile). */
     parentPromptProfile?: "simple" | "classic";
+    /** Model catalog (for the name→Model allowlist resolution). */
     models?: Record<string, Model>;
+    /** F4 agentType registry: deployment agent definitions `agent(…, {agentType})` resolves (SHADOW over
+     *  built-in Explore/Plan; `builtinAgents:false` removes the built-ins). Same registry the Agent tool uses. */
     agents?: import("../core/types.js").AgentDefinition[];
     builtinAgents?: boolean;
+    /** Optional run store for cross-replica `/workflows` observability (opt-in). */
     store?: WorkflowRunStore;
+    /** design/97 CORE-9 (Part A) — optional LOAD-BEARING resume journal: records each agent result so a
+     *  `resumeFromRunId` re-run replays the unchanged prefix (durable cross-replica resume). Opt-in. */
     journalStore?: WorkflowJournalStore;
+    /** design/149 ([1422]③ 裁 a): the process-level BackgroundChildEvent sink — workflow-spawned agents
+     *  mint synthetic `wa*` rows (spawn/tick/terminal) on the SAME observer bg subagents use
+     *  (RunnerDeps.onBackgroundChildEvent), immune to any run-leg forwarding freeze. Opt-in. */
     onBackgroundChildEvent?: (event: import("../core/types.js").BackgroundChildEvent) => void;
+    /** design/97 CORE-9 (Part B) — optional steerable-handle sink. When set, the script's `agent()` primitive runs
+     *  each agent STEERABLE and emits its {@link WorkflowAgentHandle} here (the script never sees the handle); the
+     *  deployment registers it by runId+label to route a human/cross-replica steer. Unset ⇒ non-steerable. Opt-in. */
     onAgentSpawn?: (handle: WorkflowAgentHandle) => void;
+    /** Tenant/grouping key for the run. */
     scope?: string;
+    /** Completion re-invoke seam. */
     notifier?: WorkflowCompletionNotifier;
+    /** The originating session id, threaded into every completion notify. */
     originatingSessionId?: string;
+    /** δ 批 codex D-1 — the ROOT host session of the delegation tree (prepare-task passes
+     *  `internals?.rootSessionId ?? sessionId` per task). The AUTO-MOUNTED tool's execute ctx is the
+     *  harness-native one (no internals enrichment — that wrapper covers spec.tools only), so the
+     *  root MUST ride deps; `ctx.rootSessionId` stays first for a deployment-composed mount that
+     *  does get the enriched ctx. */
     rootSessionId?: string;
+    /** Process-local unified task registry. When present, RunWorkflow returns `task_id === runId` with a `w*` id. */
     taskRegistry?: TaskRegistry;
+    /** design/115 P2 core slice: run-local task-notification sink for SDK event + live model XML injection. */
     taskNotification?: (notification: TaskNotificationPayload) => void;
+    /** Runner-owned owner fallback for registry access when the execute context is unavailable. */
     taskOwner?: string;
+    /** Hard ceilings. */
     limits?: WorkflowLimits;
+    /** B5/F2 (CC scriptPath/name surface): optional script-persistence seam. When wired, EVERY invocation's
+     *  resolved script is persisted (best-effort) and its path returned in the tool result; `scriptPath`
+     *  re-runs a persisted file and `name` resolves a saved workflow. Absent ⇒ inline `script` only. */
     scriptStore?: WorkflowScriptStore;
+    /** design/140 §6 1c — `false` removes the BUILT-IN named workflows (`team-discussion`, …) wholesale (the
+     *  `builtinAgents:false` analog). Default ON: `{name}` resolves a built-in even with NO deployment script
+     *  store; a deployment `scriptStore.resolveName` hit for the same name always SHADOWS the built-in. */
     builtinWorkflows?: boolean;
+    /** CC `workflowSizeGuideline` — advisory size guideline appended to the tool card.
+     *  Direct-construction face; wins over `limits.sizeGuideline` (the RunnerDeps-reachable channel).
+     *  See {@link WorkflowLimits.sizeGuideline}. */
     sizeGuideline?: WorkflowSizeGuideline;
+    /** The originating task id + principal, threaded to the notifier. */
     sourceTaskId?: string;
     principal?: string;
+    /** 黑板 [1909]⑧/[1910]/[1911] — mirrors {@link "../core/types.js".TaskSpec.oneShot}: this submission has
+     *  no later turn for an async notification to land in. Branches the launch receipt's `note` guidance
+     *  (see {@link createRunWorkflowTool}'s `note` composition) toward an active block-wait instead of
+     *  "end your turn and wait" — the latter is actively wrong for a one-shot caller. */
     oneShot?: boolean;
+    /** design/173 §8.3 (r3-F1) — the HOST run's RESOLVED interaction posture, threaded as a MOUNT
+     *  dep because prepare-task's auto-mount seals this tool without the rich-ctx wrapper (the same
+     *  reason `forwardEvent`/`inheritedGateForChildren` ride deps); `ctx.interactionPosture` still
+     *  wins when a wrapping path provides it. */
     parentInteractionPosture?: "interactive" | "headless";
+    /** TRUSTED nesting depth from the run's internals (NOT a tool param) — passed to `startWorkflow` so a
+     *  cross-process child workflow is rejected by the one-level guard. */
     workflowDepth?: number;
+    /** The HOST task's effective working root — threaded into every spawned agent's trusted internals so a
+     *  TOC env factory can root the child at the parent's cwd (CC parity, 2026-07-03). */
     parentCwd?: string;
+    /** Call-time getter for the HOST task's current thinking level — a spawned agent with no explicit
+     *  script/baseline `thinking` inherits it (the parentCwd/model-snapshot companion). */
     parentThinking?: () => import("../core/types.js").TaskSpec["thinking"];
+    /** [1238](A) — call-time getter for the HOST task's RESOLVED Model object: a spawned agent whose
+     *  fold chain produced no model inherits the parent's full object (baseUrl/key routing included),
+     *  mirroring the subagent lane's ctx.model semantics. */
     parentModel?: () => import("../internal/llm.js").Model | undefined;
+    /** [1258] v2 — the HOST task's per-model auth hook ([893]④a): the CREDENTIAL half of model
+     *  inheritance. The Model object fixed the URL routing but the child brain still authenticated
+     *  with the boot env token (clay rerun: 7/7 kimi-route 401s with the qwen key). The subagent lane
+     *  has inherited this hook since [893]④a; the workflow lane never did — the governance whitelist
+     *  rightly blocks SCRIPTS from setting it, but host inheritance is a different lane. */
     parentGetApiKeyAndHeaders?: import("../core/types.js").TaskSpec["getApiKeyAndHeaders"];
+    /** The HOST run's display sink (its `RunInternals.onForwardEvent`, already filtered to `task_progress`
+     *  by the runner's ctx wrapper) — threaded via `startWorkflow` into every spawned agent's trusted
+     *  internals so a workflow child's progress ticks bubble to the deployment's one sink, the same
+     *  channel a `createSubagentTool` delegation threads. Display-only; absent ⇒ ticks stay in each
+     *  child's own stream. (A dep, not read off the execute ctx: the mounted tool's `AgentTool.execute`
+     *  wrapper builds a minimal `{toolCallId, signal}` ctx — the rich-ctx injection only wraps
+     *  `spec.tools`. `ctx.forwardEvent` still wins when a wrapping path provides it.) */
     forwardEvent?: (event: import("../core/types.js").TaskEvent) => void;
+    /** Parent effective-policy inheritance: the HOST task's `inheritedGateForChildren` chain accessor,
+     *  called at LAUNCH time and threaded via `RunWorkflowOptions.inheritedGate` into every spawned agent's
+     *  trusted internals — workflow children inherit the host's evaluated gate exactly like a
+     *  `createSubagentTool` delegation. (A dep for the same reason as `forwardEvent`: the direct mount's
+     *  execute ctx is minimal; `ctx.inheritedGateForChildren` still wins when a wrapping path provides it.) */
     inheritedGateForChildren?: () => import("../core/runner/prepare-task.js").InheritedGate;
+    /** RB-201 FO-3 — the HOST session's auto-mode classifier, threaded via `RunWorkflowOptions.autoModeReview`
+     *  so every child this workflow spawns is reviewed before it starts, exactly like a `createSubagentTool`
+     *  delegation's child. (A dep for the same reason as `forwardEvent`/`inheritedGateForChildren`: the direct
+     *  mount's execute ctx is minimal; `ctx.autoModeReview` still wins when a wrapping path provides it.)
+     *  A call-time getter, not a value — the decider is built during prepare and this dep is read at launch.
+     *  Absent on both seats ⇒ auto-mode is not armed and the review legs are a complete no-op. */
     autoModeReview?: () => {
         decider: import("../core/auto-mode.js").AutoModeDecider;
     } | undefined;
 }
+/**
+ * Build the `run_workflow` tool. ASSERTS the runner is a hard sandbox (defense in depth — prepare-task only
+ * mounts it under the same gate). Returns a structured error (not a throw) for an LLM-correctable problem
+ * (oversized / malformed-meta / nesting), so the model can fix and retry.
+ *
+ * Async since codex F3: the card's named-workflow roster is derived from the SAME sources the execute path
+ * resolves against (built-ins probed through `resolveName` shadowing + awaited `list()`), so the card can
+ * never advertise a workflow the call would resolve differently.
+ */
 export declare function createRunWorkflowTool(d: RunWorkflowToolDeps): Promise<AgentTool>;