experimental-ash 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # experimental-ash
 
+## 0.38.0
+
+### Minor Changes
+
+- e157d85: Tool approval callbacks now receive schema-typed `toolInput`, and raw
+  `defineChannel` calls can advertise typed cross-channel receive args.
+
+### Patch Changes
+
+- 6563a08: Fix flaky `HookConflictError` in the driver loop by using SDK-generated hook tokens for turn completion instead of explicit deterministic tokens that could collide during handler re-entry.
+- 1a962b8: Rename `AshCallbackContext` to `SessionContext` and export a new `ChannelContext<TCtx>` type from `defineChannel`. `ToolContext` and `HookContext` are unchanged aliases that now extend `SessionContext`.
+- f243a3e: Vendor the code-mode runtime and only include its inline worker assets in hosted function bundles when `CODE_MODE=1`.
+
+## 0.37.0
+
+### Minor Changes
+
+- 25ef58e: Reject extra top-level fields passed to core `define*` helpers while preserving literal inference for valid definitions. TypeScript now also enforces documented exclusivity for schedules (`markdown` or `run`) and eval suites (`load` or `cases`, `task.prompt` or `task.messages`).
+
+### Patch Changes
+
+- 8b678cc: Channel event handlers now receive `AshCallbackContext` fields — `ctx.session` (with `turn`/`parent`), `ctx.getSandbox()`, and `ctx.getSkill()`. Channel-specific `continuationToken` and `setContinuationToken` are available at the top level of the event context.
+
 ## 0.36.0
 
 ### Minor Changes

package/README.md

