What changed, release by release.

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

    'session.surfaces': readonly RenderSurface[];    'session.authorize': SessionAuthorization;    'session.usage': SessionUsage;    'session.version': SessionVersion;    'turn.abort': void;    'prompt.read': PromptBox;    'tool.list': ToolInfo[];…    'store.set': void;    'store.delete': void;    'store.keys': string[];    'state.get': StateRead;    'state.set': StateSetResult;    'clock.now': number;    'clock.sleep': void;    'clock.after': void;

What a hooks module uses, as the host scanned its source before loading it: the same lists claude plugin validate prints and the host's rule reads.

        reads: readonly string[];        writes: readonly string[];    };    state?: {        reads: readonly StateName[];        writes: readonly StateName[];    };};

Runs one text completion through the session's own API client and resolves a result: the reply's text and cost, or why there is no text.

(request: ModelCompleteRequest) => Promise<string>(request: ModelCompleteRequest) => Promise<ModelCompleteResult>

Runs one tool-less completion over the session's OWN transcript as the main thread last sent it, so the API serves that prefix from its cache.

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

Returns the transcript so far, one SessionMessage per user or assistant message; progress rows, $.ui.log lines and notices are not messages.

() => Promise<SessionMessage[]>SessionMessagesCall

Opens a pane, a framed region the surface places and this plugin draws by hooking ui.render for { component: "Pane" }; says if it is drawn.

(pane: PaneOpenArgs) => Promise<void>(pane: PaneOpenArgs) => Promise<UiOpenResult>

The argument of $.session.messages(args): {} for the main conversation, { agentId } for one of its agents, as for the form.

NoArgsSessionMessagesArgs

The chunk type of each streaming event, by name: what its stream yields.

export type ChunkOf = {    'turn.step': TurnStepChunk;    'process.spawn': ProcessSpawnChunk;};

What a test holds as $, the engine's own: every call on it is made as the REPL, the query loop and the render sites make theirs, over every plugin.

export type Engine = {    [N in keyof EventCalls]: N extends 'ui' ? EngineNoun<N> & EnginePress & EngineMount : EngineNoun<N>;    [N in keyof EventCalls]: N extends 'ui' ? EngineNoun<N> & EnginePress & EngineInput & EngineSelect & EngineMount : EngineNoun<N>;} & {    classic: EngineClassic;};

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

    session: {        start: (input: SessionStartInput) => Promise<SessionStartResult>;        receive: (input: SessionReceiveInput) => Promise<SessionReceiveResult>;        send: (input: SessionSendArgs) => Promise<SessionSendResult>;        compact: (input?: SessionCompactArgs) => Promise<SessionCompactResult>;        attach: (input: SessionAttachInput) => Promise<SessionAttachResult>;        detach: (input: SessionDetachInput) => Promise<SessionDetachResult>;

What $.model.complete takes.

    prompt: string;    system?: string;    maxTokens?: number;    effort?: ModelEffort;    timeoutMs?: number;};

What $.model.fork resolves to: a completion's result (ModelCompleteResult) or that there was nothing to fork yet.

export type ModelForkResult = {    text: string;    usage: ModelForkUsage;export type ModelForkResult = ModelCompleteResult | {    isAnswered: false;    reason: 'nothing-to-fork';};

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

export type OpValueOf = {    'model.complete': string;    'model.complete': ModelCompleteResult;    'model.classify': string | undefined;    'model.fork': ModelForkResult | null;    'model.fork': ModelForkResult;    'audio.play': void;    'audio.speak': SpeakResult;    'mcp.call': McpToolResult;…    'session.model': string;    'session.turns': number;    'session.id': string;    'session.messages': SessionMessage[];    'session.messages': SessionMessagesValue;    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.surfaces': readonly RenderSurface[];…    'ui.log': void;    'ui.notice': void;    'ui.invalidate': void;    'ui.open': void;    'ui.open': UiOpenResult;    'ui.close': void;    'ui.panes': readonly UiPane[];    'ui.copy': UiCopyResult;    'ui.blit': UiBlitResult;    'fs.read': string | FsBytes;    'fs.write': void;…    'clock.every': void;    'http.fetch': HttpResponse;    'process.run': ProcessRunResult;    'process.spawn': ProcessSpawnResult;    'settings.read': Settings;    'env.get': string | undefined;    'env.set': void;

A compaction that stands: the conversation as it reads afterwards, and the counts and request usage the engine recorded when it was the one compacting.

    messages: readonly SessionMessage[];    tokensBefore?: number;    tokensAfter?: number;    usage?: ModelUsage;    skip?: undefined;};

The context window broken down as /context breaks it down: the rows, the grid and the lists beneath it, in the SDK's get_context_usage shape.

    skills?: ContextSkills;    autoCompactThreshold?: number;    isAutoCompactEnabled: boolean;    apiUsage: ContextApiUsage | null;    apiUsage: ModelUsage | null;};

