@sema-ai/core 1.275.1

package/dist/agents/agent-definition.d.ts

@@ -0,0 +1,10 @@
+import type { AgentDefinition } from "../core/types.js";
+/**
+ * Validate + freeze a declarative sub-agent definition (design/38 1B). A thin, fail-fast factory: it
+ * checks the only hard requirement (a non-empty `name`) and returns a shallow-frozen copy so a stored
+ * definition can't be mutated out from under the registry. Registry-level checks (name uniqueness,
+ * collision with reserved/tool names, model-ref resolution) happen when the set is handed to
+ * {@link createSubagentTool}, where the tool name + model catalog are available.
+ */
+export declare function defineAgent(def: AgentDefinition): AgentDefinition;
+//# sourceMappingURL=agent-definition.d.ts.map

package/dist/agents/agent-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.d.ts","sourceRoot":"","sources":["../../src/agents/agent-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CASjE"}

package/dist/agents/agent-definition.js

@@ -0,0 +1,18 @@
+/**
+ * Validate + freeze a declarative sub-agent definition (design/38 1B). A thin, fail-fast factory: it
+ * checks the only hard requirement (a non-empty `name`) and returns a shallow-frozen copy so a stored
+ * definition can't be mutated out from under the registry. Registry-level checks (name uniqueness,
+ * collision with reserved/tool names, model-ref resolution) happen when the set is handed to
+ * {@link createSubagentTool}, where the tool name + model catalog are available.
+ */
+export function defineAgent(def) {
+    if (!def.name || !def.name.trim()) {
+        const e = new Error("defineAgent: `name` is required and must be a non-empty string.");
+        e.code = "config.agent.invalid";
+        throw e;
+    }
+    // Shallow freeze: the top-level definition can't be reassigned, but a nested `model` Model object stays
+    // mutable. Fine here — AgentDefinitions are trusted deployment-side config, not adversarial input.
+    return Object.freeze({ ...def });
+}
+//# sourceMappingURL=agent-definition.js.map

package/dist/agents/agent-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.js","sourceRoot":"","sources":["../../src/agents/agent-definition.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAoB;IAC9C,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,iEAAiE,CAA8B,CAAC;QACpH,CAAC,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAChC,MAAM,CAAC,CAAC;IACV,CAAC;IACD,wGAAwG;IACxG,mGAAmG;IACnG,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/agents/builtin-agents.d.ts

