What changed, release by release.

agent.spawn's input as the call takes it: what the Agent tool's caller says; the engine fills the rest.

export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd' | 'background'>>;export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd'>>;

What an agent.spawn hook returns and what next(e) resolves to: the started subagent's { model, agentId }, or { deny: reason }, refusing it.

export type AgentSpawnResult = {    model: string;    text?: string;    isError?: true;    agentId?: string;    deny?: undefined;} | {    deny: string;    model?: undefined;    text?: undefined;    isError?: undefined;    agentId?: undefined;};

The handler on(...).catch(handler) takes for a hook of type F: the hook's ($, e, next), run afresh when it throws, misreturns or overruns.

export type CatchHandler<F> = F extends ($: infer D, e: infer E, next: infer N) => infer R ? ($: D, e: E, next: N & Caught) => R | undefined | Promise<Awaited<R> | undefined> : never;export type CatchHandler<F> = F extends ($: infer D, e: infer E, next: infer N) => infer R ? [R] extends [AsyncGenerator<unknown, unknown, unknown>] ? ($: D, e: E, next: N & Caught) => R : ($: D, e: E, next: N & Caught) => R | undefined | Promise<Awaited<R> | undefined> : never;

command.run's input as a plugin's $.command.run takes it: args may be left out (/command, bare), and origin is the engine's to set.

export type CommandRunArgs = Omit<CommandRunInput, 'origin'>;export type CommandRunArgs = Omit<CommandRunInput, 'origin' | 'args'> & {    args?: string;};

The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) resolves to its result, or to its stream.

export type EventCalls = {    tool: {        call: ToolCallOverloads;        check: (input: ToolCheckArgs) => Promise<ToolCheckResult>;        describe: (input: ToolDescribeInput) => Promise<ToolDescribeResult>;    };    command: {        run: (input: CommandRunArgs) => Promise<CommandRunResult>;        describe: (input: CommandDescribeInput) => Promise<CommandDescribeResult>;    };    config: {        set: (input: ConfigSetArgs) => Promise<ConfigSetResult>;        describe: (input: ConfigDescribeInput) => Promise<ConfigDescribeResult>;    };    prompt: {        submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;…        start: (input: SessionStartInput) => Promise<SessionStartResult>;        receive: (input: SessionReceiveInput) => Promise<SessionReceiveResult>;        compact: (input?: SessionCompactArgs) => Promise<SessionCompactResult>;        attach: (input: SessionAttachInput) => Promise<SessionAttachResult>;        detach: (input: SessionDetachInput) => Promise<SessionDetachResult>;    };    turn: {        start: (input: TurnStartInput) => Promise<TurnStartResult>;        step: (input: TurnStepInput) => Promise<TurnStepResult>;        step: (input: TurnStepInput) => HookStream<TurnStepChunk, TurnStepResult>;        complete: (input: TurnCompleteInput) => Promise<TurnCompleteResult>;    };    ui: {

The hook signature of each event, ($, e, next), as one mapped type over EventOf; a streaming event's is the generator form (StreamHook).

export type Events = {    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;    [E in keyof EventOf]: E extends StreamingEventName ? StreamHook<E> : ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;};

What $.ui.invalidate takes: a render event, or one of the five events whose answers the engine caches for the session.

export type InvalidatableEventName = RenderEventName | 'prompt.section' | 'prompt.context' | 'tool.describe' | 'command.describe';export type InvalidatableEventName = RenderEventName | 'prompt.section' | 'prompt.context' | 'tool.describe' | 'command.describe' | 'config.describe';

The hook on(pattern, matcher, hook) takes: ($, e, next) with e narrowed by the matcher (MatchedEvent), and a tagged result the same way.

export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {export type MatchedHook<P extends Pattern, M> = P extends StreamingEventName ? MatchedStreamHook<P, M> : ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {    [K in MatchedNames<P, M>]: Narrowed<Args<K>, M>;}>) => MatchedResult<P, M> | Promise<MatchedResult<P, M>>;

What each call on $ answers (the value of its event's result), by event name.

    'session.messages': SessionMessage[];    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.surfaces': readonly RenderSurface[];    'session.authorize': SessionAuthorization;    'session.usage': SessionUsage;    'turn.abort': void;…    'command.register': {        command: string;    };    'config.list': ConfigRow[];    'agent.list': AgentInfo[];    'ui.toast': void;    'ui.status': void;

prompt.submit's input as a plugin's call takes it: origin, turnId and wait are the engine's to set, context the hooks' to attach.

export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' | 'turnId' | 'wait'>;export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' | 'turnId' | 'wait' | 'context'>;

The input of prompt.submit: the prompt as typed, after the input became a user message and before it enters the session.

export type PromptSubmitInput = {    text: string;    attachments?: readonly PromptAttachment[];    context?: readonly string[];    turnId?: string;    wait: boolean;    origin: PromptOrigin;

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

        title: string;        isFocused: boolean;        bodyColumns: number;        placement: 'dock' | 'inline';        scroll: SiteScroll;    };};

One settled run of a link beneath the caller, as next.trace lists it: data, not a handle.

    readonly outcome: TraceOutcome;    readonly reason?: string;    readonly ms: number;    readonly chunks?: number;    readonly received: E;    readonly returned: O | undefined;};

What every turn.complete carries whatever its reason: the answer, the duration, the interrupt flag, the turn's id, its loop and what it cost.

    durationMs: number;    isAborted: boolean;    turnId: string;    agentId?: string;    usage?: TurnUsage;};