The input of session.receive: one inbound delivery, sanitized, before it is queued (a relay's event, a peer's message, a message for an agent).

    origin: SessionReceiveOrigin;    text: string;    event?: SessionReceiveEvent;    agentId?: 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 = {    kind: 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';    kind: 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';} | {    kind: 'peer' | 'coordinator';    plugin?: string;} | {    kind: 'peer' | 'coordinator';    plugin?: string;    teammate: string;    isVerified: boolean;};

What $.session.usage() answers: when the session began, the context window's fill, the account's rate-limit windows and the session's cost.

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

The rest of the chain as a hook on a streaming event receives it: Next, except that next(e) is the stream beneath (HookStream), not a promise.

export type StreamNext<N extends StreamingEventName = StreamingEventName, E = Args<N>, O = NextResult<N>, S extends {export type StreamNext<N extends StreamingEventName = StreamingEventName, E = Args<N>, O = EventResult<N>, S extends {    [K in N]?: unknown;} = {    [K in N]: Args<K>;

The events that stream: their hooks are async generators, next(e) is the stream of everything beneath, and the result is what it returns.

export type StreamingEventName = 'turn.step';export type StreamingEventName = 'turn.step' | 'process.spawn';

What a tool.call hook returns and what next(e) and $.tool.call(input) resolve to: the tool's result ({ result, context? }) or { deny }.

    ref?: undefined;    text?: undefined;    isError?: undefined;    isReadOnly?: undefined;} | {    result: ToolResultOf<Name>;    context?: readonly string[];    ref?: number;    text?: string;    isReadOnly?: true;    isError?: undefined;    deny?: undefined;} | {…    text?: string;    ref?: number;    context?: readonly string[];    isReadOnly?: true;    deny?: undefined;};

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).

    result?: unknown;    text?: string;    isError?: true;    agentId?: string;    durationMs?: number;};

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

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

Reads a file and returns its text, or with { as: "bytes" } its bytes as { base64 }.

(path: string) => Promise<string>FsReadCall

Returns { kind, size, mtimeMs, isLink } of the path: what it leads to, and whether it is itself a symbolic link. Rejects when missing.

(path: string) => Promise<FsStat>(path: string, options?: FsStatOptions) => Promise<FsStat>

One pointer event over a Client's region, as surface.onPointer hands it: region-relative cells, and the sub-cell position where known.

    type: ClientPointerType;    x: number;    y: number;    fine?: {        x: number;        y: number;    };    button?: 'left' | 'middle' | 'right';    shift?: true;    alt?: true;

A surface drawing a component instance through the plugins, then driven by key through a handle typed by that surface (Mounted).

export type EngineMount = {    mount: (target: MountTarget) => Promise<MountedClient>;    mount: <P extends RenderSurface, C extends RenderComponent>(target: MountTarget<P, C>) => Promise<Mounted<P, C>>;};

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

        suggest: (input: PromptSuggestArgs) => Promise<PromptSuggestResult>;        section: (input: PromptSectionInput) => Promise<PromptSectionResult>;        context: (input: PromptContextInput) => Promise<PromptContextResult>;        attachment: (input: PromptAttachmentInput) => Promise<PromptAttachmentResult>;    };    skill: {        prompt: (input: SkillPromptInput) => Promise<SkillPromptResult>;

The argument of $.fs.ancestors: the file names to look for in each directory, the file to walk down to, and the directory to walk beneath.

export type FsAncestorsRequest = {    names: readonly string[];    of?: string;    below?: string;};

One entry of $.fs.list: the entry itself, a link not followed.

    name: string;    kind: 'file' | 'dir' | 'other';    size: number;    isLink: boolean;};

