What changed, release by release.

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;};

The element constructors each surface draws, by e.surface: what $.ui.resolve(e) resolves to, and what a ui.resolve hook passes on.

        Input: ElementConstructor<InputProps>;        Select: ElementConstructor<SelectProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;    };    desktop: {        div: ElementConstructor<DomProps>;…        Select: ElementConstructor<SelectProps>;        Svg: ElementConstructor<SvgProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;    };};

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

    tool: {        call: ToolCallOverloads;        describe: (input: ToolDescribeInput) => Promise<ToolDescribeResult>;    };    command: {        run: (input: CommandRunArgs) => Promise<CommandRunResult>;        describe: (input: CommandDescribeInput) => Promise<CommandDescribeResult>;    };    prompt: {        submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;

The argument of each event, by event name: what a hook receives as e and what the call on $ takes. Plain data, frozen to every depth.

export type EventOf = EngineEventOf & OpEventOf;export type EventOf = CoreEventOf & NounEventOf;

The hook type per pattern: an event's own (Events), *'s (AnyEventHook), or a glob's over the events it selects (GlobHook), as one conditional type.

export type HookFor<E extends EventName | '*'> = E extends '*' ? AnyEventHook : Events[E & EventName];export type HookFor<P extends Pattern> = P extends '*' ? AnyEventHook : P extends EventName ? Events[P] : GlobHook<P>;

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

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

    b: DomProps & { children?: Children }    Svg: SvgProps    Link: LinkProps & { children?: Children }    Code: CodeProps    Button: {      key?: string      label?: string

What next takes in a matched hook: the variants of e the matcher can match (KeptMembers), as declared, so a rewrite of a pinned field passes.

type KeptEvent<E extends EventName | '*', M> = MatchedNames<E, M> extends infer N extends EventName ? N extends unknown ? KeptMembers<Args<N>, M> : never : never;type KeptEvent<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? KeptMembers<Args<N>, M> : never : never;

The argument a matched hook receives: e narrowed by M (Narrowed), per event the registration covers.

export type MatchedEvent<E extends EventName | '*', M> = MatchedNames<E, M> extends infer N extends EventName ? N extends unknown ? Narrowed<Args<N>, M> : never : never;export type MatchedEvent<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? Narrowed<Args<N>, M> : never : never;

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<E extends EventName | '*', M> = ($: EngineInterface, e: MatchedEvent<E, M>, next: Next<MatchedNames<E, M>, KeptEvent<E, M>, MatchedResult<E, M>, {    [K in MatchedNames<E, M>]: Narrowed<Args<K>, M>;}>) => MatchedResult<E, M> | Promise<MatchedResult<E, M>>;export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: 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 events a matched registration on P covers: the event named, or for a glob every selected event whose input has each key the matcher names.

type MatchedNames<E, M = never> = E extends '*' ? {    [N in EventName]: [M] extends [never] ? N : keyof M extends AnyKeyOf<Args<N>> ? N : never;}[EventName] : E;type MatchedNames<P, M = never> = P extends EventName ? P : {    [N in Selected<P & string>]: [M] extends [never] ? N : keyof M extends AnyKeyOf<Args<N>> ? N : never;}[Selected<P & string>];

What a matched hook returns: the event's result, narrowed by M where the result is a union tagged by the matcher's tag keys.

export type MatchedResult<E extends EventName | '*', M> = MatchedNames<E, M> extends infer N extends EventName ? N extends unknown ? Select<EventResult<N>, Selection<Args<N>, M>> : never : never;export type MatchedResult<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? Select<EventResult<N>, Selection<Args<N>, M>> : never : never;

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 signal: AbortSignal;    readonly is: <M extends N>(name: M, e: unknown) => e is S[M];    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is S[Extract<N, Selected<M>>];    readonly event: N;    readonly origin: string;    readonly trace: readonly TraceEntry<N, E, O>[];};

The events whose argument is exactly NoArgs (session.cwd, a declared plugin noun's () => ...); their overloads come last (LateOverload).

type NoArgsEvent = {    [N in OpEventName]: OpEventOf[N] extends NoArgs ? NoArgs extends OpEventOf[N] ? N : never : never;}[OpEventName];    [N in EventName]: Args<N> extends NoArgs ? NoArgs extends Args<N> ? N : never : never;}[EventName];

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 = {    <E extends EventName | '*'>(event: E, hook: HookFor<E>): void;    <E extends EventName | '*', const M extends Matcher<Args<MatchedNames<E>>>>(event: E, matcher: M, hook: MatchedHook<E, M>): void;    <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;};

The result of a call on $ as its event's hooks see it: { value } (the call's answer) or { deny }.

export type OpEventResult<N extends OpEventName = OpEventName> = {    value: OpValueOf[N];    deny?: undefined;} | {    deny: string;    value?: undefined;};export type OpEventResult<N extends OpEventName = OpEventName> = ValueOrDeny<OpValueOf[N]>;

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

    'tool.register': {        tool: string;    };    'command.list': CommandInfo[];    'command.register': {        command: string;    };    'agent.list': AgentInfo[];    'ui.toast': void;    'ui.status': void;    'ui.log': void;    'ui.notice': void;    'ui.invalidate': void;    'ui.open': void;    'ui.close': void;    'fs.readFile': string;    'fs.writeFile': void;    'fs.listDir': FsEntry[];

How a site instance asks for its ui.render answer: the version it is on, whether a static frame is drawing, and whose submit it serves.

export type RenderAnswerOptions = {    version: number;    version: string;    staticFrame: boolean;    submittedBy?: string;};

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

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

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.

    props: LinkProps;    children?: RenderNode[];} | {    type: 'Code';    props: CodeProps;    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 }).

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

What each event's hook returns, and what its next(e) resolves to, by event name.

export type ResultOf = EngineResultOf & {export type ResultOf = EngineResultOf & ClassicResultOf & {    [N in OpEventName]: OpEventResult<N>;} & {    [N in NounEventName]: NounEventResult<N>;};

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 = StarOverloads & {export type StarNext = OrderedOverloads<EventName> & {    (e: unknown): Promise<unknown>;    readonly signal: AbortSignal;    readonly is: <M extends EventName>(name: M, e: unknown) => e is Args<M>;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Args<Selected<M>>;    readonly event: EventName;    readonly origin: string;    readonly trace: readonly TraceEntry<EventName, unknown, unknown>[];};