The input of turn.step: one model request inside a turn, at the moment the engine is about to send it; the bottom of the chain sends it.

export type TurnStepInput = {    turnId: string;    index: number;    answer: string;    toolUses: readonly TurnStepToolUse[];    stopReason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'compaction' | 'refusal' | 'model_context_window_exceeded';    usage?: TurnUsage;    model: string;    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number;    messageCount: number;};

What a turn.step hook returns and what next(e) resolves to: the model's response to the step's request, once its blocks are all in.

export type TurnStepResult = {    turnId: string;    index: number;    usage?: TurnUsage;    answer: string;    toolUses: readonly TurnStepToolUse[];    stopReason: TurnStopReason;    usage: TurnUsage | null;};

Runs one tool-less completion over the session's OWN transcript, sharing the main thread's prompt cache; the reply's text and the fork's usage.

(request: ModelForkRequest) => Promise<ModelForkReply | null>(request: ModelForkRequest) => Promise<ModelForkResult | null>

Asks the user question in the engine's own AskUserQuestion dialog and resolves to the label they chose, or the text typed under "Other".

(question: string, options?: readonly string[] | AskProps) => Promise<string>(question: string, options?: readonly string[] | AskOptions) => Promise<string>

Fires when a Button a render hook drew is pressed on a surface; e is { plugin, element, component, surface }, element the button's key.

UiPressInputUiPressArgument

The input of command.describe: how one slash command presents in the typeahead and /help, at the moment the engine lists it.