What $.fs.stat resolves with: what the path leads to, whether the path itself is a symbolic link, and where it lands when asked.

    kind: 'file' | 'dir' | 'other';    size: number;    mtimeMs: number;    isLink: boolean;    realPath?: string;};

Options of $.http.fetch.

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

The props of Image, the terminal surface's picture leaf: pixels over a box of cells where the terminal can (kitty, Ghostty), the alt elsewhere.

export type ImageProps = {    key?: string;    source: ImageSource;    columns: number;    rows: number;

The picture an Image shows: base64 bytes the plugin holds (at most 2 MiB decoded), or the name of a file or POSIX shared-memory object it does not.

    rgba: string;    width: number;    height: number;} | {    file: string;    format: 'png';    generation?: number;} | {    file: string;    format: 'rgba' | 'rgb';    width: number;    height: number;    generation?: number;} | {    shm: string;    format: 'rgba' | 'rgb';    width: number;    height: number;    generation?: number;};

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

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

What $.ui.mount takes: whose elements the test will act on, the surface that draws, and the component instance the engine asks the plugins for.

export type MountTarget = {export type MountTarget<P extends RenderSurface = RenderSurface, C extends RenderComponent = RenderComponent> = {    plugin: string;    key: string;    surface: P;    component: C;    props: RenderPropsOf[C];    requestId?: string;    columns?: number;    rows?: number;    viewport?: RenderViewport;};

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

    'ui.close': void;    'ui.panes': readonly UiPane[];    'ui.blit': UiBlitResult;    'fs.read': string;    'fs.read': string | FsBytes;    'fs.write': void;    'fs.list': FsEntry[];    'fs.exists': boolean;

The argument of $.ui.open: which pane, its title, whether it asks the person's keyboard, its dialog manners, its size: rows inline, columns docked.

    closeOnEscape?: true;    holdToasts?: true;    rows?: number;    columns?: number;};

What $.ui.press takes: the plugin whose ui.render hook drew the element, the key it gave it, the instance and surface when several, a link.

    plugin: string;    key: string;    requestId?: string;    surface?: RenderSurface;    link?: PressedLink;};

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[];    attachments?: readonly PromptSubmitAttachment[];    context?: readonly string[];    turnId?: string;    wait: boolean;

Everything ui.render can draw: one name per component that has a render site; a matcher narrows on it.

export type RenderComponent = 'AskUserQuestion' | 'UserMessage' | 'AssistantMessage' | 'ToolUse' | 'ToolResult' | 'ToolGroup' | 'CommandOutput' | 'Spinner' | 'TurnDuration' | 'InfoNotice' | 'SessionMode' | 'PromptHint' | 'AbovePrompt' | 'Pane';export type RenderComponent = 'AskUserQuestion' | 'UserMessage' | 'AssistantMessage' | 'ToolUse' | 'ToolResult' | 'ToolGroup' | 'ToolProgress' | 'CommandOutput' | 'Spinner' | 'TurnDuration' | 'InfoNotice' | 'SessionMode' | 'PromptHint' | 'AbovePrompt' | 'Pane';

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

} | {    type: 'Image';    props: ImageProps;    image: {        plugin: string;    };    children?: undefined;} | {    type: 'engine';

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

        isErrored: boolean;        onScreen?: OnScreen | null;    };    ToolProgress: {        tool_use_id: string;        kind: 'background_hint';        hint: string;    };    Spinner: {        word: string;        message: string | null;        suffix: string;        mode: 'requesting' | 'responding' | 'thinking' | 'tool-input' | 'tool-use';    };    TurnDuration: {

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;    isDeferred?: true;    provider: Origin;};

What a tool.describe hook returns: the description the model sees for that tool and, when the hook moves it, where the tool waits (ToolDeferral).

export type ToolDescribeResult = {    description: string;    isDeferred?: ToolDeferral;};

What a plugin's $.ui.blit(args) takes: a Raster's next cells (RasterBlitArgs) or a keyed Image's next source (ImageBlitArgs).

export type UiBlitArgs = {    requestId: string;    key: string;    cells: string;    columns?: number;    rows?: number;};export type UiBlitArgs = RasterBlitArgs | ImageBlitArgs;