@@ -61,7 +61,7 @@ Runtime accessors live on the subpath that owns the concern:
 - `getSkill(identifier)` — handle for a named skill visible to the current agent (`experimental-ash/skills`)
 - `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`experimental-ash/context`)
 
-The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/typescript-api.md`](./dist/docs/public/typescript-api.md).
+The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/advanced/typescript-api.md`](./dist/docs/public/advanced/typescript-api.md).
 
 ## Tiny Example
 
@@ -121,7 +121,7 @@ CLI commands:
 
 ## Deploying
 
-Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/vercel-deployment.md`](./dist/docs/public/vercel-deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
+Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/advanced/vercel-deployment.md`](./dist/docs/public/advanced/vercel-deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
 
 ## Read Next
 
@@ -129,14 +129,14 @@ These files ship inside the installed package at `node_modules/experimental-ash/
 
 - [Full docs index](./dist/docs/public/README.md) — recommended entry point
 - [Getting Started](./dist/docs/public/getting-started.md) — install, scaffold, and run locally
-- [Project Layout](./dist/docs/public/project-layout.md) — every authored directory in depth
+- [Project Layout](./dist/docs/public/advanced/project-layout.md) — every authored directory in depth
 - [`agent.ts`](./dist/docs/public/agent-ts.md) — agent config reference
-- [TypeScript API](./dist/docs/public/typescript-api.md) — complete `define*` and runtime helper reference
-- [Vercel Deployment](./dist/docs/public/vercel-deployment.md) — deploy to production
+- [TypeScript API](./dist/docs/public/advanced/typescript-api.md) — complete `define*` and runtime helper reference
+- [Vercel Deployment](./dist/docs/public/advanced/vercel-deployment.md) — deploy to production
 
-By authoring concern: [Tools](./dist/docs/public/tools.md) · [Channels](./dist/docs/public/channels/README.md) · [Hooks](./dist/docs/public/hooks.md) · [Skills](./dist/docs/public/skills.md) · [Sandbox](./dist/docs/public/sandbox.md) · [Workspace](./dist/docs/public/workspace.md) · [Connections](./dist/docs/public/connections.md) · [Subagents](./dist/docs/public/subagents.md) · [Schedules](./dist/docs/public/schedules.md) · [Human In The Loop](./dist/docs/public/human-in-the-loop.md) · [Evals](./dist/docs/public/evals.md)
+By authoring concern: [Tools](./dist/docs/public/tools.md) · [Channels](./dist/docs/public/channels/README.md) · [Hooks](./dist/docs/public/advanced/hooks.md) · [Skills](./dist/docs/public/skills.md) · [Sandbox](./dist/docs/public/sandbox.md) · [Workspace](./dist/docs/public/advanced/workspace.md) · [Connections](./dist/docs/public/connections.md) · [Subagents](./dist/docs/public/subagents.md) · [Schedules](./dist/docs/public/schedules.md) · [Human In The Loop](./dist/docs/public/human-in-the-loop.md) · [Evals](./dist/docs/public/advanced/evals.md)
 
-By runtime concern: [Sessions and Streaming](./dist/docs/public/runs-and-streaming.md) · [Session Context](./dist/docs/public/session-context.md) · [Context Control](./dist/docs/public/context-control.md) · [Auth and Route Protection](./dist/docs/public/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/cli-build-and-debugging.md) · [Instrumentation](./dist/docs/public/instrumentation.md)
+By runtime concern: [Sessions and Streaming](./dist/docs/public/advanced/runs-and-streaming.md) · [Session Context](./dist/docs/public/advanced/session-context.md) · [Context Control](./dist/docs/public/advanced/context-control.md) · [Auth and Route Protection](./dist/docs/public/advanced/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/advanced/cli-build-and-debugging.md) · [Instrumentation](./dist/docs/public/advanced/instrumentation.md)
 
 ## Architecture (Internals)
 

package/dist/docs/internals/README.md

@@ -6,7 +6,7 @@ The architecture is a three-layer split:
 - **The harness** does one unit of AI work and returns `{ session, next }`.
 - **The runtime** persists state, follows `next`, streams events, and owns workflow primitives.
 
-All runtime state flows through a single `AshContext` bound by one `AsyncLocalStorage`. Authored code should not know anything about workflow orchestration.
+All runtime state flows through a single `AlsContext` bound by one `AsyncLocalStorage`. Authored code should not know anything about workflow orchestration.
 
 ## Start Here
 

package/dist/docs/internals/context.md

@@ -1,13 +1,13 @@
 # Unified Context
 
-Ash uses a single `AshContext` container bound by one `AsyncLocalStorage` instance. No secondary storage, no custom dehydration, no out-of-band parameter passing.
+Ash uses a single `AlsContext` container bound by one `AsyncLocalStorage` instance. No secondary storage, no custom dehydration, no out-of-band parameter passing.
 
 ## Core Model
 
 `ContextContainer` holds a durable map and a virtual overlay. Reads check the virtual overlay first, then the durable map. Writes always target the durable map.
 
 ```ts
-interface AshContext {
+interface AlsContext {
   get<T>(key: ContextKey<T>): T | undefined;
   require<T>(key: ContextKey<T>): T;
   has<T>(key: ContextKey<T>): boolean;
@@ -26,7 +26,7 @@ ContextReader    { get, require, has }
     ↑ extends
 ContextAccessor  { set, ensure }
     ↑ extends
-AshContext        { entries() }
+AlsContext        { entries() }
 ```
 
 ## Seed Keys

package/dist/docs/internals/core-beliefs.md

@@ -14,7 +14,7 @@ That is why authored identifiers are derived from paths. A file path is a single
 source of truth; a repeated `name` field is a second source that can drift.
 
 The hooks surface (`agent/hooks/`) deliberately reuses the unified
-`AshContext` rather than introducing a parallel state-patch channel:
+`AlsContext` rather than introducing a parallel state-patch channel:
 hooks read and write through `ctx` like every other authored function.
 One context, one set of keys, one place to look when debugging.
 
@@ -36,7 +36,7 @@ and easier to fork accidentally.
 
 ## Context Is A Single Ambient Contract
 
-Ash uses one `AshContext` container for runtime state. Seed keys carry
+Ash uses one `AlsContext` container for runtime state. Seed keys carry
 serializable values across step boundaries; providers derive values for the
 current step. Additional `AsyncLocalStorage` instances or hidden dehydration
 protocols create parallel contracts that agents and humans must rediscover.

package/dist/docs/internals/hooks.md

@@ -17,10 +17,10 @@ inside the agent" and "extension contributed by a plugin": both flow
 through one runtime registry, one `HookContext`, one set of ordering
 rules.
 
-The hooks surface deliberately reuses the unified `AshContext`:
-`HookContext` extends `AshCallbackContext`, giving hooks the same
+The hooks surface deliberately reuses the unified `AlsContext`:
+`HookContext` extends `SessionContext`, giving hooks the same
 context surface tools, providers, and channels get. There is no
-parallel state-patch channel — one `AshContext`, one set of keys, one
+parallel state-patch channel — one `AlsContext`, one set of keys, one
 place to look when debugging.
 
 `HookContext` carries `agent`, `channel`, and `session` (which includes
@@ -200,5 +200,5 @@ documented expectations:
 
 - [Hooks](../public/hooks.md) — author-facing reference
 - [Discovery](./discovery.md) — discovery layout and the unified slot walker
-- [Unified Context](./context.md) — `AshContext` surface shared by hooks
+- [Unified Context](./context.md) — `AlsContext` surface shared by hooks
 - [Message Runtime](./message-runtime.md) — runtime stream events

package/dist/docs/internals/mechanical-invariants.md

@@ -88,7 +88,7 @@ invariant is enforced structurally by the `runStep` ALS-scope split
 ### One Ambient Context Contract
 
 Do not introduce additional `new AsyncLocalStorage()` instances for Ash runtime
-state. Ambient state should flow through the single `AshContext` container and
+state. Ambient state should flow through the single `AlsContext` container and
 its provider/seed model.
 
 Enforcement target: a source-shape test that allowlists the context storage

package/dist/docs/public/README.md

@@ -16,25 +16,25 @@ Important naming note:
 Read in this order:
 
 1. [Getting Started](./getting-started.md)
-2. [Project Layout](./project-layout.md)
+2. [Project Layout](./advanced/project-layout.md)
 3. [`agent.ts`](./agent-ts.md)
-4. [TypeScript API](./typescript-api.md)
-5. [Context Control](./context-control.md)
+4. [TypeScript API](./advanced/typescript-api.md)
+5. [Context Control](./advanced/context-control.md)
 6. [Skills](./skills.md)
 7. [Tools](./tools.md)
 8. [Connections](./connections.md)
-9. [Workspace](./workspace.md)
+9. [Workspace](./advanced/workspace.md)
 10. [Sandboxes](./sandbox.md)
 11. [Channels](./channels/README.md)
 12. [Human In The Loop](./human-in-the-loop.md)
-13. [Session Context](./session-context.md)
-14. [Sessions And Streaming](./runs-and-streaming.md)
+13. [Session Context](./advanced/session-context.md)
+14. [Sessions And Streaming](./advanced/runs-and-streaming.md)
 15. [Subagents](./subagents.md)
 16. [Schedules](./schedules.md)
-17. [Evals](./evals.md)
-18. [Auth And Route Protection](./auth-and-route-protection.md)
-19. [Vercel Deployment](./vercel-deployment.md)
-20. [CLI, Build, And Debugging](./cli-build-and-debugging.md)
+17. [Evals](./advanced/evals.md)
+18. [Auth And Route Protection](./advanced/auth-and-route-protection.md)
+19. [Vercel Deployment](./advanced/vercel-deployment.md)
+20. [CLI, Build, And Debugging](./advanced/cli-build-and-debugging.md)
 
 ## The Public Mental Model
 

package/dist/docs/public/{auth-and-route-protection.md → advanced/auth-and-route-protection.md}

@@ -1,6 +1,7 @@
 ---
 title: "Auth And Route Protection"
 description: "Protect agent routes with HTTP Basic, JWT, OIDC, and Vercel OIDC."
+url: /auth-and-route-protection
 ---
 
 Ash protects its own HTTP routes through the channel layer.

package/dist/docs/public/{cli-build-and-debugging.md → advanced/cli-build-and-debugging.md}

@@ -1,6 +1,7 @@
 ---
 title: "CLI, Build, And Debugging"
 description: "CLI commands: dev, build, info, eval. Debugging techniques."
+url: /cli-build-and-debugging
 ---
 
 Ash's CLI gives you the normal day-to-day workflow for authoring, inspecting, and shipping an app.

package/dist/docs/public/{context-control.md → advanced/context-control.md}

@@ -1,6 +1,7 @@
 ---
 title: "Context Control"
 description: "Author always-on instructions with instructions.md or instructions.ts."
+url: /context-control
 ---
 
 Ash gives you a few different levers for controlling what the model sees and when it sees it.

package/dist/docs/public/{evals.md → advanced/evals.md}

@@ -1,6 +1,7 @@
 ---
 title: "Evals"
 description: "Define eval suites with test cases, scoring rubrics, and automated runs."
+url: /evals
 ---
 
 Evals let you define repeatable checks for an Ash agent and run them with the `ash eval` CLI

package/dist/docs/public/{faqs.md → advanced/faqs.md}

@@ -1,6 +1,7 @@
 ---
 title: "FAQs"
 description: "Frequently asked questions about Ash."
+url: /faqs
 ---
 
 # FAQs

package/dist/docs/public/{hooks.md → advanced/hooks.md}

@@ -1,6 +1,7 @@
 ---
 title: "Hooks"
 description: "Subscribe to lifecycle moments and runtime stream events from agent/hooks/."
+url: /hooks
 ---
 
 Hooks are Ash's authored extension points for the per-turn lifecycle and

package/dist/docs/public/{instrumentation.md → advanced/instrumentation.md}

@@ -1,6 +1,7 @@
 ---
 title: "instrumentation.ts"
 description: "Configure OpenTelemetry exporters and AI SDK span behavior for your agent."
+url: /instrumentation
 ---
 
 `instrumentation.ts` is the single place to configure OpenTelemetry for an Ash agent. It controls

package/dist/docs/public/advanced/meta.json

@@ -0,0 +1,19 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "project-layout",
+    "context-control",
+    "hooks",
+    "auth-and-route-protection",
+    "vercel-deployment",
+    "runs-and-streaming",
+    "session-context",
+    "workspace",
+    "evals",
+    "instrumentation",
+    "cli-build-and-debugging",
+    "typescript-api",
+    "...",
+    "faqs"
+  ]
+}