@@ -0,0 +1,69 @@
+import type { AgentDefinition } from "../core/types.js";
+/**
+ * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the CC 2.1.198 BUILT-IN `Explore` and
+ * `Plan` agent types, ported to sema's AgentDefinition roster shape.
+ *
+ * 198 锚 (亲核 2026-07-10, drift 调研: 198→204→206 逐字零漂移):
+ *  - Explore definition `qme` — pretty.js:409186-409198 (`agentType:"Explore"`, whenToUse=nbm,
+ *    whenToUseLean=rbm, `disallowedTools:[is,NR,s0,xa,Ic,FR]` = Agent/Artifact/ExitPlanMode/Edit/Write/
+ *    NotebookEdit, `model:"inherit"`, `omitClaudeMd:!0`, getSystemPrompt=tbm).
+ *  - Explore whenToUse `nbm` / whenToUseLean `rbm` — pretty.js:409173-409174 (verbatim below).
+ *  - Explore system prompt `tbm()` — pretty.js:409122-409160 (verbatim below, unix+Glob/Grep arm).
+ *  - Plan definition `Xor` — pretty.js:486943-486953 (`agentType:"Plan"`, single whenToUse, same six
+ *    disallowedTools, `tools: qme.tools` = undefined, `model:"inherit"`, `omitClaudeMd:!0`).
+ *  - Plan system prompt `kBm()` — pretty.js:486874-486930 (verbatim below, unix arm).
+ *  - Registry `HCe` — pretty.js:487221-487240: Explore+Plan ship behind `iAt()` (487127-487131:
+ *    env kill-switch `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` + `tengu_slate_ibis` gate DEFAULT ON)
+ *    ⇒ GA default-on in 198 (and byte-stable through 204/206 — CC-DRIFT-198-206-AGENT-TYPES 锚 1-7).
+ *    SDK entrypoints ship them too (only `claude-code-guide` is non-SDK); the SDK-form opt-out is
+ *    `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` (487221) → sema's deployment-config analog is
+ *    `SubagentToolOptions.builtinAgents: false` (config-driven, not env-driven).
+ *
+ * sema adaptations (deliberate, each recorded):
+ *  - De-branding (prompt-sovereignty / SUBAGENT_PROMPT precedent): CC's persona first sentences name the
+ *    product ("… for Claude Code, Anthropic's official CLI for Claude." / "… for Claude Code.") — sema
+ *    stays provider-neutral, the brand clause is dropped; every other byte is CC-verbatim.
+ *  - Platform arm: CC's `tbm`/`kBm` interpolate per-platform tool guidance (unix Bash vs PowerShell) and
+ *    a bash-only search mode (`ww()`). sema children run in a POSIX ExecutionEnv with first-party
+ *    Glob/Grep/Read/Bash under CC-identical names — the unix + Glob/Grep arm is baked verbatim
+ *    (Mu="Glob" :149761, Jc="Grep" :224202, Ls="Read", Lo="Bash").
+ *  - `model:"inherit"` — sema shape: `model` omitted on an AgentDefinition = inherit the caller's current
+ *    model (identical semantics). CC's Explore firstParty opus UPGRADE (`GAe`, 409162-409171: built-in
+ *    Explore may upshift to opus on first-party subscriptions) is a CC-subscription ladder concern —
+ *    NOT ported (sema is provider-neutral; inherit is the base arm both sides share).
+ *  - `omitClaudeMd:!0` (422063: drops the CLAUDE.md user-context layer for these types) — NOT ported this
+ *    round: sema's project-context layer is assembled in prepare-task (design/113 C4), a concurrent-batch
+ *    conflict domain at port time. Recorded as the F7 residual; the deployment `loadProjectMemory` seam
+ *    already receives `isSubagent`/`agentName` and can trim today.
+ *  - `disallowedTools` → `denyTools` (sema name), with the DELEGATION-tool entry tracking the deployment's
+ *    actual tool name (default "Agent" = CC-verbatim). "Artifact"/"ExitPlanMode" have first-party sema
+ *    referents only partially (present_plan canonicalizes to ExitPlanMode; Artifact has none) — a deny of
+ *    an unmounted name is a documented no-op (tool-filter), kept for CC listing-tail byte parity.
+ */
+/** CC 198 `nbm` (pretty.js:409173) — Explore `whenToUse`, verbatim. */
+export declare const EXPLORE_WHEN_TO_USE = "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis \u2014 it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.";
+/** CC 198 `rbm` (pretty.js:409174) — Explore `whenToUseLean`, verbatim. */
+export declare const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches \u2014 when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
+/** CC 198 Plan `whenToUse` (pretty.js:486945), verbatim (Plan has no lean variant in 198). */
+export declare const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
+/** CC 198 `tbm()` (pretty.js:409122-409160) — Explore persona, unix+Glob/Grep arm, first sentence de-branded. */
+export declare const EXPLORE_SYSTEM_PROMPT = "You are a file search specialist. You excel at thoroughly navigating and exploring codebases.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYour strengths:\n- Rapidly finding files using glob patterns\n- Searching code and text with powerful regex patterns\n- Reading and analyzing file contents\n\nGuidelines:\n- Use Glob for broad file pattern matching\n- Use Grep for searching file contents with regex\n- Use Read when you know the specific file path you need to read\n- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n- Adapt your search approach based on the thoroughness level specified by the caller\n- Communicate your final report directly as a regular message - do NOT attempt to create files\n\nNOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:\n- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations\n- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files\n\nComplete the user's search request efficiently and report your findings clearly.";
+/** CC 198 `kBm()` (pretty.js:486874-486930) — Plan persona, unix arm, first sentence de-branded. */
+export declare const PLAN_SYSTEM_PROMPT = "You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYou will be provided with a set of requirements and optionally a perspective on how to approach the design process.\n\n## Your Process\n\n1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.\n\n2. **Explore Thoroughly**:\n   - Read any files provided to you in the initial prompt\n   - Find existing patterns and conventions using Glob, Grep, and Read\n   - Understand the current architecture\n   - Identify similar features as reference\n   - Trace through relevant code paths\n   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n\n3. **Design Solution**:\n   - Create implementation approach based on your assigned perspective\n   - Consider trade-offs and architectural decisions\n   - Follow existing patterns where appropriate\n\n4. **Detail the Plan**:\n   - Provide step-by-step implementation strategy\n   - Identify dependencies and sequencing\n   - Anticipate potential challenges\n\n## Required Output\n\nEnd your response with:\n\n### Critical Files for Implementation\nList 3-5 files most critical for implementing this plan:\n- path/to/file1.ts\n- path/to/file2.ts\n- path/to/file3.ts\n\nREMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.";
+/**
+ * CC 198 `disallowedTools:[is,NR,s0,xa,Ic,FR]` (pretty.js:409189 Explore / :486948 Plan) — the six-tool
+ * deny set shared by both read-only built-ins, constants resolved 亲核: is="Agent"(147382),
+ * NR="Artifact"(143265), s0="ExitPlanMode"(149770), xa="Edit"(143358), Ic="Write"(143375),
+ * NotebookEdit FR(143373). The delegation-tool entry is parameterized on the deployment's actual tool
+ * name (default = "Agent", CC-verbatim).
+ */
+export declare const BUILTIN_READONLY_DENY_TOOLS: (delegationToolName?: string) => string[];
+/**
+ * Build the built-in agent definitions offered by {@link import("./subagent.js").createSubagentTool}
+ * (CC `HCe` registry analog, SDK arm: Explore + Plan; general-purpose is sema's OMITTED-`subagent_type`
+ * fallback and fork lives in the `subagent_type` value domain — neither needs a definition here).
+ * A deployment definition of the same name SHADOWS a built-in (fork-shadowing precedent), and
+ * `builtinAgents: false` removes them wholesale (CC `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` form).
+ */
+export declare function builtinAgentDefinitions(delegationToolName?: string): AgentDefinition[];
+//# sourceMappingURL=builtin-agents.d.ts.map