type CommandDescribeInput = {export type CommandDescribeInput = {    command: string;    description: string;    argumentHint?: string;

What a command.describe hook returns: the description, hint and hidden flag the menu uses; the name, immediate and provider stay as they were.

type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;export type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;

One slash command as $.command.list() returns it.

type CommandInfo = {export type CommandInfo = {    name: string;    description: string;    source: CommandSource;

command.run's input as a plugin's $.command.run takes it: origin is the engine's to set (the calling plugin's name).

type CommandRunArgs = Omit<CommandRunInput, 'origin'>;export type CommandRunArgs = Omit<CommandRunInput, 'origin'>;

The input of command.run: one slash command about to run, the way the person typed it (/name args), and where the run came from.

type CommandRunInput = {export type CommandRunInput = {    command: string;    args: string;    origin: PromptOrigin;

What a command.run hook returns and what next(e) and $.command.run resolve to: the command's output text, when it has one.

type CommandRunResult = {export type CommandRunResult = {    text?: string;    ref?: number;};

Where a slash command comes from, as $.command.list() tells them apart.

type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';export type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';

What $.command.register takes: the slash command this plugin serves.

type CommandSpec = {export type CommandSpec = {    name: string;    description: string;    argumentHint?: string;

The element constructors each surface draws, by e.surface: what $.ui.resolve(e) returns and a ui.resolve hook passes on; no globals.

        Code: ElementConstructor<CodeProps>;        Client: ElementConstructor<ClientProps>;    };    mobile: {        Box: ElementConstructor<BoxProps>;        Text: ElementConstructor<TextProps>;        Button: ElementConstructor<ButtonProps>;        Svg: ElementConstructor<SvgProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;    };};

The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) dispatches the event and resolves to its result.

    };    prompt: {        submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;        fill: (input: PromptFillArgs) => Promise<PromptFillResult>;        suggest: (input: PromptSuggestArgs) => Promise<PromptSuggestResult>;        section: (input: PromptSectionInput) => Promise<PromptSectionResult>;        context: (input: PromptContextInput) => Promise<PromptContextResult>;    };

The hook signature of each event, ($, e, next), as one mapped type over EventOf.

export type Events = {    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Args<E>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;};

The hook on(pattern, hook) takes for a glob or a negation: one function placed on every selected event, e and the result typed as their union.

export type GlobHook<P extends Pattern, N extends EventName = Selected<P>> = ($: EngineInterface, e: Args<N>, next: GlobNext<P>) => EventResult<N> | Promise<EventResult<N>>;export type GlobHook<P extends Pattern, N extends EventName = Selected<P>> = ($: EngineInterface, e: Frozen<Args<N>>, next: GlobNext<P>) => EventResult<N> | Promise<EventResult<N>>;

next in a hook on a glob or a negation: an overload per selected event, then one over their union for an e not yet narrowed.

    (e: Args<N>): Promise<GlobNextResult<N>>;    readonly to: (e: Args<N>, tier: TargetTier) => Promise<GlobNextResult<N>>;    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Args<Extract<N, Selected<M>>>;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<Args<Extract<N, Selected<M>>>>;    readonly event: N;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, Args<N>, GlobNextResult<N>>[];

Options of $.http.fetch.

    method?: string;    headers?: Record<string, string>;    body?: string;    auth?: string;};

The hook on(pattern, matcher, hook) takes: ($, e, next) with e narrowed by the matcher (MatchedEvent), and a tagged result the same way.

export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: MatchedEvent<P, M>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {    [K in MatchedNames<P, M>]: Narrowed<Args<K>, M>;}>) => MatchedResult<P, M> | Promise<MatchedResult<P, M>>;

The rest of the chain, as one hook receives it: made once per dispatch per hook, frozen; next(e) resolves to the downstream result.

        (e: E, tier: TargetTier): Promise<O>;    };    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is S[Extract<N, Selected<M>>];    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<S[Extract<N, Selected<M>>]>;    readonly event: N;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, E, O>[];

What each call on $ answers (the value of its event's result), by event name.

export type OpValueOf = {    'model.complete': string;    'model.classify': string | undefined;    'model.fork': ModelForkReply | null;    'model.fork': ModelForkResult | null;    'audio.play': void;    'audio.speak': SpeakResult;    'mcp.call': McpToolResult;    'session.cwd': string;    'session.model': string;    'session.turnCount': number;    'session.turns': number;    'session.id': string;    'session.messages': SessionMessage[];    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.authorize': SessionAuthorization;    'session.usage': SessionUsage;    'turn.abort': void;    'tool.list': ToolInfo[];

Who raised a dispatch, as next.origin holds it: the calling plugin's name and the tier it sits in; the engine reads engine in core.

type Origin = {export type Origin = {    readonly plugin: string;    readonly tier: Tier;};

The argument of $.ui.close: the pane to close ({ id }). origin is the engine's to set: a plugin's call reads plugin at the hooks.

type PaneCloseArgs = Omit<PaneCloseInput, 'origin'>;export type PaneCloseArgs = Omit<PaneCloseInput, 'origin'>;

The input of ui.close: the pane closing and why (PaneCloseOrigin). Closing an id that is not open does nothing.

type PaneCloseInput = {export type PaneCloseInput = {    id: string;    origin: PaneCloseOrigin;};

Why a pane closes, as the engine stamped it at ui.close.

type PaneCloseOrigin = 'plugin' | 'person' | 'unload';export type PaneCloseOrigin = {    kind: 'plugin' | 'person' | 'unload';};

The argument of $.ui.open: which pane, its title, and whether the plugin asks the person's keyboard for it.

type PaneOpenArgs = {export type PaneOpenArgs = {    id: string;    title?: string;    focus?: true;

Options of $.process.run.

type ProcessRunInit = {export type ProcessRunInit = {    cwd?: string;    env?: Record<string, string>;    stdin?: string;

What $.process.run resolves with once the child has exited.

type ProcessRunResult = {export type ProcessRunResult = {    exitCode: number;    stdout: string;    stderr: string;

What an element takes as children, as JSX passes them: a node, a number (drawn as its string), a value the factory drops, or a list that may nest.

export type RenderChildren = RenderNode | readonly RenderChildren[];export type RenderChildren = RenderNode | number | boolean | null | undefined | readonly RenderChildren[];

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

export type RenderPropsOf = {    AskUserQuestion: {        toolName: string;        tool: string;        questions: unknown[];        metadataSource?: string;    };…    };    AssistantMessage: {        text: string;        firstOfReply: boolean;        isFirstOfReply: boolean;    };    ToolUse: {        tool_use_id: string;        toolName: string;        tool: string;        input: unknown;        running: boolean;        errored: boolean;        interrupted: boolean;        isRunning: boolean;        isErrored: boolean;        isInterrupted: boolean;        output?: unknown;    };    ToolResult: {        tool_use_id: string;        toolName: string;        tool: string;        output: unknown;        errored: boolean;        isErrored: boolean;    };    ToolGroup: {        calls: ReadonlyArray<ToolGroupCall>;        active: boolean;        expanded: boolean;        isActive: boolean;        isExpanded: boolean;    };    Spinner: {        word: string;…    };    Pane: {        title: string;        focused: boolean;        isFocused: boolean;        bodyColumns: number;        scroll: SiteScroll;    };

Where a render event's component is drawn: terminal is Ink, which draws the hook's whole tree; desktop (Claude Code Desktop) and mobile (the Claude mobile app) are remote surfaces that draw the tree themselves.

export type RenderSurface = 'terminal' | 'desktop';export type RenderSurface = 'terminal' | 'desktop' | 'mobile';

type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'verification_required' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';

The live context window as the status line reads it: the last API response's input side against the model's window.

type SessionContextUsage = {export type SessionContextUsage = {    tokens?: number;    window: number;    percent?: number;

What the session has cost, as /cost and the status line total it.

type SessionCost = {export type SessionCost = {    usd: number;};

One rate-limit window as the rate-limit notices read it.

type SessionRateLimit = {export type SessionRateLimit = {    kind: string;    percentUsed: number;    resetsAt?: string;

Where an inbound delivery came from, as the bridge classified it from the server's stamps: prompt.submit's e.origin, less what never arrives.

export type SessionReceiveOrigin = 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';export type SessionReceiveOrigin = {    kind: 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';};

The input of session.start: the session the process starts with, read the way $.session reads it at that moment.

export type SessionStartInput = {    cwd: string;    surface: RenderSurface | null;    interactive: boolean;    isInteractive: boolean;};

What $.session.usage() answers: the context window's fill, the account's rate-limit windows and the session's cost, as the status line has them.

type SessionUsage = {export type SessionUsage = {    context: SessionContextUsage;    rateLimits: SessionRateLimit[];    cost?: SessionCost;

What $.settings.read answers: an object keyed as a settings.json is (permissions, env, hooks, model, enabledPlugins, ...).

type Settings = Readonly<Record<string, unknown>>;export type Settings = Readonly<Record<string, unknown>>;

What $.settings.read(args) takes.

type SettingsReadArgs = {export type SettingsReadArgs = {    source?: SettingsSource;};

One source of settings by the name a plugin gives it, lowest precedence first; the engine's own name is the same word with Settings appended.

type SettingsSource = 'user' | 'project' | 'local' | 'flag' | 'policy';export type SettingsSource = 'user' | 'project' | 'local' | 'flag' | 'policy';

Where a site's window sits over the tree a hook drew in it (a pane's body, the band): the engine's to move (the person scrolls), the plugin's to read.

type SiteScroll = {export type SiteScroll = {    offset: number;    bodyRows: number;};

next in a * hook: the set of events is open at runtime, so e is unknown until next.is(pattern, e) narrows it to events it knows.

    (e: unknown): Promise<unknown>;    readonly to: (e: unknown, tier: TargetTier) => Promise<unknown>;    readonly signal: AbortSignal;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Args<Selected<M>>;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Frozen<Args<Selected<M>>>;    readonly event: EventName;    readonly origin: Origin;    readonly trace: readonly TraceEntry<EventName, unknown, unknown>[];

The props of Svg, the desktop and mobile surfaces' vector leaf: the markup is the element's data, as a string is a Text's, drawn isolated.

    alt: string;    width?: number;    height?: number;    interactive?: boolean;    isInteractive?: boolean;};

One tool call of a ToolGroup, as ui.render sees it under calls.

export type ToolGroupCall = {    tool_use_id?: string;    toolName: string;    tool: string;    input: unknown;    running: boolean;    errored: boolean;    interrupted: boolean;    isRunning: boolean;    isErrored: boolean;    isInterrupted: boolean;    output?: unknown;};

One tool_result block of a user message.

export type ToolResultSummary = {    id: string;    tool_use_id: string;    text: string;    isError: boolean;    result?: unknown;

One tool_use block of an assistant message, with its outcome once the transcript holds the call's tool_result (paired by tool_use_id).

export type ToolUseSummary = {    id: string;    name: string;    tool_use_id: string;    tool: string;    input: Record<string, unknown>;    result?: unknown;    text?: string;

What the chain decided for one link, as next.trace names it.

type TraceOutcome = 'caught' | 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';export type TraceOutcome = 'caught' | 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';

What every turn.complete carries whatever its reason: the answer, the duration, the interrupt flag, the turn's id and what the turn cost.

type TurnCompleteFields = {    answer: string;    durationMs: number;    aborted: boolean;    isAborted: boolean;    turnId: string;    usage?: TurnUsage;};

What a model turn, or one response inside it, cost as the API reported it: the four token counts ($.model.fork's usage shape) and the model's id.

type TurnUsage = ModelForkUsage & {export type TurnUsage = ModelForkUsage & {    model: string;};

The argument of ui.input: a change of, or a submit from, an Input a render hook drew. Flat and frozen like every event's.

type UiInputArgument = {export type UiInputArgument = {    plugin: string;    element: string;    component: RenderComponent;    requestId: string;    surface: RenderSurface;    kind: 'change' | 'submit';    value: string;

What a ui.input hook returns and what next(e) resolves to.

type UiInputResult = {export type UiInputResult = {    element: string;    value: string;};

The argument of ui.select: a pick from a Select a render hook drew. Flat and frozen like every event's.

type UiSelectArgument = {export type UiSelectArgument = {    plugin: string;    element: string;    component: RenderComponent;    requestId: string;    surface: RenderSurface;    value: string;};

What a ui.select hook returns and what next(e) resolves to.

type UiSelectResult = {export type UiSelectResult = {    element: string;    value: string;};

The elements of the surface e is drawn on (Elements[e.surface]): a frozen table of constructors, the JSX tags a render hook draws with.

<E extends RenderInput>(e: E) => Promise<Elements[E['surface']]><E extends ResolveInput>(e: E) => Elements[E['surface']]

Fires when the plugins load (not per draw), once per surface, component and plugin: e names the surface and component, never the props.

RenderInputResolveInput

One agent loop of this session as $.agent.list() returns it: a subagent or an in-process teammate.

    description: string;    type: string;    status: string;    parentId?: string;    spawnedBy?: string;    name?: string;};

The input of agent.offer: one agent type, at the moment the engine offers it to the model.

    agent: string;    description: string;    source: string;    provider: Origin;};

The input of agent.spawn (agent-spawn/): what the Agent tool decided about the subagent it is about to start, before its model is resolved.

    prompt: string;    description: string;    subagentType: string;    provider: Origin;    model?: string;    parentModel: string;    parentAgentId?: string;    permissionMode?: string;    background: boolean;    fork: boolean;

The props of Box: the layout, margin, padding and border props of Ink's Box a tree may set (render-site/ RENDER_PROPS), and the two of hover.

export type BoxProps = {    key?: string;    hover?: BoxHoverProps;    flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';    flexGrow?: number;    flexShrink?: number;

The props of Button, every surface's pressable leaf: an address, a label, the closure a press runs, and the label styles a hover overrides.

    label?: string;    hotkey?: string;    plain?: true;    hover?: TextHoverProps;    onPress: () => void;};

The classic (settings) hook events, one per classic event name: e is what the classic hook receives on stdin for that event.

export type ClassicEventOf = {    [E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? ToolCallInput : ClassicHookInputs[E];    [E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? ToolCallEnvelope : ClassicHookInputs[E];};

The input of command.describe: how one slash command presents in the typeahead and /help, at the moment the engine lists it.

    argumentHint?: string;    isHidden: boolean;    immediate: boolean;    provider: Origin;};

What a command.describe hook returns: the description, hint and hidden flag the menu uses; the name, immediate and provider stay as they were.

type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate'>;type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;

The children field every element constructor's props carry, appended beside its own props type: one child, or a list that may nest.

export type ElementChildren = {    children?: RenderNode | readonly RenderNode[];    children?: RenderChildren;};

The element constructors each surface draws, by e.surface: what $.ui.resolve(e) returns and a ui.resolve hook passes on; no globals.

    terminal: {        Box: ElementConstructor<BoxProps>;        Text: ElementConstructor<TextProps>;        div: ElementConstructor<DomProps>;        span: ElementConstructor<DomProps>;        b: ElementConstructor<DomProps>;        Button: ElementConstructor<ButtonProps>;        Input: ElementConstructor<InputProps>;        Select: ElementConstructor<SelectProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;        Client: ElementConstructor<ClientProps>;    };    desktop: {        div: ElementConstructor<DomProps>;        span: ElementConstructor<DomProps>;        b: ElementConstructor<DomProps>;        Box: ElementConstructor<BoxProps>;        Text: ElementConstructor<TextProps>;        Button: ElementConstructor<ButtonProps>;…        Svg: ElementConstructor<SvgProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;        Client: ElementConstructor<ClientProps>;    };};

The events as calls on $, one signature each: $.<noun>.<event>(input) takes the event's input and resolves to its result, from either side.

    };    session: {        start: (input: SessionStartInput) => Promise<SessionStartResult>;        receive: (input: SessionReceiveInput) => Promise<SessionReceiveResult>;        compact: (input?: SessionCompactArgs) => Promise<SessionCompactResult>;    };    turn: {        start: (input: TurnStartInput) => Promise<TurnStartResult>;…    };    ui: {        render: <C extends RenderComponent>(input: RenderInput<C>) => Promise<RenderElement>;        resolve: <E extends RenderInput>(e: E) => Promise<Elements[E['surface']]>;        resolve: <E extends ResolveInput>(e: E) => Elements[E['surface']];    };};

next in a hook on a glob or a negation: an overload per selected event, then one over their union for an e not yet narrowed.

export type GlobNext<P extends Pattern, N extends EventName = Selected<P>> = OrderedOverloads<N> & {    (e: Args<N>): Promise<GlobNextResult<N>>;    readonly to: (e: Args<N>, tier: TargetTier) => Promise<GlobNextResult<N>>;    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Args<Extract<N, Selected<M>>>;    readonly event: N;    readonly origin: string;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, Args<N>, GlobNextResult<N>>[];};

JSX over the element table: every tag is a constructor from $.ui.resolve(e) (const { Box, Text } = $.ui.resolve(e)), typed by its props; there are no intrinsic (string) tags.

namespace JSX {  type Element = RenderElement  type Children = RenderNode | readonly RenderNode[]  type ElementType =    | keyof IntrinsicElements    | ((props: never) => RenderNode | null | undefined)  interface IntrinsicElements {    Box: BoxProps & { children?: Children }    box: BoxProps & { children?: Children }    Text: TextProps & { children?: Children }    text: TextProps & { children?: Children }    div: DomProps & { children?: Children }    span: DomProps & { children?: Children }    b: DomProps & { children?: Children }    Svg: SvgProps    Link: LinkProps & { children?: Children }    Code: CodeProps    Button: {      key?: string      label?: string      hotkey?: string      plain?: true      onPress: () => void      children?: string    }    Input: InputProps    Select: SelectProps  }  type Children = RenderChildren  type ElementType = (props: never) => RenderNode | null | undefined  interface IntrinsicElements {}  interface ElementChildrenAttribute {    children: unknown  }

What matches one value of type V, by the runtime's kinds (matchesWith): a scalar leaf takes the value or a RegExp; an object, a partial of it.

type MatcherOne<V> = unknown extends V ? MatcherData : V extends readonly (infer Item)[] ? MatcherOne<Item> : V extends string ? V | RegExp : V extends number | boolean | null ? V : V extends object ? Matcher<V> : V extends undefined ? never : unknown;type MatcherOne<V> = unknown extends V ? MatcherData : V extends readonly (infer Item)[] ? MatcherOne<Item> : V extends string | number | boolean | null ? V | RegExp : V extends object ? Matcher<V> : V extends undefined ? never : unknown;

The rest of the chain, as one hook receives it: made once per dispatch per hook, frozen; next(e) resolves to the downstream result.

}> = {    <T extends string>(e: E & ToolNamed<T>): Promise<NextResultFor<N, O, T>>;    (e: E): Promise<O>;    readonly to: {        <T extends string>(e: E & ToolNamed<T>, tier: TargetTier): Promise<NextResultFor<N, O, T>>;        (e: E, tier: TargetTier): Promise<O>;    };    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is S[Extract<N, Selected<M>>];    readonly event: N;    readonly origin: string;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, E, O>[];};

Registers hook on the events pattern selects: one by name, every one under a namespace (classic.*), all (*), or all but some (!tool.*).

export type On = {    <P extends Pattern>(pattern: P, hook: NoInfer<HookFor<P>>): void;    <P extends Pattern, const M extends Matcher<Args<MatchedNames<P>>>>(pattern: P, matcher: M, hook: NoInfer<MatchedHook<P, M>>): void;    <P extends Pattern>(pattern: P, hook: NoInfer<HookFor<P>>): Registration<HookFor<P>>;    <P extends Pattern, const M extends Matcher<Args<MatchedNames<P>>>>(pattern: P, matcher: M, hook: NoInfer<MatchedHook<P, M>>): Registration<MatchedHook<P, M>>;};

What each call on $ answers (the value of its event's result), by event name.

    'session.messages': SessionMessage[];    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.usage': SessionUsage;    'turn.abort': void;    'tool.list': ToolInfo[];    'tool.register': {…    'ui.invalidate': void;    'ui.open': void;    'ui.close': void;    'fs.readFile': string;    'fs.writeFile': void;    'fs.listDir': FsEntry[];    'fs.read': string;    'fs.write': void;    'fs.list': FsEntry[];    'fs.exists': boolean;    'fs.stat': FsStat;    'fs.ancestors': readonly FsAncestor[];…    'store.keys': string[];    'http.fetch': HttpResponse;    'process.run': ProcessRunResult;    'settings.read': Settings;    'env.get': string | undefined;    'env.set': void;};

The hooks module's entry: export function register(on, options). on registers hooks; options is the plugin's configuration (PluginOptions).

export type Register = (on: On, options: PluginOptions) => void | Promise<void>;export type Register = (on: On, options: PluginOptions) => unknown;

What a render hook returns, and what next(e) resolves to: a plain-data tree of elements, strings allowed as children of Text and Box.

export type RenderElement = {    type: 'Box' | 'Text' | 'div' | 'span' | 'b';    type: 'Box';    props?: Record<string, string | number | boolean>;    hover?: BoxHoverProps;    children?: RenderNode[];} | {    type: 'Text';    props?: Record<string, string | number | boolean>;    hover?: TextHoverProps;    children?: RenderNode[];} | {    type: 'Button';…        plugin: string;        handle: number;    };    hover?: TextHoverProps;} | {    type: 'Input';    props: {…    props: CodeProps;    children?: undefined;} | {    type: 'Client';    props: ClientProps;    client: {        plugin: string;    };    children?: undefined;} | {    type: 'Svg';    props: SvgProps;    children?: undefined;

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

        hasSurvey: boolean;        isWorking: boolean;        maxRows: number;        scroll: SiteScroll;    };    Pane: {        title: string;        focused: boolean;        bodyColumns: number;        scroll: PaneScroll;        scroll: SiteScroll;    };};

type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens';type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';

One message of the transcript as $.session.messages() returns it.

    text: string;    toolUses: ToolUseSummary[];    toolResults?: ToolResultSummary[];    handle?: string;};

next in a * hook: the set of events is open at runtime, so e is unknown until next.is(pattern, e) narrows it to events it knows.

export type StarNext = OrderedOverloads<EventName> & {    (e: unknown): Promise<unknown>;    readonly to: (e: unknown, tier: TargetTier) => Promise<unknown>;    readonly signal: AbortSignal;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Args<Selected<M>>;    readonly event: EventName;    readonly origin: string;    readonly origin: Origin;    readonly trace: readonly TraceEntry<EventName, unknown, unknown>[];};

The props of Text: the color and style props of Ink's Text a tree may set (render-site/ RENDER_PROPS). Colors are a theme key or a raw color.

export type TextProps = {    hover?: TextHoverProps;    color?: string;    backgroundColor?: string;    dimColor?: boolean;

tool.call's input as the call takes it: tool_use_id and agentId may ride along (a hook passing its event's input on) and are dropped.

export type ToolCallArgs = ToolCallInput extends infer I ? I extends ToolCallInput ? Omit<I, 'tool_use_id'> & ToolCallReserved<I['tool']> : never : never;export type ToolCallArgs = ToolCallEnvelope extends infer I ? I extends ToolCallEnvelope ? Omit<I, 'tool_use_id'> & ToolCallReserved<I['tool']> : never : never;

The input of tool.call: the tool, the id of this call, the tool's arguments beside them (e.command for Bash), and agentId in a subagent.

export type ToolCallInput = BuiltinToolCallInput | McpToolCallInput;export type ToolCallInput = ToolCallEnvelope & AgentLoop;

The input of tool.describe: one tool's description, at the moment the engine first renders the tool's schema for the model.

export type ToolDescribeInput = {    tool: string;    description: string;    provider: Origin;};

One settled run of a link beneath the caller, as next.trace lists it: data, not a handle.

type TraceEntry<N extends EventName = EventName, E = Args<N>, O = NextResult<N>> = {export type TraceEntry<N extends EventName = EventName, E = Args<N>, O = NextResult<N>> = {    readonly index: number;    readonly plugin: string;    readonly tier: Tier;    readonly event: N;    readonly outcome: TraceOutcome;    readonly reason?: string;    readonly ms: number;    readonly received: E;    readonly returned: O | undefined;

What the chain decided for one link, as next.trace names it.

type TraceOutcome = 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';type TraceOutcome = 'caught' | 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';

What every turn.complete carries whatever its reason: the answer, the duration, the interrupt flag, the turn's id and what the turn cost.

    durationMs: number;    aborted: boolean;    turnId: string;    usage?: TurnUsage;};

What a turn.complete hook returns and what next(e) resolves to: { text }; a text other than the answer's is shown beneath it.

export type TurnCompleteResult = {    text: string;    usage?: TurnUsage;};

The input of turn.step: one model response inside a turn, once its blocks are all in: at its first tool result, or at the turn's end.

    answer: string;    toolUses: readonly TurnStepToolUse[];    stopReason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'compaction' | 'refusal' | 'model_context_window_exceeded';    usage?: TurnUsage;};

What a turn.step hook returns and what next(e) resolves to, echoed by core with the step's usage; a hook's value does not change the step.

export type TurnStepResult = {    turnId: string;    index: number;    usage?: TurnUsage;};