package/dist/docs/public/{project-layout.md → advanced/project-layout.md}

@@ -1,6 +1,7 @@
 ---
 title: "Project Layout"
 description: "Directory structure and filesystem conventions."
+url: /project-layout
 ---
 
 Ash supports two layouts:

package/dist/docs/public/{runs-and-streaming.md → advanced/runs-and-streaming.md}

@@ -1,6 +1,7 @@
 ---
 title: "Sessions And Streaming"
 description: "The HTTP API, NDJSON event stream, and session lifecycle."
+url: /runs-and-streaming
 ---
 
 Ash is durable and session-based by default.

package/dist/docs/public/{session-context.md → advanced/session-context.md}

@@ -1,6 +1,7 @@
 ---
 title: "Session Context"
 description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
+url: /session-context
 ---
 
 Ash exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers,
@@ -164,10 +165,10 @@ export default defineHook({
 
 ### API
 
-| Method       | Description                                                                      |
-| ------------ | -------------------------------------------------------------------------------- |
-| `get()`      | Read the current value. Returns `initial()` on first access. Throws outside ALS. |
-| `update(fn)` | Apply a function to the current value. Throws outside ALS.                       |
+| Method       | Description                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `get()`      | Read the current value. Returns `initial()` on first access. Throws outside managed scope. |
+| `update(fn)` | Apply a function to the current value. Throws outside managed scope.                       |
 
 ## Where These APIs Work
 
@@ -188,20 +189,18 @@ explaining the required scope.
 
 ## How It Works
 
-All runtime accessors read from the same `AshContext` container bound by a single `AsyncLocalStorage`.
-The framework sets up this context before invoking authored code:
+The framework sets up a context container before invoking authored code:
 
-1. The runtime entry point creates an `AshContext` and populates durable seed keys (auth, session
-   ID, compiled bundle).
-2. Before each step, providers create virtual step-local values (session metadata, sandbox access,
-   skill access) from the current context.
-3. The step callback runs inside the `AsyncLocalStorage` scope, making the context available to
-   all authored code in the call chain.
-4. After the step, framework providers with provider-owned mutable state (for example the sandbox)
-   commit those changes back onto the harness session.
+1. The runtime populates durable seed values (auth, session ID, compiled bundle).
+2. Before each step, the framework derives step-local values (session metadata, sandbox access,
+   skill access) from the durable state.
+3. Authored code runs inside the managed scope, so `ctx` and `defineState` accessors resolve
+   automatically.
+4. After the step, the framework commits mutable state (for example sandbox changes) back to
+   the durable session.
 
-This lifecycle is fully managed by the framework. Authored code only needs to call the public
-accessors.
+This lifecycle is fully managed by the framework. Authored code only needs to use `ctx` and
+the public accessors.
 
 ## What To Read Next
 

package/dist/docs/public/{typescript-api.md → advanced/typescript-api.md}

@@ -1,6 +1,7 @@
 ---
 title: "TypeScript API"
 description: "TypeScript API: defineAgent, defineTool, defineSandbox, and all runtime helpers."
+url: /typescript-api
 ---
 
 This page is the quick reference for Ash's public TypeScript surface.

package/dist/docs/public/{vercel-deployment.md → advanced/vercel-deployment.md}

@@ -1,6 +1,7 @@
 ---
 title: "Vercel Deployment"
 description: "Deploy your agent to Vercel."
+url: /vercel-deployment
 ---
 
 Ash is designed to run locally and on Vercel.

package/dist/docs/public/{workspace.md → advanced/workspace.md}

@@ -1,6 +1,7 @@
 ---
 title: "Workspace"
 description: "Shared filesystem state and the default workspace."
+url: /workspace
 ---
 
 Every Ash session gets a shared runtime workspace exposed to the model as the `bash` tool.

package/dist/docs/public/meta.json

@@ -12,20 +12,7 @@
     "schedules",
     "connections",
     "---",
-    "project-layout",
-    "context-control",
-    "hooks",
-    "auth-and-route-protection",
-    "vercel-deployment",
-    "runs-and-streaming",
-    "session-context",
-    "workspace",
-    "evals",
-    "instrumentation",
-    "cli-build-and-debugging",
-    "typescript-api",
-    "...",
-    "faqs",
+    "advanced",
     "---",
     "research"
   ]

package/dist/src/channel/compiled-channel.d.ts

@@ -3,7 +3,7 @@ import type { RouteHandler, SendFn } from "#channel/routes.js";
 import type { Session } from "#channel/session.js";
 import type { SessionAuthContext } from "#channel/types.js";
 export declare const CHANNEL_SENTINEL: "ash:channel";
-export interface CompiledChannel<TState = undefined> {
+export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<string, unknown>> {
     readonly __kind: typeof CHANNEL_SENTINEL;
     readonly routes: readonly {
         method: string;
@@ -13,7 +13,7 @@ export interface CompiledChannel<TState = undefined> {
     readonly adapter: ChannelAdapter<any>;
     readonly receive?: (input: {
         readonly message: string;
-        readonly args: Readonly<Record<string, unknown>>;
+        readonly args: Readonly<TReceiveArgs>;
         readonly auth: SessionAuthContext | null;
     }, args: {
         send: SendFn<TState>;

package/dist/src/channel/types.d.ts

@@ -248,7 +248,7 @@ export interface Runtime {
      * Starts a new run from a flat platform-shape input.
      *
      * The runtime loads the compiled bundle (using the node id
-     * baked in at construction time), builds the seeded {@link AshContext},
+     * baked in at construction time), builds the seeded {@link AlsContext},
      * and drives the step loop to completion.
      */
     run(input: RunInput): Promise<RunHandle>;

package/dist/src/compiled/.vendor-stamp.json

@@ -6,6 +6,7 @@
     "@chat-adapter/state-memory": "4.29.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
+    "experimental-ai-sdk-code-mode": "1.0.10",
     "@ai-sdk/google": "4.0.0-canary.73",
     "gray-matter": "4.0.3",
     "jose": "6.2.3",
@@ -26,5 +27,5 @@
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "de60e990328c8664beec98bc5e81625ecdc0cdace1ba8bd8aa267bf9bea29af4"
+  "scriptHash": "6a2fa642d99a77617cbfb4e0dc7bbbd774c22d880ea5726a09069c812896bfdd"
 }

package/dist/src/compiled/experimental-ai-sdk-code-mode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/compiled/experimental-ai-sdk-code-mode/index.d.ts

@@ -0,0 +1,144 @@
+import type { ModelMessage, ToolSet } from "ai";
+
+export interface CodeModeInterruptPayload {
+  readonly kind?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface CodeModeContinuation {
+  readonly outerToolCallId: string;
+  readonly [key: string]: unknown;
+}
+
+export interface CodeModePendingContinuation<
+  Payload extends CodeModeInterruptPayload = CodeModeInterruptPayload,
+> {
+  readonly continuation: CodeModeContinuation;
+  readonly interrupt: CodeModeInterruptCore<Payload>;
+  readonly type: "code-mode-pending-continuation";
+  readonly [key: string]: unknown;
+}
+
+export interface CodeModeInterruptCore<
+  Payload extends CodeModeInterruptPayload = CodeModeInterruptPayload,
+> {
+  readonly continuation: CodeModeContinuation;
+  readonly interruptId: string;
+  readonly payload: Payload;
+  readonly type: "code-mode-interrupt";
+}
+
+export interface CodeModeInterrupt<
+  Payload extends CodeModeInterruptPayload = CodeModeInterruptPayload,
+> extends CodeModeInterruptCore<Payload> {
+  readonly pendingContinuation: CodeModePendingContinuation<Payload>;
+}
+
+export interface CodeModeApprovalInterrupt {
+  readonly approvalId: string;
+  readonly continuation: CodeModeContinuation;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly type: "code-mode-approval-required";
+}
+
+export interface CodeModeInterruptExecutionContext<
+  Payload extends CodeModeInterruptPayload = CodeModeInterruptPayload,
+  Resolution = unknown,
+> {
+  readonly interruptId: string;
+  readonly payload: Payload;
+  readonly resolution: Resolution;
+}
+
+export interface CodeModeNestedToolCallEvent {
+  readonly bridgeIndex: number;
+  readonly input: unknown;
+  readonly inputBytes: number;
+  readonly invocationId: string;
+  readonly outerToolCallId: string;
+  readonly replayed?: boolean;
+  readonly startedAtMs: number;
+  readonly toolCallId: string;
+  readonly toolName: string;
+}
+
+export interface CodeModeNestedToolResultEvent {
+  readonly bridgeIndex: number;
+  readonly completedAtMs: number;
+  readonly durationMs: number;
+  readonly error?: unknown;
+  readonly input: unknown;
+  readonly inputBytes: number;
+  readonly invocationId: string;
+  readonly outerToolCallId: string;
+  readonly output?: unknown;
+  readonly outputBytes?: number;
+  readonly replayed?: boolean;
+  readonly startedAtMs: number;
+  readonly status: "fulfilled" | "rejected" | "interrupted" | "approval-required";
+  readonly toolCallId: string;
+  readonly toolName: string;
+}
+
+export interface CodeModeLifecycleHookErrorEvent {
+  readonly event: unknown;
+  readonly hook: string;
+}
+
+export interface CodeModeOptions {
+  readonly approval?: {
+    readonly mode: "interrupt";
+  };
+  readonly lifecycle?: {
+    readonly onHookError?: (
+      error: unknown,
+      event: CodeModeLifecycleHookErrorEvent,
+    ) => void | Promise<void>;
+    readonly onInterrupt?: (event: unknown) => void | Promise<void>;
+    readonly onNestedToolCall?: (event: CodeModeNestedToolCallEvent) => void | Promise<void>;
+    readonly onNestedToolResult?: (event: CodeModeNestedToolResultEvent) => void | Promise<void>;
+  };
+}
+
+export interface CodeModeUnwrappedResult {
+  readonly interrupt?: CodeModeInterrupt | CodeModeApprovalInterrupt;
+  readonly output?: unknown;
+  readonly status: "completed" | "interrupted";
+}
+
+export class CodeModeProtocolError extends Error {
+  readonly code: "CODE_MODE_PROTOCOL_ERROR";
+  readonly details?: unknown;
+  constructor(message: string, details?: unknown);
+}
+
+export function createCodeModeTool(tools: ToolSet, options?: CodeModeOptions): unknown;
+export function continueCodeModeApproval(input: {
+  readonly approvalResponse: unknown;
+  readonly interrupt: CodeModeApprovalInterrupt;
+  readonly options?: CodeModeOptions;
+  readonly tools: ToolSet;
+}): Promise<unknown>;
+export function continueCodeModeInterrupt(input: {
+  readonly interrupt: CodeModeInterrupt;
+  readonly resolution: unknown;
+  readonly options?: CodeModeOptions;
+  readonly tools: ToolSet;
+}): Promise<unknown>;
+export function getCodeModeApprovalResponse(
+  messages: readonly ModelMessage[],
+  interrupt: CodeModeApprovalInterrupt,
+): unknown | undefined;
+export function getCodeModeInterrupt(value: unknown): CodeModeInterrupt | undefined;
+export function isCodeModeApprovalInterrupt(value: unknown): value is CodeModeApprovalInterrupt;
+export function replaceCodeModeInterruptResult(
+  messages: readonly ModelMessage[],
+  pending: CodeModePendingContinuation,
+  finalOutput: unknown,
+): ModelMessage[];
+export function requestCodeModeInterrupt(payload: CodeModeInterruptPayload): never;
+export function toCodeModeApprovalMessages(
+  interrupt: CodeModeApprovalInterrupt,
+): readonly ModelMessage[];
+export function unwrapCodeModeResult(value: unknown): CodeModeUnwrappedResult;