package/dist/agents/builtin-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.d.ts","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAMxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,mnBACikB,CAAC;AAElmB,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,4ZACiX,CAAC;AAEvZ,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,uOACyM,CAAC;AAEvO,iHAAiH;AACjH,eAAO,MAAM,qBAAqB,64DAgC+C,CAAC;AAElF,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,wwEAiDkH,CAAC;AAElJ;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,wBAAwB,MAAM,KAAkC,MAAM,EAO7G,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,kBAAkB,GAAE,MAAqC,GAAG,eAAe,EAAE,CAkBpH"}

package/dist/agents/builtin-agents.js

@@ -0,0 +1,177 @@
+/** Default delegation-tool name (= subagent.ts `DEFAULT_SUBAGENT_TOOL_NAME`, duplicated here as a
+ *  literal to keep this module import-cycle-free; CC 198 `is`="Agent" — locked by test). */
+const DEFAULT_DELEGATION_TOOL_NAME = "Agent";
+/**
+ * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the CC 2.1.198 BUILT-IN `Explore` and
+ * `Plan` agent types, ported to sema's AgentDefinition roster shape.
+ *
+ * 198 锚 (亲核 2026-07-10, drift 调研: 198→204→206 逐字零漂移):
+ *  - Explore definition `qme` — pretty.js:409186-409198 (`agentType:"Explore"`, whenToUse=nbm,
+ *    whenToUseLean=rbm, `disallowedTools:[is,NR,s0,xa,Ic,FR]` = Agent/Artifact/ExitPlanMode/Edit/Write/
+ *    NotebookEdit, `model:"inherit"`, `omitClaudeMd:!0`, getSystemPrompt=tbm).
+ *  - Explore whenToUse `nbm` / whenToUseLean `rbm` — pretty.js:409173-409174 (verbatim below).
+ *  - Explore system prompt `tbm()` — pretty.js:409122-409160 (verbatim below, unix+Glob/Grep arm).
+ *  - Plan definition `Xor` — pretty.js:486943-486953 (`agentType:"Plan"`, single whenToUse, same six
+ *    disallowedTools, `tools: qme.tools` = undefined, `model:"inherit"`, `omitClaudeMd:!0`).
+ *  - Plan system prompt `kBm()` — pretty.js:486874-486930 (verbatim below, unix arm).
+ *  - Registry `HCe` — pretty.js:487221-487240: Explore+Plan ship behind `iAt()` (487127-487131:
+ *    env kill-switch `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` + `tengu_slate_ibis` gate DEFAULT ON)
+ *    ⇒ GA default-on in 198 (and byte-stable through 204/206 — CC-DRIFT-198-206-AGENT-TYPES 锚 1-7).
+ *    SDK entrypoints ship them too (only `claude-code-guide` is non-SDK); the SDK-form opt-out is
+ *    `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` (487221) → sema's deployment-config analog is
+ *    `SubagentToolOptions.builtinAgents: false` (config-driven, not env-driven).
+ *
+ * sema adaptations (deliberate, each recorded):
+ *  - De-branding (prompt-sovereignty / SUBAGENT_PROMPT precedent): CC's persona first sentences name the
+ *    product ("… for Claude Code, Anthropic's official CLI for Claude." / "… for Claude Code.") — sema
+ *    stays provider-neutral, the brand clause is dropped; every other byte is CC-verbatim.
+ *  - Platform arm: CC's `tbm`/`kBm` interpolate per-platform tool guidance (unix Bash vs PowerShell) and
+ *    a bash-only search mode (`ww()`). sema children run in a POSIX ExecutionEnv with first-party
+ *    Glob/Grep/Read/Bash under CC-identical names — the unix + Glob/Grep arm is baked verbatim
+ *    (Mu="Glob" :149761, Jc="Grep" :224202, Ls="Read", Lo="Bash").
+ *  - `model:"inherit"` — sema shape: `model` omitted on an AgentDefinition = inherit the caller's current
+ *    model (identical semantics). CC's Explore firstParty opus UPGRADE (`GAe`, 409162-409171: built-in
+ *    Explore may upshift to opus on first-party subscriptions) is a CC-subscription ladder concern —
+ *    NOT ported (sema is provider-neutral; inherit is the base arm both sides share).
+ *  - `omitClaudeMd:!0` (422063: drops the CLAUDE.md user-context layer for these types) — NOT ported this
+ *    round: sema's project-context layer is assembled in prepare-task (design/113 C4), a concurrent-batch
+ *    conflict domain at port time. Recorded as the F7 residual; the deployment `loadProjectMemory` seam
+ *    already receives `isSubagent`/`agentName` and can trim today.
+ *  - `disallowedTools` → `denyTools` (sema name), with the DELEGATION-tool entry tracking the deployment's
+ *    actual tool name (default "Agent" = CC-verbatim). "Artifact"/"ExitPlanMode" have first-party sema
+ *    referents only partially (present_plan canonicalizes to ExitPlanMode; Artifact has none) — a deny of
+ *    an unmounted name is a documented no-op (tool-filter), kept for CC listing-tail byte parity.
+ */
+/** CC 198 `nbm` (pretty.js:409173) — Explore `whenToUse`, verbatim. */
+export const EXPLORE_WHEN_TO_USE = 'Fast read-only search agent for locating code. Use it to find files by pattern (eg. "src/components/**/*.tsx"), grep for symbols or keywords (eg. "API endpoints"), or answer "where is X defined / which files reference Y." Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: "quick" for a single targeted lookup, "medium" for moderate exploration, or "very thorough" to search across multiple locations and naming conventions.';
+/** CC 198 `rbm` (pretty.js:409174) — Explore `whenToUseLean`, verbatim. */
+export const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
+/** CC 198 Plan `whenToUse` (pretty.js:486945), verbatim (Plan has no lean variant in 198). */
+export const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
+/** CC 198 `tbm()` (pretty.js:409122-409160) — Explore persona, unix+Glob/Grep arm, first sentence de-branded. */
+export const EXPLORE_SYSTEM_PROMPT = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.`;
+/** CC 198 `kBm()` (pretty.js:486874-486930) — Plan persona, unix arm, first sentence de-branded. */
+export const PLAN_SYSTEM_PROMPT = `You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using Glob, Grep, and Read
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts
+- path/to/file2.ts
+- path/to/file3.ts
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.`;
+/**
+ * CC 198 `disallowedTools:[is,NR,s0,xa,Ic,FR]` (pretty.js:409189 Explore / :486948 Plan) — the six-tool
+ * deny set shared by both read-only built-ins, constants resolved 亲核: is="Agent"(147382),
+ * NR="Artifact"(143265), s0="ExitPlanMode"(149770), xa="Edit"(143358), Ic="Write"(143375),
+ * NotebookEdit FR(143373). The delegation-tool entry is parameterized on the deployment's actual tool
+ * name (default = "Agent", CC-verbatim).
+ */
+export const BUILTIN_READONLY_DENY_TOOLS = (delegationToolName = DEFAULT_DELEGATION_TOOL_NAME) => [
+    delegationToolName,
+    "Artifact",
+    "ExitPlanMode",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+];
+/**
+ * Build the built-in agent definitions offered by {@link import("./subagent.js").createSubagentTool}
+ * (CC `HCe` registry analog, SDK arm: Explore + Plan; general-purpose is sema's OMITTED-`subagent_type`
+ * fallback and fork lives in the `subagent_type` value domain — neither needs a definition here).
+ * A deployment definition of the same name SHADOWS a built-in (fork-shadowing precedent), and
+ * `builtinAgents: false` removes them wholesale (CC `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` form).
+ */
+export function builtinAgentDefinitions(delegationToolName = DEFAULT_DELEGATION_TOOL_NAME) {
+    const denyTools = BUILTIN_READONLY_DENY_TOOLS(delegationToolName);
+    return [
+        {
+            name: "Explore",
+            whenToUse: EXPLORE_WHEN_TO_USE,
+            whenToUseLean: EXPLORE_WHEN_TO_USE_LEAN,
+            denyTools,
+            systemPrompt: EXPLORE_SYSTEM_PROMPT,
+            // model omitted = inherit the caller's model (CC `model:"inherit"`; the firstParty opus upshift GAe is not ported).
+        },
+        {
+            name: "Plan",
+            whenToUse: PLAN_WHEN_TO_USE,
+            denyTools: [...denyTools],
+            systemPrompt: PLAN_SYSTEM_PROMPT,
+        },
+    ];
+}
+//# sourceMappingURL=builtin-agents.js.map

package/dist/agents/builtin-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.js","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"AAEA;4FAC4F;AAC5F,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAC9B,+lBAA+lB,CAAC;AAElmB,2EAA2E;AAC3E,MAAM,CAAC,MAAM,wBAAwB,GACnC,oZAAoZ,CAAC;AAEvZ,8FAA8F;AAC9F,MAAM,CAAC,MAAM,gBAAgB,GAC3B,oOAAoO,CAAC;AAEvO,iHAAiH;AACjH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iFAgC4C,CAAC;AAElF,oGAAoG;AACpG,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iJAiD+G,CAAC;AAElJ;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,qBAA6B,4BAA4B,EAAY,EAAE,CAAC;IAClH,kBAAkB;IAClB,UAAU;IACV,cAAc;IACd,MAAM;IACN,OAAO;IACP,cAAc;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,qBAA6B,4BAA4B;IAC/F,MAAM,SAAS,GAAG,2BAA2B,CAAC,kBAAkB,CAAC,CAAC;IAClE,OAAO;QACL;YACE,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,mBAAmB;YAC9B,aAAa,EAAE,wBAAwB;YACvC,SAAS;YACT,YAAY,EAAE,qBAAqB;YACnC,oHAAoH;SACrH;QACD;YACE,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,gBAAgB;YAC3B,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC;YACzB,YAAY,EAAE,kBAAkB;SACjC;KACF,CAAC;AACJ,CAAC"}

package/dist/agents/cascade.d.ts

@@ -0,0 +1,101 @@
+import type { Runner } from "../core/runner/runtask.js";
+import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
+/**
+ * Quality-gate cascade (design/27). Run the SAME task across a ladder of models (cheapest → strongest);
+ * after each rung a caller-supplied **decidable gate** judges "good enough" — pass = keep it, fail =
+ * escalate to the next rung. Classic FrugalGPT cascade, as a thin function over `runner.runTask`
+ * (no Runner-core changes).
+ *
+ * APPLICABILITY: cascade only helps when the gate is **decidable** (a schema check, a verifier model, a
+ * concrete assertion). Open-ended "completeness" tasks (find every bug, writing quality) have no oracle —
+ * the gate keeps passing the first plausible cheap answer and escalation idles. Those want breadth /
+ * adversarial debate (a `team`), not a depth ladder.
+ *
+ * Cost note (design/27 §2): each rung is an independent COLD `runTask` — every escalation repays the
+ * full input cost. Cascade wins when (a) the cheap rung usually passes and (b) the prompt isn't so large
+ * that the restart tax dominates. It is NOT always cheaper than running the strongest model directly.
+ *
+ * Boundary vs teacher mode: teacher injects advice and continues the SAME session (recovery); cascade
+ * does independent re-runs on a model ladder (breadth). Orthogonal, not merged.
+ */
+/** A gate's verdict: a bare boolean, or `{ pass, diagnostics }` to attach reasoning to `attempts[]`. */
+export type GateVerdict = boolean | {
+    pass: boolean;
+    diagnostics?: string;
+};
+export interface CascadeRung {
+    /** The model this rung runs on. */
+    model: ModelRef;
+    /** Optional per-rung overrides (default: inherit the task's). */
+    overrides?: Partial<Pick<TaskSpec, "limits" | "degrade" | "systemPrompt">>;
+}
+export interface CascadeConfig {
+    /** Model ladder, cheapest → strongest. ≥1 rung; the last rung is the fallback (returned even if it doesn't pass). */
+    ladder: CascadeRung[];
+    /**
+     * Quality gate: given a rung's result, return whether it is good enough (true/`{pass:true}` = keep,
+     * false = escalate). Default: `status === "completed"` — and, if `spec.outputSchema` is set, also
+     * requires a valid `structuredOutput` (so a schema auto-gives "only keep a rung that actually produced
+     * valid structured output"; a prose-only completion escalates). The gate can be a pure check (structured
+     * output / fields), a verifier model, semantic agreement, etc. **A throw is treated as "did not pass"**
+     * (fail-open to escalate) and recorded as `attempts[].gateError` — so a broken gate can't strand the run,
+     * but a verifier-gate's own failure is still visible. The gate must be decidable (see APPLICABILITY).
+     *
+     * @warning unredacted — the gate receives the UNREDACTED `TaskResult` (model output, structured output,
+     * stats); this is prose advisory, not an enforced boundary (design/54 §3.5, [46] DESIGN1). If your gate
+     * forwards output to an external service, ensure it has no sensitive data or sanitize first.
+     */
+    gate?: (result: TaskResult, rung: {
+        index: number;
+        model: ModelRef;
+    }) => GateVerdict | Promise<GateVerdict>;
+    /** Max escalations (rungs run ≤ maxEscalations + 1). Default = `ladder.length - 1` (the whole ladder). */
+    maxEscalations?: number;
+    /** Stop escalating once cumulative cost reaches this; return the current best. Optional. */
+    costCeilingMicroUsd?: number;
+    /** Overall wall-clock ceiling for the whole cascade (per-rung time is `spec.limits.timeout`). Optional. */
+    totalTimeoutMs?: number;
+    /** Per-rung callback (observability). */
+    onRung?: (info: {
+        index: number;
+        model: ModelRef;
+        passed: boolean;
+        result: TaskResult;
+    }) => void;
+}
+export interface CascadeAttempt {
+    index: number;
+    model: ModelRef;
+    passed: boolean;
+    costMicroUsd: number;
+    status: TaskResult["status"];
+    /** The rung's own failure code (e.g. "auth") if its `runTask` failed — distinct from "gate rejected it". */
+    errorCode?: string;
+    /** Set when the gate THREW (vs returned false) — surfaces a broken verifier-gate (expired key, etc.). */
+    gateError?: string;
+    /** Optional reasoning the gate attached to its verdict. */
+    diagnostics?: string;
+}
+export interface CascadeRunResult extends TaskResult {
+    /**
+     * The cascade's conclusion, **distinct from the inherited `status`**: `"passed"` = some rung passed the
+     * gate; `"exhausted"` = ladder/guards ran out with no rung passing (the last rung's result is returned,
+     * and its `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`).
+     */
+    cascadeOutcome: "passed" | "exhausted";
+    /** True if the returned result came from a rung after the first (i.e. an escalation happened). */
+    escalated: boolean;
+    /** Which rung (0-based) produced the returned result. */
+    finalRung: number;
+    /** Per-rung audit detail (cost, pass/fail, why). Each attempt's `costMicroUsd` includes that rung's nested
+     *  (delegated) cost; the top-level `stats.costMicroUsd` is the sum of the rungs' OWN cost (nested totals live
+     *  in `stats.nested.costMicroUsd`), so it is NOT the plain sum of `attempts[].costMicroUsd`. */
+    attempts: CascadeAttempt[];
+}
+/**
+ * Side-effect note: `runCascade` runs the task up to N times. If your tools have non-idempotent effects
+ * (`effect: "write"`), those execute once PER rung — ensure idempotency, or gate before the side effect
+ * (e.g. a structured-output gate). `TaskSpec` never guaranteed idempotency; cascade makes it explicit.
+ */
+export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig): Promise<CascadeRunResult>;
+//# sourceMappingURL=cascade.d.ts.map

package/dist/agents/cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/agents/cascade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIvE;;;;;;;;;;;;;;;;;GAiBG;AAEH,wGAAwG;AACxG,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,KAAK,EAAE,QAAQ,CAAC;IAChB,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,aAAa;IAC5B,qHAAqH;IACrH,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5G,0GAA0G;IAC1G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2GAA2G;IAC3G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;CAClG;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD;;;;OAIG;IACH,cAAc,EAAE,QAAQ,GAAG,WAAW,CAAC;IACvC,kGAAkG;IAClG,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;;oGAEgG;IAChG,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAeD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC,CA6K3B"}

package/dist/agents/cascade.js

@@ -0,0 +1,189 @@
+import { releaseSession } from "./session-util.js";
+import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+/**
+ * Default gate: the rung must have `status === "completed"` — AND, when the task asked for structured
+ * output (`spec.outputSchema` set), it must actually have produced a valid `structuredOutput`. So a
+ * caller who sets a schema automatically gets "only keep a rung that returned valid structured output"
+ * (a cheap rung that completes with prose-only escalates instead of silently passing). Override `gate`
+ * to change this.
+ */
+function makeDefaultGate(spec) {
+    const requiresStructured = spec.outputSchema != null;
+    return (result) => result.status === "completed" && (!requiresStructured || result.structuredOutput !== undefined);
+}
+/**
+ * Side-effect note: `runCascade` runs the task up to N times. If your tools have non-idempotent effects
+ * (`effect: "write"`), those execute once PER rung — ensure idempotency, or gate before the side effect
+ * (e.g. a structured-output gate). `TaskSpec` never guaranteed idempotency; cascade makes it explicit.
+ */
+export async function runCascade(runner, spec, config) {
+    const ladder = config.ladder;
+    if (!ladder || ladder.length === 0) {
+        throw new Error("runCascade: config.ladder must have at least one rung");
+    }
+    const maxEscalations = config.maxEscalations ?? ladder.length - 1;
+    const maxRungs = Math.min(ladder.length, Math.max(0, maxEscalations) + 1);
+    const gate = config.gate ?? makeDefaultGate(spec);
+    const startedAt = Date.now();
+    const attempts = [];
+    let totalCost = 0; // ceiling check: OWN + nested costMicroUsd (total spend across rungs)
+    // R-5 (round-3 council): keep OWN and NESTED stats DISJOINT (teacher A-7 convention — a consumer adds
+    // `stats.X + stats.nested.X` for the true total). B-5 wrongly folded nested INTO the own totals (= double-
+    // count once `stats.nested` is also reported). Accumulate every own field separately + a nested object;
+    // recalc cacheHitRate from cumulative own prompt/cached. (Was: only tokens/turns/costMicroUsd/costUsd, and
+    // those mistakenly included nested.)
+    let ownTokens = 0, ownTurns = 0, ownPrompt = 0, ownCached = 0, ownOutput = 0, ownCostMicro = 0, ownCostUsd = 0;
+    let ownCacheWrite = 0, ownCacheWriteLong = 0; // additive across rungs (mirror teacher finalize) — else the spread leaks the last rung's value as cumulative
+    let nestedTokens = 0, nestedTurns = 0, nestedTasks = 0, nestedCostMicro = 0, nestedCostUsd = 0;
+    // costBreakdown sub-fields + humanReview accumulate across rungs too — else the cumulativeStats spread leaks
+    // the LAST rung's value, so costBreakdown stops reconciling with the cumulative costMicroUsd (R3 bug-hunt).
+    let ownLlmRootMicro = 0, ownCompactionMicro = 0;
+    let hrCount = 0, hrWaitMs = 0;
+    const hrGates = [];
+    // Build the cumulative stats object over a base (last rung's stats) — own fields cumulative, nested
+    // disjoint. Closure captures the running accumulators (read at call time, after the loop).
+    const cumulativeStats = (baseStats) => ({
+        ...baseStats,
+        tokens: ownTokens,
+        turns: ownTurns,
+        promptTokens: ownPrompt || undefined,
+        totalInputTokens: ownPrompt || undefined,
+        cachedTokens: ownCached || undefined,
+        outputTokens: ownOutput || undefined,
+        cacheWriteTokens: ownCacheWrite || undefined,
+        cacheWriteTokensLong: ownCacheWriteLong || undefined,
+        cacheHitRate: ownPrompt > 0 ? ownCached / ownPrompt : undefined,
+        costMicroUsd: ownCostMicro,
+        costUsd: ownCostUsd || undefined,
+        nested: nestedTokens > 0 || nestedTasks > 0
+            ? { tokens: nestedTokens, turns: nestedTurns, tasks: nestedTasks, costMicroUsd: nestedCostMicro || undefined, costUsd: nestedCostUsd || undefined }
+            : undefined,
+        // Cumulative breakdown (mirrors assemble-result's base), so `llmRoot + nestedSubagent + compaction` still
+        // reconciles to the cumulative LLM total instead of describing only the last rung.
+        costBreakdown: {
+            llmRootMicroUsd: ownLlmRootMicro,
+            nestedSubagentMicroUsd: nestedCostMicro,
+            memoryConsolidationMicroUsd: 0, // filled async after consolidation, same as assemble-result's base
+            compactionMicroUsd: ownCompactionMicro,
+        },
+        humanReview: hrCount > 0 ? { count: hrCount, totalWaitMs: hrWaitMs, gates: hrGates } : undefined,
+    });
+    let lastResult;
+    let passedRung = -1;
+    // Each rung is an independent cold re-run in its OWN session (no carry-forward in v1) — strip `sessionId`
+    // once up front rather than re-destructuring `spec` every rung.
+    const { sessionId: _drop, ...specBase } = spec;
+    for (let i = 0; i < maxRungs; i++) {
+        // Before escalating (any rung past the first), honor the cost/time ceilings.
+        if (i > 0) {
+            if (config.totalTimeoutMs != null && Date.now() - startedAt >= config.totalTimeoutMs)
+                break;
+            if (config.costCeilingMicroUsd != null && totalCost >= config.costCeilingMicroUsd)
+                break;
+        }
+        const rung = ladder[i];
+        const result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}) });
+        lastResult = result;
+        // rungCost (ceiling + reported attempt cost) = total spend = own + nested.
+        const s = result.stats;
+        const rungCost = (s.costMicroUsd ?? 0) + (s.nested?.costMicroUsd ?? 0);
+        totalCost += rungCost;
+        // R-5: own fields cumulative (disjoint from nested).
+        ownTokens += s.tokens;
+        ownTurns += s.turns;
+        ownPrompt += s.promptTokens ?? 0;
+        ownCached += s.cachedTokens ?? 0;
+        ownOutput += s.outputTokens ?? 0;
+        ownCacheWrite += s.cacheWriteTokens ?? 0;
+        ownCacheWriteLong += s.cacheWriteTokensLong ?? 0;
+        ownCostMicro += s.costMicroUsd ?? 0;
+        ownCostUsd += s.costUsd ?? 0;
+        if (s.costBreakdown) {
+            ownLlmRootMicro += s.costBreakdown.llmRootMicroUsd;
+            ownCompactionMicro += s.costBreakdown.compactionMicroUsd;
+        }
+        if (s.humanReview) {
+            hrCount += s.humanReview.count;
+            hrWaitMs += s.humanReview.totalWaitMs;
+            hrGates.push(...s.humanReview.gates);
+        }
+        if (s.nested) {
+            nestedTokens += s.nested.tokens;
+            nestedTurns += s.nested.turns;
+            nestedTasks += s.nested.tasks;
+            nestedCostMicro += s.nested.costMicroUsd ?? 0;
+            nestedCostUsd += s.nested.costUsd ?? 0;
+        }
+        // design/45 §11 Q6 hard boundary: a rung that suspended on a durable approval gate can't be driven
+        // from inside the cascade. Stop immediately — do NOT escalate/re-run (side effects) and do NOT
+        // release its (pinned) session (that would orphan the checkpoint). Surface it to the top-level caller
+        // with the token so they can resume. Attempts so far are reported; this rung counts as the final one.
+        if (isDurablePause(result.status)) {
+            const mapped = mapNestedSuspend(result); // design/80 D-B: covers needs_review/plan_review too, with the right code
+            attempts.push({ index: i, model: rung.model, passed: false, costMicroUsd: rungCost, status: result.status, errorCode: mapped.errorCode });
+            return {
+                ...mapped,
+                stats: cumulativeStats(result.stats),
+                cascadeOutcome: "exhausted",
+                escalated: i > 0,
+                finalRung: i,
+                attempts,
+            };
+        }
+        let passed = false;
+        let gateError;
+        let diagnostics;
+        try {
+            try {
+                const verdict = await gate(result, { index: i, model: rung.model });
+                if (typeof verdict === "boolean")
+                    passed = verdict;
+                else {
+                    passed = verdict.pass;
+                    diagnostics = verdict.diagnostics;
+                }
+            }
+            catch (e) {
+                passed = false; // fail-open: a throwing gate escalates rather than stranding the run
+                gateError = e instanceof Error ? e.message : String(e);
+            }
+            attempts.push({
+                index: i,
+                model: rung.model,
+                passed,
+                costMicroUsd: rungCost,
+                status: result.status,
+                errorCode: result.errorCode,
+                gateError,
+                diagnostics,
+            });
+            // onRung is an observability callback — a throw from it must NOT abort the whole cascade and discard the
+            // result (fail-open, symmetric with the gate's catch above; the finally still releases the session).
+            try {
+                config.onRung?.({ index: i, model: rung.model, passed, result });
+            }
+            catch {
+                /* swallow: a broken observer can't strand the cascade */
+            }
+        }
+        finally {
+            await releaseSession(runner, result.sessionId); // always release, even if onRung throws
+        }
+        if (passed) {
+            passedRung = i;
+            break;
+        }
+    }
+    const base = lastResult; // at least one rung always ran (ladder non-empty)
+    const finalRung = attempts.length - 1;
+    return {
+        ...base,
+        // R-5: every field cumulative across rungs, own/nested disjoint (was: only 4 fields, nested-folded).
+        stats: cumulativeStats(base.stats),
+        cascadeOutcome: passedRung >= 0 ? "passed" : "exhausted",
+        escalated: finalRung > 0,
+        finalRung,
+        attempts,
+    };
+}
+//# sourceMappingURL=cascade.js.map

package/dist/agents/cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.js","sourceRoot":"","sources":["../../src/agents/cascade.ts"],"names":[],"mappings":"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"}