{"version":"2.1.319","generated_at":"2026-11-06T01:04:07+00:00","counts":{"nouns":22,"verbs":89,"events":92,"declarations":663},"engine":[{"noun":"plugin","doc":{"desc":["This plugin, as loaded: its manifest name and its directory."],"params":[],"example":[],"returns":[]},"members":[{"name":"name","optional":false,"kind":"verb","sig":"string","doc":{"desc":["From plugin.json; debug-log and `$.ui.log` lines carry it."],"params":[],"example":[],"returns":[]}},{"name":"root","optional":false,"kind":"verb","sig":"string","doc":{"desc":["The plugin's directory (the one holding plugin.json), absolute."],"params":[],"example":[],"returns":[]}}]},{"noun":"ui","doc":{"desc":["Display: a line under an open dialog, a redraw or a repaint, a log line,","panes the surface places, a window or ring, a surface's clipboard."],"params":[],"example":[],"returns":[]},"members":[{"name":"notice","optional":false,"kind":"verb","sig":"(tool_use_id: string, text: string | undefined) => void","doc":{"desc":["Shows `text` as one line under the dialog open for `tool_use_id`, or","removes the line when `text` is undefined.","","Core removes the line when the call resolves. A call that is not open","is refused, as is another plugin's `$.tool.call` run."],"params":[["tool_use_id","the call whose open dialog gets the line"],["text","the line to show; undefined removes it"]],"example":["$.ui.notice(e.tool_use_id, \"checked by my-plugin\"); return next(e)"],"returns":[]}},{"name":"invalidate","optional":false,"kind":"verb","sig":"(event: InvalidatableEventName) => void","doc":{"desc":["Re-runs an event whose results the engine caches: `ui.render` draws the","instances this plugin may draw again; the others drop the cached answers.","","A redraw: ten a second at most, thirty in the terminal for a shown pane,","expanded band and prompt hint (sooner calls fold). A cached answer drops","next turn; a changed tool or section text rewrites what a thread sent,","which loses its thinking and the prompt cache, so do not call it for","these once a thread has sent."],"params":[["event","`ui.render`, or a cached-answer event: `prompt.section`, `prompt.context`, `prompt.attachment`, `tool/command/config.describe`"]],"example":[],"returns":[]}},{"name":"blit","optional":false,"kind":"verb","sig":"(args: UiBlitArgs) => Promise","doc":{"desc":["Repaints a mounted `Raster` this plugin's own render hook drew with new","cells, or swaps a keyed `Image` it drew to a new source; no redraw.","","The surface paints the cells or source at its next frame, so blits","between frames fold into one: up to 120 a second taken, some sixty","shown. An Image swap sends one small command; a resize is a redraw."],"params":[["args","`requestId` (the site), `key`, and `cells` (RasterProps) or `source` (ImageSource); `columns`, `rows` (the mounted size)"]],"example":["$.clock.every(33, () => $.ui.blit({ requestId, key, cells: frame() }))","await $.ui.blit({ requestId: 'browser', key: 'view',"," source: { shm: name, format: 'rgb', width, height } })"],"returns":["`{}` once the cells or source are its next frame, or `{ deny }`"," (not mounted, not this plugin's, another size, cells that do"," not decode, a bad source, or an Image drawing its alt there:"," no placeholder images, or a file this terminal cannot read)"]}},{"name":"resolve","optional":false,"kind":"verb","sig":"(e: E) => Elements[E['surface']]","doc":{"desc":["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.","","A read, not a dispatch: the engine ran `ui.resolve` (the other hooks,","then core) at load, per surface and component. Narrowed `e.surface`:","that table exactly; unnarrowed: the union, so shared names type-check."],"params":[["e","this hook's own `ui.render` argument (its surface and component pick the table)"]],"example":["const { Box, Text } = $.ui.resolve(e)","return {await next(e)}done"],"returns":["the surface's frozen element table (`Elements[e.surface]`)"]}},{"name":"log","optional":false,"kind":"verb","sig":"(text: string, options?: UiLogOptions) => void","doc":{"desc":["Appends one line to the transcript, drawn like a system notice (dim;","not sent to the model), or with `{ to: \"debug\" }` to the debug log alone.","","A row of its own at the next frame, in logging order; a `-p` or SDK","host receives it as `ui_log`; the debug log has it either way, to 10000","characters. Raised as `ui.log`: a hook above may rewrite `e.to`."],"params":[["text","the line's text, of any length: the terminal draws its first 2000 characters, a remote surface 10000"],["options","`to`: `transcript` (the default) or `debug`"]],"example":["$.ui.log(`prompt from ${e.origin.kind}: ${e.text.length} chars`)","$.ui.log(`cache miss for ${e.tool_use_id}`, { to: \"debug\" })"],"returns":[]}},{"name":"ask","optional":false,"kind":"verb","sig":"(question: string, options?: readonly string[] | AskOptions) => Promise","doc":{"desc":["Asks the user `question` in the engine's own AskUserQuestion dialog and","resolves to the label they chose, or the text typed under \"Other\".","","A `tool.call` of `AskUserQuestion` through every hook but the calling","one, drawn by `ui.render` on `AskUserQuestion`; a multi-select answer is","comma-joined. Rejects when dismissed, and in a `-p` run (no one to ask)."],"params":[["question","the question, ending in a question mark"],["options","2-4 option labels, or `{ options, header, multiSelect }`"]],"example":["const mood = await $.ui.ask(\"How careful?\", [\"Bold\", \"Careful\"])"],"returns":["the label chosen, the chosen labels comma-joined, or free text"," typed under \"Other\" (so compare it with the labels exactly)"]}},{"name":"toast","optional":false,"kind":"verb","sig":"(text: string, options?: ToastOptions) => void","doc":{"desc":["Shows `text` for a few seconds under the plugin's name: a small box on","the stack of plugin toasts over the transcript's top right corner.","","A click takes it off, the pointer over it holds it. Where the transcript","is printed into scrollback (nothing to float over) it is one line on the","notification bar. It leaves the transcript and the model untouched."],"params":[["text","the line to show, its first 2000 characters drawn (10000 remotely); an unpaired surrogate half in it is drawn as U+FFFD"],["options","`timeoutMs`: how long it stays (default 4000)"]],"example":["$.ui.toast(`turn took ${Math.round(e.durationMs / 1000)} s`)"],"returns":[]}},{"name":"notify","optional":false,"kind":"verb","sig":"(text: string, options?: NotifyOptions) => Promise","doc":{"desc":["Raises a native notification of `text` through the person's own","notification channel, the one their `preferredNotifChannel` names.","","Their `Notification` hooks run first, reading `plugin_notification`,","then the channel writes. Raised as `ui.notify`; nothing limits how","often. With no terminal the hooks alone run; unbound or exiting, none."],"params":[["text","the notification's body, sent as given, of any length"],["options","`title`: what heads it (default: the plugin's name)"]],"example":["const sent = await $.ui.notify(\"tests passed\", { title: \"CI\" })"],"returns":["`{ isSent: true, channel }`, or `{ isSent: false, reason }`:"," turned off (`disabled`), `no-channel`, `no-surface`, `refused`"]}},{"name":"status","optional":false,"kind":"verb","sig":"(text: string | undefined) => void","doc":{"desc":["Pins `text` as this plugin's status line under the prompt, beside the","engine's own pinned notices, until the next call replaces it.","","One per plugin; `undefined` removes it."],"params":[["text","the line to keep on screen, its first 2000 characters drawn (10000 remotely); undefined clears it"]],"example":["$.ui.status(\"thinking...\"); return next(e)"],"returns":[]}},{"name":"open","optional":false,"kind":"verb","sig":"(pane: PaneOpenArgs) => Promise","doc":{"desc":["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.","","One per id (an open id retitles; a `ui.open` hook may refuse). Asked,","the person's command, prompt or press behind it (not `focus`), it is","placed at any width; unasked, from 144 columns, 110 for one once asked."],"params":[["pane","`id` (1-64 of letters, digits, `_`, `-`), `title`, `focus`, `closeOnEscape` and `holdToasts` (a dialog), `backgroundColor` (what is painted under its body), `rows` / `columns` wanted"]],"example":["await $.ui.open({ id: \"clock\", title: \"Clock\" })","await $.ui.open({ id: \"ask\", focus: true, closeOnEscape: true, rows: 9 })","const opened = await $.ui.open({ id: \"clock\" })","if (!opened.isPlaced) $.ui.log(\"clock: \" + opened.reason)"],"returns":["`{ isPlaced: true }` once drawn (or retitled), else `{ isPlaced:"," false, reason }` (UiOpenResult); `dock` or `inline` is on `Pane` props"]}},{"name":"close","optional":false,"kind":"verb","sig":"(pane: PaneCloseArgs) => Promise","doc":{"desc":["Closes one of the open panes; an id that is not open is left alone.","","Every close raises `ui.close`, `e.origin` naming whose it is: this call","(`plugin`), the person's mark or key (`person`), an unload (`unload`).","A hook answering without `next` keeps the pane open, save on an unload."],"params":[["pane","`id`: the id the pane was opened under"]],"example":["onPress: () => $.ui.close({ id: \"clock\" })"],"returns":["settles once the pane is gone or a hook answered for it;"," rejects on a hook's `{ deny }`"]}},{"name":"panes","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Lists this plugin's own open panes (UiPane): each one's id and title,","and whether it is shown, holds the keyboard, and is placed.","","The engine's record, not the module's: a module reloaded while its","pane stayed up finds it here. Another plugin's panes are not listed."],"params":[],"example":["const isUp = (await $.ui.panes()).some(pane => pane.id === \"clock\")","if (!isUp) await $.ui.open({ id: \"clock\", title: \"Clock\" })"],"returns":["the panes in open order, placed ones first; empty with none"]}},{"name":"place","optional":false,"kind":"verb","sig":"(args: UiPlaceArgs) => Promise","doc":{"desc":["Places one row at the transcript's end, which scrolls with the","conversation and draws what `ui.render` answers for `Placed`.","","A hook reads `e.props.id` and `e.props.plugin`. Display only: the model","and the transcript file never read it, and `--resume` brings none back. A","hook that passes draws nothing; the same id answers the row that stands."],"params":[],"example":["await $.ui.place({ id: \"build\" })"],"returns":[]}},{"name":"scroll","optional":false,"kind":"verb","sig":"(args: UiScrollArgs) => Promise","doc":{"desc":["Scrolls something into view as the DOM's `scrollIntoView` would: a","render instance by `requestId`, an element by `key`, a site's edge.","","A site of this plugin's (its pane, the band it draws into) moves under","the event `ui.scroll`, origin `plugin`. A transcript row moves only","while this call answers the person's own input, where one scrolls."],"params":[["args","`to` (what), `in` (which site, required for `start` and `end`), `block` (where it lands; `nearest` by default)"]],"example":["onPress: () => $.ui.scroll({ in: \"log\", to: \"end\" })"],"returns":["`{}` once it moved, or `{ deny }` saying why not"]}},{"name":"focus","optional":false,"kind":"verb","sig":"(args: UiFocusArgs) => Promise","doc":{"desc":["Moves the focus ring of one of this plugin's sites onto an element it","drew there, as the DOM's `element.focus()`, while it holds the keys.","","Raised as `ui.focus`, origin `plugin`; the engine's inverse marks it.","A site not holding the keys, or holding them on another's element, is","`{ deny }`; an element not yet drawn is awaited, bounded: no retrying."],"params":[["args","`requestId` (which site: a pane's id, the band's) and `key` (the element's, as drawn)"]],"example":["await $.ui.open({ id: \"files\", focus: true })","await $.ui.focus({ requestId: \"files\", key: \"row:0\" })"],"returns":["`{}` once it moved, or `{ deny }` saying why not"]}},{"name":"copy","optional":false,"kind":"verb","sig":"(args: UiCopyArgs) => Promise","doc":{"desc":["Puts `text` on the clipboard of a surface the session draws on, as the","DOM's `navigator.clipboard.writeText`, and says whether it took.","","`surface` names which (a press hook passes `e.surface`); left out, the","session's first. Raised as `ui.copy` with that target on `e`. The","terminal writes as `/copy` does; a remote surface has no path yet."],"params":[["args","`text`, what the person pastes; `surface`, where"]],"example":["onPress: press => $.ui.copy({ text: url, surface: press.surface })"],"returns":["`{ isCopied: true }`, or `{ isCopied: false, reason }`"]}},{"name":"selection","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns what the person last selected with the mouse: the text as a","copy would take it, and the transcript row it lies in.","","A key or a click takes the highlight down before a command or a press","runs, so the answer stays what the person last selected, until they","select again, dismiss it, or their next prompt or command has run."],"params":[],"example":["const selected = await $.ui.selection()"],"returns":["the selection; `undefined` with nothing selected, and where"," none is seen: fullscreen off, -p, a surface that answers none"]}},{"name":"view","optional":false,"kind":"verb","sig":"(view: SiteView) => Promise","doc":{"desc":["Puts an agent's transcript in the main view, as the person's own","switch from the tasks list does; `{}` goes back to the main one.","","Only while the call answers the person's own input (a press, a pick,","their prompt or command): the viewed agent takes the prompt's next","Enter. A site reads the view in force as `e.props.view`."],"params":[["view","`agentId`: the agent's `id` in `$.agent.list()`; absent for the main conversation"]],"example":["onPress: () => $.ui.view({ agentId: agent.id })","onPress: () => $.ui.view({})"],"returns":["`{}` once the view shows it, or `{ deny }` saying why not"]}}]},{"noun":"theme","doc":{"desc":["The session's one theme: how the app looks behind and around the","conversation. One theme stands at a time, the latest set, whichever plugin","set it; there is no stack."],"params":[],"example":[],"returns":[]},"members":[{"name":"set","optional":false,"kind":"verb","sig":"(attributes: ThemeSetArgs) => Promise","doc":{"desc":["Sets the session's theme from one object of named top-level attributes.","`backdrop` is drawn behind the conversation by what `ui.render` answers","for `Backdrop`: full window on desktop under its frosted panels, full","screen on mobile under one veil (`tint` and `opacity`, not yet `blur`).","Display only: `--resume` brings none back and a plugin that unloads","takes its own with it, so set it at `session.start`."],"params":[["attributes","`backdrop`: `id`, `glass` (`blur`, `tint`, `opacity`) or `false`, and `colorScheme` (`light` or `dark`)"]],"example":["await $.theme.set({ backdrop: { id: \"lagoon\", glass: { blur: 14, opacity: 0.55 } } })"],"returns":["`{ isDrawn: true, requestId }`, or `isDrawn: false` and why"]}},{"name":"clear","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Clears the session's theme, back to the app's own look.","","IT CLEARS WHATEVER THEME STANDS, WHICHEVER PLUGIN SET IT: there is one","theme, so a clear is the session's and not the caller's own. Clear on a","person's ask (a command, a button), never at `session.start` or on a","reload: a plugin that clears there wipes another plugin's theme each time."],"params":[],"example":["await $.theme.clear() // a preview ends with no theme to go back to"],"returns":["`isDrawn: false` and why"]}}]},{"noun":"model","doc":{"desc":["Completions through the session's own client and credentials."],"params":[],"example":[],"returns":[]},"members":[{"name":"complete","optional":false,"kind":"verb","sig":"(request: ModelCompleteRequest, options?: ModelCompleteOptions) => Promise","doc":{"desc":["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.","","No tools, no history, no system prompt beyond the CLI's identity block","and `request.system`; ModelCompleteRequest says the rest. Only a request","the engine refuses to send (a blocked model, a bad cap) rejects."],"params":[["request","the model (an alias such as `haiku`, or a full id resolved like `--model`), prompt, cap, effort, time limit"],["options","`signal`: the plugin's own AbortSignal; aborting it cuts the call while it runs, which then resolves `aborted`"]],"example":["const r = await $.model.complete({ model: \"haiku\", prompt, effort })","// one handler starts it, a later one cancels it while it runs","let stop = new AbortController()","const start = async () => {"," stop = new AbortController()"," const r = await $.model.complete(ask, { signal: stop.signal })"," if (!r.isAnswered && r.reason === \"aborted\") $.ui.log(\"cancelled\")","}","const cancel = () => stop.abort()"],"returns":["the reply (`isAnswered`, `text`, `usage`), else the `reason`:"," `api-error` with `status` and `error`, `empty-reply`, `aborted`"]}},{"name":"fork","optional":false,"kind":"verb","sig":"(request: ModelForkRequest) => Promise","doc":{"desc":["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.","","The main thread's last request again (its model, system prompt, tools,","messages) with `prompt` after it: every tool denied, its own tail never","cached, the prefix billed afresh once the entry lapsed or after `/model`.","It thinks as hard as the session does unless `effort` says otherwise;","ModelForkRequest says what holds that level and when it costs the cache."],"params":[["request","the one user message the fork answers, and its effort"]],"example":["const reply = await $.model.fork({ prompt: \"One line to learn?\" })","$.ui.log(reply.isAnswered ? reply.text : `no reply: ${reply.reason}`)","// a quick side job in a session the person runs at max","const cut = await $.model.fork({ prompt: \"Shorter.\", effort: \"low\" })"],"returns":["always a result, never null: the reply (`isAnswered`, `text`,"," `usage`, the `effort` sent), or why there is no text (`reason`:"," `nothing-to-fork` before the first request and after `/clear`,"," `api-error` with its HTTP `status` and `error` kind,"," `empty-reply`, or `aborted` when the turn whose hook forked was"," interrupted); a request of the wrong shape (no prompt, an"," `effort` that is no level) rejects instead"]}},{"name":"classify","optional":false,"kind":"verb","sig":"(text: string, labels: readonly string[], options?: ClassifyOptions) => Promise","doc":{"desc":["Picks one of `labels` for `text` with one completion over","`$.model.complete` and a fixed classifier prompt.","","`text` is data; the model answers with a label alone. It resolves","`undefined` when the answer named none of `labels`. A failed request,","an abort or a reply with no text rejects, naming the cause."],"params":[["text","what to classify"],["labels","the labels to choose from (2 or more)"],["options","`model`: an alias or id; default the engine's small fast model"]],"example":["const kind = await $.model.classify(e.text, [\"bug\", \"feature\"])","if (kind === undefined) return next(e)"],"returns":["the label the model named, or undefined when it named none;"," rejects when the request fails or the reply has no text"]}}]},{"noun":"audio","doc":{"desc":["Sound: clip playback and platform speech."],"params":[],"example":[],"returns":[]},"members":[{"name":"play","optional":false,"kind":"verb","sig":"(clip: AudioClip, options?: PlayOptions) => Promise","doc":{"desc":["Plays one audio clip, starting now; clips are not queued, so two calls","play together (a bed under speech).","","`{ asset }` is the plugin's own file; `afplay` plays it on macOS, and a","Linux or Windows terminal, having no player, plays nothing. Resolves once","played or skipped; rejects, naming the cause, when the clip cannot play."],"params":[["clip","the plugin's own file (`{ asset }`), a URL the engine fetches, or the bytes as base64 with their MIME type"],["options","`shouldLoop`, `gain`, and an AbortSignal that stops the clip"]],"example":["await $.audio.play({ asset: \"sounds/done.wav\" })"],"returns":[]}},{"name":"speak","optional":false,"kind":"verb","sig":"(text: string, options?: SpeakOptions) => Promise","doc":{"desc":["Speaks `text` with the platform's own synthesizer (`say` on macOS).","Plain text.","","Utterances are queued among themselves; clips are not. Resolves when","the utterance has ended; rejects, naming the cause, when there is no","synthesizer, the voice is not installed, or the utterance failed."],"params":[["text","what to say, as plain text"],["options","`voice`: the system voice's exact name (`Samantha`); absent, the synthesizer's default"]],"example":[],"returns":["which synthesizer spoke, once the utterance has ended"]}}]},{"noun":"mcp","doc":{"desc":["The engine's MCP servers: calling a connected one's tools, and","connecting one the plugin lists itself."],"params":[],"example":[],"returns":[]},"members":[{"name":"call","optional":false,"kind":"verb","sig":"(server: string, tool: string, args?: Record) => Promise","doc":{"desc":["Calls `tool` on one of the engine's connected MCP servers with the","engine's own connection and credentials.","","A `cached` server is dialed on first use. No permission prompt: the","plugin's call, seen by the hooks above it, is the grant. Positional, not","the `{ tool: \"mcp__server__tool\", ... }` shape a `tool.call` hook sees."],"params":[["server","the server's name as /mcp lists it (`claude.ai Gmail`; the tool-name spelling `claude_ai_Gmail` is accepted too)"],["tool","the tool's name on that server (`create_draft`)"],["args","the tool's arguments; none when absent"]],"example":["const { content } = await $.mcp.call(\"claude.ai Gmail\", \"create_draft\", {"," to: \"team@example.com\","," subject: \"Release notes\",","})"],"returns":["the tool's result as MCP returns it: `content` blocks and"," `isError`"]}},{"name":"connect","optional":false,"kind":"verb","sig":"(server: string) => Promise","doc":{"desc":["Connects one of the MCP servers this plugin's own manifest lists, if","the session has not already: a listed server joins it at its start.","","So listing a server defers nothing: to hold its tools back, refuse","their calls at `tool.check`. The same server run under another name","answers with that name; a refusal resolves with `reason`, `message`."],"params":[["server","the server's key in this plugin's manifest"]],"example":["const browser = await $.mcp.connect(\"browser\")","if (browser.isConnected) $.mcp.call(browser.server, \"open\", { url })"],"returns":["connected, with the name `call` takes, or why not"]}}]},{"noun":"session","doc":{"desc":["The running session, read as plain data; compacting it; and sending a","message from it to another agent or session."],"params":[],"example":[],"returns":[]},"members":[{"name":"messages","optional":false,"kind":"verb","sig":"SessionMessagesCall","doc":{"desc":["Returns the transcript so far, one SessionMessage per user or assistant","message; progress rows, `$.ui.log` lines and notices are not messages.","","With `{ agentId }`, one of this session's agents' instead (a subagent, a","fork, a teammate in this process): what the session saved for it joined","with what the engine holds. With `{ as: \"api\" }`, either as ApiMessage."],"params":[["args","`agentId`, the id `tool.call`, `turn.complete` and `$.agent .list()` carry; `as: \"api\"` for ApiMessage; hooks see both"]],"example":["const last = (await $.session.messages()).at(-1)","const request = await $.session.messages({ as: \"api\" })","await $.http.fetch(AUDIT_URL, {"," method: \"POST\","," body: JSON.stringify({ session: await $.session.id(), request }),","})","on(\"turn.complete\", async ($, e, next) => {"," if (e.agentId === undefined) return next(e)"," const found = await $.session.messages({ agentId: e.agentId })"," if (!(\"deny\" in found)) $.ui.log(`${found.length} messages`)"," return next(e)","})"],"returns":["the newest 4096 entries, `{ role, text, toolUses }` (a user"," message may add `toolResults`; a `toolUses` entry adds `result`"," and `text` once answered, an Agent tool use its `agentId`), or"," with `as` `{ role, content }`, blocks intact, at most 4096"," opening on a user message; for an `agentId` the session"," cannot read, `{ deny }` (SessionMessagesDeny), never main"]}},{"name":"cwd","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the directory the session runs in, absolute.","","A timer that outlives its hook reads the session's directory; keep the","value read inside the hook if you need the hook's (a subagent's own)."],"params":[],"example":[],"returns":[]}},{"name":"root","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the session's project root, absolute: where it started, or","where `/cd`, a host's directory change or a worktree move took it.","","A shell `cd` during the session does not move it; nested instruction","files are read only beneath it."],"params":[],"example":[],"returns":[]}},{"name":"model","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the main loop's model, as `/model` shows it."],"params":[],"example":[],"returns":[]}},{"name":"turns","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns how many prompts the user has sent this session (user turns in","the transcript)."],"params":[],"example":[],"returns":[]}},{"name":"id","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the session's id (the transcript file's name)."],"params":[],"example":[],"returns":[]}},{"name":"repo","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the git repository the session runs in, read from the working","copy on each call; null when the directory is not inside one."],"params":[],"example":["const repo = await $.session.repo(); const publicRepo = !repo?.internal"],"returns":[]}},{"name":"surfaces","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns every surface the session draws on, each once: `terminal` under","the REPL first, then the remote ones in the order they attached.","","A session may draw on several at once (a terminal and two phones):","clients attach (`session.attach`) and detach, and a render hook still","reads `e.surface` per ask. Empty in a plain -p run; never rejects."],"params":[],"example":["const inApp = (await $.session.surfaces()).some(s => s !== \"terminal\")"],"returns":[]}},{"name":"surface","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the first of `$.session.surfaces()`, or null where nothing","draws."],"params":[],"example":[],"returns":[]}},{"name":"usage","optional":false,"kind":"verb","sig":"(args?: SessionUsageArgs) => Promise","doc":{"desc":["Returns when the session began, and the context window's fill, the","rate-limit windows and the cost as the status line has them, itemized.","","The plain call costs nothing; `\"full\"` counts each category with the","token-count API as /context does, `\"summary\"` estimates locally, and","`context.breakdown` comes back in the SDK's `get_context_usage` shape."],"params":[["args","`{ breakdown, columns }`: how the breakdown is counted and the width its grid is drawn in; nothing for the status line's figures"]],"example":["const { context } = await $.session.usage()","if ((context.percent ?? 0) >= 85) await $.session.compact()","const isOlder = stat.mtimeMs < (await $.session.usage()).startedAt","const usage = await $.session.usage({ breakdown: \"full\", columns })","for (const row of usage.context.breakdown?.gridRows ?? []) draw(row)"],"returns":["`{ startedAt, context, rateLimits, cost }` as the status line"," has them"]}},{"name":"version","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the version of the engine the session runs on, the release it","is built from, and when it was built.","","The same three values the engine's own analytics rows carry, answered","in every mode and build; `base` is absent when the version is not","spelled as a release, `builtAt` in a run from source that stamps none."],"params":[],"example":["const { version, base, builtAt } = await $.session.version()","row.env = { version, version_base: base, build_time: builtAt }","const isRelease = !(await $.session.version()).base?.endsWith(\"-dev\")"],"returns":["the full `version`, its release `base` (`2.1.280`, or"," `2.1.280-dev` for a development build) and an ISO `builtAt`"]}},{"name":"compact","optional":false,"kind":"verb","sig":"EventCalls['session']['compact']","doc":{"desc":["Compacts the conversation: the event `session.compact` with `trigger`","`plugin`, the same call `/compact` makes, between turns.","","It runs through every hook but the calling one, then core: a summary","and the kept messages in the transcript's place. Resolves `{ skip }`","when a hook vetoed it; rejects while a turn runs."],"params":[],"example":["const { skip } = await $.session.compact({ instructions: \"the plan\" })"],"returns":[]}},{"name":"send","optional":false,"kind":"verb","sig":"EventCalls['session']['send']","doc":{"desc":["Sends a plain-text message to another agent or session: the event","`session.send`, the model's SendMessage tool's own call and delivery.","","`to` is the tool's spelling (a name, an agent id, a received `from`","address) or `{ sessionId }` / `{ agentId }`; framed at the receiver as a","peer's, `origin.plugin` naming this plugin there. Resolves once queued."],"params":[],"example":["const sent = await $.session.send({ to: { sessionId }, text: \"ok\" })","await $.session.send({ to: { agentId }, text: \"stop after this file\" })"],"returns":[]}},{"name":"append","optional":false,"kind":"verb","sig":"(args: SessionAppendArgs) => Promise","doc":{"desc":["Appends a row to a conversation of the session: the event","`session.append`, the engine's own call for every row it keeps.","","A user-role row the person does not see as typed or a notice, of text","blocks alone in this release (else refused with the reason): listed at","once. `{ deny: reason }` when a plugin above refused it, nothing stored."],"params":[],"example":["await $.session.append({ message: { type: \"user\", content: [note] } })"],"returns":[]}},{"name":"authorize","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Holds the session's Anthropic credential on the host and answers an","opaque handle and its kind; the secret never reaches the plugin.","","The handle is spent through `$.http.fetch(url, { auth: handle })`,","which sets the credential header, only for a first-party host. Null","with no first-party credential (a 3P provider, a gateway, no login)."],"params":[],"example":["await $.http.fetch(url, { auth: (await $.session.authorize())?.handle })"],"returns":[]}},{"name":"identity","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns how the session is signed in, to a mod the organization's","managed settings install; `{ deny }` to any other. No request is made.","","The account (organization, plan, email) only where managed","`forceLoginOrgUUID` lists its organization; else `kind` alone. A","contract, not a wall: any mod can read the person's own config file."],"params":[],"example":["const { kind, organizationId, email } = await $.session.identity()"],"returns":[]}}]},{"noun":"turn","doc":{"desc":["The running model turn: ending it."],"params":[],"example":[],"returns":[]},"members":[{"name":"abort","optional":false,"kind":"verb","sig":"(input: OpEventOf['turn.abort']) => Promise","doc":{"desc":["Cancels the main loop's running model turn (the id its `turn.start`","handed this plugin), its running tools stopped, no interruption marker.","","The event `turn.abort`, seen by the hooks above; the prompt this","plugin submits next is the context. Rejects, naming both ids, when","`turnId` is not the running turn's; a hook may end its own turn."],"params":[["input","`turnId`: the id the main loop's `turn.start` carried"]],"example":["on(\"turn.start\", ($, e, next) => {"," if (e.agentId === undefined) held = e.turnId"," return next(e)","})"],"returns":[]}}]},{"noun":"prompt","doc":{"desc":["Submitting a prompt the model reads as a user turn, and the person's","prompt box: read as it stands, written, or proposed into."],"params":[],"example":[],"returns":[]},"members":[{"name":"submit","optional":false,"kind":"verb","sig":"EventCalls['prompt']['submit']","doc":{"desc":["Submits a prompt: the event `prompt.submit`, the same call the engine","makes for a typed prompt; a turn of its own, once the session is idle.","","It goes through every hook but the calling one (the plugin's others","see it) with `e.origin` `{ kind: 'plugin', name }`, the name the","model reads it under unless a hook leaves it out of its answer."],"params":[],"example":["void $.prompt.submit({ text: \"List the TODOs you just mentioned.\" })"],"returns":[]}},{"name":"read","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the prompt box as it stands, the draft typed so far and the","cursor's offset into it, so a `fill` can keep what the person typed.","","Never rejects: `{ text: '', cursor: 0 }` where the session draws no box","(a -p run, an SDK host) or none is mounted yet."],"params":[],"example":["const { text, cursor } = await $.prompt.read()"],"returns":[]}},{"name":"media","optional":false,"kind":"verb","sig":"(args: PromptMediaArgs) => Promise","doc":{"desc":["Returns one image or document of the prompt being submitted, by the","`id` `e.attachments` lists it under: its bytes, base64, 4 MiB a call.","","For a `prompt.submit` hook; else `{ deny }`, as once the submission","has settled. The engine's own read, no event: no hook answers for it.","`{ unreadable }`: no image."],"params":[],"example":["const media = id ? await $.prompt.media({ id }) : undefined"],"returns":[]}},{"name":"fill","optional":false,"kind":"verb","sig":"(input: PromptFillArgs) => Promise","doc":{"desc":["Puts `input.text` in the prompt box as the draft, by `mode`: `replace`","(the default) over it, `append` after it, `insert` at the cursor.","","The event `prompt.fill` through the other plugins' hooks; `isFilled:","false` under a dialog or headless. To hand the model text WITH the next","prompt instead, a `prompt.submit` hook adds `context` (second example)."],"params":[],"example":["await $.prompt.fill({ text: `> ${quote}\\n`, mode: \"insert\" })","($, e, next) => next({ ...e, context: [...(e.context ?? []), hunk] })"],"returns":[]}},{"name":"paint","optional":false,"kind":"verb","sig":"(input: PromptPaintArgs) => Promise","doc":{"desc":["Sets this plugin's own decorations over the draft and nothing else.","","No text, caret or undo entry, no `prompt.change` or `prompt.edit`. Hooks","may rewrite or `{ deny }` it. `isPainted: false`, the box handed back,","when the draft no longer reads `text`, or another plugin hooks its read."],"params":[],"example":["await $.prompt.paint({ text, decorations: [{ start, end, bold: true }] })"],"returns":[]}},{"name":"suggest","optional":false,"kind":"verb","sig":"EventCalls['prompt']['suggest']","doc":{"desc":["Proposes `input.text` as the prompt box's dim suggestion, Tab to take:","the event `prompt.suggest`, as the engine's own guess after a turn.","","It goes through every other plugin's hook with `e.origin` `{ kind:","'plugin', name }`, the engine's own suggestions on or off; `{ isShown:","false }` while the box holds text, a turn runs, or headless (no box)."],"params":[],"example":["void $.prompt.suggest({ text: \"run the tests you just wrote\" })"],"returns":[]}},{"name":"compose","optional":false,"kind":"verb","sig":"EventCalls['prompt']['compose']","doc":{"desc":["Returns the system prompt's sections for `facts`: the event","`prompt.compose`, the call the engine makes for every prompt it sends.","","A fact left out is the session's own (its model, its tools). Through","every other plugin's hook, over the engine's own composition; composed","for nobody to send, so nothing the session holds is written."],"params":[],"example":["const ids = (await $.prompt.compose()).sections.map(s => s.id)"],"returns":[]}}]},{"noun":"tool","doc":{"desc":["The tools the model has in this session, and running one."],"params":[],"example":[],"returns":[]},"members":[{"name":"list","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the tools the model can call now, built-in and MCP alike, in","the order the model sees them."],"params":[],"example":["const names = (await $.tool.list()).map(t => t.name)"],"returns":[]}},{"name":"call","optional":false,"kind":"verb","sig":"EventCalls['tool']['call']","doc":{"desc":["Calls a tool: the event `tool.call`, the same call the engine makes for","the model's tool calls, under a `tool_use_id` of its own.","","It runs through every hook but the calling one (the plugin's others","see it), the permission check and its dialog, then the tool. Rejects","when no tool has that name or the call is aborted."],"params":[],"example":["const { text } = await $.tool.call({ tool: \"Read\", file_path: \"a.md\" })"],"returns":[]}},{"name":"check","optional":false,"kind":"verb","sig":"EventCalls['tool']['check']","doc":{"desc":["Asks the engine's permission decision for a tool call now: the event","`tool.check`, resolved to its verdict (`{ decision, reason?, ... }`).","","The hooks run (the calling hook's own frame skipped, `next.origin` this","plugin, no `tool_use_id`); nothing runs, no dialog opens, no PreToolUse","hook or classifier is asked."],"params":[],"example":["const { decision } = await $.tool.check({ tool: \"Read\", input })"],"returns":[]}},{"name":"register","optional":false,"kind":"verb","sig":"(tool: ToolSpec) => Promise","doc":{"desc":["Declares a tool the model can call from the next prompt on: the name,","description and input schema of `mcp____`.","","Serve it with a `tool.call` hook on `{ tool: \"mcp____\" }`","that returns the result (a call no hook answers fails); a name registered","again is replaced. Rejects until the session binds, at `session.start`."],"params":[["tool","`name`, `description` (what the model reads), `inputSchema` (default `{ type: \"object\" }`), `isDeferred` (ToolSpec)"]],"example":["await $.tool.register({ name: \"weather\", description: \"Weather.\" })"],"returns":["`{ tool }`, the registered tool's full name"," `mcp____`"]}}]},{"noun":"command","doc":{"desc":["The slash commands the person can run in this session, and running one."],"params":[],"example":[],"returns":[]},"members":[{"name":"list","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the slash commands the person can run now, built-in, plugin","and MCP alike, in the order the typeahead lists them."],"params":[],"example":["const names = (await $.command.list()).map(c => c.name)"],"returns":[]}},{"name":"run","optional":false,"kind":"verb","sig":"EventCalls['command']['run']","doc":{"desc":["Runs a slash command as if the person typed `/command args`: the","event `command.run`, queued and run once the session is idle.","","It runs through every hook but the calling one with `e.origin` `{ kind:","'plugin', name }`, its lines in the transcript. Rejects an unknown name,","inside a hook the turn or the session's start waits on, past a Stop or","a host's limit."],"params":[],"example":["const { text } = await $.command.run({ command: \"status\" })"],"returns":[]}},{"name":"register","optional":false,"kind":"verb","sig":"(command: CommandSpec) => Promise","doc":{"desc":["Declares the slash command `/` for this session, listed in the","typeahead from the next keystroke on.","","Serve it with a `command.run` hook on `{ command: \"\" }` that","returns `{ text }`; a run no hook answers says so as its output.","Registering a name again replaces it; a built-in's name is refused."],"params":[["command","`name`, `description` (what the menu shows), `argumentHint` (dim after the name), `immediate` (runs mid-turn)"]],"example":["await $.command.register({ name: \"hello\", description: \"Says hi.\" })"],"returns":["`{ command }`, the registered name"]}}]},{"noun":"config","doc":{"desc":["Every row of the settings menu (`/config`), the panel's own and each","enabled plugin's `userConfig` fields alike: listing and changing them."],"params":[],"example":[],"returns":[]},"members":[{"name":"list","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the rows the `/config` menu would draw now, in its order,","each with its current value, its kind, its owner and its lock.","","After every `config.describe` hook: a hidden row is left out, a","relabelled one carries the new label."],"params":[],"example":["const theme = (await $.config.list()).find(row => row.key === \"theme\")"],"returns":[]}},{"name":"set","optional":false,"kind":"verb","sig":"EventCalls['config']['set']","doc":{"desc":["Changes one row as if the person did in the menu: the event","`config.set` with `origin` `{ kind: 'plugin', name }`, then the writer.","","Through the other plugins' hooks, this plugin's own skipped; `{ deny }`","when a hook refused, the value does not fit, a trusted source owns the","row or only its dialog changes it. Rejects a key no row has."],"params":[["args","`key` (as `list` names it) and `value` (the row's kind)"]],"example":["const { deny } = await $.config.set({ key: \"verbose\", value: true })"],"returns":["`{ value }` once written, or `{ deny }`"]}}]},{"noun":"telemetry","doc":{"desc":["Analytics: first-party rows and feature marks for Anthropic, and records","for the telemetry collector the session's operator configured."],"params":[],"example":[],"returns":[]},"members":[{"name":"log","optional":false,"kind":"verb","sig":"(entry: TelemetryLogArgs) => Promise","doc":{"desc":["Logs one record to the destination `entry.to` names, the event","`telemetry.log`; `e.to` is pinned, and `anthropic` when left out.","","A first-party row is queued by the built-in plugin that hooks the","event, for built-ins and the engine alone. A collector record reaches","the collector only when the engine raised it; any plugin may hook."],"params":[["entry","a first-party row, or a collector record"]],"example":["await $.telemetry.log({"," to: \"anthropic\","," event: \"survey_answered\","," props: { answer: 2, page: { value: \"ready\", of: [\"ready\", \"later\"] } },","})"],"returns":["once the hooks have answered; rejects when one denies"]}},{"name":"mark","optional":false,"kind":"verb","sig":"(entry: TelemetryMarkInput) => Promise","doc":{"desc":["Marks one use of a feature as the CLI's own feature events do, the","event `telemetry.mark`; it takes no `to` and always means `anthropic`.","","The engine does nothing with it: the built-in plugins that hook the","event queue the row. They serve built-ins and the engine alone; any","plugin may hook it."],"params":[["entry","the feature, how its use went, why, and its properties"]],"example":["await $.telemetry.mark({ feature: \"learn_page\", kind: \"sad\","," reason: \"blocked\" })"],"returns":["once the hooks have answered; rejects when one denies"]}}]},{"noun":"agent","doc":{"desc":["Subagents."],"params":[],"example":[],"returns":[]},"members":[{"name":"spawn","optional":false,"kind":"verb","sig":"EventCalls['agent']['spawn']","doc":{"desc":["Spawns a subagent: the event `agent.spawn`, the same call the engine","makes when the Agent tool starts one; the engine fills the rest.","","It runs every hook but the calling one, then the Agent tool in the","background under this call's origin: `{ model, agentId }` once the","subagent started (its answer is its `turn.complete`), or `{ deny }`.","","`{ deny }` is a hook's refusal, or the engine's own with its reason:","past a Stop or a host's limit nothing is spawned, as for a prompt."],"params":[],"example":["const { agentId } = await $.agent.spawn({ prompt: \"Read README.md.\" })"],"returns":[]}},{"name":"list","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns the session's agents so far, subagents and teammates: the ones","the model spawned and the ones plugins did alike.","","One entry an agent, until the engine drops its task: as a teammate ends","or seconds after, a subagent's later. Loops the engine tracks as agents","with no `agent.spawn` (a forked skill) are here; a workflow's are not."],"params":[],"example":[],"returns":[]}},{"name":"register","optional":false,"kind":"verb","sig":"(spec: AgentSpec) => Promise","doc":{"desc":["Defines an agent type the Agent tool dispatches from the next turn on,","named `:`: the event `agent.register`.","","Every field takes effect as in an agent file; re-registered, a name is","replaced; unloaded, a plugin's types go. `agent.offer` hides it from","the model alone; any plugin's `$.agent.spawn` answers to `agent.spawn`."],"params":[["spec","`name`, `description` (when to delegate), `prompt` (its system prompt), and any other field of an agent definition"]],"example":["await $.agent.register({ name: \"runner\", description: \"Runs a spec\","," prompt: RUNNER_PROMPT, tools: [\"Read\", \"Bash\"], omitClaudeMd: true })","// runner-only: hidden from the model, spawned by this plugin's tool,","// answered by the subagent's turn.complete (matched by agentId)","on(\"agent.offer\", { agent: \"lab:runner\" }, () => ({ isOffered: false }))","on(\"tool.call\", { tool: \"mcp__lab__run\" }, async ($, e) => {"," const { agentId, deny } = await $.agent.spawn({"," subagentType: \"lab:runner\", prompt: e.spec, description: \"run\" })"," return { result: deny ?? (await answerOf(agentId)) }","})"],"returns":["`{ agent }`, the full name; rejects until the session binds,"," on a spec the schema refuses (its reason), on a hook's deny"]}}]},{"noun":"fs","doc":{"desc":["The file system as the engine's own process reaches it; a relative path","is under the session's working directory, and text is UTF-8.","","An absolute path is used as given; where one may go is an `fs.*` hook's","to say. A read or write over 4 MiB rejects, the implementation beneath the","hooks rejects a network location untouched, an OS refusal with its errno."],"params":[],"example":[],"returns":[]},"members":[{"name":"read","optional":false,"kind":"verb","sig":"FsReadCall","doc":{"desc":["Reads a file and returns its text, or with `{ as: \"bytes\" }` its bytes","as `{ base64 }`.","","Rejects when missing, or over 4 MiB, which bounds what one read copies","into the plugin's environment. A file the plugin ships is under","`$.plugin.root`."],"params":[["path","relative to the working directory, or absolute"],["options","`as`: `\"text\"` (the default) or `\"bytes\"`"]],"example":["const readme = await $.fs.read(\"README.md\")","const { base64 } = await $.fs.read("," `${$.plugin.root}/hooks/weights.bin`, { as: \"bytes\" })","const weights = Uint8Array.fromBase64(base64)"],"returns":["the file's text, or `{ base64 }`"]}},{"name":"write","optional":false,"kind":"verb","sig":"(path: string, text: string) => Promise","doc":{"desc":["Writes `text` to a file, creating it and its directories as needed."],"params":[["path","relative to the working directory, or absolute"],["text","the whole new content"]],"example":[],"returns":[]}},{"name":"list","optional":false,"kind":"verb","sig":"(path?: string) => Promise","doc":{"desc":["Lists a directory by name: `{ name, kind, size, mtimeMs, isLink }` per","entry, each entry as it stands.","","A symbolic link is `other` with `isLink`; `size` and `mtimeMs` are a","regular file's own and 0 for every other kind (`$.fs.stat` has those)."],"params":[["path","the directory's path; absent, the working directory"]],"example":["const logs = await $.fs.list(\"logs\")","const newest = [...logs].sort((a, b) => b.mtimeMs - a.mtimeMs)[0]"],"returns":["the entries, `{ name, kind, size, mtimeMs, isLink }` each"]}},{"name":"exists","optional":false,"kind":"verb","sig":"(path: string) => Promise","doc":{"desc":["Returns whether the path exists; rejects only a network location, which","the implementation beneath the hooks never touches."],"params":[],"example":[],"returns":[]}},{"name":"stat","optional":false,"kind":"verb","sig":"(path: string, options?: FsStatOptions) => Promise","doc":{"desc":["Returns `{ kind, size, mtimeMs, isLink }` of the path: what it leads to,","and whether it is itself a symbolic link. Rejects when missing.","","With `{ resolve: true }` also `realPath`, where the path lands, absent","when it leads nowhere; a guard matches it and denies without it, since a","spelling it cannot resolve (`~`, a file not there yet) the tool may open."],"params":[["path","relative to the working directory, or absolute"],["options","`resolve`: also answer `realPath` (one more file system call)"]],"example":["// ROOT was resolved the same way and SEP is its separator; an","// allow-list under it is the robust guard, a deny-list on spellings","// only best effort (a hard link or a case alias keeps its own)","on(\"tool.call\", { tool: \"Read\" }, async ($, e, next) => {"," const stat = await $.fs.stat(e.file_path, { resolve: true })"," .catch(() => undefined)"," const real = stat?.realPath"," const isInside = real !== undefined && real.startsWith(ROOT + SEP)"," return isInside ? next(e) : { deny: \"outside the project\" }","})","// a Write may name a file not there yet: `placed` answers where the","// path lands or undefined, and the guard denies on undefined or","// outside ROOT. Unplaceable by spelling first, with no file system","// call (drive-relative `D:x`, a `\\\\` or `//` network or device path,","// a name that is empty, \".\", \"..\" or itself `C:...`); then the file","// if it stats; else its folder, cut after the last separator and","// keeping it so a drive or share root stays that root, plus the name","const placed = async (path) => {"," const cut = Math.max(path.lastIndexOf(\"/\"), path.lastIndexOf(\"\\\\\"))"," const name = path.slice(cut + 1)"," const isPlaceable = !/^[A-Za-z]:(?![\\\\/])/.test(path) &&"," !/^[\\\\/][\\\\/]/.test(path) && !/^[A-Za-z]:/.test(name) &&"," name !== \"\" && name !== \".\" && name !== \"..\""," if (!isPlaceable) return undefined"," const own = await $.fs.stat(path, { resolve: true })"," .catch(() => undefined)"," if (own) return own.realPath"," const folder = cut < 0 ? \".\" : path.slice(0, cut + 1)"," const dir = await $.fs.stat(folder, { resolve: true })"," .catch(() => undefined)"," return dir?.realPath === undefined ? undefined"," : `${dir.realPath.replace(/[\\\\/]$/, \"\")}${SEP}${name}`","}","const real = await placed(e.file_path)","const isInside = real !== undefined && real.startsWith(ROOT + SEP)","return isInside ? next(e) : { deny: \"cannot place it, or outside\" }"],"returns":["the stat, `realPath` with it when asked and resolvable; rejects"," `ENOENT` for a missing path"]}},{"name":"ancestors","optional":false,"kind":"verb","sig":"(request: FsAncestorsRequest) => Promise","doc":{"desc":["Reads the named instruction files in every directory above the","session's original working directory, the way the engine reads CLAUDE.md.","","Root first, each `{ dir, name, content }` that exists, the content","with its `@include`s after it; `of` and `below` together are the","engine's own walk for a nested CLAUDE.md between root and read file."],"params":[["request","`names`, relative `.md` file names (no `..`); `of`, the file walked down to; `below`, the directory the walk stays inside"]],"example":["const found = await $.fs.ancestors({ names: [\"AGENTS.md\"] })","const stack = await $.fs.ancestors({ names: [\"AGENTS.md\"], of: path })","const nested = await $.fs.ancestors({"," names: [\"AGENTS.md\"],"," of: e.file_path,"," below: await $.session.root(),","})"],"returns":["the files found, root first"]}}]},{"noun":"store","doc":{"desc":["This plugin's own key-value store, kept between sessions and hot","reloads; values are JSON data.","","A JSON file of the plugin's own under the user's Claude Code","configuration directory."],"params":[],"example":[],"returns":[]},"members":[{"name":"get","optional":false,"kind":"verb","sig":"(key: string) => Promise","doc":{"desc":["Returns the value under `key`, or `undefined` when unset."],"params":[],"example":["const count = Number((await $.store.get(\"count\")) ?? 0) + 1"],"returns":[]}},{"name":"set","optional":false,"kind":"verb","sig":"(key: string, value: unknown) => Promise","doc":{"desc":["Sets `key` to `value`, which must be JSON data.","","`get` reads back `JSON.parse(JSON.stringify(value))`: a Date is its ISO","string, an `undefined` field is dropped, a Map or Set is `{}`. Rejects","a function, a cycle, or a store over 4 MiB of JSON text in all."],"params":[],"example":[],"returns":[]}},{"name":"delete","optional":false,"kind":"verb","sig":"(key: string) => Promise","doc":{"desc":["Removes `key` from the store."],"params":[],"example":[],"returns":[]}},{"name":"keys","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Returns every key set, in insertion order."],"params":[],"example":[],"returns":[]}}]},{"noun":"state","doc":{"desc":["Named values held by the host for the session, each with a version: plain","data that survives a hot reload of the plugin's code.","","A `get` made while a `ui.render` hook draws subscribes that instance: a","later `set` draws it again, nobody calling `$.ui.invalidate`. Any plugin","reads any value; its owner alone writes it. Persist through `$.store`."],"params":[],"example":[],"returns":[]},"members":[{"name":"get","optional":false,"kind":"verb","sig":"

(ref: StateRef) => Promise>>","doc":{"desc":["Resolves the value under `ref` and the version it stands at; a value","never written is `undefined` at version 0.","","Every `get` of one dispatch reads one moment, whatever is written","meanwhile. `plugin` and `key` must be literals in source (`claude plugin","validate` lists them); only a family member's `id` may be computed."],"params":[["ref","`{ plugin, key }` as the owner's contract declares it in PluginState, with `id` for a StateFamily key"]],"example":["const workers = { plugin: \"swarm\", key: \"workers\" } as const","const { value = [] } = await $.state.get(workers)"],"returns":["`{ value, version }`"]}},{"name":"set","optional":false,"kind":"verb","sig":"

(ref: StateRef, value: StateValue, options?: StateSetOptions) => Promise","doc":{"desc":["Writes `value` under `ref`, which must be this plugin's own; the sites","that read it while drawing are drawn again, at the redraw rate.","","Refused while a `ui.render` hook draws (write from `onPress` or another","event) and for another plugin's value (hook its `state.set` and rewrite","`e.value`). JSON data, as `$.store.set` takes; never `undefined`."],"params":[["ref","`{ plugin, key }`, with `id` for a StateFamily key"],["value","the value, of the type the contract declares"],["options","`ifVersion`: write only while it stands at that version"]],"example":["await $.state.set(count, held.value + 1, { ifVersion: held.version })"],"returns":["`{ isSet, version }`; `isSet` false when `ifVersion` missed"]}}]},{"noun":"clock","doc":{"desc":["The time and timers, each an event through the host: `clock.now` reads","the time; `clock.sleep`, `after` and `every` wait until it has passed.","","A timer's callback is the plugin's own function, kept in its environment","and run there when the wait resolves; a hot reload of the plugin cancels","its pending waits with the old environment."],"params":[],"example":[],"returns":[]},"members":[{"name":"now","optional":false,"kind":"verb","sig":"() => Promise","doc":{"desc":["Resolves milliseconds since the epoch, now."],"params":[],"example":["const startedAt = await $.clock.now()"],"returns":[]}},{"name":"sleep","optional":false,"kind":"verb","sig":"(ms: number, options?: SleepOptions) => Promise","doc":{"desc":["Resolves after `ms` milliseconds; rejects at once when `signal` aborts.","","The wait is the hook's own time and its budget runs on through it, as","through no other `$` call: a `turn.step` generator that polls with it","pays every sleep out of its one budget (`next.budget.remainingMs`)."],"params":[["ms","how long, in milliseconds"],["options","`signal`: ends the wait early with a rejection (pass `next.signal` so a hook's wait ends with its dispatch)"]],"example":["await $.clock.sleep(500, { signal: next.signal })"],"returns":[]}},{"name":"after","optional":false,"kind":"verb","sig":"TimerCall","doc":{"desc":["Calls `fn` once after `ms` milliseconds; `cancel()` before then stops it.","","One `clock.after` dispatch: `fn` runs when it resolves, and never when","a hook refuses it."],"params":[],"example":[],"returns":[]}},{"name":"every","optional":false,"kind":"verb","sig":"TimerCall","doc":{"desc":["Calls `fn` every `ms` milliseconds (at least 1) until `cancel()`.","","One `clock.every` dispatch per period: `fn` runs when it resolves and","the next period is asked; a refused period ends the interval."],"params":[],"example":["const tick = $.clock.every(1000, () => $.ui.status(\"polling\"))"],"returns":[]}}]},{"noun":"http","doc":{"desc":["The network, through the host."],"params":[],"example":[],"returns":[]},"members":[{"name":"fetch","optional":false,"kind":"verb","sig":"(url: string, init?: HttpInit) => Promise","doc":{"desc":["Fetches `url` through the host (never the plugin's own network) and","resolves `{ status, ok, headers, text }` once the body is read.","","http or https, to whatever the host reaches, unless the organization's","web-fetch policy refuses it. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`","refuses a built-in's request, and any plugin's that carries `auth`."],"params":[["url","the URL (http or https)"],["init","`{ method, headers, body, auth, socketPath }` (body a string; socketPath a Unix socket to go over instead of TCP)"]],"example":["const { ok, text } = await $.http.fetch(\"https://example.com/status\")","await $.http.fetch(\"http://bridge/reload\", {"," method: \"POST\","," socketPath: `${runDirectory}/bridge.sock`,","})"],"returns":["`{ status, ok, headers, text }` once the body is read"]}}]},{"noun":"process","doc":{"desc":["Commands on the host, run as the user the session runs as. CLI only.","","Local execution, not a network path: what a command of its own reaches","is its own, as for the Bash tool and a settings `command` hook."],"params":[],"example":[],"returns":[]},"members":[{"name":"run","optional":false,"kind":"verb","sig":"(argv: readonly string[], init?: ProcessRunInit) => Promise","doc":{"desc":["Runs a command on the host by its argument vector (no shell) and","resolves `{ exitCode, stdout, stderr }` once it exits, any exit code.","","One shot: the whole output is read, so a background process left","writing holds the call until the timeout. Rejects when the command","cannot start or is still running then. Git runs with repo hooks off."],"params":[["argv","the command and its arguments, `argv[0]` the executable"],["init","`{ cwd, env, stdin, timeoutMs }` (cwd the session's by default; timeout 30 s by default, ten minutes at most)"]],"example":["const { exitCode, stdout } = await $.process.run([\"git\", \"status\"])"],"returns":["`{ exitCode, stdout, stderr }`, each stream's first 4194304"," bytes (`isStdoutTruncated`, `isStderrTruncated` say when cut)"]}},{"name":"spawn","optional":false,"kind":"verb","sig":"(request: ProcessSpawnRequest) => HookStream","doc":{"desc":["Starts a command on the host by its argument vector (no shell) and","streams what it writes, piece by piece, then how it ended.","","The loop is the child's life: leaving it, `return()` on the stream,","`next.signal` aborting or the module unloading kills the child, and","nothing else does, a hook's return included: end the loop to end it."],"params":[["request","`{ argv, cwd, env, input }`, `$.process.run`'s rules; `e` for a hook on `process.spawn` (a generator, its budget per piece)"]],"example":["// inline: the hook's dispatch waits on the loop; leaving it kills make","const make = $.process.spawn({ argv: [\"make\"], cwd: \"build\" })","for await (const { stream, text } of make) {"," if (stream === \"stderr\" && text.includes(\"error\")) break","}","// a child for the session's life: the loop runs on after the hook","// returns, and ends with the child or with the module","on(\"session.start\", async ($, e, next) => {"," const started = await next(e)"," void (async () => {"," const bridge = $.process.spawn({ argv: [\"bridge\", \"watch\", e.cwd] })"," for await (const { text } of bridge) $.ui.log(text, { to: \"debug\" })"," })()"," return started","})","// above another plugin's spawn: redact each piece before it reads it","on(\"process.spawn\", async function* ($, e, next) {"," for await (const chunk of next(e)) {"," yield { ...chunk, text: chunk.text.replaceAll(token, \"***\") }"," }","})"],"returns":["the pieces `{ stream, text }` (text as it came, not lines),"," then `{ code, signal }`; rejects its first pull if it cannot start"]}}]},{"noun":"settings","doc":{"desc":["What the settings files, `--settings` and managed policy hold, as the","engine runs under it; read only.","","Every key crosses as the source holds it, `env` and the helper commands","included: nothing is filtered. The OAuth session and the global config","(~/.claude.json) are not settings and are never read."],"params":[],"example":[],"returns":[]},"members":[{"name":"read","optional":false,"kind":"verb","sig":"SettingsReadOverloads","doc":{"desc":["Resolves with the settings merged over every source, with one","source's settings as loaded (`{ source }`), or with the value of one","top-level key (`{ key }`), undefined when the settings hold none.","","A snapshot in plain data each call; a source with no file answers","`{}`. Every read raises `settings.read` once, its layers on `e`","(SettingsReadInput); a read of one key is the read of the object,","projected, and raises no event of its own.","","The sources (SettingsSource) rise in precedence from `user` to","`policy`; with no hook the object is the engine's merge: a scalar","from the last source that has it, lists joined, objects merged.","","Raised by a plugin's call, and by the engine for its own merge once","the loaded plugins or the settings have changed, `next.origin` then","the engine. What the hooks answer there is what every reader of the","merged settings reads, and a changed answer takes effect as a changed","settings file does.","","No key is closed to a hook, the keys that decide which plugins load","included: those are read before any plugin is loaded, so the first set","loads by the files' own values and an answer applies from the load","after. A merge that never settles, an answer changing which plugins","load and those answering otherwise, is told in the settings error","list, and the files' own value stands for that key."],"params":[["args","`{ source }` for one source, `{ key }` for one key's value, nothing for the merge"]],"example":["const { permissions } = await $.settings.read()","const policy = await $.settings.read({ source: \"policy\" })","const days = await $.settings.read({ key: \"cleanupPeriodDays\" })"],"returns":["the settings object, keyed as a settings.json is, or the"," key's value"]}}]},{"noun":"env","doc":{"desc":["The environment of this process, the one every Bash child, MCP server","and `$.process.run` command started after inherits.","","`get` and `set` take the variable's name as a string literal, so what a","module reads and writes is read off its source: `claude plugin validate`","lists the names, and a name the module does not spell is refused."],"params":[],"example":[],"returns":[]},"members":[{"name":"get","optional":false,"kind":"verb","sig":"(name: string) => Promise","doc":{"desc":["Resolves with the variable's value, or `undefined` when it is unset.","","`name` must be a string literal; `claude plugin validate` lists the","names your module reads and writes."],"params":[],"example":["const home = await $.env.get(\"HOME\")"],"returns":[]}},{"name":"set","optional":false,"kind":"verb","sig":"(name: string, value: string | undefined) => Promise","doc":{"desc":["Sets the variable for this process and everything it starts after, or","unsets it when `value` is `undefined`.","","`name` must be a string literal; `claude plugin validate` lists the","names your module reads and writes."],"params":[],"example":["await $.env.set(\"GIT_PAGER\", \"cat\")"],"returns":["`{}` once it is set or unset, or `{ deny }` saying why not"]}}]}],"events":{"EngineEventOf":[{"event":"tool.call","optional":false,"type":"ToolCallInput","doc":{"desc":["Fires when the engine is about to run a tool. Each `next(e)` runs the","hooks beneath, then core (the permission prompt, the tool itself).","","`{ deny: reason }` refuses and `{ result }` answers in place of `next`: a","deny after `next(e)` resolved undoes nothing it ran; returning with `next`","pending aborts what runs beneath. Managed-settings hooks' deny comes first."],"params":[],"example":[],"returns":[]}},{"event":"tool.check","optional":false,"type":"ToolCheckInput","doc":{"desc":["Fires when the engine decides whether a tool call may run, after the","`tool.call` and PreToolUse hooks and before the mode settles an ask.","","`next(e)` resolves to the engine's verdict (rules, mode, the tool's own","check, PreToolUse's decision) and runs no tool: return any `{ decision }`,","a deny after it too. `$.tool.check` runs the same chain, executing nothing."],"params":[],"example":["on(\"tool.check\", { tool: \"Read\" }, () => ({ decision: \"allow\" }))"],"returns":[]}},{"event":"ui.render","optional":false,"type":"RenderInput","doc":{"desc":["Fires when the engine is about to draw a component: once per input value","(props, viewport width), plugin load or `$.ui.invalidate(\"ui.render\")`.","","A repaint reuses the answer; a clock invalidates. `next(e)` resolves to the","drawing: return it, wrap it, draw your own, or rewrite `props`. An invalid","tree, or a throw while drawn, draws the engine's; `--plugin-dir` is told."],"params":[],"example":[],"returns":[]}},{"event":"ui.resolve","optional":false,"type":"ResolveInput","doc":{"desc":["Fires when the plugins load (not per draw), once per surface, component","and plugin: `e` names the surface and component, never the props.","","`next(e)` resolves to the surface's table, which `$.ui.resolve(e)` then","reads. Return it, one with an element restyled for every other plugin,","or one with a key left out (a fragment there); own table: hook skipped."],"params":[],"example":[],"returns":[]}},{"event":"ui.press","optional":false,"type":"UiPressArgument","doc":{"desc":["Fires when a `Button` a render hook drew is pressed on a surface; `e` is","`{ plugin, element, component, surface }`, `element` the button's `key`.","","`next(e)` runs the hooks beneath, then core: the element's own `onPress`","closure, in its plugin's environment, resolving to `{ element }`. Return","`next(e)` to let the press through, or `{ element }` to take it."],"params":[],"example":[],"returns":[]}},{"event":"ui.input","optional":false,"type":"UiInputArgument","doc":{"desc":["Fires when an `Input` a render hook drew changes or is submitted; `e` is","`{ plugin, element, component, surface, kind, value }`.","","`next(e)` runs the hooks beneath, then the element's own `onInput` or","`onSubmit` with `e.value` as the chain left it, resolving to `{ element,","value }`; `next({ ...e, value })` rewrites the typing, an answer takes it."],"params":[],"example":[],"returns":[]}},{"event":"ui.select","optional":false,"type":"UiSelectArgument","doc":{"desc":["Fires when a `Select` a render hook drew is picked from; `e` is","`{ plugin, element, component, surface, value }`.","","`next(e)` runs the hooks beneath, then the element's own `onSelect` with","`e.value` as the chain left it, resolving to `{ element, value }`;","`next({ ...e, value })` rewrites the pick, an answer takes it."],"params":[],"example":[],"returns":[]}},{"event":"ui.message","optional":false,"type":"UiMessageArgument","doc":{"desc":["Fires when a `Client` THIS plugin drew posts from its surface module","(`surface.post(data)`); only this plugin's hooks see it.","","`next.origin` names `client`: `data` came from code. Core answers `{}`;","`next({ ...e, data })` rewrites the data; `{ props }` hands the posting","instance its next props without a redraw. One per instance per frame."],"params":[],"example":[],"returns":[]}},{"event":"ui.fault","optional":false,"type":"UiFaultInput","doc":{"desc":["Fires when a `Client` THIS plugin drew failed on a surface: its module","did not load, its drawing failed, or its code failed after it had drawn.","","Only this plugin's hooks see it; `e.phase` says when, `e.reason` why.","Observe only: core answers `{}`. The engine then draws that site again,","unasked: fall back by leaving the `Client` out."],"params":[],"example":["on(\"ui.fault\", ($, e, next) => ($.ui.log(e.reason), next(e)))"],"returns":[]}},{"event":"ui.scroll","optional":false,"type":"UiScrollInput","doc":{"desc":["Fires before a site's window moves: the person's wheel or scroll keys on","a `Pane` body or the `AbovePrompt` band, at its edges too; `$.ui.scroll`.","","`next(e)` moves it to `e.offset` and draws: `{}`; `next({ ...e, offset","})` elsewhere; no `next` (`{}` or `{ deny }`) leaves it undrawn, so a hook","drawing its own rows under a header moves them by `e.by` and invalidates."],"params":[],"example":["on(\"ui.scroll\", { requestId: \"log\" }, ($, e) => (scrollOwnRows(e.by), {}))"],"returns":[]}},{"event":"ui.focus","optional":false,"type":"UiFocusInput","doc":{"desc":["Fires before a site's focus ring moves: the person's Tab, arrows or click","in a `Pane` or the band; an `autoFocus` element taking it; `$.ui.focus`.","","`next(e)` lands it on `e.element` (absent: one of the engine's stops) and","draws: `{}`; `next({ ...e, element })` on another of `e.plugin`'s; no","`next` (`{}` or `{ deny }`) keeps it where it was, drawn as it was."],"params":[],"example":["on(\"ui.focus\", { requestId: \"list\" }, ($, e, next) => (mark(e), next(e)))"],"returns":[]}},{"event":"agent.offer","optional":false,"type":"AgentOfferInput","doc":{"desc":["Fires when the engine offers an agent type to the model, in the agent","listing and again at dispatch; `next(e)` resolves to `{ isOffered: true }`.","","Return `{ isOffered: false }` to keep the type out of the listing and","refuse its dispatch. A hook that fails passes it through."],"params":[],"example":["on(\"agent.offer\", { agent: \"Plan\" }, () => ({ isOffered: false }))"],"returns":[]}},{"event":"agent.spawn","optional":false,"type":"AgentSpawnInput","doc":{"desc":["Fires when the Agent tool, or a workflow script's `agent()`","(`e.workflow`), is about to start an agent, its model not yet resolved.","","`next(e)` resolves to `{ model }`. Return it, `next({ ...e, model })`,","`{ model }` of your own (an alias resolves like the tool's parameter), or","`{ deny: reason }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.submit","optional":false,"type":"PromptSubmitInput","doc":{"desc":["Fires when a prompt is submitted, before the turn starts. `next(e)` runs","the hooks beneath and the UserPromptSubmit settings hooks, then it enters.","","Rewrite with `next({ ...e, text })` (the user message on screen follows)","or, in its place, stop it with `{ drop: reason }`; a broken plugin never","blocks one. Typed while a turn ran, it fires at Enter, with that turn's id."],"params":[],"example":[],"returns":[]}},{"event":"prompt.fill","optional":false,"type":"PromptFillInput","doc":{"desc":["Fires when a text is about to be put in the prompt box as the person's","draft (a plugin's `$.prompt.fill`); `next(e)` writes it by `e.mode`.","","`replace` over the draft, `append` after it, `insert` at the cursor;","rewrite `text` or `mode` going down, or answer `{ isFilled: false }`","without `next` to keep it out, as core does under a dialog or headless."],"params":[],"example":["on(\"prompt.fill\", ($, e, next) => next({ ...e, text: e.text.trim() }))"],"returns":[]}},{"event":"prompt.suggest","optional":false,"type":"PromptSuggestInput","doc":{"desc":["Fires when a text is proposed as the prompt box's dim suggestion, Tab to","take: the engine's guess after a turn, or a plugin's `$.prompt.suggest`.","","`next(e)` shows it: `{ isShown }`. Rewrite with `next({ ...e, text })`,","or answer `{ isShown: false }` without `next` to drop it; core answers","that too while the box holds text or a turn runs."],"params":[],"example":["on(\"prompt.suggest\", () => ({ isShown: false }))"],"returns":[]}},{"event":"prompt.edit","optional":false,"type":"PromptEditInput","doc":{"desc":["Fires when the person edits the main prompt box: a key the editor took as","an edit, or a paste; `next(e)` resolves the box the editor shows.","","`e` is the draft before and the splice (`start`, `end`, `inputText`); a","burst of keys is one edit. Rewrite `inputText` going down or the box","coming up; `{ text: e.text, cursor: e.cursor }` without `next` consumes."],"params":[],"example":["on(\"prompt.edit\", ($, e) => ({ text: e.text, cursor: e.cursor }))"],"returns":[]}},{"event":"prompt.change","optional":false,"type":"PromptChangeInput","doc":{"desc":["Fires after the main prompt box's text changed and no `prompt.edit`","carried it: a recalled history entry, a clear, a plugin's fill.","","`e` is the box as it stands and `e.origin` who changed it. Observe only:","the change is in the box. One per batch of changes, one at a time."],"params":[],"example":["on(\"prompt.change\", ($, e, next) => ($.ui.status(e.origin.kind), next(e)))"],"returns":[]}},{"event":"prompt.autocomplete","optional":false,"type":"PromptAutocompleteInput","doc":{"desc":["Fires as the person types in the main prompt box, for the token at the","cursor; `next(e)` resolves to `{ suggestions }`, rows for the typeahead.","","Nothing waits on it: the engine's own rows draw first and these join","beneath them, unhighlighted, for the word still being typed. Taking one","writes its `text` over the token. Only while a plugin hooks it."],"params":[],"example":["on(\"prompt.autocomplete\", () => ({ suggestions: [{ text: \"#123\" }] }))"],"returns":[]}},{"event":"prompt.section","optional":false,"type":"PromptSectionInput","doc":{"desc":["Fires once per named section of the system prompt, when the engine","assembles it; `next(e)` resolves to `{ text }` as core computed it.","","`e.name` is the section's id, on every model the one `prompt.compose`","lists. Cached, so keep it steady: after `$.ui.invalidate(\"prompt.section\")`","a changed answer goes out next turn over the text the main thread sent,","which loses its thinking and the cache. A failed hook passes through."],"params":[],"example":["on(\"prompt.section\", { name: \"memory\" }, () => ({ text: null }))"],"returns":[]}},{"event":"prompt.context","optional":false,"type":"PromptContextInput","doc":{"desc":["Fires once per conversation, when the engine computes the context blocks","its first user message carries; `next(e)` resolves to `{ blocks }`.","","Append, drop, reorder or rewrite with `next({ ...e, blocks })`; the","answer stands until `$.ui.invalidate(\"prompt.context\")` or a re-read","(compaction, `/clear`). `PromptContextResult` says what the model is sent."],"params":[],"example":["on(\"prompt.context\", () => ({ blocks: [] }))"],"returns":[]}},{"event":"prompt.compose","optional":false,"type":"PromptComposeInput","doc":{"desc":["Fires when the engine renders a system prompt; `next(e)` resolves to","`{ sections }`, each `{ id, text, scope }`, in the order they are sent.","","The ids depend on the prompt composed (`lean`, `bare` in `e.traits`): read","them off `next(e)`. Append (as `session`), replace, reorder or drop; a list","with a `shared` section after a `session` one skips the hook."],"params":[],"example":[],"returns":[]}},{"event":"prompt.attachment","optional":false,"type":"PromptAttachmentInput","doc":{"desc":["Fires once per message the engine injects for the model on its own (a","reminder, a mode transition, a mentioned file), as a request carries it.","","`next(e)` resolves to `{ text }`; `{ text: null }` leaves it out. The","answer holds per attachment for the process (asked again on resume or","`$.ui.invalidate`); the transcript keeps the engine's record."],"params":[],"example":["on(\"prompt.attachment\", { type: \"todo_reminder\" }, () => ({ text: null }))"],"returns":[]}},{"event":"prompt.mention","optional":false,"type":"PromptMentionInput","doc":{"desc":["Fires once per path a prompt names after an `@`, a directory aside,","before the engine reads it; `next(e)` reads it and resolves `{ type }`.","","No `tool.call` is raised for this read. Add `context` to what `next`","gave, read another `path` with `next({ ...e, path })`, or answer","`{ deny: reason }` so nothing is read."],"params":[],"example":["on(\"prompt.mention\", { path: /\\.env$/ }, () => ({ deny: \"a secret\" }))"],"returns":[]}},{"event":"tool.describe","optional":false,"type":"ToolDescribeInput","doc":{"desc":["Fires when the engine first renders the tool's schema in a session;","`next(e)` resolves to `{ description, isDeferred? }`.","","An MCP tool behind ToolSearch fires twice: its short text, then the one","loaded. Cached until `$.ui.invalidate(\"tool.describe\")`: a changed answer","for a tool a thread has sent goes out next turn over that text, which","loses its thinking and the whole prompt cache."],"params":[],"example":["on(\"tool.describe\", { tool: \"Bash\" }, ($, e) => ({ ...e, description }))","on(\"tool.describe\", { tool: \"Monitor\" }, pin) // {...e, isDeferred: false}"],"returns":[]}},{"event":"command.run","optional":false,"type":"CommandRunInput","doc":{"desc":["Fires when a slash command is about to run (`/name args` typed, or a","plugin's `$.command.run`); `next(e)` resolves to `{ text }`, its output.","","Core is the engine's command (a registered one has none). Rewrite `args`","with `next`, or return `{ text }` without it to answer in its place; one","after `next` replaces a printed output, not a panel or prompt it opened."],"params":[],"example":["on(\"command.run\", { command: \"hello\" }, () => ({ text: \"hello\" }))"],"returns":[]}},{"event":"command.describe","optional":false,"type":"CommandDescribeInput","doc":{"desc":["Fires once per command, when the engine lists it for the typeahead and","`/help`; `next(e)` resolves to `{ description, argumentHint, isHidden }`.","","Listed answers are cached for the session until","`$.ui.invalidate(\"command.describe\")`. A hook that fails passes it","through."],"params":[],"example":["on(\"command.describe\", ($, e, next) => next({ ...e, isHidden: true }))"],"returns":[]}},{"event":"config.set","optional":false,"type":"ConfigSetInput","doc":{"desc":["Fires when a `/config` row is about to change, from the menu or a","plugin's `$.config.set`; `next(e)` resolves to `{ value }` once written.","","Return `{ deny: reason }` to leave the row as it is (the menu says why),","or `next({ ...e, value })` to clamp it; a value of the wrong kind for","the row is refused. A row a trusted source owns is core's to refuse."],"params":[],"example":["on(\"config.set\", { key: \"theme\" }, () => ({ deny: \"the theme stays\" }))"],"returns":[]}},{"event":"config.describe","optional":false,"type":"ConfigDescribeInput","doc":{"desc":["Fires once per `/config` row, when the menu lists it and for","`$.config.list`; `next(e)` resolves to `{ label, description, isHidden }`.","","Relabel, re-describe or hide with `next({ ...e, isHidden: true })`; the","answers are cached until `$.ui.invalidate(\"config.describe\")` or the","loaded plugins change. A hook that fails passes the row through."],"params":[],"example":["on(\"config.describe\", { key: \"tips\" }, hide) // answers isHidden: true"],"returns":[]}},{"event":"telemetry.log","optional":false,"type":"TelemetryLogInput","doc":{"desc":["Fires when a record is about to be logged to the destination `e.to`","names: a built-in's `$.telemetry.log`, or the engine's own events.","","`e.to` is pinned: a hook rewrites what the record carries, never where","it goes. `next(e)` resolves `{ value: undefined }`; `{ deny }` rejects the","caller. Beneath the hooks the engine exports its own collector records."],"params":[],"example":["on(\"telemetry.log\", { to: \"collector\" }, ($, e, next) => next(e))"],"returns":[]}},{"event":"telemetry.mark","optional":false,"type":"TelemetryMarkInput","doc":{"desc":["Fires when one use of a feature is marked (`$.telemetry.mark`), as the","CLI's own feature events mark one; always for `anthropic`, no `to`.","","`next(e)` resolves `{ value: undefined }`; `{ deny }` rejects the caller.","The engine does nothing with a mark: the built-ins hooked here do."],"params":[],"example":["on(\"telemetry.mark\", { kind: \"bad\" }, ($, e, next) => next(e))"],"returns":[]}},{"event":"skill.prompt","optional":false,"type":"SkillPromptInput","doc":{"desc":["Fires when the engine expands a skill's prompt for the model (`/name`,","the Skill tool, a preload); `next(e)` resolves to `{ text }` as computed.","","Return `{ text }` with the text the model reads instead. A hook that","fails passes it through."],"params":[],"example":["on(\"skill.prompt\", { skill: \"commit\" }, () => ({ text: \"A haiku.\" }))"],"returns":[]}},{"event":"attribution.text","optional":false,"type":"AttributionTextInput","doc":{"desc":["Fires when the engine composes a git text the model is to write (`kind`:","`commit`, `pr`, `exemption`, `remedy`); `next(e)` resolves to `{ text }`.","","Return `{ text }` with the text the model reads instead. A hook that","fails passes it through."],"params":[],"example":["on(\"attribution.text\", { kind: \"commit\" }, () => ({ text: \"\" }))"],"returns":[]}},{"event":"session.start","optional":false,"type":"SessionStartInput","doc":{"desc":["Fires once per process for each loaded plugin, before the first prompt,","then once per fresh load of one (never `/clear`); `next(e)` is `{ cwd }`.","","Observe. The first is awaited: a `$.tool.register` is listed by turn one.","A later one runs its hooks alone: an enable, a worker respawn, or a reload","(changed modules only; all if one hooks `engine.create`/`plugin.register`)."],"params":[],"example":["on(\"session.start\", ($, e, next) => $.tool.register(t).then(() => next(e)))"],"returns":[]}},{"event":"session.receive","optional":false,"type":"SessionReceiveInput","doc":{"desc":["Fires when a delivery reaches the session, before it is queued: a relay's","event, a peer's message, a Remote Control prompt, room events; `{ text }`.","","Rewrite with `next({ ...e, text })`, or return `{ consumed: reason }` to","take it: nothing is queued, shown or read by the model. `origin`,","`event` and `agentId` pass on as received; `session.send` is its dual."],"params":[],"example":["on(\"session.receive\", { origin: \"peer\" }, () => ({ consumed: \"muted\" }))"],"returns":[]}},{"event":"session.append","optional":false,"type":"SessionAppendInput","doc":{"desc":["Fires once per row a conversation of this session keeps (a prompt, a","response block, a tool result, a notice), before it is stored.","","`next({ ...e, message })` rewrites `content`: stored and sent after. The","screen, an SDK stream or Remote Control may show the row just before its","rewrite; the model and the transcript file never read that form."],"params":[],"example":["on(\"session.append\", { door: \"tool-result\" }, ($, e, n) => n(scrub(e)))"],"returns":[]}},{"event":"session.send","optional":false,"type":"SessionSendInput","doc":{"desc":["Fires when a plain-text message is about to leave this conversation for","another agent or session (the SendMessage tool, or `$.session.send`).","","`e.origin` says who sends, `e.agentId` which loop. Rewrite `text` or","readdress `to` with `next` (a new `to` is judged again); `{ isDelivered:","false, reason }` without `next` refuses it. `next(e)` resolves queued."],"params":[],"example":["on(\"session.send\", ($, e, next) => next({ ...e, text: redact(e.text) }))"],"returns":[]}},{"event":"session.compact","optional":false,"type":"SessionCompactInput","doc":{"desc":["Fires when the conversation is about to be compacted (`/compact`, the","threshold, a plugin, or ahead of time); `next(e)` resolves `{ messages }`.","","Rewrite `instructions` or `messages` on the way down, the messages on","the way up, or answer `{ messages }` of your own; `{ skip: reason }`","leaves the conversation as it is. `trigger` passes on as received."],"params":[],"example":["on(\"session.compact\", { trigger: \"precompute\" }, () => ({ skip: \"off\" }))"],"returns":[]}},{"event":"session.attach","optional":false,"type":"SessionAttachInput","doc":{"desc":["Fires when a remote client joins the session's roster of attached","surfaces: it said so (ui_attach), or it first asked to draw.","","Observe (a phone joined: draw the lobby); `next(e)` resolves to","`{ clientId }`, a different return changes nothing. `$.session.surfaces()`","reads the roster; a render hook still reads `e.surface` per ask."],"params":[],"example":["on(\"session.attach\", { surface: \"mobile\" }, ($, e, next) => next(e))"],"returns":[]}},{"event":"session.detach","optional":false,"type":"SessionDetachInput","doc":{"desc":["Fires when a client leaves the roster: it detached, or the session ended","with it attached (`e.reason`). Observe; `next(e)` echoes `{ clientId }`.","","With reason `end` it runs inside `session.end`'s one short bound: there","`next.budget` reads that bound and `next.signal` aborts at it."],"params":[],"example":[],"returns":[]}},{"event":"session.measure","optional":false,"type":"SessionMeasureInput","doc":{"desc":["Fires when the engine measures the session and a unit moved: after each","main-thread turn, and when a rate-limit window moves a whole point.","","Observe; `next(e)` echoes `{ changed }`. `$.session.usage()`'s figures,","pushed, not polled: compare them with your own threshold here, call the","op for the breakdown. One at a time, a burst folding into one more."],"params":[],"example":["on(\"session.measure\", ($, e, next) => (toastPast90(e.rateLimits), next(e)))"],"returns":[]}},{"event":"session.end","optional":false,"type":"SessionEndInput","doc":{"desc":["Fires once when the session ends (exit, /clear, resume, logout, signal, a","`-p` run done), after its SessionEnd settings hooks; `e.reason` says which.","","`next(e)` runs the engine's end step, `{ sessionId }`; `e.resume.id` is","`--resume`'s. Exits stay fast whatever is loaded: the whole chain shares","one short wall-clock bound, which `next.budget` reads (SessionEndInput)."],"params":[],"example":["on(\"session.end\", async ($, e, next) => (await save(next.budget), next(e)))"],"returns":[]}},{"event":"plugin.register","optional":false,"type":"PluginRegisterInput","doc":{"desc":["Fires once per hooks module about to join the chain, at load (the set","folded and built, nothing swapped in) and at reload; core allows.","","Return `{ refuse: reason }` and it never joins: no hook, no noun, no tool","of it; the debug log names who refused. Its judges, `$` whole, are the","plugins admitted before it and the binary's; judge by `tier` and `uses`."],"params":[],"example":["on(\"plugin.register\", { tier: \"user\" }, () => ({ refuse: \"managed only\" }))"],"returns":[]}},{"event":"turn.start","optional":false,"type":"TurnStartInput","doc":{"desc":["Fires when a model turn begins, main's or a subagent's (`e.agentId`),","before its first model call; `next(e)` resolves to `{ turnId }`.","","Observe: a different return changes nothing. For the main loop alone,","return `next(e)` first when `e.agentId !== undefined`. An agent's start","skips the hooks its spawn was nested in, as its `turn.step`s do."],"params":[],"example":[],"returns":[]}},{"event":"turn.step","optional":false,"type":"TurnStepInput","doc":{"desc":["Fires when the engine is about to send a model request of a turn, main's","or a subagent's (`e.agentId`); `next(e)` resolves to the whole response.","","`next({ ...e, model })` or `effort` sends another; the turn, the index and","the message count are pinned. An answer without `next` sends no request.","It streams (StreamNext): the hook's budget counts its own code alone."],"params":[],"example":[],"returns":[]}},{"event":"turn.complete","optional":false,"type":"TurnCompleteInput","doc":{"desc":["Fires when a model turn has ended, at the point its duration is reported;","`next(e)` resolves to `{ text }`, the answer. `e.reason` says why.","","Return `{ text }` with a different text to show it beneath the answer (a","synopsis, a TL;DR line); the transcript's record is never rewritten. A","hook that fails leaves the answer as it was."],"params":[],"example":[],"returns":[]}},{"event":"engine.create","optional":false,"type":"EngineCreateInput","doc":{"desc":["Runs while `$` is being built, once per load or reload of this plugin","and before any other hook of it; `next(e)` resolves to `$` built so far.","","A step may ADD nouns and, outside `user`, WITHHOLD them (leave one out, or","return without `next`). It fails, and its plugin unloads, when it REPLACES","another's; in `user`, also past its own stub, or adding a seated name."],"params":[],"example":[],"returns":[]}}],"EngineResultOf":[{"event":"tool.call","optional":false,"type":"ToolCallResult","doc":{"desc":["`{ result, context? }`, `{ deny }`, or core's `{ ref, result }`."],"params":[],"example":[],"returns":[]}},{"event":"tool.check","optional":false,"type":"ToolCheckResult","doc":{"desc":["`{ decision, reason?, rule?, hook?, setting?, plugin?, ceiling? }`."],"params":[],"example":[],"returns":[]}},{"event":"ui.render","optional":false,"type":"RenderElement","doc":{"desc":["The tree to draw; `{ type: \"engine\", ref }` is core's own drawing."],"params":[],"example":[],"returns":[]}},{"event":"ui.resolve","optional":false,"type":"ElementTable","doc":{"desc":["The surface's element table (Elements[e.surface]): constructors from props","to a RenderElement."],"params":[],"example":[],"returns":[]}},{"event":"ui.press","optional":false,"type":"UiPressResult","doc":{"desc":["`{ element }`: the element whose handler the press reached."],"params":[],"example":[],"returns":[]}},{"event":"ui.input","optional":false,"type":"UiInputResult","doc":{"desc":["`{ element, value }`: the field whose handler the input reached, and","the text it received."],"params":[],"example":[],"returns":[]}},{"event":"ui.select","optional":false,"type":"UiSelectResult","doc":{"desc":["`{ element, value }`: the picker whose handler the pick reached, and","the value it received."],"params":[],"example":[],"returns":[]}},{"event":"ui.message","optional":false,"type":"UiMessageResult","doc":{"desc":["`{ props? }`: the posting instance's next props, when a hook hands some."],"params":[],"example":[],"returns":[]}},{"event":"ui.fault","optional":false,"type":"UiFaultResult","doc":{"desc":["`{}`: the fault was heard."],"params":[],"example":[],"returns":[]}},{"event":"ui.scroll","optional":false,"type":"UiScrollResult","doc":{"desc":["`{}` once the window moved, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"ui.focus","optional":false,"type":"UiFocusResult","doc":{"desc":["`{}` once the ring moved, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"agent.offer","optional":false,"type":"AgentOfferResult","doc":{"desc":["`{ isOffered }`."],"params":[],"example":[],"returns":[]}},{"event":"agent.spawn","optional":false,"type":"AgentSpawnResult","doc":{"desc":["`{ model }` or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.submit","optional":false,"type":"PromptSubmitResult","doc":{"desc":["`{ text, context? }` or `{ drop }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.fill","optional":false,"type":"PromptFillResult","doc":{"desc":["`{ isFilled }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.suggest","optional":false,"type":"PromptSuggestResult","doc":{"desc":["`{ isShown }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.edit","optional":false,"type":"PromptEditResult","doc":{"desc":["`{ text, cursor }`, the box the editor shows next."],"params":[],"example":[],"returns":[]}},{"event":"prompt.change","optional":false,"type":"PromptChangeResult","doc":{"desc":["`{ text }`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.autocomplete","optional":false,"type":"PromptAutocompleteResult","doc":{"desc":["`{ suggestions }`, the rows the plugins add to the typeahead."],"params":[],"example":[],"returns":[]}},{"event":"prompt.section","optional":false,"type":"PromptSectionResult","doc":{"desc":["`{ text }` (null leaves the section out)."],"params":[],"example":[],"returns":[]}},{"event":"prompt.context","optional":false,"type":"PromptContextResult","doc":{"desc":["`{ blocks }` (a block left out is not sent)."],"params":[],"example":[],"returns":[]}},{"event":"prompt.compose","optional":false,"type":"PromptComposeResult","doc":{"desc":["`{ sections }`, every `shared` one ahead of every `session` one (a","section left out is not sent)."],"params":[],"example":[],"returns":[]}},{"event":"prompt.attachment","optional":false,"type":"PromptAttachmentResult","doc":{"desc":["`{ text }` (null leaves the attachment out)."],"params":[],"example":[],"returns":[]}},{"event":"prompt.mention","optional":false,"type":"PromptMentionResult","doc":{"desc":["`{ type, context? }` (null when nothing was attached) or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"tool.describe","optional":false,"type":"ToolDescribeResult","doc":{"desc":["`{ description, isDeferred? }`."],"params":[],"example":[],"returns":[]}},{"event":"command.run","optional":false,"type":"CommandRunResult","doc":{"desc":["`{ text }` (the command's output, when it printed one)."],"params":[],"example":[],"returns":[]}},{"event":"command.describe","optional":false,"type":"CommandDescribeResult","doc":{"desc":["`{ description, argumentHint, isHidden }`."],"params":[],"example":[],"returns":[]}},{"event":"config.set","optional":false,"type":"ConfigSetResult","doc":{"desc":["`{ value }` once written, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"config.describe","optional":false,"type":"ConfigDescribeResult","doc":{"desc":["`{ label, description, isHidden }`."],"params":[],"example":[],"returns":[]}},{"event":"telemetry.log","optional":false,"type":"TelemetryLogResult","doc":{"desc":["`{ value: undefined }`, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"telemetry.mark","optional":false,"type":"TelemetryMarkResult","doc":{"desc":["`{ value: undefined }`, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"skill.prompt","optional":false,"type":"SkillPromptResult","doc":{"desc":["`{ text }`."],"params":[],"example":[],"returns":[]}},{"event":"attribution.text","optional":false,"type":"AttributionTextResult","doc":{"desc":["`{ text }`."],"params":[],"example":[],"returns":[]}},{"event":"session.start","optional":false,"type":"SessionStartResult","doc":{"desc":["`{ cwd }`."],"params":[],"example":[],"returns":[]}},{"event":"session.receive","optional":false,"type":"SessionReceiveResult","doc":{"desc":["`{ text }`, or `{ consumed }`."],"params":[],"example":[],"returns":[]}},{"event":"session.append","optional":false,"type":"SessionAppendResult","doc":{"desc":["`{ message, uuid }`, the row as stored."],"params":[],"example":[],"returns":[]}},{"event":"session.send","optional":false,"type":"SessionSendResult","doc":{"desc":["`{ isDelivered: true }`, or `{ isDelivered: false, reason }`."],"params":[],"example":[],"returns":[]}},{"event":"session.compact","optional":false,"type":"SessionCompactResult","doc":{"desc":["`{ messages, tokensBefore?, tokensAfter? }`, or `{ skip }`."],"params":[],"example":[],"returns":[]}},{"event":"session.attach","optional":false,"type":"SessionAttachResult","doc":{"desc":["`{ clientId }`."],"params":[],"example":[],"returns":[]}},{"event":"session.detach","optional":false,"type":"SessionDetachResult","doc":{"desc":["`{ clientId }`."],"params":[],"example":[],"returns":[]}},{"event":"session.measure","optional":false,"type":"SessionMeasureResult","doc":{"desc":["`{ changed }`."],"params":[],"example":[],"returns":[]}},{"event":"session.end","optional":false,"type":"SessionEndResult","doc":{"desc":["`{ sessionId }`."],"params":[],"example":[],"returns":[]}},{"event":"plugin.register","optional":false,"type":"PluginRegisterResult","doc":{"desc":["`{ allow: true }`, or `{ refuse }`."],"params":[],"example":[],"returns":[]}},{"event":"turn.start","optional":false,"type":"TurnStartResult","doc":{"desc":["`{ turnId }`."],"params":[],"example":[],"returns":[]}},{"event":"turn.step","optional":false,"type":"TurnStepResult","doc":{"desc":["The response: `{ turnId, index, answer, toolUses, stopReason, usage }`,","and `serverToolUses` when the API ran tools of its own in the request."],"params":[],"example":[],"returns":[]}},{"event":"turn.complete","optional":false,"type":"TurnCompleteResult","doc":{"desc":["`{ text }`."],"params":[],"example":[],"returns":[]}},{"event":"engine.create","optional":false,"type":"EngineCreateResult","doc":{"desc":["`$` as built so far, with this plugin's interface added and any it","withheld left out; `next(e)` resolves to EngineInterfaceBuilt."],"params":[],"example":[],"returns":[]}}],"OpEventOf":[{"event":"model.complete","optional":false,"type":"ModelCompleteInput","doc":{"desc":["The argument of `$.model.complete(request, { signal })`, its text as","strings and its blocks beside them (ModelCompleteInput).","","The signal does not cross, it aborts the call."],"params":[],"example":[],"returns":[]}},{"event":"model.fork","optional":false,"type":"ModelForkRequest","doc":{"desc":["The argument of `$.model.fork(request)`."],"params":[],"example":[],"returns":[]}},{"event":"audio.speak","optional":false,"type":"SpeakRequest","doc":{"desc":["The argument of `$.audio.speak(text, { voice })`."],"params":[],"example":[],"returns":[]}},{"event":"session.cwd","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.cwd()`."],"params":[],"example":[],"returns":[]}},{"event":"session.root","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.root()`."],"params":[],"example":[],"returns":[]}},{"event":"session.model","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.model()`."],"params":[],"example":[],"returns":[]}},{"event":"session.turns","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.turns()`."],"params":[],"example":[],"returns":[]}},{"event":"session.id","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.id()`."],"params":[],"example":[],"returns":[]}},{"event":"session.messages","optional":false,"type":"SessionMessagesArgs","doc":{"desc":["The argument of `$.session.messages(args)`: `{}` for the main","conversation, `{ agentId }` for one of its agents, `as` for the form."],"params":[],"example":[],"returns":[]}},{"event":"session.repo","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.repo()`."],"params":[],"example":[],"returns":[]}},{"event":"session.surface","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.surface()`."],"params":[],"example":[],"returns":[]}},{"event":"session.surfaces","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.surfaces()`."],"params":[],"example":[],"returns":[]}},{"event":"session.authorize","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.authorize()`."],"params":[],"example":[],"returns":[]}},{"event":"session.identity","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.identity()`."],"params":[],"example":[],"returns":[]}},{"event":"session.usage","optional":false,"type":"SessionUsageArgs","doc":{"desc":["The argument of `$.session.usage({ breakdown, columns })`."],"params":[],"example":[],"returns":[]}},{"event":"session.version","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.session.version()`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.read","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.prompt.read()`."],"params":[],"example":[],"returns":[]}},{"event":"prompt.paint","optional":false,"type":"PromptPaintArgs","doc":{"desc":["The argument of `$.prompt.paint(...)`: the draft and this plugin's runs."],"params":[],"example":[],"returns":[]}},{"event":"tool.list","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.tool.list()`."],"params":[],"example":[],"returns":[]}},{"event":"tool.register","optional":false,"type":"RegisteredToolSpec","doc":{"desc":["The argument of `$.tool.register(spec)`."],"params":[],"example":[],"returns":[]}},{"event":"command.list","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.command.list()`."],"params":[],"example":[],"returns":[]}},{"event":"command.register","optional":false,"type":"CommandSpec","doc":{"desc":["The argument of `$.command.register(spec)`."],"params":[],"example":[],"returns":[]}},{"event":"config.list","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.config.list()`."],"params":[],"example":[],"returns":[]}},{"event":"agent.list","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.agent.list()`."],"params":[],"example":[],"returns":[]}},{"event":"agent.register","optional":false,"type":"AgentSpec","doc":{"desc":["The argument of `$.agent.register(spec)`: the agent type as the plugin","defined it. A hook above rewrites any of it; the type stays the caller's."],"params":[],"example":[],"returns":[]}},{"event":"ui.open","optional":false,"type":"PaneOpenArgs","doc":{"desc":["The argument of `$.ui.open({ id, title, focus })`; a hook above the","opener may retitle it or refuse it with `{ deny }`, never rename it."],"params":[],"example":[],"returns":[]}},{"event":"ui.close","optional":false,"type":"PaneCloseInput","doc":{"desc":["The argument of `$.ui.close({ id })` with `origin` `plugin`; the engine","raises it too, for the person (`person`) and an unload (`unload`)."],"params":[],"example":[],"returns":[]}},{"event":"ui.panes","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.ui.panes()`."],"params":[],"example":[],"returns":[]}},{"event":"ui.place","optional":false,"type":"UiPlaceArgs","doc":{"desc":["The argument of `$.ui.place({ id })`."],"params":[],"example":[],"returns":[]}},{"event":"theme.set","optional":false,"type":"ThemeSetArgs","doc":{"desc":["The argument of `$.theme.set(attributes)`: the attributes themselves."],"params":[],"example":[],"returns":[]}},{"event":"theme.clear","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.theme.clear()`."],"params":[],"example":[],"returns":[]}},{"event":"ui.selection","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.ui.selection()`."],"params":[],"example":[],"returns":[]}},{"event":"ui.copy","optional":false,"type":"UiCopyArgs","doc":{"desc":["The argument of `$.ui.copy({ text, surface })`, `surface` filled with","the session's first when left out; rewritable, deniable, answerable."],"params":[],"example":[],"returns":[]}},{"event":"ui.view","optional":false,"type":"SiteView","doc":{"desc":["The argument of `$.ui.view({ agentId })`: whose transcript the main view","is to show, none for the main conversation; rewritable and deniable."],"params":[],"example":[],"returns":[]}},{"event":"ui.blit","optional":false,"type":"UiBlitArgs","doc":{"desc":["The argument of `$.ui.blit(...)`: a Raster's `cells` or a keyed Image's","`source`; a hook above may rewrite either with `next`, or `{ deny }`."],"params":[],"example":[],"returns":[]}},{"event":"fs.ancestors","optional":false,"type":"FsAncestorsRequest","doc":{"desc":["The argument of `$.fs.ancestors({ names, of, below })`."],"params":[],"example":[],"returns":[]}},{"event":"store.keys","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.store.keys()`."],"params":[],"example":[],"returns":[]}},{"event":"state.get","optional":false,"type":"StateGetEvent","doc":{"desc":["The argument of `$.state.get(ref)`: the reference itself, `plugin`, `key`","and a family member's `id`; identity, pinned."],"params":[],"example":[],"returns":[]}},{"event":"state.set","optional":false,"type":"StateSetEvent","doc":{"desc":["The argument of `$.state.set(ref, value, { ifVersion })`: the reference,","the value, the condition, and `previous`, what stood there (the host's).","","A hook above rewrites `value` with `next({ ...e, value })`; the","reference is identity, pinned. Raised by the value's owner alone. A","`{ deny }` after `next(e)` was answered, a `.catch`'s too, fails the hook."],"params":[],"example":[],"returns":[]}},{"event":"clock.now","optional":false,"type":"NoArgs","doc":{"desc":["The argument of `$.clock.now()`."],"params":[],"example":[],"returns":[]}},{"event":"clock.sleep","optional":false,"type":"ClockWait","doc":{"desc":["The argument of `$.clock.sleep(ms, { signal })`; the signal does not","cross, it aborts the dispatch."],"params":[],"example":[],"returns":[]}},{"event":"clock.after","optional":false,"type":"ClockWait","doc":{"desc":["The argument of `$.clock.after(ms, fn)`: the wait before `fn`, which","stays in the plugin's environment and runs once the dispatch resolves."],"params":[],"example":[],"returns":[]}},{"event":"clock.every","optional":false,"type":"ClockWait","doc":{"desc":["The argument of `$.clock.every(ms, fn)`, dispatched once per period:","`fn` runs each time a dispatch resolves, and the next period is asked."],"params":[],"example":[],"returns":[]}},{"event":"process.spawn","optional":false,"type":"ProcessSpawnRequest","doc":{"desc":["The argument of `$.process.spawn(request)`: the request itself.","","A hook's `{ deny }` rejects the caller's stream and lets the child go","(one still running is killed). Once a child of the call handed up a","piece or its exit, the rejection says it started or ran."],"params":[],"example":[],"returns":[]}},{"event":"settings.read","optional":false,"type":"SettingsReadInput","doc":{"desc":["The argument of `$.settings.read({ source })`, and the layers the read","is made of, which the engine fills; rewritable, deniable."],"params":[],"example":[],"returns":[]}}]},"declarations":[{"name":"AgentCallRecord","kind":"type","line":109,"doc":{"desc":["What an Agent call a plugin raised (`$.tool.call({ tool: \"Agent\", ... })`)","answers as `result` once the agent settles; `text` is its final answer.","","A plugin's spawn always runs in the background, so the call resolves with","this record and not the Agent tool's own (BuiltinToolResults), which is","what a model's Agent call carries at `tool.call`."],"params":[],"example":[],"returns":[]},"text":" export type AgentCallRecord = {\n /**\n * The spawned agent's id, as `$.agent.list()` names it.\n */\n agentId: string;\n /**\n * The model the agent resolved to, when one is known.\n */\n resolvedModel?: string;\n };"},{"name":"AgentInfo","kind":"type","line":124,"doc":{"desc":["One agent loop of this session as `$.agent.list()` returns it: a subagent","or a teammate."],"params":[],"example":[],"returns":[]},"text":" export type AgentInfo = {\n /**\n * The agent's one id: `agent.spawn` answers it as `agentId`, its loop's\n * events carry it as `agentId`, a spawn inside it as `parentAgentId`.\n *\n * The Agent tool's record spells it `agentId` too, the classic events\n * (SubagentStart, SubagentStop, TeammateIdle) `agent_id`. A teammate in a\n * terminal pane of its own runs no loop here: its id is its address.\n */\n id: string;\n /**\n * A teammate's address in its team, `@`, which the roster keys\n * it by; absent for any other agent.\n *\n * It joins `agent.spawn`'s `teammateId` and the Agent tool's `teammate_id`,\n * and no event's `agentId`: that is `id`. A respawn under the name keeps it.\n */\n teammateId?: string;\n /**\n * The Agent call's own `description` of the task (a few words), as an\n * `agent.spawn` hook left it.\n */\n description: string;\n /**\n * The agent type it was spawned as, `agent.spawn`'s `subagentType`\n * (`general-purpose`, `Explore`, ...); `teammate` for one spawned as none.\n *\n * A teammate's classic events give its `name` as `agent_type`, not this.\n */\n type: string;\n /**\n * Where its loop stands now (AgentStatus): a teammate that waits for a\n * message is `idle`, not `running`.\n *\n * One in a terminal pane of its own is `running` or `idle` by what it last\n * wrote in its team's roster, at a turn's start and at its end: a pane that\n * is closed or dies leaves that word standing.\n */\n status: AgentStatus;\n /**\n * The id of the agent whose loop spawned it; absent when the main loop\n * did.\n */\n parentId?: string;\n /**\n * The plugin whose `$.agent.spawn` (or Agent `$.tool.call`) started it;\n * absent when the model or the person did.\n *\n * The origin axis: which plugin caused it, whichever loop that hook ran in.\n */\n spawnedBy?: string;\n /**\n * What SendMessage addresses it by (`Agent({ name })`, or the engine's own\n * for a background agent), when it has one; not `description` or `type`.\n *\n * A teammate's is its name in the team, with a suffix when the call's was\n * taken. Two agents may hold one name: `id` tells them apart.\n */\n name?: string;\n };"},{"name":"AgentLoop","kind":"type","line":193,"doc":{"desc":["Which model loop an event happened in: the loop's agent id inside a","subagent's or a teammate's loop, absent on the main loop.","","The agent axis, not the origin axis: `next.origin` names the plugin whose","hook frame caused the dispatch (the recursion skip), whichever loop it ran","in; `agentId` names the loop, whoever caused the call."],"params":[],"example":[],"returns":[]},"text":" export type AgentLoop = {\n /**\n * The id of the loop this call runs in: for a subagent or a teammate, the\n * `id` `$.agent.list()` gives it; absent on the main loop.\n *\n * A workflow's agents and the engine's own forks (compaction, memory) carry\n * ids no list names. Pinned: a different value is refused, one left out is\n * kept. Which loop, not which plugin caused it (that is `next.origin`).\n */\n agentId?: string;\n };"},{"name":"AgentOfferInput","kind":"type","line":213,"doc":{"desc":["The input of `agent.offer`: one agent type, at the moment the engine","offers it to the model.","","Listed for the model (the agent listing) or named by it at dispatch","(`subagent_type`): the same event at each. Model-facing only: a plugin's","own `$.agent.spawn` of a type is no offer, and `agent.spawn` governs it."],"params":[],"example":[],"returns":[]},"text":" export type AgentOfferInput = {\n /**\n * Which type (`Explore`, `Plan`, a plugin's agent); the key a matcher\n * narrows on.\n */\n agent: string;\n /**\n * Its listing line's text as the definition states it (`whenToUse`).\n */\n description: string;\n /**\n * Where the definition came from (`built-in`, `plugin`, a settings\n * source), so a matcher tells a built-in from a user's agent of its name.\n */\n source: string;\n /**\n * Who provides this agent: the plugin and its tier; `{ plugin: \"engine\",\n * tier: \"core\" }` for a built-in. Pinned: a rewrite is refused.\n */\n provider: Origin;\n };"},{"name":"AgentOfferResult","kind":"type","line":239,"doc":{"desc":["What an `agent.offer` hook returns: whether the model is offered the agent","type, in its listing and at dispatch."],"params":[],"example":[],"returns":[]},"text":" export type AgentOfferResult = {\n isOffered: boolean;\n };"},{"name":"AgentSpawnArgs","kind":"type","line":250,"doc":{"desc":["`agent.spawn`'s input as the call takes it: what the Agent tool's caller","says; the engine fills the rest.","","A call's spawn runs in the background: it resolves once the subagent","started, and nothing holds it in the foreground."],"params":[],"example":[],"returns":[]},"text":" export type AgentSpawnArgs = Pick & Partial>;"},{"name":"AgentSpawnInput","kind":"type","line":260,"doc":{"desc":["The input of `agent.spawn`: what is decided about an agent about to start,","before its model is resolved.","","A subagent, a teammate, a workflow agent or a resumed run. A hook rewrites","content (prompt, description, subagentType, model, background, cwd) unless","`resume` fixes it, or `workflow` all but two; every other key is pinned."],"params":[],"example":[],"returns":[]},"text":" export type AgentSpawnInput = {\n /**\n * The Agent tool call this spawn belongs to (for `$.ui.notice`). Pinned:\n * the spawn's identity.\n *\n * For a workflow agent, the Workflow tool call that started its run, shared\n * by all of the run's agents and possibly empty on a resumed or\n * server-launched run.\n */\n tool_use_id: string;\n /**\n * The task the subagent is given: the Agent tool's `prompt` parameter. A\n * rewrite is the prompt the subagent runs with.\n *\n * A workflow agent's is a fixed placeholder on a run that keeps its script\n * out of SDK events (Code Review's, say): a hook has not seen the prompt, so\n * a rewrite of it is not applied, and the agent starts with the script's own.\n */\n prompt: string;\n /**\n * The Agent tool's short `description` of the task (a few words). A rewrite\n * is what the task shows as.\n */\n description: string;\n /**\n * The resolved agent type (`general-purpose`, `Explore`, a plugin's agent,\n * `fork`). A rewrite names another agent this call can dispatch, exactly.\n *\n * That definition is the one spawned; a name matching none refuses the\n * spawn, and a fork dispatches no other. A teammate's may be a role no\n * definition has, as the call spelled it, or `teammate` when it named none.\n */\n subagentType: string;\n /**\n * Who provides this agent: the plugin and its tier; `{ plugin: \"engine\",\n * tier: \"core\" }` for a built-in. Pinned with the spawn's identity.\n */\n provider: Origin;\n /**\n * The Agent tool's `model` parameter as given, an alias (`haiku`) or a\n * full id; undefined lets the agent's own model, then the parent's, decide.\n *\n * Ignored for forks, which always inherit. A hook sets this to pick the\n * subagent's model; where the session forces one model on every subagent,\n * that outranks a workflow agent's, a hook's included.\n */\n model?: string;\n /**\n * The parent's effective model, what `inherit` resolves to. Pinned: a fact\n * of the parent (set `model` to change what the subagent runs on).\n */\n parentModel: string;\n /**\n * The id of the loop the spawn happens in (its `tool.call` `agentId`; for a\n * subagent or teammate its `$.agent.list()` id); absent from main.\n *\n * Pinned: a different value is refused, one left out is kept. The agent\n * axis, not the origin: `next.origin` names the plugin whose hook frame\n * caused the spawn, this names the model loop it happened in.\n */\n parentAgentId?: string;\n /**\n * The parent's permission mode (`default`, `acceptEdits`, `plan`, ...), which\n * the subagent inherits. Pinned: a fact of the parent.\n */\n permissionMode?: string;\n /**\n * True when the subagent will run in the background (or remotely). A\n * rewrite is read back as the call's `run_in_background`.\n *\n * The agent's own definition and remote isolation can still force it on,\n * and disabled background tasks force it off. A teammate's is true: a\n * rewrite is left out, said once in the plugin's failure line.\n */\n background: boolean;\n /**\n * True for a fork of the parent: it inherits the parent's context and model,\n * and `model` is ignored. Pinned: the spawn's identity.\n */\n fork: boolean;\n /**\n * Present, and true, when the call starts a teammate: a named agent of the\n * session's team, which goes idle between turns and wakes on a message.\n *\n * Absent for any other agent. Pinned: the spawn's identity.\n */\n isTeammate?: true;\n /**\n * Present when a workflow script's `agent()` starts the agent, absent for\n * any other. Pinned: the spawn's identity.\n *\n * A rewrite of its `prompt` and `model` applies; `description`,\n * `subagentType`, `background` and `cwd` do not apply to it, and one is left\n * out and said once. A deny is the error the script's `agent()` call throws.\n *\n * `next` settles with the first attempt's `agentId`; a stalled agent's\n * retry is not raised again. With `isolation: 'remote'` (internal builds\n * only) no `turn.complete`, loop event or list row carries that id.\n */\n workflow?: {\n /**\n * The run's id, which starts `wf_` (empty only outside a real run).\n *\n * A child `workflow()`'s agents carry their parent run's, and a resume\n * keeps it; a Workflow call that starts a fresh run gets a new id.\n */\n runId: string;\n /**\n * This agent's place among the run's `agent()` calls, from 1. Agents\n * replayed from the run's journal count but are not raised.\n *\n * The journal knows an agent by what the script asked, before any hook.\n * It restarts whenever the run's script starts over (a new run, a resume\n * or a background hand-off of the same `runId`); a call that reopens a\n * settled run keeps counting. A cap across resumes keeps its own count.\n */\n agentIndex: number;\n };\n /**\n * Present when the run resumes a subagent or brings a teammate back from\n * disk (`isTeammate` beside it), absent for a new agent.\n *\n * A hook can only refuse it; a changed content key is ignored, said once.\n * `prompt` is the resuming message (empty where none is appended). A deny\n * starts no run and ends nothing: a denied wake leaves its agent parked.\n */\n resume?: {\n /**\n * The id the run continues under, as `$.agent.list()` lists it; `next`\n * settles with it. An agent started with no event raised has one too.\n */\n agentId: string;\n };\n /**\n * Given by the call (`Agent({ name })`, addressable by SendMessage);\n * undefined when unnamed. Pinned: the address the parent routes by.\n *\n * A teammate whose name the team has already gets a suffix (`scout-2`),\n * which the answer's `teammateId` and `$.agent.list()` show.\n */\n name?: string;\n /**\n * The directory the subagent runs in when the call set one (`cwd`); undefined\n * means the parent's. A rewrite is where the subagent runs.\n *\n * A teammate runs in the session's: a rewrite is left out, as `background`'s.\n */\n cwd?: string;\n };"},{"name":"AgentSpawnResult","kind":"type","line":421,"doc":{"desc":["What an `agent.spawn` hook returns and what `next(e)` resolves to: the","started subagent's `{ model, agentId }`, or `{ deny: reason }`, refusing it.","","It and `$.agent.spawn(input)` resolve once the subagent started; its answer","is its own `turn.complete`, carrying this `agentId`. Keep the id and set","`got[agentId]` to what waits; a `turn.complete` hook resolves it:"],"params":[],"example":["on(\"turn.complete\", ($, e, next) => (got[e.agentId]?.(e.answer), next(e)))"],"returns":[]},"text":" export type AgentSpawnResult = {\n /**\n * What the subagent runs on: from core the resolved id; from a hook an\n * alias (`haiku`) or an id.\n */\n model: string;\n /**\n * The started subagent's id: the same string its loop's `tool.call`\n * events carry as `agentId` and `$.agent.list()` lists it by.\n *\n * A workflow's remote agent has no local loop, so nothing else carries\n * it. Set by core; a hook that answers without `next` started none.\n */\n agentId?: string;\n /**\n * A started teammate's address in its team, `@`, as\n * `$.agent.list()` gives it; absent for any other agent.\n *\n * Set by core. It joins the list's `teammateId` and the tool's\n * `teammate_id`; every event of the teammate's loop carries `agentId`.\n */\n teammateId?: string;\n deny?: undefined;\n } | {\n /**\n * Refuses the spawn, so nothing starts; the text is the Agent tool's\n * error, or the error a workflow script's `agent()` call throws.\n *\n * Returned after a `next(e)` was answered it fails the hook: its\n * `.catch` is asked (a deny from it fails too), or it is skipped by\n * name and its last `next` stands.\n */\n deny: string;\n model?: undefined;\n agentId?: undefined;\n teammateId?: undefined;\n };"},{"name":"AgentSpec","kind":"type","line":466,"doc":{"desc":["What `$.agent.register` takes: an agent type this plugin defines, spelled","as an agent definition in settings JSON is, plus its `name`.","","Every field an agent file or `--agents` entry may carry is here and takes","effect as it does there; the engine validates it with the same schema."],"params":[],"example":[],"returns":[]},"text":" type AgentSpec = {\n /**\n * The type's short name (letters, digits, `_`, `-`; up to 64); the type is\n * `:`, as a plugin's agent file `agents/.md` names one.\n */\n name: string;\n /**\n * When to delegate to this agent: the line the model reads in its listing\n * of agent types, and `agent.offer`'s `description`.\n */\n description: string;\n /**\n * The agent's system prompt, whole: it replaces the session's.\n */\n prompt: string;\n /**\n * What the agent may call, by tool name (`Read`, `Bash`, `mcp__x__y`); a\n * call to any other is refused. Left out: every tool the parent has.\n */\n tools?: readonly string[];\n /**\n * Tools withheld from the agent, by name, out of whatever `tools` allows.\n */\n disallowedTools?: readonly string[];\n /**\n * The agent's model: an alias (`haiku`, `sonnet`, `opus`), a full id, or\n * `inherit` for the parent's. Left out: the session's subagent default.\n */\n model?: string;\n /**\n * The agent's effort: a level (`low`, `medium`, `high`, `xhigh`, `max`)\n * or an integer budget.\n */\n effort?: string | number;\n /**\n * How the agent's permission asks are decided, a mode: `default`,\n * `acceptEdits`, `plan`, `auto`, `dontAsk` or `bypassPermissions`.\n *\n * Left out: the parent's.\n */\n permissionMode?: string;\n /**\n * Servers connected over MCP for the agent's run: a configured server's\n * name, or `{ \"\": { command, args } }`, one server's config inline.\n */\n mcpServers?: readonly (string | Record)[];\n /**\n * Settings hooks in force while the agent runs, in settings.json's `hooks`\n * shape (`{ PreToolUse: [{ matcher, hooks: [...] }] }`).\n */\n hooks?: Record;\n /**\n * The most turns the agent takes before it stops.\n */\n maxTurns?: number;\n /**\n * Token count, 100000 to 1000000, at which the agent compacts its own\n * conversation as a subagent. It only lowers the window the agent would\n * otherwise get.\n */\n autoCompactWindow?: number;\n /**\n * Preloaded into the agent's context before its first turn: skill names.\n */\n skills?: readonly string[];\n /**\n * The agent's first user turn; `{{intent}}` in it takes the spawn's prompt.\n * Left out: the spawn's prompt is the first turn.\n */\n initialPrompt?: string;\n /**\n * A persistent memory the agent keeps between runs, and where: `user`,\n * `project` or `local`.\n */\n memory?: 'user' | 'project' | 'local';\n /**\n * Set so that every spawn of the agent runs in the background.\n */\n background?: true;\n /**\n * Set so that the agent's context carries no CLAUDE.md block (the person's,\n * the project's, the rules): it takes what it needs from its prompt.\n */\n omitClaudeMd?: true;\n /**\n * Where the agent runs apart from the session: `worktree`, a git worktree\n * of its own; `remote`, a cloud session where the build allows one.\n */\n isolation?: 'worktree' | 'remote';\n };"},{"name":"AgentStatus","kind":"type","line":565,"doc":{"desc":["Where an agent's loop stands: `pending` (not started), `running` a turn,","`waiting` (held), `idle` (between turns, until a message wakes it), or ended.","","`waiting` is on background work it owns, on a plan's approval or, in a","background subagent, on an Agent call alone. Ended is `completed`, `failed`","or `killed` (stopped); a message may yet resume one, under the same id."],"params":[],"example":[],"returns":[]},"text":" export type AgentStatus = 'pending' | 'running' | 'waiting' | 'idle' | 'completed' | 'failed' | 'killed';"},{"name":"AgentTeammateRecord","kind":"type","line":574,"doc":{"desc":["What an Agent call that started a teammate answers as `result` at","`tool.call`: the started teammate's two ids, its name and its model.","","The call answers once the teammate started; each of its turns ends in its","own `turn.complete`, carrying `agentId` (none here from a terminal pane)."],"params":[],"example":[],"returns":[]},"text":" export type AgentTeammateRecord = {\n status: 'teammate_spawned';\n /**\n * The teammate's one id, as every Agent record spells it: `agent.spawn`'s\n * `agentId`, its loop's events' `agentId`, its `$.agent.list()` `id`.\n *\n * For one in a terminal pane, which runs no loop here, its address. Absent\n * from a record an earlier version wrote, which a resumed transcript holds.\n */\n agentId?: string;\n /**\n * The same id in this record's older spelling, which the classic events\n * share (`classic.SubagentStop`'s `agent_id`).\n */\n agent_id: string;\n /**\n * Its address in its team, `@`: `$.agent.list()`'s\n * `teammateId`, and no event's `agentId`.\n */\n teammate_id: string;\n /**\n * What SendMessage addresses it by: the call's `name`, any `@` replaced,\n * with a suffix (`scout-2`) when the team already has it.\n */\n name: string;\n /**\n * The team it joined: the session's own.\n */\n team_name?: string;\n /**\n * What it was spawned as, when the call named a type.\n */\n agent_type?: string;\n /**\n * What it was started on, an alias resolved, as every Agent record spells\n * it: `agent.spawn`'s `model`.\n *\n * Absent where `agentId` is: `model` has it then, an alias as spelled.\n */\n resolvedModel?: string;\n /**\n * The older spelling of that, an alias left as the call spelled it.\n */\n model?: string;\n /**\n * The task it was given, as an `agent.spawn` hook left it.\n */\n prompt: string;\n };"},{"name":"AnyEventHook","kind":"type","line":635,"doc":{"desc":["The hook `on(\"*\", hook)` takes: it runs on every event, plugin nouns no","declaration names included, so `e` is `unknown` and `next` is StarNext.","","Until `next.is(pattern, e)` narrows `e`, all a hook can do with it is pass","it on, time it, log it, or fail it; once narrowed it is an ordinary hook on","those events."],"params":[["$","the engine interface; at `engine.create` the empty table, so a hook that reads `$` tests `next.is(\"engine.create\", e)` first"]],"example":[],"returns":[]},"text":" export type AnyEventHook = ($: EngineInterface, e: unknown, next: StarNext) => unknown;"},{"name":"AnyKeyOf","kind":"type","line":640,"doc":{"desc":["Every key of every variant, index signatures included."],"params":[],"example":[],"returns":[]},"text":" type AnyKeyOf = I extends unknown ? keyof I : never;"},{"name":"ApiContentBlock","kind":"type","line":650,"doc":{"desc":["One content block of an ApiMessage: `type` names its kind (`text`,","`tool_use`, `tool_result`, `image`, `document`, `thinking`, ...).","","The other fields are that kind's as the Messages API defines them (see its","reference); the engine hands the block over as it holds it, nothing renamed","or dropped."],"params":[],"example":[],"returns":[]},"text":" type ApiContentBlock = {\n /**\n * The block's kind; the rest of the block is that kind's fields.\n */\n type: string;\n [field: string]: unknown;\n };"},{"name":"ApiMessage","kind":"type","line":666,"doc":{"desc":["One message of the conversation in Messages API form, as","`$.session.messages({ as: \"api\" })` returns it.","","The messages are the ones the next request is built from, after the","engine's normalization (the last compaction's summary in place of what it","replaced, reminders as text blocks); at most 4096, opening on a user one."],"params":[],"example":[],"returns":[]},"text":" type ApiMessage = {\n /**\n * Who wrote it.\n */\n role: 'user' | 'assistant';\n /**\n * Its blocks in order, always an array: text, tool_use and tool_result\n * (paired across an assistant message and the next), image and document.\n *\n * Media inline as the engine holds it, thinking as it goes back. In no\n * message: the system prompt, the tool list, and what one send adds for\n * its model (cache marks, reminders promoted to system turns).\n */\n content: ApiContentBlock[];\n };"},{"name":"Args","kind":"type","line":686,"doc":{"desc":["The argument of event `N`: `e` in its hooks, and what its call takes. For a","union of names, the union of their arguments."],"params":[],"example":[],"returns":[]},"text":" export type Args = EventOf[N];"},{"name":"AskOptions","kind":"type","line":691,"doc":{"desc":["Options of `$.ui.ask`."],"params":[],"example":[],"returns":[]},"text":" export type AskOptions = {\n /**\n * 2-4 option labels; fewer than two are padded with Yes/No; free text is the\n * dialog's Other.\n */\n options?: readonly string[];\n /**\n * A short chip beside the question (`Approach`, 12 characters at most).\n */\n header?: string;\n /**\n * Allow several options; the answer comes back comma-joined.\n */\n multiSelect?: true;\n };"},{"name":"Atom","kind":"type","line":714,"doc":{"desc":["A named value with its initial, as `atom(ref, initial)` makes it: read, it","is never `undefined`; while nothing is written it reads as the initial.","","Plain frozen data, the plugin's own: pass it to `read`, `update`, `derive`","and `memberOf`. The engine knows nothing of it."],"params":[],"example":[],"returns":[]},"text":" export type Atom = {\n readonly ref: StateAddress;\n readonly initial: T;\n /**\n * The tag the value is kept under, when the atom was given one: a stored\n * value under another tag reads as absent (Shaped).\n */\n readonly shape?: string;\n };"},{"name":"AtomFunction","kind":"type","line":734,"doc":{"desc":["`atom(ref, initial)`: a named value with its initial, so a read is never","`undefined`; given `{ shape }`, for a key declared `Shaped`.","","Pure: it builds a frozen description and calls nothing. A family's","reference is given without its `id`, which `memberOf` adds."],"params":[],"example":["const count = atom({ plugin: \"counter\", key: \"count\" } as const, 0)"],"returns":[]},"text":" export type AtomFunction = {\n

(ref: StateName & Readonly>, initial: StateValue): Atom>;\n

(ref: StateName & Readonly>, initial: ShapedValue>, options: AtomOptions): Atom>>;\n };"},{"name":"AtomOptions","kind":"type","line":746,"doc":{"desc":["The options of `atom`: `shape`, a tag the value is kept under, so a reload","of the plugin's code that names another tag finds the value absent.","","Bump it when the code's idea of the value changed; the engine keeps whole","what the old code wrote, and the tag is how the new code declines it."],"params":[],"example":[],"returns":[]},"text":" export type AtomOptions = {\n shape: string;\n };"},{"name":"AttributionTextInput","kind":"type","line":757,"doc":{"desc":["The input of `attribution.text`: one text the engine asks the model to","write into a commit or a pull request, at the moment it is composed.","","Composed for the Bash description, the commit skills, a PR's body, the","pre-ship mandate and the commit gate's deny: the same event at each."],"params":[],"example":[],"returns":[]},"text":" export type AttributionTextInput = {\n /**\n * Which text (`commit`, `pr`, `exemption`, `remedy`); the key a matcher\n * narrows on.\n */\n kind: AttributionTextKind;\n /**\n * As the engine composed it, the settings applied.\n */\n text: string;\n };"},{"name":"AttributionTextKind","kind":"type","line":773,"doc":{"desc":["Which git text `attribution.text` carries: the commit trailer, the PR","footer, the mandate's or the commit gate's sentence naming the exemption."],"params":[],"example":[],"returns":[]},"text":" export type AttributionTextKind = 'commit' | 'pr' | 'exemption' | 'remedy';"},{"name":"AttributionTextResult","kind":"type","line":779,"doc":{"desc":["What an `attribution.text` hook returns: the text the model reads in","that place."],"params":[],"example":[],"returns":[]},"text":" export type AttributionTextResult = {\n text: string;\n };"},{"name":"AudioClip","kind":"type","line":786,"doc":{"desc":["What `$.audio.play` plays: a URL the engine fetches, or the bytes."],"params":[],"example":[],"returns":[]},"text":" export type AudioClip = {\n /**\n * A file of the calling plugin's own, relative to the plugin's\n * directory (`fx/open.wav`); no `.`, no leading slash.\n *\n * The engine resolves it and loads the file from disk.\n */\n asset: string;\n url?: undefined;\n base64?: undefined;\n mime?: undefined;\n } | {\n /**\n * The clip's URL; the engine fetches it (never the plugin), or refuses\n * it as `$.http.fetch` would refuse the same URL.\n */\n url: string;\n asset?: undefined;\n base64?: undefined;\n mime?: undefined;\n } | {\n /**\n * The clip's bytes, base64.\n */\n base64: string;\n /**\n * What the bytes are (`audio/mpeg`, `audio/wav`).\n */\n mime: string;\n asset?: undefined;\n url?: undefined;\n };"},{"name":"BackgroundTaskSummary","kind":"type","line":819,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type BackgroundTaskSummary = {\n id: string;\n /**\n * Friendly task-type label (e.g. 'shell', 'subagent', 'monitor', 'workflow'). Falls back to the raw discriminant for unknown types.\n */\n type: string;\n status: string;\n /**\n * Free-text description. Capped at 1000 chars; clipped values append an in-string \"... [+N chars]\" marker.\n */\n description: string;\n /**\n * Shell command line. Only present for 'shell' tasks. Capped at 1000 chars with the same \"... [+N chars]\" marker.\n */\n command?: string;\n /**\n * Subagent type name. Only present for 'subagent' tasks.\n */\n agent_type?: string;\n /**\n * MCP server name. Only present for 'monitor' / 'MCP task' tasks.\n */\n server?: string;\n /**\n * MCP tool name. Only present for 'monitor' / 'MCP task' tasks.\n */\n tool?: string;\n /**\n * Workflow name. Only present for 'workflow' tasks.\n */\n name?: string;\n };"},{"name":"BaseHookInput","kind":"type","line":852,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type BaseHookInput = {\n session_id: string;\n transcript_path: string;\n cwd: string;\n /**\n * UUID correlating a user prompt with all subsequent events until the next prompt. Same value emitted on OpenTelemetry events as the `prompt.id` attribute, so hook output can be joined to OTel events at prompt grain. Absent until the first user input of the process lifetime.\n */\n prompt_id?: string;\n permission_mode?: string;\n /**\n * Subagent identifier. Present only when the hook fires from within a subagent (e.g., a tool called by an AgentTool worker). Absent for the main thread, even in --agent sessions. Use this field (not agent_type) to distinguish subagent calls from main-thread calls.\n */\n agent_id?: string;\n /**\n * Agent type name (e.g., \"general-purpose\", \"code-reviewer\"). Present when the hook fires from within a subagent (alongside agent_id), or on the main thread of a session started with --agent (without agent_id).\n */\n agent_type?: string;\n /**\n * Reasoning effort applied to the current turn. Same shape as StatusLineCommandInput.effort. Present for hooks that fire within a tool-use context (PreToolUse, PostToolUse, Stop, SubagentStop, etc.) on a model that supports the effort parameter; absent for session-lifecycle hooks and models without effort support.\n */\n effort?: {\n /**\n * Active effort level for the current turn (e.g., \"low\", \"medium\", \"high\", \"xhigh\", \"max\"), after any silent downgrade for the selected model. Also exposed to hook commands and Bash as the CLAUDE_EFFORT env var.\n */\n level: string;\n };\n };"},{"name":"BoxHoverProps","kind":"type","line":888,"doc":{"desc":["The `Box` props a `hover` may override, none of which moves the Box's","siblings, and `scope`, which names the hover group the Box joins.","","The surface applies a hover as the pointer moves and as what is drawn","under a resting pointer changes; a reveal that keeps moving what it rests","on settles, never loops."],"params":[],"example":[],"returns":[]},"text":" export type BoxHoverProps = {\n /**\n * Names a hover group of this plugin's: every element it draws with the\n * same `scope`, in any site, lights while any is hovered, reveals included.\n *\n * A Pane row and a mark on a transcript message can share one. Another\n * plugin's elements under the same string are a different group. One to\n * 64 characters, no control characters; no keyed Box needed; no hook runs.\n */\n scope?: string;\n /**\n * Restyles a border the Box has; it adds none.\n */\n borderStyle?: string;\n borderColor?: Color;\n borderDimColor?: boolean;\n backgroundColor?: Color;\n /**\n * `\"flex\"` alone, on a Box drawn `display: \"none\"`: with a `scope`, every\n * member of the lit group is revealed, in whichever site it sits.\n *\n * So a pointer on a glyph in the transcript can swap an entry into a fixed\n * row of the band, or reveal an absolutely positioned card.\n */\n display?: 'flex';\n /**\n * Moves a Box drawn `position: \"absolute\"`, as `left`, `right` and\n * `bottom` do; none of the four moves a Box in the flow.\n */\n top?: number;\n left?: number;\n right?: number;\n bottom?: number;\n };"},{"name":"BoxProps","kind":"type","line":927,"doc":{"desc":["The props of `Box`: the layout, position, margin, padding and border props","of Ink's Box a tree may set, and the two of hover."],"params":[],"example":[],"returns":[]},"text":" export type BoxProps = {\n /**\n * Makes the Box a hover scope: while the pointer is anywhere over it, its\n * own `hover` and that of every element beneath it apply.\n *\n * A nested Box with a `key` of its own scopes what is beneath it, a placed\n * card outside its rows included. A key a sibling Box already took, or one\n * that is no plain string, names no scope: hovers beneath it stay inert.\n */\n key?: string;\n /**\n * Style overrides applied by the surface while the pointer is over the\n * nearest keyed `Box`, this one included, or, given a `scope`, its group.\n *\n * No hook runs and nothing crosses to the plugin. To reveal on hover, draw\n * the Box `display: \"none\"` with `hover: { display: \"flex\" }` in a visible\n * keyed Box or under a `scope`; on a `position: \"absolute\"` Box, no reflow.\n */\n hover?: BoxHoverProps;\n /**\n * `\"absolute\"` leaves the flow, as in CSS: placed against its parent by\n * the offsets, no room among its siblings, painted over those before it.\n *\n * So showing or moving it (a hover may) moves nothing; the pointer on it is\n * on its parent. Clipped, pointer and paint, by the region its site is in\n * (viewport, pane, band), by the site itself on the main screen or export.\n *\n * @example glyphthe card\n */\n position?: 'relative' | 'absolute';\n /**\n * Rows from the parent's top edge, in character cells: an integer,\n * negative above the edge.\n *\n * With `bottom` and no `height` the Box spans the two.\n */\n top?: number;\n /**\n * Columns from the parent's left edge, in character cells: an integer,\n * negative left of the edge.\n *\n * With `right` and no `width` the Box spans the two.\n */\n left?: number;\n /**\n * Columns from the parent's right edge, in character cells: an integer,\n * negative right of the edge.\n */\n right?: number;\n /**\n * Rows from the parent's bottom edge, in character cells: an integer,\n * negative below the edge.\n */\n bottom?: number;\n flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';\n flexGrow?: number;\n flexShrink?: number;\n flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';\n alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch';\n alignSelf?: 'flex-start' | 'center' | 'flex-end' | 'auto';\n justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';\n /**\n * Space between the children, across and down, in cells or a step name.\n * Spacing flows from the parent: set `gap` on the Box rather than a margin\n * on each child. A graphical surface draws `xs` between the Buttons of a\n * row Box with no gap; the terminal draws them as written.\n */\n gap?: Space;\n columnGap?: Space;\n rowGap?: Space;\n width?: number | string;\n height?: number | string;\n minWidth?: number | string;\n minHeight?: number | string;\n margin?: Space;\n marginX?: Space;\n marginY?: Space;\n marginTop?: Space;\n marginBottom?: Space;\n marginLeft?: Space;\n marginRight?: Space;\n padding?: Space;\n paddingX?: Space;\n paddingY?: Space;\n paddingTop?: Space;\n paddingBottom?: Space;\n paddingLeft?: Space;\n paddingRight?: Space;\n borderStyle?: string;\n borderColor?: Color;\n borderDimColor?: boolean;\n backgroundColor?: Color;\n overflow?: 'visible' | 'hidden';\n display?: 'flex' | 'none';\n };"},{"name":"BuiltinToolCallInput","kind":"type","line":1028,"doc":{"desc":["One variant per built-in tool; with none in the table (a plugin author's","project with no tools entry laid), one loose variant over every name."],"params":[],"example":[],"returns":[]},"text":" export type BuiltinToolCallInput = [BuiltinToolName] extends [never] ? BuiltinToolCallInputFallback : {\n [N in BuiltinToolName]: ToolInputOf;\n }[BuiltinToolName];"},{"name":"BuiltinToolCallInputFallback","kind":"type","line":1036,"doc":{"desc":["The built-in branch's answer when no built-in tool is declared: every","name, its args unconstrained."],"params":[],"example":[],"returns":[]},"text":" type BuiltinToolCallInputFallback = {\n /**\n * The name of the tool being called (`Bash`); comparing it narrows `e` once\n * the table has entries. Reserved: a rewrite of it is ignored by core.\n */\n tool: string;\n /**\n * The tool_use block's id: the same at every event of the call and in\n * `$.ui.notice`. Reserved: a rewrite of it is ignored by core.\n */\n tool_use_id: string;\n [argument: string]: unknown;\n };"},{"name":"BuiltinToolInputs","kind":"interface","line":1061,"doc":{"desc":["The arguments of each built-in tool by name, for declaration merging;","empty until a declaration file adds entries, then `e.tool === \"Bash\"`","narrows `e` to Bash's arguments.","","The engine lays this build's set beside a mod it loads","(claude-code-tools/index.d.ts), from each tool's input schema."],"params":[],"example":["interface BuiltinToolInputs { Bash: { command: string; timeout?: number } }"],"returns":[]},"text":" export interface BuiltinToolInputs {\n }"},{"name":"BuiltinToolName","kind":"type","line":1067,"doc":{"desc":["The names of the built-in tools."],"params":[],"example":[],"returns":[]},"text":" export type BuiltinToolName = keyof BuiltinToolInputs & string;"},{"name":"BuiltinToolResults","kind":"interface","line":1081,"doc":{"desc":["The structured result of each built-in tool by name, for declaration","merging; empty until a declaration file adds entries, then after","`e.tool === \"Bash\"` the `result` of `next(e)` is Bash's record.","","The engine lays this build's set beside a mod it loads","(claude-code-tools/index.d.ts), from each tool's output schema; a tool","without one is `unknown`."],"params":[],"example":["interface BuiltinToolResults { Bash: { stdout: string; stderr: string } }"],"returns":[]},"text":" export interface BuiltinToolResults {\n }"},{"name":"ButtonProps","kind":"type","line":1092,"doc":{"desc":["The props of `Button`, every surface's pressable: an address, a label or","children, the closure a press runs, and the styles a hover overrides.","","The terminal draws `[ label ]` (when `plain`, `1: label` or the label","alone), a desktop a native button; a click, a `hotkey`, the chord for its","`action`, or Enter under the focus raises `ui.press`, its bottom `onPress`."],"params":[],"example":[],"returns":[]},"text":" export type ButtonProps = {\n /**\n * The element's address: `e.element` at `ui.press`, what a matcher names.\n * Defaults to the `label`, or the one string child.\n *\n * Needed where the Button holds other children and no `label`: a row's\n * text holds what changes (a count, an age), its address must not.\n *\n * Give every Button in a list its own: a surface finds one again by it\n * after a redraw, and cannot tell apart two that share it.\n */\n key?: string;\n /**\n * The text drawn on the button; or the one string child.\n *\n * Children of strings and `Text` (a chip, a dim part) are drawn in its\n * place, one press wherever on them it lands; any other element is refused.\n * The label then names the control; absent, it is the children's text.\n *\n * @example\n * \n */\n label?: string;\n /**\n * One digit (`\"1\"`) or one lowercase letter (`\"w\"`) that presses it while\n * the plugin's site holds the focus; anything else is refused.\n *\n * Its site holds it after ctrl+x tab, a click or `open({ focus })`: the band\n * or its `Pane`; never the composer, save that a bare digit in an empty one\n * answers a band Button (a survey). Shift+w is `\"w\"`; two clash, later wins.\n */\n hotkey?: string;\n /**\n * An engine keybinding action (`\"app:cycleDiffBase\"`) whose chord, as the\n * person bound it, presses this from the prompt; unknown names refused.\n *\n * Chords, or a modified key Global or an active context binds, on the\n * terminal while mounted, no dialog up and no engine handler of the action\n * mounted; a pane's over the band's over another's, then the last drawn.\n */\n action?: string;\n /**\n * Drawn without chrome: the hotkey in the accent color, a colon, the\n * label (`1: Yes`), as a survey's row reads; no `hotkey`, the label alone.\n *\n * A one-glyph label (`'\\u{1F50A}'`, a speaker) is then a control by\n * itself: the focus and the pointer still invert it, `dimColor` and `hover`\n * still apply. A desktop draws its native button either way.\n */\n plain?: true;\n /**\n * The label drawn dim at rest, as `Text`'s `dimColor`, and at full strength\n * under the pointer or the focus: a secondary control, a path in a list.\n */\n dimColor?: boolean;\n /**\n * Which button of several is the main action: `\"primary\"` is drawn as the\n * surface marks the one to press, `\"secondary\"`, and absent, as before.\n *\n * The terminal draws a primary `[ label ]` in the accent color, a desktop\n * its own primary button; `dimColor`, `hover`, the focus and the pointer\n * apply to both. `plain` wins: a plain Button draws the same either way.\n *\n * @example \n */\n variant?: 'primary' | 'secondary';\n /**\n * Marks the Button that closes its site: a drawing hint only. `onPress`\n * still does the dismissing and the press is raised as for any Button.\n *\n * The terminal draws it as without the prop; a desktop draws its native\n * close control at the site's trailing edge, the label its accessible name.\n *\n * @example \n */\n role?: 'dismiss';\n /**\n * The site's focus ring starts here when the site takes the keyboard,\n * instead of on nothing, as the DOM's `autofocus`: Enter acts on it at once.\n *\n * A pane opened with `focus`, or the person's focus chord or click, is the\n * take. Of several in one site the first drawn wins; it raises `ui.focus`,\n * origin this plugin. A ring the person has moved stays where it was put.\n */\n autoFocus?: true;\n /**\n * Label style overrides (the `Text` set) applied by the surface while the\n * nearest enclosing keyed `Box`, or given a `scope` its group, is hovered.\n *\n * No hook runs and nothing crosses to the plugin; under the pointer itself\n * the button inverts as it always has. Refused outside a keyed Box unless\n * it names a `scope`.\n */\n hover?: TextHoverProps;\n /**\n * What the press runs, in the plugin's own environment: the bottom of the\n * `ui.press` chain. The host holds only a handle, for the drawing's life.\n *\n * Run with the `ui.press` argument as the chain above left it: `e.surface`\n * names the surface the press came from, which a copy passes on.\n *\n * @example\n * onPress: press => $.ui.copy({ text: url, surface: press.surface })\n */\n onPress: (e: UiPressArgument) => void;\n };"},{"name":"CatchHandler","kind":"type","line":1207,"doc":{"desc":["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.","","`next` carries `error` and `called` (Caught) and is replay-safe; a return","within the grace is the hook's result, `undefined` the hook absent. On a","streaming event the handler is a generator too, continuing the stream."],"params":[],"example":[],"returns":[]},"text":" export type CatchHandler = F extends ($: infer D, e: infer E, next: infer N) => infer R ? [R] extends [AsyncGenerator] ? ($: D, e: E, next: N & Caught) => R : ($: D, e: E, next: N & Caught) => R | undefined | Promise | undefined> : never;"},{"name":"Caught","kind":"type","line":1217,"doc":{"desc":["What `next` carries into a `.catch` handler and nowhere else: why the","hook failed, and whether it had called `next` before it did.","","There `next` is replay-safe: when `called`, `next(e)` resolves to what the","hook's last call settled to, nothing beneath running again, the argument","unread; when not, it runs the hooks beneath once and a later call replays."],"params":[],"example":[],"returns":[]},"text":" export type Caught = {\n /**\n * Why the hook failed (HookFailure); undefined on an ordinary hook's\n * `next`, so its presence says a handler is running.\n */\n readonly error: HookFailure;\n /**\n * True when the failed hook had called `next()` or `next.to()` at least\n * once, settled or in flight; the handler runs once that call settled.\n */\n readonly called: boolean;\n };"},{"name":"Chunk","kind":"type","line":1234,"doc":{"desc":["What a hook on streaming event `N` yields, and what its `next(e)` yields","to it (ChunkOf by name)."],"params":[],"example":[],"returns":[]},"text":" export type Chunk = ChunkOf[N];"},{"name":"ChunkOf","kind":"type","line":1239,"doc":{"desc":["The chunk type of each streaming event, by name: what its stream yields."],"params":[],"example":[],"returns":[]},"text":" export type ChunkOf = {\n /**\n * One piece of the model's response (TurnStepChunk).\n */\n 'turn.step': TurnStepChunk;\n /**\n * One piece of the child's output (ProcessSpawnChunk).\n */\n 'process.spawn': ProcessSpawnChunk;\n };"},{"name":"ChunkRef","kind":"type","line":1258,"doc":{"desc":["What every `turn.step` chunk may carry: the engine's handle on the item","of its own stream the chunk was read off, absent on a chunk a hook made.","","A hook that passes a chunk on, or rewrites it by spreading it, keeps the","handle, and whatever it left unchanged reaches the engine as the engine","streamed it; a chunk built afresh has none and is taken at its word."],"params":[],"example":[],"returns":[]},"text":" type ChunkRef = {\n /**\n * The engine's handle on its own streamed item; opaque, this step's only.\n */\n ref?: number;\n };"},{"name":"ClassicEventName","kind":"type","line":1273,"doc":{"desc":["The name of a classic hook event as a function-hooks event: the settings","hook's own name under `classic` (`classic.Stop`, `classic.PreToolUse`).","","Each fires wherever the engine runs the classic hook, whether or not any","settings hook is configured, and reaches a `*` or `classic.*` hook as it","reaches a named one."],"params":[],"example":[],"returns":[]},"text":" export type ClassicEventName = `classic.${ClassicHookEvent}`;"},{"name":"ClassicEventOf","kind":"type","line":1286,"doc":{"desc":["The classic (settings) hook events, one per classic event name: `e` is the","hook's whole stdin input, base fields (`transcript_path`, `cwd`) included.","","The chain is [managed settings hooks, ...hooks modules, the other settings","hooks as core], so a managed block ends it above every module. In shape","`classic.PreToolUse` alone differs: its `e` is ToolCallEnvelope, no more."],"params":[],"example":[],"returns":[]},"text":" export type ClassicEventOf = {\n [E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? ToolCallEnvelope : ClassicHookInputs[E];\n };"},{"name":"ClassicHookEvent","kind":"type","line":1293,"doc":{"desc":["The name of a classic hook event: `PreToolUse`, `Stop`, and the rest."],"params":[],"example":[],"returns":[]},"text":" export type ClassicHookEvent = HookInput['hook_event_name'];"},{"name":"ClassicHookInputs","kind":"type","line":1299,"doc":{"desc":["What a classic hook receives on stdin for each event, by event name: the","Agent SDK's `HookInput`."],"params":[],"example":[],"returns":[]},"text":" export type ClassicHookInputs = {\n [I in HookInput as I['hook_event_name']]: I;\n };"},{"name":"ClassicResult","kind":"type","line":1311,"doc":{"desc":["Everything a classic hook event's answer can carry, named as the classic","hook's JSON output names it; each event reads its subset (ClassicResultOf).","","The settings hooks below fold into one of these (last write wins, contexts","concatenate); a hooks module returns `next(e)`, a copy with fields changed,","or its own. A field of the wrong shape fails the hook, which is skipped."],"params":[],"example":[],"returns":[]},"text":" export type ClassicResult = {\n /**\n * `decision: \"block\"` with this text as `reason` (a command hook's exit\n * code 2): the event's block, veto or re-prompt.\n */\n block?: string;\n /**\n * `continue: false`: the session stops after this event.\n */\n preventContinuation?: true;\n /**\n * Shown when `preventContinuation` stops the session (`stopReason`).\n */\n stopReason?: string;\n /**\n * `hookSpecificOutput.additionalContext`, one entry per hook: text handed\n * to the model with the event.\n */\n additionalContext?: string[];\n /**\n * `hookSpecificOutput.sessionTitle` (UserPromptSubmit, SessionStart).\n */\n sessionTitle?: string;\n /**\n * `hookSpecificOutput.suppressOriginalPrompt` (UserPromptSubmit,\n * UserPromptExpansion).\n */\n suppressOriginalPrompt?: true;\n /**\n * `hookSpecificOutput.initialUserMessage` (SessionStart).\n */\n initialUserMessage?: string;\n /**\n * `hookSpecificOutput.watchPaths` (SessionStart).\n */\n watchPaths?: string[];\n /**\n * `hookSpecificOutput.reloadSkills` (SessionStart).\n */\n reloadSkills?: true;\n /**\n * `hookSpecificOutput.permissionDecision` (PreModelSwitch).\n */\n permissionDecision?: 'allow' | 'deny' | 'ask';\n /**\n * `hookSpecificOutput.permissionDecisionReason` (PreModelSwitch).\n */\n permissionDecisionReason?: string;\n /**\n * `hookSpecificOutput.decision` (PermissionRequest).\n */\n decision?: PermissionRequestDecision;\n /**\n * `hookSpecificOutput.updatedToolOutput` (PostToolUse): replaces what the\n * model sees of the tool's result.\n */\n updatedToolOutput?: unknown;\n /**\n * `hookSpecificOutput.updatedMCPToolOutput` (PostToolUse, MCP tools only).\n */\n updatedMCPToolOutput?: unknown;\n /**\n * `hookSpecificOutput.retry` (PermissionDenied).\n */\n retry?: true;\n /**\n * `hookSpecificOutput.displayContent` (MessageDisplay).\n */\n displayContent?: string;\n /**\n * `hookSpecificOutput.worktreePath` (WorktreeCreate; a command hook prints\n * it): the worktree the hook created, absolute or relative to its cwd.\n *\n * Left unset, the session creates its git worktree as it would unhooked.\n */\n worktreePath?: string;\n };"},{"name":"ClassicResultFields","kind":"type","line":1395,"doc":{"desc":["The event-specific fields of ClassicResult each classic event reads (its","`hookSpecificOutput`), by event; an event absent here reads none of them.","","`block`, `preventContinuation` and `stopReason` are every event's."],"params":[],"example":[],"returns":[]},"text":" export type ClassicResultFields = {\n UserPromptSubmit: 'additionalContext' | 'sessionTitle' | 'suppressOriginalPrompt';\n UserPromptExpansion: 'additionalContext' | 'suppressOriginalPrompt';\n SessionStart: 'additionalContext' | 'initialUserMessage' | 'sessionTitle' | 'watchPaths' | 'reloadSkills';\n Setup: 'additionalContext';\n PreModelSwitch: 'permissionDecision' | 'permissionDecisionReason';\n PostModelSwitch: 'additionalContext';\n SubagentStart: 'additionalContext';\n PostToolUse: 'additionalContext' | 'updatedToolOutput' | 'updatedMCPToolOutput';\n PostToolUseFailure: 'additionalContext';\n PostToolBatch: 'additionalContext';\n Stop: 'additionalContext';\n SubagentStop: 'additionalContext';\n PermissionDenied: 'retry';\n PermissionRequest: 'decision';\n MessageDisplay: 'displayContent';\n WorktreeCreate: 'worktreePath';\n };"},{"name":"ClassicResultOf","kind":"type","line":1421,"doc":{"desc":["What each classic hook event's hook returns and its `next(e)` resolves to:","the event's own subset of ClassicResult.","","`classic.PreToolUse` keeps its `allow` / `ask` / `deny` result","(PreToolUseResult)."],"params":[],"example":[],"returns":[]},"text":" export type ClassicResultOf = {\n [E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? PreToolUseResult : Pick;\n };"},{"name":"ClassifyOptions","kind":"type","line":1428,"doc":{"desc":["Options of `$.model.classify`."],"params":[],"example":[],"returns":[]},"text":" export type ClassifyOptions = {\n /**\n * An alias (`haiku`) or a full model id; default the engine's small fast\n * model.\n */\n model?: string;\n };"},{"name":"ClientElements","kind":"type","line":1444,"doc":{"desc":["The element table a surface module draws with, `surface.elements`: the","terminal's (Elements) less `Client` (none nests), `Raster` and `Image`.","","What `$.ui.resolve(e)` is to a hooks module; a Button, Input or Select","keeps its handler here. A tree of them keeps every tree's bounds (20,000","nodes, 32 deep, 100,000 characters serialized) or the instance unmounts."],"params":[],"example":[],"returns":[]},"text":" export type ClientElements = Omit;"},{"name":"ClientKeyEvent","kind":"type","line":1450,"doc":{"desc":["One key the person pressed while a `Client` had the focus, as","`surface.onKey` hands it. Escape never arrives: it returns the focus."],"params":[],"example":[],"returns":[]},"text":" export type ClientKeyEvent = {\n /**\n * A special key's name (`up`, `down`, `left`, `right`, `return`, `tab`,\n * `backspace`, `delete`, `pageup`, `home`, ...) or the character typed.\n */\n key: string;\n /**\n * Modifier keys held with it, each present only when true.\n */\n ctrl?: true;\n shift?: true;\n meta?: true;\n };"},{"name":"ClientModule","kind":"type","line":1475,"doc":{"desc":["The component a surface module exports (default, or its one PascalCase","export): from props and surface to the tree drawn (no nested `Client`).","","Runs on the drawing thread, a second per call at most; `h` and `Fragment`","are the environment's, so nothing of the module's takes those names. A","throw, an overrun or a tree past the bounds (ClientElements) unmounts it."],"params":[],"example":["const Tag: ClientModule = (t, s) => s.elements.Text({ children: t })"],"returns":[]},"text":" export type ClientModule

= (props: P, surface: ClientSurface) => RenderElement;"},{"name":"ClientPointerEvent","kind":"type","line":1485,"doc":{"desc":["One pointer event over a `Client`'s region, as `surface.onPointer` hands","it: region-relative cells, and the sub-cell position where known.","","After a `down` in the region the instance holds the pointer until the","`up`: every `move` reaches it, past the edges too (negative, or beyond","`columns`/`rows`), and the transcript neither selects nor scrolls."],"params":[],"example":[],"returns":[]},"text":" export type ClientPointerEvent = {\n type: ClientPointerType;\n /**\n * The column under the pointer, 0 at the region's left edge; on `enter`\n * and `leave`, the last column a move reported.\n */\n x: number;\n /**\n * The row under the pointer, 0 at the region's top edge.\n */\n y: number;\n /**\n * The same position with the fraction of a cell kept (`x: 12`, `fine.x:\n * 12.375`), where the surface knows it: a terminal that reports pixels.\n *\n * kitty, Ghostty, iTerm2, WezTerm and foot do; tmux passes none through.\n * Absent elsewhere and on `enter`/`leave`; present, a `move` comes within\n * a cell too. What a module showing another program's pixels forwards.\n *\n * @example\n * surface.onPointer(e => click((e.fine?.x ?? e.x + 0.5) * pixelsPerCell))\n */\n fine?: {\n x: number;\n y: number;\n };\n /**\n * Which button is down (`down`, `move` while held) or came up (`up`);\n * absent on a hover `move`, `enter` and `leave`.\n */\n button?: 'left' | 'middle' | 'right';\n /**\n * Modifier keys the terminal reported held, each present only when true.\n */\n shift?: true;\n alt?: true;\n ctrl?: true;\n };"},{"name":"ClientPointerType","kind":"type","line":1528,"doc":{"desc":["What the pointer did over a `Client`'s region: a button went down, the","pointer moved, the button came up, or the pointer crossed the region's edge."],"params":[],"example":[],"returns":[]},"text":" export type ClientPointerType = 'down' | 'move' | 'up' | 'enter' | 'leave';"},{"name":"ClientProps","kind":"type","line":1534,"doc":{"desc":["The props of `Client`: which of the plugin's surface modules draws here,","under what key, with what data, in how much room."],"params":[],"example":[],"returns":[]},"text":" export type ClientProps = {\n /**\n * The instance's address within the drawing: two `Client`s of one plugin in\n * one tree take two keys. What `e.element` carries at `ui.message`.\n *\n * The engine keeps the instance (its local state, its timers) across the\n * plugin's redraws while a `Client` under this key stays in the tree.\n */\n key: string;\n /**\n * The surface module's path, a string literal relative to this file:\n * `module: \"./.tsx\"` (or `.jsx`, `.ts`, `.js`, `.mjs`).\n *\n * Read off the source: a variable there is refused at load, as is a path\n * outside the plugin or naming no file. Its default export draws, else\n * its one PascalCase export; loaded, the tree carries the plugin's path.\n */\n module: string;\n /**\n * Plain data (JsonValue) handed to the module function; a new value on a\n * redraw reaches the running instance, its state kept.\n *\n * At most 100000 characters serialized; not a channel for closures.\n * Typed `unknown` so a matcher over a tree stays shallow.\n */\n props?: unknown;\n /**\n * Columns the instance's region takes: a count, or a percentage of the\n * parent. Absent, the region is as wide as what the module draws.\n */\n width?: number | string;\n /**\n * Rows the instance's region takes: a count, or a percentage of the parent.\n * Absent, the region is as tall as what the module draws.\n */\n height?: number | string;\n /**\n * How the region grows into free room along the parent's direction, as a\n * Box's `flexGrow`.\n */\n flexGrow?: number;\n };"},{"name":"ClientSurface","kind":"type","line":1585,"doc":{"desc":["What a surface module's function receives as its second argument: its","elements, the instance's local state, its region, input, clock and port.","","Called again (same `surface`, same `state`) on new props, after","`setState`, and on a resize; what it returns is drawn in the region. No","`$` here: the hooks module has it, and `post` is the way to reach it."],"params":[],"example":[],"returns":[]},"text":" export type ClientSurface = {\n /**\n * The surface's element table (ClientElements), the tags the module draws\n * with: `const { Box, Text } = surface.elements`. No `Client` in it.\n */\n readonly elements: ClientElements;\n /**\n * The instance's local state: `undefined` until the first `setState`.\n * Kept across the plugin's redraws; dropped with the instance.\n */\n readonly state: S | undefined;\n /**\n * Replaces the local state and schedules one more call of the function on\n * the next frame; several calls before it coalesce into one redraw.\n *\n * A `setState` on each of three renders in a row with no key, pointer,\n * tick, press or props between is a render loop: the instance unmounts.\n */\n setState: (next: S) => void;\n /**\n * The region's width in cells, as last laid out (0 before the first\n * layout).\n */\n readonly columns: number;\n /**\n * The region's height in cells, as last laid out (0 before the first\n * layout).\n */\n readonly rows: number;\n /**\n * Calls `fn` every `ms` milliseconds on the surface's frame clock until\n * the returned function is called or the instance unmounts.\n *\n * Start it once (while `state` is still undefined), not on every call.\n */\n every: (ms: number, fn: () => void) => () => void;\n /**\n * Sets the instance's pointer listener (one; a later call replaces it)\n * and returns what clears it. See ClientPointerEvent for capture.\n */\n onPointer: (fn: (event: ClientPointerEvent) => void) => () => void;\n /**\n * Sets the instance's key listener (one; a later call replaces it),\n * reached while a click has given it the focus; Escape returns that.\n */\n onKey: (fn: (event: ClientKeyEvent) => void) => () => void;\n /**\n * Sends plain data to the plugin's hooks module: `e.data` of a\n * `ui.message` only that plugin's hooks see, one per frame at most.\n *\n * A later post in the same frame replaces an undelivered one; a hook\n * answering `{ props }` hands this instance its next props. At most\n * 20,000 values, 32 deep, 100,000 characters, or the post is not sent.\n */\n post: (data: JsonValue) => void;\n };"},{"name":"ClockWait","kind":"type","line":1646,"doc":{"desc":["The argument of the `$.clock` waits (`sleep`, `after`, `every`): how long,","in milliseconds, before the dispatch resolves."],"params":[],"example":[],"returns":[]},"text":" type ClockWait = {\n /**\n * The wait, a non-negative number of milliseconds.\n */\n ms: number;\n };"},{"name":"CodeProps","kind":"type","line":1661,"doc":{"desc":["The props of `Code`, source text every surface draws with the engine's own","highlighter: coloured tokens, a line gutter on request, or a unified diff.","","A leaf: no children. `source` is the element's data as a string is a","Text's, free of control characters the same way; the colour","on screen is the engine's, never the plugin's."],"params":[],"example":[],"returns":[]},"text":" export type CodeProps = {\n /**\n * The text drawn: source code, or under `format: 'diff'` one or more\n * unified-diff hunks.\n *\n * Of any length, one drawing drawing 100000 characters in all; tab and\n * newline its only control characters. A diff cut mid-hunk does not parse.\n */\n source: string;\n /**\n * A highlighter language id or alias (`typescript`, `ts`, `py`), a\n * plugin-contributed grammar's included.\n *\n * Absent, the language is inferred from `path`; when neither resolves,\n * the text is drawn plain.\n */\n language?: string;\n /**\n * A file path the language is inferred from when `language` is absent:\n * its extension or name, else a shebang on the first line.\n *\n * Drawn nowhere and never read: nothing touches the disk.\n */\n path?: string;\n /**\n * The 1-based number of the first line of `source`: present, a dim\n * right-aligned gutter numbers the lines from it; absent, no gutter.\n *\n * Ignored under `format: 'diff'`, whose hunks carry their own numbers.\n */\n startLine?: number;\n /**\n * `'source'` (the default) draws `source` as code; `'diff'` reads it as\n * unified-diff hunks and draws gutters, markers, add and remove colouring.\n *\n * A hunk is `@@ -a,b +c,d @@` then ` `, `+` or `-` lines; a `---`/`+++`\n * pair and `\\ No newline at end of file` are read past. A source that\n * parses as no hunks is drawn as plain code, unnumbered; the log says so.\n */\n format?: 'source' | 'diff';\n /**\n * What a line wider than the room does, in Text's `wrap` vocabulary:\n * `'wrap'` (the default) continues it on rows under the gutter.\n *\n * `'truncate-end'` cuts it at the edge with an ellipsis; Text's other\n * spellings are refused, since a gutter leaves them no sense here.\n */\n wrap?: 'wrap' | 'truncate-end';\n };"},{"name":"Color","kind":"type","line":1718,"doc":{"desc":["What a prop that paints may hold: a theme key, which follows the person's","theme, or any other string, a raw color (a name such as `\"red\"`, or hex).","","The keys are named so that an editor lists them; every string is","admitted. What a surface draws for one it does not know is its own."],"params":[],"example":[],"returns":[]},"text":" export type Color = ThemeKey | (string & {});"},{"name":"CommandDescribeInput","kind":"type","line":1724,"doc":{"desc":["The input of `command.describe`: how one slash command presents in the","typeahead and `/help`, at the moment the engine lists it."],"params":[],"example":[],"returns":[]},"text":" export type CommandDescribeInput = {\n /**\n * Names the command without its slash; the key a matcher narrows on. A\n * rewrite is refused.\n */\n command: string;\n /**\n * The one-line description the menu shows, as the command declares it.\n */\n description: string;\n /**\n * The hint drawn dim after the name (`[name]`), when the command has one.\n */\n argumentHint?: string;\n /**\n * Whether the typeahead and `/help` leave the command out; a hidden\n * command still runs when typed in full.\n */\n isHidden: boolean;\n /**\n * Whether the command declares it runs at once when typed mid-turn,\n * instead of waiting for the turn to end.\n *\n * One that decides per invocation reads false. Read only: not part of\n * what a hook answers, and a rewrite is refused.\n */\n immediate: boolean;\n /**\n * Who provides this command: the plugin and its tier; `{ plugin: \"engine\",\n * tier: \"core\" }` for a built-in. Pinned: a rewrite is refused.\n */\n provider: Origin;\n };"},{"name":"CommandDescribeResult","kind":"type","line":1762,"doc":{"desc":["What a `command.describe` hook returns: the description, hint and hidden","flag the menu uses; the name, `immediate` and `provider` stay as they were."],"params":[],"example":[],"returns":[]},"text":" export type CommandDescribeResult = Omit;"},{"name":"CommandInfo","kind":"type","line":1767,"doc":{"desc":["One slash command as `$.command.list()` returns it."],"params":[],"example":[],"returns":[]},"text":" export type CommandInfo = {\n /**\n * What the person runs it by, without the slash.\n */\n name: string;\n /**\n * The one line the typeahead shows for it.\n */\n description: string;\n /**\n * Where it comes from (CommandSource).\n */\n source: CommandSource;\n /**\n * Which plugin added it, when `source` is `plugin` and the engine knows:\n * the one that registered it, or whose manifest carries it.\n */\n plugin?: string;\n };"},{"name":"CommandPresentation","kind":"type","line":1796,"doc":{"desc":["Where a command's answer will show: which of the terminal's two layouts","the surface renders, and how wide it is when the command runs.","","A fact the engine stamps on `command.run`, so a command that draws (opens","a pane, prints a wide table) can suit the room it has: the fullscreen","layout docks a pane beside the transcript from 110 columns, the main","screen places it inline above the prompt at any width."],"params":[],"example":[],"returns":[]},"text":" export type CommandPresentation = {\n /**\n * True under the fullscreen (alternate-screen) layout; false on the main\n * screen (`CLAUDE_CODE_NO_FLICKER=0`, tmux by default) and headless.\n *\n * The fact `RenderViewport`'s `isFullscreen` carries on every terminal\n * drawing, from the same source: the two agree.\n */\n isFullscreen: boolean;\n /**\n * The terminal's width in cells as the command runs; 80 where no terminal\n * has measured (headless with no tty).\n */\n columns: number;\n };"},{"name":"CommandRunArgs","kind":"type","line":1816,"doc":{"desc":["`command.run`'s input as a plugin's `$.command.run` takes it: `args` may","be left out (`/command`, bare); `origin` and `presentation` the engine sets."],"params":[],"example":[],"returns":[]},"text":" export type CommandRunArgs = Omit & {\n /**\n * Everything after the name, as the person would type it; left out, `\"\"`.\n */\n args?: string;\n };"},{"name":"CommandRunInput","kind":"type","line":1827,"doc":{"desc":["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."],"params":[],"example":[],"returns":[]},"text":" export type CommandRunInput = {\n /**\n * Names the command without its slash (`compact`, `hello`), aliases and\n * folds resolved; the key a matcher narrows on. A rewrite is refused.\n */\n command: string;\n /**\n * Everything after the name, as typed (`\"\"` when nothing was); a hook\n * rewrites it with `next({ ...e, args })`.\n */\n args: string;\n /**\n * Where the run came from, in `prompt.submit`'s words (PromptOrigin):\n * the person's Enter (`composer`), the bridge, the SDK, or a plugin.\n *\n * A plugin's `$.command.run` reads `{ kind: 'plugin', name }`. `next(e)`\n * passes it on as received.\n */\n origin: PromptOrigin;\n /**\n * Where the command's answer will show (CommandPresentation): the\n * fullscreen layout or the main screen, and the terminal's width.\n *\n * Pinned: the engine stamps it, `next(e)` passes it on, a rewrite that\n * leaves it out keeps it and one that changes it is refused.\n */\n presentation: CommandPresentation;\n };"},{"name":"CommandRunResult","kind":"type","line":1872,"doc":{"desc":["What a `command.run` hook returns and what `next(e)` and `$.command.run`","resolve to: the command's output text and the notes it leaves the model.","","From core, `text` is what the command printed (a `local` command's","returned text; a panel command may print nothing), `context` what it","recorded for the model beside that, and `ref` names the run.","","A hook's own answer without `next` runs no command: its `text` is shown","as the command's output, under the names of the plugins hooking the","command unless each is bundled with Claude Code, whose answer reads as","the built-in command's own, and its `context` is recorded after it.","","Both are the plugin's to size, as a core command's output is; what bounds","them is what bounds any transcript row where a surface draws it."],"params":[],"example":[],"returns":[]},"text":" export type CommandRunResult = {\n /**\n * The command's output as a transcript line, or undefined when the\n * command showed nothing as text (a panel, a prompt for the model).\n */\n text?: string;\n /**\n * What the model reads after the command's output and the person never\n * sees, each entry one hidden user message recorded after the output row.\n *\n * From core, the notes the command left the model, absent when none. Kept\n * whole from `next`: left out after `next`, the last answer's notes ride\n * along; written, it keeps every entry that answer had (none empty).\n */\n context?: readonly string[];\n /**\n * Whether `text` is for the person alone and `context` is all the model\n * reads: the output row is drawn and kept, and goes in no request.\n *\n * Read on a hook's own answer without `next`, when every plugin hooking the\n * command is bundled with Claude Code, whose answer reads as the built-in\n * command's own, on the queued lanes: a panel answered mid-turn keeps its\n * text in requests. Any other plugin's text stays in requests.\n */\n isTextDisplayOnly?: true;\n /**\n * What the process exits with when this command was the whole prompt of a\n * headless run (`claude -p \"/lint\"`): a whole number from 0 to 255.\n *\n * Left out, the run exits as it would have; any other value fails the\n * hook. An interactive session ignores it, and core never sets it. The\n * answer the chain ends on decides: a hook above answering its own drops it.\n *\n * @example\n * on(\"command.run\", { command: \"lint\" }, () => ({ text, exitCode: 3 }))\n */\n exitCode?: number;\n /**\n * Set by core on what `next(e)` resolves to: names the engine's run of\n * the command (its result stays on the host side).\n *\n * A hook that returns the object it got makes the engine use that run\n * verbatim. Absent on a hook's own `{ text }` and on `$.command.run`'s.\n */\n ref?: number;\n };"},{"name":"CommandSource","kind":"type","line":1926,"doc":{"desc":["Where a slash command comes from, as `$.command.list()` tells them apart.","","`builtin` ships with Claude Code; `plugin` is a plugin's markdown command,","skill or `$.command.register`; `user` is the user's or project's own","file; `mcp` an MCP server's prompt."],"params":[],"example":[],"returns":[]},"text":" export type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';"},{"name":"CommandSpec","kind":"type","line":1931,"doc":{"desc":["What `$.command.register` takes: the slash command this plugin serves."],"params":[],"example":[],"returns":[]},"text":" export type CommandSpec = {\n /**\n * The command's name without the slash (letters, digits, `_`, `-`; up to\n * 64); the person runs it as `/`.\n */\n name: string;\n /**\n * The one line the typeahead and `/help` show for it.\n */\n description: string;\n /**\n * The hint drawn dim after the name (`[name]`), when it takes arguments.\n */\n argumentHint?: string;\n /**\n * Set so that `/` typed while a turn is in flight runs at once\n * instead of waiting for the turn to end, as it does when left out.\n *\n * Its `command.run` hook then runs while a turn may still be streaming and\n * must not assume the turn's state (what the transcript holds, whether a\n * tool is mid-call); its `{ text }` prints as an idle run's does.\n */\n immediate?: true;\n };"},{"name":"ConfigChangeHookInput","kind":"type","line":1956,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type ConfigChangeHookInput = BaseHookInput & {\n hook_event_name: 'ConfigChange';\n source: 'user_settings' | 'project_settings' | 'local_settings' | 'policy_settings' | 'skills';\n file_path?: string;\n };"},{"name":"ConfigDescribeInput","kind":"type","line":1966,"doc":{"desc":["The input of `config.describe`: how one `/config` row presents, at the","moment the menu lists it (and for `$.config.list`)."],"params":[],"example":[],"returns":[]},"text":" export type ConfigDescribeInput = {\n /**\n * Names the row, as `config.set`'s `key` does; the key a matcher narrows\n * on. Pinned: a rewrite is refused.\n */\n key: string;\n /**\n * What the menu draws for the row, before its value.\n */\n label: string;\n /**\n * The help text beneath the label, when the row has one (a plugin\n * field's `description`); absent for the panel's own rows.\n */\n description?: string;\n /**\n * Whether the menu leaves the row out; a hidden row still answers\n * `$.config.set` and `/config key=value`.\n */\n isHidden: boolean;\n /**\n * Who owns the row, as `config.set`'s `provider`. Pinned.\n */\n provider: Origin;\n };"},{"name":"ConfigDescribeResult","kind":"type","line":1996,"doc":{"desc":["What a `config.describe` hook returns: the label, help text and hidden","flag the menu uses; the key and provider stay as they were."],"params":[],"example":[],"returns":[]},"text":" export type ConfigDescribeResult = Omit;"},{"name":"ConfigKind","kind":"type","line":2002,"doc":{"desc":["How a `/config` row takes its value: `boolean` toggles, `choice` picks one","of its `options`, `text` takes a string, `number` a number."],"params":[],"example":[],"returns":[]},"text":" export type ConfigKind = 'boolean' | 'choice' | 'text' | 'number';"},{"name":"ConfigOrigin","kind":"type","line":2010,"doc":{"desc":["Where a `config.set` came from, in `prompt.submit`'s words: the person","in the `/config` menu (`composer`), the bridge, or a plugin, named.","","Set by the engine; `next(e)` passes it on as received and none sets it."],"params":[],"example":[],"returns":[]},"text":" export type ConfigOrigin = {\n /**\n * The person's own change in the `/config` menu (a toggle, a pick, a\n * typed value), or their `/config key=value`.\n */\n kind: 'composer';\n } | {\n /**\n * A `/config key=value` that arrived over the Remote Control bridge (a\n * phone or web client, or a relay): not attestably the owner's hand.\n */\n kind: 'bridge';\n } | {\n /**\n * A plugin's `$.config.set`; that plugin's own hooks do not see it.\n */\n kind: 'plugin';\n /**\n * The calling plugin's name.\n */\n name: string;\n };"},{"name":"ConfigRow","kind":"type","line":2037,"doc":{"desc":["One `/config` row as `$.config.list()` returns it: what the menu would","draw now, after every `config.describe` hook, a hidden row left out."],"params":[],"example":[],"returns":[]},"text":" export type ConfigRow = {\n /**\n * Names the row: the panel's id for a built-in, `.` for a\n * plugin's `userConfig` field; what `$.config.set` takes.\n */\n key: string;\n /**\n * What the menu draws for the row, before its value.\n */\n label: string;\n /**\n * The help text under the label, when the row has one.\n */\n description?: string;\n /**\n * How the row takes its value (ConfigKind).\n */\n kind: ConfigKind;\n /**\n * What the row holds now.\n */\n value: ConfigValue;\n /**\n * The values a `choice` row takes, in order (a plugin string field's\n * declared `options` for its row); absent otherwise.\n */\n options?: readonly string[];\n /**\n * Who owns the row: the engine for the panel's own, else the plugin.\n */\n provider: Origin;\n /**\n * Whether a trusted source (managed settings, the organization's policy)\n * owns the value, so the menu shows it and refuses a change.\n */\n isLocked: boolean;\n };"},{"name":"ConfigSetArgs","kind":"type","line":2079,"doc":{"desc":["`config.set`'s input as a plugin's `$.config.set(args)` takes it: the","row's key and the value; the engine fills the rest."],"params":[],"example":[],"returns":[]},"text":" export type ConfigSetArgs = Pick;"},{"name":"ConfigSetInput","kind":"type","line":2085,"doc":{"desc":["The input of `config.set`: one `/config` row about to change, from the","menu or a plugin's `$.config.set`, with what it holds now and who owns it."],"params":[],"example":[],"returns":[]},"text":" export type ConfigSetInput = {\n /**\n * Names the row: the panel's own id for a built-in (`theme`, `verbose`,\n * `autoCompact`), `.` for a plugin's `userConfig` field.\n *\n * The key a matcher narrows on; pinned: a rewrite is refused.\n */\n key: string;\n /**\n * What the row is being set to; `next({ ...e, value })` clamps or\n * replaces it, held to the row's kind (a toggle takes a boolean).\n */\n value: ConfigValue;\n /**\n * What the row holds before the change, as the menu shows it. Pinned.\n */\n previous: ConfigValue;\n /**\n * Who owns the row: `{ plugin: \"engine\", tier: \"core\" }` for the panel's\n * own, the plugin and its tier for a `userConfig` field. Pinned.\n */\n provider: Origin;\n /**\n * Where the change came from (ConfigOrigin): the person in the menu\n * (`composer`) or a plugin's `$.config.set`. Pinned.\n */\n origin: ConfigOrigin;\n };"},{"name":"ConfigSetResult","kind":"type","line":2122,"doc":{"desc":["What a `config.set` hook returns and what `next(e)` resolves to:","`{ value }` once written, or `{ deny: reason }`, the row left as it was.","","The menu shows a deny's reason; `$.config.set` resolves with it. A deny","after a `next(e)` was answered fails the hook: its `.catch` is asked (a","deny from it fails too), or it is skipped by name and its last `next` stands."],"params":[],"example":[],"returns":[]},"text":" export type ConfigSetResult = {\n value: ConfigValue;\n deny?: undefined;\n } | {\n deny: string;\n value?: undefined;\n };"},{"name":"ConfigValue","kind":"type","line":2134,"doc":{"desc":["A `/config` row's value as a hook and `$.config` see it: a toggle's","boolean, a choice's or a text's string, a number, or a list of strings."],"params":[],"example":[],"returns":[]},"text":" export type ConfigValue = boolean | string | number | readonly string[];"},{"name":"ContextAgent","kind":"type","line":2140,"doc":{"desc":["One custom agent whose description the Agent tool's prompt carries;","built-in agents are left out."],"params":[],"example":[],"returns":[]},"text":" export type ContextAgent = {\n /**\n * The agent's type, as the Agent tool names it.\n */\n agentType: string;\n /**\n * Where it was defined, by the engine's word (`projectSettings`,\n * `userSettings`, `plugin`); the display label is the renderer's.\n */\n source: string;\n /**\n * The description's estimated tokens.\n */\n tokens: number;\n };"},{"name":"ContextBreakdownDetail","kind":"type","line":2162,"doc":{"desc":["How a context breakdown is counted: `full` with the token-count API per","category, `summary` from the last response's usage and local estimates.","","The SDK's `get_context_usage` takes the same two words as its `detail`."],"params":[],"example":[],"returns":[]},"text":" export type ContextBreakdownDetail = 'summary' | 'full';"},{"name":"ContextCategory","kind":"type","line":2168,"doc":{"desc":["One row of the breakdown, as /context lists it beside the grid (`System","prompt`, `Messages`, `Free space`, `Autocompact buffer`)."],"params":[],"example":[],"returns":[]},"text":" export type ContextCategory = {\n /**\n * The row's label as /context prints it.\n */\n name: string;\n /**\n * The row's estimated tokens; a `deferred` row's do not count toward the\n * total.\n */\n tokens: number;\n /**\n * The theme colour /context draws the row and its squares in, by its key\n * in the theme (`promptBorder`, `inactive`, `permission`).\n */\n color: string;\n /**\n * Whether the row is tool schemas loaded on demand, which the grid leaves\n * out; the same fact as `kind` `deferred`.\n */\n isDeferred: boolean;\n /**\n * What the row is (ContextCategoryKind), stamped by the engine.\n */\n kind: ContextCategoryKind;\n };"},{"name":"ContextCategoryKind","kind":"type","line":2201,"doc":{"desc":["What a breakdown row is; branch on this, never on the row's `name`.","","`used` content occupies the window, `free` is the window left, `buffer`","the compaction reserve, `deferred` tool schemas loaded on demand and","outside the window."],"params":[],"example":[],"returns":[]},"text":" export type ContextCategoryKind = 'used' | 'free' | 'buffer' | 'deferred';"},{"name":"ContextGridSquare","kind":"type","line":2207,"doc":{"desc":["One square of the grid /context draws: which row it belongs to and how","full it is."],"params":[],"example":[],"returns":[]},"text":" export type ContextGridSquare = {\n /**\n * The theme colour of the square's row, by its key in the theme.\n */\n color: string;\n /**\n * Whether the square holds any of its row's tokens.\n */\n isFilled: boolean;\n /**\n * The `name` of the row the square belongs to (`Free space` for the\n * window left).\n */\n categoryName: string;\n /**\n * The row's tokens, repeated on each of its squares.\n */\n tokens: number;\n /**\n * The row's share of the window as a whole percentage, repeated likewise.\n */\n percentage: number;\n /**\n * How full this one square is, 0 to 1: a row's last square is the partial\n * one (/context draws it hollow under 0.7).\n */\n squareFullness: number;\n };"},{"name":"ContextMcpTool","kind":"type","line":2239,"doc":{"desc":["One MCP tool's schema as the context carries it."],"params":[],"example":[],"returns":[]},"text":" export type ContextMcpTool = {\n /**\n * The tool's wire name (`mcp__linear__create_issue`).\n */\n name: string;\n /**\n * The server it belongs to, as /mcp lists it.\n */\n serverName: string;\n /**\n * The schema's estimated tokens.\n */\n tokens: number;\n /**\n * Whether the schema is inside the window now: always, unless tool\n * schemas load on demand and this one has not been searched for yet.\n */\n isLoaded: boolean;\n };"},{"name":"ContextMemoryFile","kind":"type","line":2263,"doc":{"desc":["One memory file the context carries (a CLAUDE.md, a rules file, an","auto-memory entry)."],"params":[],"example":[],"returns":[]},"text":" export type ContextMemoryFile = {\n /**\n * The file's path, absolute.\n */\n path: string;\n /**\n * The display label of where it was loaded from (`Project`, `User`,\n * `Local`, `Managed`, `AutoMem`).\n */\n type: string;\n /**\n * The file's estimated tokens.\n */\n tokens: number;\n };"},{"name":"ContextSkill","kind":"type","line":2282,"doc":{"desc":["One skill whose listing the context carries."],"params":[],"example":[],"returns":[]},"text":" export type ContextSkill = {\n /**\n * The skill's name as `/skills` lists it.\n */\n name: string;\n /**\n * Where it came from, by the engine's word (`userSettings`, `plugin`,\n * `built-in`, `mcp`, `syncedSkills`); the display label is the renderer's.\n */\n source: SkillSource;\n /**\n * The providing plugin's name, when the skill comes from one.\n */\n pluginName?: string;\n /**\n * The listing's estimated tokens.\n */\n tokens: number;\n };"},{"name":"ContextSkills","kind":"type","line":2306,"doc":{"desc":["The skills the context lists for the model: how many there are, how many","fit the listing's budget, and each one's share."],"params":[],"example":[],"returns":[]},"text":" export type ContextSkills = {\n /**\n * How many skills the session has.\n */\n totalSkills: number;\n /**\n * How many the listing included within its token budget.\n */\n includedSkills: number;\n /**\n * The listing's tokens in all.\n */\n tokens: number;\n /**\n * One entry per listed skill.\n */\n skillFrontmatter: ContextSkill[];\n };"},{"name":"ContextSlashCommands","kind":"type","line":2328,"doc":{"desc":["The slash commands the Skill tool's prompt lists, counted."],"params":[],"example":[],"returns":[]},"text":" export type ContextSlashCommands = {\n /**\n * How many commands the session has.\n */\n totalCommands: number;\n /**\n * How many the listing included.\n */\n includedCommands: number;\n /**\n * The listing's tokens in all.\n */\n tokens: number;\n };"},{"name":"ContextWindowSource","kind":"type","line":2351,"doc":{"desc":["How the window the breakdown measures against was settled; /context","prints its `Auto-compact window` line off this.","","`auto` is the model's own limit; the rest name a compaction window by who","set it: the `CLAUDE_CODE_AUTO_COMPACT_WINDOW` variable, the settings, the","account, an experiment, the model's default, or an unrecognised model's."],"params":[],"example":[],"returns":[]},"text":" export type ContextWindowSource = 'env' | 'settings' | 'clientdata' | 'experiment' | 'model-default' | 'unknown-model' | 'auto';"},{"name":"CoreEngineInterface","kind":"interface","line":2360,"doc":{"desc":["The plugin's identity (`plugin`) and the nouns core contributes to `$` as","the innermost step of the `engine.create` fold.","","A plugin's finished `$` (EngineInterface) has every core noun an outer","step did not withhold, and every noun the plugins' steps added."],"params":[],"example":[],"returns":[]},"text":" export interface CoreEngineInterface {\n /**\n * This plugin, as loaded: its manifest name and its directory.\n */\n plugin: {\n /**\n * From plugin.json; debug-log and `$.ui.log` lines carry it.\n */\n name: string;\n /**\n * The plugin's directory (the one holding plugin.json), absolute.\n */\n root: string;\n };\n /**\n * Display: a line under an open dialog, a redraw or a repaint, a log line,\n * panes the surface places, a window or ring, a surface's clipboard.\n */\n ui: {\n /**\n * Shows `text` as one line under the dialog open for `tool_use_id`, or\n * removes the line when `text` is undefined.\n *\n * Core removes the line when the call resolves. A call that is not open\n * is refused, as is another plugin's `$.tool.call` run.\n *\n * @param tool_use_id the call whose open dialog gets the line\n * @param text the line to show; undefined removes it\n * @example\n * $.ui.notice(e.tool_use_id, \"checked by my-plugin\"); return next(e)\n */\n notice: (tool_use_id: string, text: string | undefined) => void;\n /**\n * Re-runs an event whose results the engine caches: `ui.render` draws the\n * instances this plugin may draw again; the others drop the cached answers.\n *\n * A redraw: ten a second at most, thirty in the terminal for a shown pane,\n * expanded band and prompt hint (sooner calls fold). A cached answer drops\n * next turn; a changed tool or section text rewrites what a thread sent,\n * which loses its thinking and the prompt cache, so do not call it for\n * these once a thread has sent.\n *\n * @remarks An ask ends with the process: a resumed thread sends what it\n * recorded; asked again, a `tool.describe` hook's answer goes over the\n * recorded description where it differs.\n * @param event `ui.render`, or a cached-answer event: `prompt.section`,\n * `prompt.context`, `prompt.attachment`, `tool/command/config.describe`\n */\n invalidate: (event: InvalidatableEventName) => void;\n /**\n * Repaints a mounted `Raster` this plugin's own render hook drew with new\n * cells, or swaps a keyed `Image` it drew to a new source; no redraw.\n *\n * The surface paints the cells or source at its next frame, so blits\n * between frames fold into one: up to 120 a second taken, some sixty\n * shown. An Image swap sends one small command; a resize is a redraw.\n *\n * @param args `requestId` (the site), `key`, and `cells` (RasterProps) or\n * `source` (ImageSource); `columns`, `rows` (the mounted size)\n * @returns `{}` once the cells or source are its next frame, or `{ deny }`\n * (not mounted, not this plugin's, another size, cells that do\n * not decode, a bad source, or an Image drawing its alt there:\n * no placeholder images, or a file this terminal cannot read)\n * @example\n * $.clock.every(33, () => $.ui.blit({ requestId, key, cells: frame() }))\n * @example\n * await $.ui.blit({ requestId: 'browser', key: 'view',\n * source: { shm: name, format: 'rgb', width, height } })\n */\n blit: (args: UiBlitArgs) => Promise;\n /**\n * The elements of the surface `e` is drawn on (Elements[e.surface]): a\n * frozen table of constructors, the JSX tags a render hook draws with.\n *\n * A read, not a dispatch: the engine ran `ui.resolve` (the other hooks,\n * then core) at load, per surface and component. Narrowed `e.surface`:\n * that table exactly; unnarrowed: the union, so shared names type-check.\n *\n * @param e this hook's own `ui.render` argument (its surface and\n * component pick the table)\n * @returns the surface's frozen element table (`Elements[e.surface]`)\n * @example\n * const { Box, Text } = $.ui.resolve(e)\n * return {await next(e)}done\n */\n resolve: (e: E) => Elements[E['surface']];\n /**\n * Appends one line to the transcript, drawn like a system notice (dim;\n * not sent to the model), or with `{ to: \"debug\" }` to the debug log alone.\n *\n * A row of its own at the next frame, in logging order; a `-p` or SDK\n * host receives it as `ui_log`; the debug log has it either way, to 10000\n * characters. Raised as `ui.log`: a hook above may rewrite `e.to`.\n *\n * @param text the line's text, of any length: the terminal draws its\n * first 2000 characters, a remote surface 10000\n * @param options `to`: `transcript` (the default) or `debug`\n * @example\n * $.ui.log(`prompt from ${e.origin.kind}: ${e.text.length} chars`)\n * @example\n * $.ui.log(`cache miss for ${e.tool_use_id}`, { to: \"debug\" })\n */\n log: (text: string, options?: UiLogOptions) => void;\n /**\n * Asks the user `question` in the engine's own AskUserQuestion dialog and\n * resolves to the label they chose, or the text typed under \"Other\".\n *\n * A `tool.call` of `AskUserQuestion` through every hook but the calling\n * one, drawn by `ui.render` on `AskUserQuestion`; a multi-select answer is\n * comma-joined. Rejects when dismissed, and in a `-p` run (no one to ask).\n *\n * @param question the question, ending in a question mark\n * @param options 2-4 option labels, or `{ options, header, multiSelect }`\n * @returns the label chosen, the chosen labels comma-joined, or free text\n * typed under \"Other\" (so compare it with the labels exactly)\n * @example\n * const mood = await $.ui.ask(\"How careful?\", [\"Bold\", \"Careful\"])\n */\n ask: (question: string, options?: readonly string[] | AskOptions) => Promise;\n /**\n * Shows `text` for a few seconds under the plugin's name: a small box on\n * the stack of plugin toasts over the transcript's top right corner.\n *\n * A click takes it off, the pointer over it holds it. Where the transcript\n * is printed into scrollback (nothing to float over) it is one line on the\n * notification bar. It leaves the transcript and the model untouched.\n *\n * @remarks While the pane shown was opened `holdToasts`, by any plugin, it\n * waits undrawn, its timer not started; past 50 waiting, an older leaves.\n * @param text the line to show, its first 2000 characters drawn (10000\n * remotely); an unpaired surrogate half in it is drawn as U+FFFD\n * @param options `timeoutMs`: how long it stays (default 4000)\n * @example\n * $.ui.toast(`turn took ${Math.round(e.durationMs / 1000)} s`)\n */\n toast: (text: string, options?: ToastOptions) => void;\n /**\n * Raises a native notification of `text` through the person's own\n * notification channel, the one their `preferredNotifChannel` names.\n *\n * Their `Notification` hooks run first, reading `plugin_notification`,\n * then the channel writes. Raised as `ui.notify`; nothing limits how\n * often. With no terminal the hooks alone run; unbound or exiting, none.\n *\n * @remarks A hook that notifies is left out of the hooks its own call\n * runs. Rejects on a hook's `{ deny }`, and on a failed write.\n * @param text the notification's body, sent as given, of any length\n * @param options `title`: what heads it (default: the plugin's name)\n * @returns `{ isSent: true, channel }`, or `{ isSent: false, reason }`:\n * turned off (`disabled`), `no-channel`, `no-surface`, `refused`\n * @example\n * const sent = await $.ui.notify(\"tests passed\", { title: \"CI\" })\n */\n notify: (text: string, options?: NotifyOptions) => Promise;\n /**\n * Pins `text` as this plugin's status line under the prompt, beside the\n * engine's own pinned notices, until the next call replaces it.\n *\n * One per plugin; `undefined` removes it.\n *\n * @param text the line to keep on screen, its first 2000 characters drawn\n * (10000 remotely); undefined clears it\n * @example\n * $.ui.status(\"thinking...\"); return next(e)\n */\n status: (text: string | undefined) => void;\n /**\n * Opens a pane, a framed region the surface places and this plugin draws\n * by hooking `ui.render` for `{ component: \"Pane\" }`; says if it is drawn.\n *\n * One per id (an open id retitles; a `ui.open` hook may refuse). Asked,\n * the person's command, prompt or press behind it (not `focus`), it is\n * placed at any width; unasked, from 144 columns, 110 for one once asked.\n *\n * @remarks Below that it waits undrawn (`$.ui.panes()`: `isPlaced` false)\n * for their open or a wider terminal; with no surface attached, for one.\n * @param pane `id` (1-64 of letters, digits, `_`, `-`), `title`, `focus`,\n * `closeOnEscape` and `holdToasts` (a dialog), `backgroundColor` (what\n * is painted under its body), `rows` / `columns` wanted\n * @returns `{ isPlaced: true }` once drawn (or retitled), else `{ isPlaced:\n * false, reason }` (UiOpenResult); `dock` or `inline` is on `Pane` props\n * @example\n * await $.ui.open({ id: \"clock\", title: \"Clock\" })\n * @example\n * await $.ui.open({ id: \"ask\", focus: true, closeOnEscape: true, rows: 9 })\n * @example\n * const opened = await $.ui.open({ id: \"clock\" })\n * if (!opened.isPlaced) $.ui.log(\"clock: \" + opened.reason)\n */\n open: (pane: PaneOpenArgs) => Promise;\n /**\n * Closes one of the open panes; an id that is not open is left alone.\n *\n * Every close raises `ui.close`, `e.origin` naming whose it is: this call\n * (`plugin`), the person's mark or key (`person`), an unload (`unload`).\n * A hook answering without `next` keeps the pane open, save on an unload.\n *\n * @param pane `id`: the id the pane was opened under\n * @returns settles once the pane is gone or a hook answered for it;\n * rejects on a hook's `{ deny }`\n * @example\n * onPress: () => $.ui.close({ id: \"clock\" })\n */\n close: (pane: PaneCloseArgs) => Promise;\n /**\n * Lists this plugin's own open panes (UiPane): each one's id and title,\n * and whether it is shown, holds the keyboard, and is placed.\n *\n * The engine's record, not the module's: a module reloaded while its\n * pane stayed up finds it here. Another plugin's panes are not listed.\n *\n * @returns the panes in open order, placed ones first; empty with none\n * @example\n * const isUp = (await $.ui.panes()).some(pane => pane.id === \"clock\")\n * if (!isUp) await $.ui.open({ id: \"clock\", title: \"Clock\" })\n */\n panes: () => Promise;\n /**\n * Places one row at the transcript's end, which scrolls with the\n * conversation and draws what `ui.render` answers for `Placed`.\n *\n * A hook reads `e.props.id` and `e.props.plugin`. Display only: the model\n * and the transcript file never read it, and `--resume` brings none back. A\n * hook that passes draws nothing; the same id answers the row that stands.\n *\n * @example\n * await $.ui.place({ id: \"build\" })\n */\n place: (args: UiPlaceArgs) => Promise;\n /**\n * Scrolls something into view as the DOM's `scrollIntoView` would: a\n * render instance by `requestId`, an element by `key`, a site's edge.\n *\n * A site of this plugin's (its pane, the band it draws into) moves under\n * the event `ui.scroll`, origin `plugin`. A transcript row moves only\n * while this call answers the person's own input, where one scrolls.\n *\n * @param args `to` (what), `in` (which site, required for `start` and\n * `end`), `block` (where it lands; `nearest` by default)\n * @returns `{}` once it moved, or `{ deny }` saying why not\n * @example\n * onPress: () => $.ui.scroll({ in: \"log\", to: \"end\" })\n */\n scroll: (args: UiScrollArgs) => Promise;\n /**\n * Moves the focus ring of one of this plugin's sites onto an element it\n * drew there, as the DOM's `element.focus()`, while it holds the keys.\n *\n * Raised as `ui.focus`, origin `plugin`; the engine's inverse marks it.\n * A site not holding the keys, or holding them on another's element, is\n * `{ deny }`; an element not yet drawn is awaited, bounded: no retrying.\n *\n * @param args `requestId` (which site: a pane's id, the band's) and `key`\n * (the element's, as drawn)\n * @returns `{}` once it moved, or `{ deny }` saying why not\n * @example\n * await $.ui.open({ id: \"files\", focus: true })\n * await $.ui.focus({ requestId: \"files\", key: \"row:0\" })\n */\n focus: (args: UiFocusArgs) => Promise;\n /**\n * Puts `text` on the clipboard of a surface the session draws on, as the\n * DOM's `navigator.clipboard.writeText`, and says whether it took.\n *\n * `surface` names which (a press hook passes `e.surface`); left out, the\n * session's first. Raised as `ui.copy` with that target on `e`. The\n * terminal writes as `/copy` does; a remote surface has no path yet.\n *\n * @param args `text`, what the person pastes; `surface`, where\n * @returns `{ isCopied: true }`, or `{ isCopied: false, reason }`\n * @example\n * onPress: press => $.ui.copy({ text: url, surface: press.surface })\n */\n copy: (args: UiCopyArgs) => Promise;\n /**\n * Returns what the person last selected with the mouse: the text as a\n * copy would take it, and the transcript row it lies in.\n *\n * A key or a click takes the highlight down before a command or a press\n * runs, so the answer stays what the person last selected, until they\n * select again, dismiss it, or their next prompt or command has run.\n *\n * @returns the selection; `undefined` with nothing selected, and where\n * none is seen: fullscreen off, -p, a surface that answers none\n * @example\n * const selected = await $.ui.selection()\n */\n selection: () => Promise;\n /**\n * Puts an agent's transcript in the main view, as the person's own\n * switch from the tasks list does; `{}` goes back to the main one.\n *\n * Only while the call answers the person's own input (a press, a pick,\n * their prompt or command): the viewed agent takes the prompt's next\n * Enter. A site reads the view in force as `e.props.view`.\n *\n * @param view `agentId`: the agent's `id` in `$.agent.list()`; absent for\n * the main conversation\n * @returns `{}` once the view shows it, or `{ deny }` saying why not\n * @example\n * onPress: () => $.ui.view({ agentId: agent.id })\n * @example\n * onPress: () => $.ui.view({})\n */\n view: (view: SiteView) => Promise;\n };\n /**\n * The session's one theme: how the app looks behind and around the\n * conversation. One theme stands at a time, the latest set, whichever plugin\n * set it; there is no stack.\n */\n theme: {\n /**\n * Sets the session's theme from one object of named top-level attributes.\n * `backdrop` is drawn behind the conversation by what `ui.render` answers\n * for `Backdrop`: full window on desktop under its frosted panels, full\n * screen on mobile under one veil (`tint` and `opacity`, not yet `blur`).\n * Display only: `--resume` brings none back and a plugin that unloads\n * takes its own with it, so set it at `session.start`.\n *\n * @param attributes `backdrop`: `id`, `glass` (`blur`, `tint`, `opacity`) or\n * `false`, and `colorScheme` (`light` or `dark`)\n * @returns `{ isDrawn: true, requestId }`, or `isDrawn: false` and why\n * @example\n * await $.theme.set({ backdrop: { id: \"lagoon\", glass: { blur: 14, opacity: 0.55 } } })\n */\n set: (attributes: ThemeSetArgs) => Promise;\n /**\n * Clears the session's theme, back to the app's own look.\n *\n * IT CLEARS WHATEVER THEME STANDS, WHICHEVER PLUGIN SET IT: there is one\n * theme, so a clear is the session's and not the caller's own. Clear on a\n * person's ask (a command, a button), never at `session.start` or on a\n * reload: a plugin that clears there wipes another plugin's theme each time.\n *\n * @returns `isDrawn: false` and why\n * @example\n * await $.theme.clear() // a preview ends with no theme to go back to\n */\n clear: () => Promise;\n };\n /**\n * Completions through the session's own client and credentials.\n */\n model: {\n /**\n * Runs one text completion through the session's own API client and\n * resolves a result: the reply's text and cost, or why there is no text.\n *\n * No tools, no history, no system prompt beyond the CLI's identity block\n * and `request.system`; ModelCompleteRequest says the rest. Only a request\n * the engine refuses to send (a blocked model, a bad cap) rejects.\n *\n * @param request the model (an alias such as `haiku`, or a full id\n * resolved like `--model`), prompt, cap, effort, time limit\n * @param options `signal`: the plugin's own AbortSignal; aborting it\n * cuts the call while it runs, which then resolves `aborted`\n * @returns the reply (`isAnswered`, `text`, `usage`), else the `reason`:\n * `api-error` with `status` and `error`, `empty-reply`, `aborted`\n * @example\n * const r = await $.model.complete({ model: \"haiku\", prompt, effort })\n * @example\n * // one handler starts it, a later one cancels it while it runs\n * let stop = new AbortController()\n * const start = async () => {\n * stop = new AbortController()\n * const r = await $.model.complete(ask, { signal: stop.signal })\n * if (!r.isAnswered && r.reason === \"aborted\") $.ui.log(\"cancelled\")\n * }\n * const cancel = () => stop.abort()\n */\n complete: (request: ModelCompleteRequest, options?: ModelCompleteOptions) => Promise;\n /**\n * Runs one tool-less completion over the session's OWN transcript as the\n * main thread last sent it, so the API serves that prefix from its cache.\n *\n * The main thread's last request again (its model, system prompt, tools,\n * messages) with `prompt` after it: every tool denied, its own tail never\n * cached, the prefix billed afresh once the entry lapsed or after `/model`.\n * It thinks as hard as the session does unless `effort` says otherwise;\n * ModelForkRequest says what holds that level and when it costs the cache.\n *\n * @param request the one user message the fork answers, and its effort\n * @returns always a result, never null: the reply (`isAnswered`, `text`,\n * `usage`, the `effort` sent), or why there is no text (`reason`:\n * `nothing-to-fork` before the first request and after `/clear`,\n * `api-error` with its HTTP `status` and `error` kind,\n * `empty-reply`, or `aborted` when the turn whose hook forked was\n * interrupted); a request of the wrong shape (no prompt, an\n * `effort` that is no level) rejects instead\n * @example\n * const reply = await $.model.fork({ prompt: \"One line to learn?\" })\n * $.ui.log(reply.isAnswered ? reply.text : `no reply: ${reply.reason}`)\n * @example\n * // a quick side job in a session the person runs at max\n * const cut = await $.model.fork({ prompt: \"Shorter.\", effort: \"low\" })\n */\n fork: (request: ModelForkRequest) => Promise;\n /**\n * Picks one of `labels` for `text` with one completion over\n * `$.model.complete` and a fixed classifier prompt.\n *\n * `text` is data; the model answers with a label alone. It resolves\n * `undefined` when the answer named none of `labels`. A failed request,\n * an abort or a reply with no text rejects, naming the cause.\n *\n * @param text what to classify\n * @param labels the labels to choose from (2 or more)\n * @param options `model`: an alias or id; default the engine's small\n * fast model\n * @returns the label the model named, or undefined when it named none;\n * rejects when the request fails or the reply has no text\n * @example\n * const kind = await $.model.classify(e.text, [\"bug\", \"feature\"])\n * if (kind === undefined) return next(e)\n */\n classify: (text: string, labels: readonly string[], options?: ClassifyOptions) => Promise;\n };\n /**\n * Sound: clip playback and platform speech.\n */\n audio: {\n /**\n * Plays one audio clip, starting now; clips are not queued, so two calls\n * play together (a bed under speech).\n *\n * `{ asset }` is the plugin's own file; `afplay` plays it on macOS, and a\n * Linux or Windows terminal, having no player, plays nothing. Resolves once\n * played or skipped; rejects, naming the cause, when the clip cannot play.\n *\n * @param clip the plugin's own file (`{ asset }`), a URL the engine\n * fetches, or the bytes as base64 with their MIME type\n * @param options `shouldLoop`, `gain`, and an AbortSignal that stops the\n * clip\n * @example\n * await $.audio.play({ asset: \"sounds/done.wav\" })\n */\n play: (clip: AudioClip, options?: PlayOptions) => Promise;\n /**\n * Speaks `text` with the platform's own synthesizer (`say` on macOS).\n * Plain text.\n *\n * Utterances are queued among themselves; clips are not. Resolves when\n * the utterance has ended; rejects, naming the cause, when there is no\n * synthesizer, the voice is not installed, or the utterance failed.\n *\n * @param text what to say, as plain text\n * @param options `voice`: the system voice's exact name (`Samantha`);\n * absent, the synthesizer's default\n * @returns which synthesizer spoke, once the utterance has ended\n */\n speak: (text: string, options?: SpeakOptions) => Promise;\n };\n /**\n * The engine's MCP servers: calling a connected one's tools, and\n * connecting one the plugin lists itself.\n */\n mcp: {\n /**\n * Calls `tool` on one of the engine's connected MCP servers with the\n * engine's own connection and credentials.\n *\n * A `cached` server is dialed on first use. No permission prompt: the\n * plugin's call, seen by the hooks above it, is the grant. Positional, not\n * the `{ tool: \"mcp__server__tool\", ... }` shape a `tool.call` hook sees.\n *\n * @param server the server's name as /mcp lists it (`claude.ai Gmail`;\n * the tool-name spelling `claude_ai_Gmail` is accepted too)\n * @param tool the tool's name on that server (`create_draft`)\n * @param args the tool's arguments; none when absent\n * @returns the tool's result as MCP returns it: `content` blocks and\n * `isError`\n * @example\n * const { content } = await $.mcp.call(\"claude.ai Gmail\", \"create_draft\", {\n * to: \"team@example.com\",\n * subject: \"Release notes\",\n * })\n */\n call: (server: string, tool: string, args?: Record) => Promise;\n /**\n * Connects one of the MCP servers this plugin's own manifest lists, if\n * the session has not already: a listed server joins it at its start.\n *\n * So listing a server defers nothing: to hold its tools back, refuse\n * their calls at `tool.check`. The same server run under another name\n * answers with that name; a refusal resolves with `reason`, `message`.\n *\n * @remarks Under `allowManagedHooksOnly` a `user`-tier plugin loads no\n * hooks: its gate is absent, yet its server connects. Ship it as managed.\n * @param server the server's key in this plugin's manifest\n * @returns connected, with the name `call` takes, or why not\n * @example\n * const browser = await $.mcp.connect(\"browser\")\n * if (browser.isConnected) $.mcp.call(browser.server, \"open\", { url })\n */\n connect: (server: string) => Promise;\n };\n /**\n * The running session, read as plain data; compacting it; and sending a\n * message from it to another agent or session.\n */\n session: {\n /**\n * Returns the transcript so far, one SessionMessage per user or assistant\n * message; progress rows, `$.ui.log` lines and notices are not messages.\n *\n * With `{ agentId }`, one of this session's agents' instead (a subagent, a\n * fork, a teammate in this process): what the session saved for it joined\n * with what the engine holds. With `{ as: \"api\" }`, either as ApiMessage.\n *\n * @param args `agentId`, the id `tool.call`, `turn.complete` and `$.agent\n * .list()` carry; `as: \"api\"` for ApiMessage; hooks see both\n * @returns the newest 4096 entries, `{ role, text, toolUses }` (a user\n * message may add `toolResults`; a `toolUses` entry adds `result`\n * and `text` once answered, an Agent tool use its `agentId`), or\n * with `as` `{ role, content }`, blocks intact, at most 4096\n * opening on a user message; for an `agentId` the session\n * cannot read, `{ deny }` (SessionMessagesDeny), never main\n * @example\n * const last = (await $.session.messages()).at(-1)\n * @example\n * const request = await $.session.messages({ as: \"api\" })\n * await $.http.fetch(AUDIT_URL, {\n * method: \"POST\",\n * body: JSON.stringify({ session: await $.session.id(), request }),\n * })\n * @example\n * on(\"turn.complete\", async ($, e, next) => {\n * if (e.agentId === undefined) return next(e)\n * const found = await $.session.messages({ agentId: e.agentId })\n * if (!(\"deny\" in found)) $.ui.log(`${found.length} messages`)\n * return next(e)\n * })\n */\n messages: SessionMessagesCall;\n /**\n * Returns the directory the session runs in, absolute.\n *\n * A timer that outlives its hook reads the session's directory; keep the\n * value read inside the hook if you need the hook's (a subagent's own).\n */\n cwd: () => Promise;\n /**\n * Returns the session's project root, absolute: where it started, or\n * where `/cd`, a host's directory change or a worktree move took it.\n *\n * A shell `cd` during the session does not move it; nested instruction\n * files are read only beneath it.\n */\n root: () => Promise;\n /**\n * Returns the main loop's model, as `/model` shows it.\n */\n model: () => Promise;\n /**\n * Returns how many prompts the user has sent this session (user turns in\n * the transcript).\n */\n turns: () => Promise;\n /**\n * Returns the session's id (the transcript file's name).\n */\n id: () => Promise;\n /**\n * Returns the git repository the session runs in, read from the working\n * copy on each call; null when the directory is not inside one.\n *\n * @example\n * const repo = await $.session.repo(); const publicRepo = !repo?.internal\n */\n repo: () => Promise;\n /**\n * Returns every surface the session draws on, each once: `terminal` under\n * the REPL first, then the remote ones in the order they attached.\n *\n * A session may draw on several at once (a terminal and two phones):\n * clients attach (`session.attach`) and detach, and a render hook still\n * reads `e.surface` per ask. Empty in a plain -p run; never rejects.\n *\n * @example\n * const inApp = (await $.session.surfaces()).some(s => s !== \"terminal\")\n */\n surfaces: () => Promise;\n /**\n * Returns the first of `$.session.surfaces()`, or null where nothing\n * draws.\n *\n * @deprecated use `surfaces()`; a session may draw on several surfaces at\n * once\n */\n surface: () => Promise;\n /**\n * Returns when the session began, and the context window's fill, the\n * rate-limit windows and the cost as the status line has them, itemized.\n *\n * The plain call costs nothing; `\"full\"` counts each category with the\n * token-count API as /context does, `\"summary\"` estimates locally, and\n * `context.breakdown` comes back in the SDK's `get_context_usage` shape.\n *\n * @param args `{ breakdown, columns }`: how the breakdown is counted and\n * the width its grid is drawn in; nothing for the status line's figures\n * @returns `{ startedAt, context, rateLimits, cost }` as the status line\n * has them\n * @example\n * const { context } = await $.session.usage()\n * if ((context.percent ?? 0) >= 85) await $.session.compact()\n * @example\n * const isOlder = stat.mtimeMs < (await $.session.usage()).startedAt\n * @example\n * const usage = await $.session.usage({ breakdown: \"full\", columns })\n * for (const row of usage.context.breakdown?.gridRows ?? []) draw(row)\n */\n usage: (args?: SessionUsageArgs) => Promise;\n /**\n * Returns the version of the engine the session runs on, the release it\n * is built from, and when it was built.\n *\n * The same three values the engine's own analytics rows carry, answered\n * in every mode and build; `base` is absent when the version is not\n * spelled as a release, `builtAt` in a run from source that stamps none.\n *\n * @returns the full `version`, its release `base` (`2.1.280`, or\n * `2.1.280-dev` for a development build) and an ISO `builtAt`\n * @example\n * const { version, base, builtAt } = await $.session.version()\n * row.env = { version, version_base: base, build_time: builtAt }\n * @example\n * const isRelease = !(await $.session.version()).base?.endsWith(\"-dev\")\n */\n version: () => Promise;\n /**\n * Compacts the conversation: the event `session.compact` with `trigger`\n * `plugin`, the same call `/compact` makes, between turns.\n *\n * It runs through every hook but the calling one, then core: a summary\n * and the kept messages in the transcript's place. Resolves `{ skip }`\n * when a hook vetoed it; rejects while a turn runs.\n *\n * @example\n * const { skip } = await $.session.compact({ instructions: \"the plan\" })\n */\n compact: EventCalls['session']['compact'];\n /**\n * Sends a plain-text message to another agent or session: the event\n * `session.send`, the model's SendMessage tool's own call and delivery.\n *\n * `to` is the tool's spelling (a name, an agent id, a received `from`\n * address) or `{ sessionId }` / `{ agentId }`; framed at the receiver as a\n * peer's, `origin.plugin` naming this plugin there. Resolves once queued.\n *\n * @example\n * const sent = await $.session.send({ to: { sessionId }, text: \"ok\" })\n * @example\n * await $.session.send({ to: { agentId }, text: \"stop after this file\" })\n */\n send: EventCalls['session']['send'];\n /**\n * Appends a row to a conversation of the session: the event\n * `session.append`, the engine's own call for every row it keeps.\n *\n * A user-role row the person does not see as typed or a notice, of text\n * blocks alone in this release (else refused with the reason): listed at\n * once. `{ deny: reason }` when a plugin above refused it, nothing stored.\n *\n * @example\n * await $.session.append({ message: { type: \"user\", content: [note] } })\n */\n append: (args: SessionAppendArgs) => Promise;\n /**\n * Holds the session's Anthropic credential on the host and answers an\n * opaque handle and its kind; the secret never reaches the plugin.\n *\n * The handle is spent through `$.http.fetch(url, { auth: handle })`,\n * which sets the credential header, only for a first-party host. Null\n * with no first-party credential (a 3P provider, a gateway, no login).\n *\n * @example\n * await $.http.fetch(url, { auth: (await $.session.authorize())?.handle })\n */\n authorize: () => Promise;\n /**\n * Returns how the session is signed in, to a mod the organization's\n * managed settings install; `{ deny }` to any other. No request is made.\n *\n * The account (organization, plan, email) only where managed\n * `forceLoginOrgUUID` lists its organization; else `kind` alone. A\n * contract, not a wall: any mod can read the person's own config file.\n *\n * @example\n * const { kind, organizationId, email } = await $.session.identity()\n */\n identity: () => Promise;\n };\n /**\n * The running model turn: ending it.\n */\n turn: {\n /**\n * Cancels the main loop's running model turn (the id its `turn.start`\n * handed this plugin), its running tools stopped, no interruption marker.\n *\n * The event `turn.abort`, seen by the hooks above; the prompt this\n * plugin submits next is the context. Rejects, naming both ids, when\n * `turnId` is not the running turn's; a hook may end its own turn.\n *\n * @param input `turnId`: the id the main loop's `turn.start` carried\n * @example\n * on(\"turn.start\", ($, e, next) => {\n * if (e.agentId === undefined) held = e.turnId\n * return next(e)\n * })\n */\n abort: (input: OpEventOf['turn.abort']) => Promise;\n };\n /**\n * Submitting a prompt the model reads as a user turn, and the person's\n * prompt box: read as it stands, written, or proposed into.\n */\n prompt: {\n /**\n * Submits a prompt: the event `prompt.submit`, the same call the engine\n * makes for a typed prompt; a turn of its own, once the session is idle.\n *\n * It goes through every hook but the calling one (the plugin's others\n * see it) with `e.origin` `{ kind: 'plugin', name }`, the name the\n * model reads it under unless a hook leaves it out of its answer.\n *\n * @example\n * void $.prompt.submit({ text: \"List the TODOs you just mentioned.\" })\n */\n submit: EventCalls['prompt']['submit'];\n /**\n * Returns the prompt box as it stands, the draft typed so far and the\n * cursor's offset into it, so a `fill` can keep what the person typed.\n *\n * Never rejects: `{ text: '', cursor: 0 }` where the session draws no box\n * (a -p run, an SDK host) or none is mounted yet.\n *\n * @example\n * const { text, cursor } = await $.prompt.read()\n */\n read: () => Promise;\n /**\n * Returns one image or document of the prompt being submitted, by the\n * `id` `e.attachments` lists it under: its bytes, base64, 4 MiB a call.\n *\n * For a `prompt.submit` hook; else `{ deny }`, as once the submission\n * has settled. The engine's own read, no event: no hook answers for it.\n * `{ unreadable }`: no image.\n *\n * @example\n * const media = id ? await $.prompt.media({ id }) : undefined\n */\n media: (args: PromptMediaArgs) => Promise;\n /**\n * Puts `input.text` in the prompt box as the draft, by `mode`: `replace`\n * (the default) over it, `append` after it, `insert` at the cursor.\n *\n * The event `prompt.fill` through the other plugins' hooks; `isFilled:\n * false` under a dialog or headless. To hand the model text WITH the next\n * prompt instead, a `prompt.submit` hook adds `context` (second example).\n *\n * @example\n * await $.prompt.fill({ text: `> ${quote}\\n`, mode: \"insert\" })\n * @example\n * ($, e, next) => next({ ...e, context: [...(e.context ?? []), hunk] })\n */\n fill: (input: PromptFillArgs) => Promise;\n /**\n * Sets this plugin's own decorations over the draft and nothing else.\n *\n * No text, caret or undo entry, no `prompt.change` or `prompt.edit`. Hooks\n * may rewrite or `{ deny }` it. `isPainted: false`, the box handed back,\n * when the draft no longer reads `text`, or another plugin hooks its read.\n *\n * @example\n * await $.prompt.paint({ text, decorations: [{ start, end, bold: true }] })\n */\n paint: (input: PromptPaintArgs) => Promise;\n /**\n * Proposes `input.text` as the prompt box's dim suggestion, Tab to take:\n * the event `prompt.suggest`, as the engine's own guess after a turn.\n *\n * It goes through every other plugin's hook with `e.origin` `{ kind:\n * 'plugin', name }`, the engine's own suggestions on or off; `{ isShown:\n * false }` while the box holds text, a turn runs, or headless (no box).\n *\n * @example\n * void $.prompt.suggest({ text: \"run the tests you just wrote\" })\n */\n suggest: EventCalls['prompt']['suggest'];\n /**\n * Returns the system prompt's sections for `facts`: the event\n * `prompt.compose`, the call the engine makes for every prompt it sends.\n *\n * A fact left out is the session's own (its model, its tools). Through\n * every other plugin's hook, over the engine's own composition; composed\n * for nobody to send, so nothing the session holds is written.\n *\n * @example\n * const ids = (await $.prompt.compose()).sections.map(s => s.id)\n */\n compose: EventCalls['prompt']['compose'];\n };\n /**\n * The tools the model has in this session, and running one.\n */\n tool: {\n /**\n * Returns the tools the model can call now, built-in and MCP alike, in\n * the order the model sees them.\n *\n * @example\n * const names = (await $.tool.list()).map(t => t.name)\n */\n list: () => Promise;\n /**\n * Calls a tool: the event `tool.call`, the same call the engine makes for\n * the model's tool calls, under a `tool_use_id` of its own.\n *\n * It runs through every hook but the calling one (the plugin's others\n * see it), the permission check and its dialog, then the tool. Rejects\n * when no tool has that name or the call is aborted.\n *\n * @example\n * const { text } = await $.tool.call({ tool: \"Read\", file_path: \"a.md\" })\n */\n call: EventCalls['tool']['call'];\n /**\n * Asks the engine's permission decision for a tool call now: the event\n * `tool.check`, resolved to its verdict (`{ decision, reason?, ... }`).\n *\n * The hooks run (the calling hook's own frame skipped, `next.origin` this\n * plugin, no `tool_use_id`); nothing runs, no dialog opens, no PreToolUse\n * hook or classifier is asked.\n *\n * @example\n * const { decision } = await $.tool.check({ tool: \"Read\", input })\n */\n check: EventCalls['tool']['check'];\n /**\n * Declares a tool the model can call from the next prompt on: the name,\n * description and input schema of `mcp____`.\n *\n * Serve it with a `tool.call` hook on `{ tool: \"mcp____\" }`\n * that returns the result (a call no hook answers fails); a name registered\n * again is replaced. Rejects until the session binds, at `session.start`.\n *\n * @param tool `name`, `description` (what the model reads), `inputSchema`\n * (default `{ type: \"object\" }`), `isDeferred` (ToolSpec)\n * @returns `{ tool }`, the registered tool's full name\n * `mcp____`\n * @example\n * await $.tool.register({ name: \"weather\", description: \"Weather.\" })\n */\n register: (tool: ToolSpec) => Promise;\n };\n /**\n * The slash commands the person can run in this session, and running one.\n */\n command: {\n /**\n * Returns the slash commands the person can run now, built-in, plugin\n * and MCP alike, in the order the typeahead lists them.\n *\n * @example\n * const names = (await $.command.list()).map(c => c.name)\n */\n list: () => Promise;\n /**\n * Runs a slash command as if the person typed `/command args`: the\n * event `command.run`, queued and run once the session is idle.\n *\n * It runs through every hook but the calling one with `e.origin` `{ kind:\n * 'plugin', name }`, its lines in the transcript. Rejects an unknown name,\n * inside a hook the turn or the session's start waits on, past a Stop or\n * a host's limit.\n *\n * @example\n * const { text } = await $.command.run({ command: \"status\" })\n */\n run: EventCalls['command']['run'];\n /**\n * Declares the slash command `/` for this session, listed in the\n * typeahead from the next keystroke on.\n *\n * Serve it with a `command.run` hook on `{ command: \"\" }` that\n * returns `{ text }`; a run no hook answers says so as its output.\n * Registering a name again replaces it; a built-in's name is refused.\n *\n * @param command `name`, `description` (what the menu shows),\n * `argumentHint` (dim after the name), `immediate` (runs mid-turn)\n * @returns `{ command }`, the registered name\n * @example\n * await $.command.register({ name: \"hello\", description: \"Says hi.\" })\n */\n register: (command: CommandSpec) => Promise;\n };\n /**\n * Every row of the settings menu (`/config`), the panel's own and each\n * enabled plugin's `userConfig` fields alike: listing and changing them.\n */\n config: {\n /**\n * Returns the rows the `/config` menu would draw now, in its order,\n * each with its current value, its kind, its owner and its lock.\n *\n * After every `config.describe` hook: a hidden row is left out, a\n * relabelled one carries the new label.\n *\n * @example\n * const theme = (await $.config.list()).find(row => row.key === \"theme\")\n */\n list: () => Promise;\n /**\n * Changes one row as if the person did in the menu: the event\n * `config.set` with `origin` `{ kind: 'plugin', name }`, then the writer.\n *\n * Through the other plugins' hooks, this plugin's own skipped; `{ deny }`\n * when a hook refused, the value does not fit, a trusted source owns the\n * row or only its dialog changes it. Rejects a key no row has.\n *\n * @param args `key` (as `list` names it) and `value` (the row's kind)\n * @returns `{ value }` once written, or `{ deny }`\n * @example\n * const { deny } = await $.config.set({ key: \"verbose\", value: true })\n */\n set: EventCalls['config']['set'];\n };\n /**\n * Analytics: first-party rows and feature marks for Anthropic, and records\n * for the telemetry collector the session's operator configured.\n */\n telemetry: {\n /**\n * Logs one record to the destination `entry.to` names, the event\n * `telemetry.log`; `e.to` is pinned, and `anthropic` when left out.\n *\n * A first-party row is queued by the built-in plugin that hooks the\n * event, for built-ins and the engine alone. A collector record reaches\n * the collector only when the engine raised it; any plugin may hook.\n *\n * @param entry a first-party row, or a collector record\n * @returns once the hooks have answered; rejects when one denies\n * @example\n * await $.telemetry.log({\n * to: \"anthropic\",\n * event: \"survey_answered\",\n * props: { answer: 2, page: { value: \"ready\", of: [\"ready\", \"later\"] } },\n * })\n */\n log: (entry: TelemetryLogArgs) => Promise;\n /**\n * Marks one use of a feature as the CLI's own feature events do, the\n * event `telemetry.mark`; it takes no `to` and always means `anthropic`.\n *\n * The engine does nothing with it: the built-in plugins that hook the\n * event queue the row. They serve built-ins and the engine alone; any\n * plugin may hook it.\n *\n * @param entry the feature, how its use went, why, and its properties\n * @returns once the hooks have answered; rejects when one denies\n * @example\n * await $.telemetry.mark({ feature: \"learn_page\", kind: \"sad\",\n * reason: \"blocked\" })\n */\n mark: (entry: TelemetryMarkInput) => Promise;\n };\n /**\n * Subagents.\n */\n agent: {\n /**\n * Spawns a subagent: the event `agent.spawn`, the same call the engine\n * makes when the Agent tool starts one; the engine fills the rest.\n *\n * It runs every hook but the calling one, then the Agent tool in the\n * background under this call's origin: `{ model, agentId }` once the\n * subagent started (its answer is its `turn.complete`), or `{ deny }`.\n *\n * `{ deny }` is a hook's refusal, or the engine's own with its reason:\n * past a Stop or a host's limit nothing is spawned, as for a prompt.\n *\n * @example\n * const { agentId } = await $.agent.spawn({ prompt: \"Read README.md.\" })\n */\n spawn: EventCalls['agent']['spawn'];\n /**\n * Returns the session's agents so far, subagents and teammates: the ones\n * the model spawned and the ones plugins did alike.\n *\n * One entry an agent, until the engine drops its task: as a teammate ends\n * or seconds after, a subagent's later. Loops the engine tracks as agents\n * with no `agent.spawn` (a forked skill) are here; a workflow's are not.\n */\n list: () => Promise;\n /**\n * Defines an agent type the Agent tool dispatches from the next turn on,\n * named `:`: the event `agent.register`.\n *\n * Every field takes effect as in an agent file; re-registered, a name is\n * replaced; unloaded, a plugin's types go. `agent.offer` hides it from\n * the model alone; any plugin's `$.agent.spawn` answers to `agent.spawn`.\n *\n * @param spec `name`, `description` (when to delegate), `prompt` (its\n * system prompt), and any other field of an agent definition\n * @returns `{ agent }`, the full name; rejects until the session binds,\n * on a spec the schema refuses (its reason), on a hook's deny\n * @example\n * await $.agent.register({ name: \"runner\", description: \"Runs a spec\",\n * prompt: RUNNER_PROMPT, tools: [\"Read\", \"Bash\"], omitClaudeMd: true })\n * @example\n * // runner-only: hidden from the model, spawned by this plugin's tool,\n * // answered by the subagent's turn.complete (matched by agentId)\n * on(\"agent.offer\", { agent: \"lab:runner\" }, () => ({ isOffered: false }))\n * on(\"tool.call\", { tool: \"mcp__lab__run\" }, async ($, e) => {\n * const { agentId, deny } = await $.agent.spawn({\n * subagentType: \"lab:runner\", prompt: e.spec, description: \"run\" })\n * return { result: deny ?? (await answerOf(agentId)) }\n * })\n */\n register: (spec: AgentSpec) => Promise;\n };\n /**\n * The file system as the engine's own process reaches it; a relative path\n * is under the session's working directory, and text is UTF-8.\n *\n * An absolute path is used as given; where one may go is an `fs.*` hook's\n * to say. A read or write over 4 MiB rejects, the implementation beneath the\n * hooks rejects a network location untouched, an OS refusal with its errno.\n */\n fs: {\n /**\n * Reads a file and returns its text, or with `{ as: \"bytes\" }` its bytes\n * as `{ base64 }`.\n *\n * Rejects when missing, or over 4 MiB, which bounds what one read copies\n * into the plugin's environment. A file the plugin ships is under\n * `$.plugin.root`.\n *\n * @param path relative to the working directory, or absolute\n * @param options `as`: `\"text\"` (the default) or `\"bytes\"`\n * @returns the file's text, or `{ base64 }`\n * @example\n * const readme = await $.fs.read(\"README.md\")\n * @example\n * const { base64 } = await $.fs.read(\n * `${$.plugin.root}/hooks/weights.bin`, { as: \"bytes\" })\n * const weights = Uint8Array.fromBase64(base64)\n */\n read: FsReadCall;\n /**\n * Writes `text` to a file, creating it and its directories as needed.\n *\n * @param path relative to the working directory, or absolute\n * @param text the whole new content\n */\n write: (path: string, text: string) => Promise;\n /**\n * Lists a directory by name: `{ name, kind, size, mtimeMs, isLink }` per\n * entry, each entry as it stands.\n *\n * A symbolic link is `other` with `isLink`; `size` and `mtimeMs` are a\n * regular file's own and 0 for every other kind (`$.fs.stat` has those).\n *\n * @param path the directory's path; absent, the working directory\n * @returns the entries, `{ name, kind, size, mtimeMs, isLink }` each\n * @example\n * const logs = await $.fs.list(\"logs\")\n * const newest = [...logs].sort((a, b) => b.mtimeMs - a.mtimeMs)[0]\n */\n list: (path?: string) => Promise;\n /**\n * Returns whether the path exists; rejects only a network location, which\n * the implementation beneath the hooks never touches.\n */\n exists: (path: string) => Promise;\n /**\n * Returns `{ kind, size, mtimeMs, isLink }` of the path: what it leads to,\n * and whether it is itself a symbolic link. Rejects when missing.\n *\n * With `{ resolve: true }` also `realPath`, where the path lands, absent\n * when it leads nowhere; a guard matches it and denies without it, since a\n * spelling it cannot resolve (`~`, a file not there yet) the tool may open.\n *\n * @param path relative to the working directory, or absolute\n * @param options `resolve`: also answer `realPath` (one more file system\n * call)\n * @returns the stat, `realPath` with it when asked and resolvable; rejects\n * `ENOENT` for a missing path\n * @example\n * // ROOT was resolved the same way and SEP is its separator; an\n * // allow-list under it is the robust guard, a deny-list on spellings\n * // only best effort (a hard link or a case alias keeps its own)\n * on(\"tool.call\", { tool: \"Read\" }, async ($, e, next) => {\n * const stat = await $.fs.stat(e.file_path, { resolve: true })\n * .catch(() => undefined)\n * const real = stat?.realPath\n * const isInside = real !== undefined && real.startsWith(ROOT + SEP)\n * return isInside ? next(e) : { deny: \"outside the project\" }\n * })\n * @example\n * // a Write may name a file not there yet: `placed` answers where the\n * // path lands or undefined, and the guard denies on undefined or\n * // outside ROOT. Unplaceable by spelling first, with no file system\n * // call (drive-relative `D:x`, a `\\\\` or `//` network or device path,\n * // a name that is empty, \".\", \"..\" or itself `C:...`); then the file\n * // if it stats; else its folder, cut after the last separator and\n * // keeping it so a drive or share root stays that root, plus the name\n * const placed = async (path) => {\n * const cut = Math.max(path.lastIndexOf(\"/\"), path.lastIndexOf(\"\\\\\"))\n * const name = path.slice(cut + 1)\n * const isPlaceable = !/^[A-Za-z]:(?![\\\\/])/.test(path) &&\n * !/^[\\\\/][\\\\/]/.test(path) && !/^[A-Za-z]:/.test(name) &&\n * name !== \"\" && name !== \".\" && name !== \"..\"\n * if (!isPlaceable) return undefined\n * const own = await $.fs.stat(path, { resolve: true })\n * .catch(() => undefined)\n * if (own) return own.realPath\n * const folder = cut < 0 ? \".\" : path.slice(0, cut + 1)\n * const dir = await $.fs.stat(folder, { resolve: true })\n * .catch(() => undefined)\n * return dir?.realPath === undefined ? undefined\n * : `${dir.realPath.replace(/[\\\\/]$/, \"\")}${SEP}${name}`\n * }\n * const real = await placed(e.file_path)\n * const isInside = real !== undefined && real.startsWith(ROOT + SEP)\n * return isInside ? next(e) : { deny: \"cannot place it, or outside\" }\n */\n stat: (path: string, options?: FsStatOptions) => Promise;\n /**\n * Reads the named instruction files in every directory above the\n * session's original working directory, the way the engine reads CLAUDE.md.\n *\n * Root first, each `{ dir, name, content }` that exists, the content\n * with its `@include`s after it; `of` and `below` together are the\n * engine's own walk for a nested CLAUDE.md between root and read file.\n *\n * @param request `names`, relative `.md` file names (no `..`); `of`, the\n * file walked down to; `below`, the directory the walk stays inside\n * @returns the files found, root first\n * @example\n * const found = await $.fs.ancestors({ names: [\"AGENTS.md\"] })\n * const stack = await $.fs.ancestors({ names: [\"AGENTS.md\"], of: path })\n * const nested = await $.fs.ancestors({\n * names: [\"AGENTS.md\"],\n * of: e.file_path,\n * below: await $.session.root(),\n * })\n */\n ancestors: (request: FsAncestorsRequest) => Promise;\n };\n /**\n * This plugin's own key-value store, kept between sessions and hot\n * reloads; values are JSON data.\n *\n * A JSON file of the plugin's own under the user's Claude Code\n * configuration directory.\n */\n store: {\n /**\n * Returns the value under `key`, or `undefined` when unset.\n *\n * @example\n * const count = Number((await $.store.get(\"count\")) ?? 0) + 1\n */\n get: (key: string) => Promise;\n /**\n * Sets `key` to `value`, which must be JSON data.\n *\n * `get` reads back `JSON.parse(JSON.stringify(value))`: a Date is its ISO\n * string, an `undefined` field is dropped, a Map or Set is `{}`. Rejects\n * a function, a cycle, or a store over 4 MiB of JSON text in all.\n */\n set: (key: string, value: unknown) => Promise;\n /**\n * Removes `key` from the store.\n */\n delete: (key: string) => Promise;\n /**\n * Returns every key set, in insertion order.\n */\n keys: () => Promise;\n };\n /**\n * Named values held by the host for the session, each with a version: plain\n * data that survives a hot reload of the plugin's code.\n *\n * A `get` made while a `ui.render` hook draws subscribes that instance: a\n * later `set` draws it again, nobody calling `$.ui.invalidate`. Any plugin\n * reads any value; its owner alone writes it. Persist through `$.store`.\n */\n state: {\n /**\n * Resolves the value under `ref` and the version it stands at; a value\n * never written is `undefined` at version 0.\n *\n * Every `get` of one dispatch reads one moment, whatever is written\n * meanwhile. `plugin` and `key` must be literals in source (`claude plugin\n * validate` lists them); only a family member's `id` may be computed.\n *\n * @param ref `{ plugin, key }` as the owner's contract declares it in\n * PluginState, with `id` for a StateFamily key\n * @returns `{ value, version }`\n * @example\n * const workers = { plugin: \"swarm\", key: \"workers\" } as const\n * const { value = [] } = await $.state.get(workers)\n */\n get:

(ref: StateRef) => Promise>>;\n /**\n * Writes `value` under `ref`, which must be this plugin's own; the sites\n * that read it while drawing are drawn again, at the redraw rate.\n *\n * Refused while a `ui.render` hook draws (write from `onPress` or another\n * event) and for another plugin's value (hook its `state.set` and rewrite\n * `e.value`). JSON data, as `$.store.set` takes; never `undefined`.\n *\n * @param ref `{ plugin, key }`, with `id` for a StateFamily key\n * @param value the value, of the type the contract declares\n * @param options `ifVersion`: write only while it stands at that version\n * @returns `{ isSet, version }`; `isSet` false when `ifVersion` missed\n * @example\n * await $.state.set(count, held.value + 1, { ifVersion: held.version })\n */\n set:

(ref: StateRef, value: StateValue, options?: StateSetOptions) => Promise;\n };\n /**\n * The time and timers, each an event through the host: `clock.now` reads\n * the time; `clock.sleep`, `after` and `every` wait until it has passed.\n *\n * A timer's callback is the plugin's own function, kept in its environment\n * and run there when the wait resolves; a hot reload of the plugin cancels\n * its pending waits with the old environment.\n */\n clock: {\n /**\n * Resolves milliseconds since the epoch, now.\n *\n * @example\n * const startedAt = await $.clock.now()\n */\n now: () => Promise;\n /**\n * Resolves after `ms` milliseconds; rejects at once when `signal` aborts.\n *\n * The wait is the hook's own time and its budget runs on through it, as\n * through no other `$` call: a `turn.step` generator that polls with it\n * pays every sleep out of its one budget (`next.budget.remainingMs`).\n *\n * @param ms how long, in milliseconds\n * @param options `signal`: ends the wait early with a rejection (pass\n * `next.signal` so a hook's wait ends with its dispatch)\n * @example\n * await $.clock.sleep(500, { signal: next.signal })\n */\n sleep: (ms: number, options?: SleepOptions) => Promise;\n /**\n * Calls `fn` once after `ms` milliseconds; `cancel()` before then stops it.\n *\n * One `clock.after` dispatch: `fn` runs when it resolves, and never when\n * a hook refuses it.\n */\n after: TimerCall;\n /**\n * Calls `fn` every `ms` milliseconds (at least 1) until `cancel()`.\n *\n * One `clock.every` dispatch per period: `fn` runs when it resolves and\n * the next period is asked; a refused period ends the interval.\n *\n * @example\n * const tick = $.clock.every(1000, () => $.ui.status(\"polling\"))\n */\n every: TimerCall;\n };\n /**\n * The network, through the host.\n */\n http: {\n /**\n * Fetches `url` through the host (never the plugin's own network) and\n * resolves `{ status, ok, headers, text }` once the body is read.\n *\n * http or https, to whatever the host reaches, unless the organization's\n * web-fetch policy refuses it. `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`\n * refuses a built-in's request, and any plugin's that carries `auth`.\n *\n * @param url the URL (http or https)\n * @param init `{ method, headers, body, auth, socketPath }` (body a\n * string; socketPath a Unix socket to go over instead of TCP)\n * @returns `{ status, ok, headers, text }` once the body is read\n * @example\n * const { ok, text } = await $.http.fetch(\"https://example.com/status\")\n * @example\n * await $.http.fetch(\"http://bridge/reload\", {\n * method: \"POST\",\n * socketPath: `${runDirectory}/bridge.sock`,\n * })\n */\n fetch: (url: string, init?: HttpInit) => Promise;\n };\n /**\n * Commands on the host, run as the user the session runs as. CLI only.\n *\n * Local execution, not a network path: what a command of its own reaches\n * is its own, as for the Bash tool and a settings `command` hook.\n */\n process: {\n /**\n * Runs a command on the host by its argument vector (no shell) and\n * resolves `{ exitCode, stdout, stderr }` once it exits, any exit code.\n *\n * One shot: the whole output is read, so a background process left\n * writing holds the call until the timeout. Rejects when the command\n * cannot start or is still running then. Git runs with repo hooks off.\n *\n * @param argv the command and its arguments, `argv[0]` the executable\n * @param init `{ cwd, env, stdin, timeoutMs }` (cwd the session's by\n * default; timeout 30 s by default, ten minutes at most)\n * @returns `{ exitCode, stdout, stderr }`, each stream's first 4194304\n * bytes (`isStdoutTruncated`, `isStderrTruncated` say when cut)\n * @example\n * const { exitCode, stdout } = await $.process.run([\"git\", \"status\"])\n */\n run: (argv: readonly string[], init?: ProcessRunInit) => Promise;\n /**\n * Starts a command on the host by its argument vector (no shell) and\n * streams what it writes, piece by piece, then how it ended.\n *\n * The loop is the child's life: leaving it, `return()` on the stream,\n * `next.signal` aborting or the module unloading kills the child, and\n * nothing else does, a hook's return included: end the loop to end it.\n *\n * @param request `{ argv, cwd, env, input }`, `$.process.run`'s rules;\n * `e` for a hook on `process.spawn` (a generator, its budget per piece)\n * @returns the pieces `{ stream, text }` (text as it came, not lines),\n * then `{ code, signal }`; rejects its first pull if it cannot start\n * @example\n * // inline: the hook's dispatch waits on the loop; leaving it kills make\n * const make = $.process.spawn({ argv: [\"make\"], cwd: \"build\" })\n * for await (const { stream, text } of make) {\n * if (stream === \"stderr\" && text.includes(\"error\")) break\n * }\n * @example\n * // a child for the session's life: the loop runs on after the hook\n * // returns, and ends with the child or with the module\n * on(\"session.start\", async ($, e, next) => {\n * const started = await next(e)\n * void (async () => {\n * const bridge = $.process.spawn({ argv: [\"bridge\", \"watch\", e.cwd] })\n * for await (const { text } of bridge) $.ui.log(text, { to: \"debug\" })\n * })()\n * return started\n * })\n * @example\n * // above another plugin's spawn: redact each piece before it reads it\n * on(\"process.spawn\", async function* ($, e, next) {\n * for await (const chunk of next(e)) {\n * yield { ...chunk, text: chunk.text.replaceAll(token, \"***\") }\n * }\n * })\n */\n spawn: (request: ProcessSpawnRequest) => HookStream;\n };\n /**\n * What the settings files, `--settings` and managed policy hold, as the\n * engine runs under it; read only.\n *\n * Every key crosses as the source holds it, `env` and the helper commands\n * included: nothing is filtered. The OAuth session and the global config\n * (~/.claude.json) are not settings and are never read.\n */\n settings: {\n /**\n * Resolves with the settings merged over every source, with one\n * source's settings as loaded (`{ source }`), or with the value of one\n * top-level key (`{ key }`), undefined when the settings hold none.\n *\n * A snapshot in plain data each call; a source with no file answers\n * `{}`. Every read raises `settings.read` once, its layers on `e`\n * (SettingsReadInput); a read of one key is the read of the object,\n * projected, and raises no event of its own.\n *\n * The sources (SettingsSource) rise in precedence from `user` to\n * `policy`; with no hook the object is the engine's merge: a scalar\n * from the last source that has it, lists joined, objects merged.\n *\n * Raised by a plugin's call, and by the engine for its own merge once\n * the loaded plugins or the settings have changed, `next.origin` then\n * the engine. What the hooks answer there is what every reader of the\n * merged settings reads, and a changed answer takes effect as a changed\n * settings file does.\n *\n * No key is closed to a hook, the keys that decide which plugins load\n * included: those are read before any plugin is loaded, so the first set\n * loads by the files' own values and an answer applies from the load\n * after. A merge that never settles, an answer changing which plugins\n * load and those answering otherwise, is told in the settings error\n * list, and the files' own value stands for that key.\n *\n * @param args `{ source }` for one source, `{ key }` for one key's\n * value, nothing for the merge\n * @returns the settings object, keyed as a settings.json is, or the\n * key's value\n * @example\n * const { permissions } = await $.settings.read()\n * const policy = await $.settings.read({ source: \"policy\" })\n * const days = await $.settings.read({ key: \"cleanupPeriodDays\" })\n */\n read: SettingsReadOverloads;\n };\n /**\n * The environment of this process, the one every Bash child, MCP server\n * and `$.process.run` command started after inherits.\n *\n * `get` and `set` take the variable's name as a string literal, so what a\n * module reads and writes is read off its source: `claude plugin validate`\n * lists the names, and a name the module does not spell is refused.\n */\n env: {\n /**\n * Resolves with the variable's value, or `undefined` when it is unset.\n *\n * `name` must be a string literal; `claude plugin validate` lists the\n * names your module reads and writes.\n *\n * @example\n * const home = await $.env.get(\"HOME\")\n */\n get: (name: string) => Promise;\n /**\n * Sets the variable for this process and everything it starts after, or\n * unsets it when `value` is `undefined`.\n *\n * `name` must be a string literal; `claude plugin validate` lists the\n * names your module reads and writes.\n *\n * @returns `{}` once it is set or unset, or `{ deny }` saying why not\n * @example\n * await $.env.set(\"GIT_PAGER\", \"cat\")\n */\n set: (name: string, value: string | undefined) => Promise;\n };\n }"},{"name":"CoreEventName","kind":"type","line":3808,"doc":{"desc":["The name of an event the engine defines itself (a key of CoreEventOf);","EventName adds the declared plugin nouns' events."],"params":[],"example":[],"returns":[]},"text":" type CoreEventName = keyof CoreEventOf;"},{"name":"CoreEventOf","kind":"type","line":3814,"doc":{"desc":["The argument of each event the engine defines itself: its call sites'","(EngineEventOf), the classic hooks' (ClassicEventOf), the calls on `$`."],"params":[],"example":[],"returns":[]},"text":" type CoreEventOf = EngineEventOf & ClassicEventOf & OpEventOf;"},{"name":"CwdChangedHookInput","kind":"type","line":3816,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type CwdChangedHookInput = BaseHookInput & {\n hook_event_name: 'CwdChanged';\n old_cwd: string;\n new_cwd: string;\n };"},{"name":"DeclaredAttachmentInput","kind":"type","line":3829,"doc":{"desc":["One `prompt.attachment` input of a type PromptAttachmentDetailOf names:","the attachment's text, and under `detail` the facts it was rendered from.","","A row the engine made holds them, unless its session keeps no plan file. That","one, or one edited by hand, carries no `detail` key: read it as it may be."],"params":[],"example":[],"returns":[]},"text":" type DeclaredAttachmentInput = {\n /**\n * As the engine names the attachment's kind, one of the names that\n * carry a `detail`; the key a matcher narrows on. Pinned.\n */\n type: K;\n /**\n * What the model reads for this attachment, inside the engine's framing;\n * rewritable with `next({ ...e, text })`.\n *\n * The `` wrapper (or the system channel that replaces\n * it) goes around what the chain answers, never inside it.\n */\n text: string;\n /**\n * Who authored the text (PromptAttachmentOrigin): the engine, a settings\n * hook, or a plugin's chain context.\n *\n * Pinned: a different value is refused, one left out is kept.\n */\n origin: PromptAttachmentOrigin;\n /**\n * The loop whose request carries the attachment: a subagent's id, the\n * `id` `$.agent.list()` gives it; absent on main.\n *\n * Pinned: a different value is refused, one left out is kept. A loop\n * forked from another carries the rows made for that one.\n */\n agentId?: string;\n /**\n * Facts of the row the engine computed as it rendered `text`, by `type`:\n * what a hook with words of its own reads in place of the engine's.\n *\n * Pinned: a different value is refused, one left out is kept. Not all\n * the text says: a host's own plan instructions are in `text` alone.\n * Absent on a row that does not hold its facts.\n *\n * @example\n * if (e.detail === undefined) return next(e)\n */\n detail?: PromptAttachmentDetailOf[K];\n };"},{"name":"DeclaredEvents","kind":"type","line":3876,"doc":{"desc":["The state events of each declared value in a union of `[plugin, key]`","pairs, one variant per pair (it distributes), so a matcher narrows `e`."],"params":[],"example":[],"returns":[]},"text":" type DeclaredEvents = Pair extends readonly [\n infer P extends keyof PluginState & string,"},{"name":"DeclaredEventsOf","kind":"type","line":3885,"doc":{"desc":["`e` of `state.get` and of `state.set` for one declared value: its typed","reference, and for a write the change, of the declared type."],"params":[],"example":[],"returns":[]},"text":" type DeclaredEventsOf

= {\n get: StateRef;\n set: StateRef & DeclaredStateChange;\n };"},{"name":"DeclaredPair","kind":"type","line":3894,"doc":{"desc":["Every named value the enabled contracts declare, as one union of","`[plugin, key]` pairs; `never` while PluginState is empty."],"params":[],"example":[],"returns":[]},"text":" type DeclaredPair = {\n [P in keyof PluginState & string]: {\n [K in keyof PluginState[P] & string]: readonly [plugin: P, key: K];\n }[keyof PluginState[P] & string];\n }[keyof PluginState & string];"},{"name":"DeclaredStateChange","kind":"type","line":3904,"doc":{"desc":["What a `state.set` on one declared value carries beside its reference:","the value being written and the one that stood there, of the declared type."],"params":[],"example":[],"returns":[]},"text":" type DeclaredStateChange

= {\n value: StateValue;\n previous: StateValue | undefined;\n /**\n * The version the caller's write is conditional on, when it gave one.\n */\n ifVersion?: number;\n };"},{"name":"Derived","kind":"type","line":3920,"doc":{"desc":["A value computed from other values, as `derive(sources, fn)` makes it:","`read` runs `fn` again only when a source's version moved.","","It holds nothing on the host: the cache is the plugin's own, lost with a","reload of its code, and rebuilt by the next read."],"params":[],"example":[],"returns":[]},"text":" export type Derived = {\n /**\n * The atoms and references it is computed from, read in this order.\n */\n readonly sources: readonly (Atom | StateAddress)[];\n /**\n * The function over the sources' values, in the order they were given.\n */\n readonly compute: (...values: never[]) => T;\n };"},{"name":"DeriveFunction","kind":"type","line":3941,"doc":{"desc":["`derive(sources, fn)`: a value computed from atoms and references, cached","by their versions: `read` runs `fn` again only when one moved.","","Pure: it builds a description and calls nothing; reading it while drawing","subscribes the drawing to every source."],"params":[],"example":["const busy = derive([workers], list => list.filter(w => w.isBusy).length)"],"returns":[]},"text":" export type DeriveFunction = (sources: S, compute: (...values: SourceValues) => T) => Derived;"},{"name":"DirectoryAddedHookInput","kind":"type","line":3943,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type DirectoryAddedHookInput = BaseHookInput & {\n hook_event_name: 'DirectoryAdded';\n /**\n * Absolute path of the directory that was added.\n */\n directory: string;\n /**\n * How the directory was added: \"slash_command\" for /add-dir, \"register_repo_root\" for the SDK control_request.\n */\n source: 'slash_command' | 'register_repo_root';\n };"},{"name":"ElementChildren","kind":"type","line":3963,"doc":{"desc":["The `children` field every element constructor's props carry, appended","beside its own props type: one child, or a list that may nest.","","JSX types a lone child as the child itself (`done`","passes the string, `{count}` the number), and a mapped list","beside a sibling as a nested list (`{rows.map(row)}ok`)."],"params":[],"example":[],"returns":[]},"text":" export type ElementChildren = {\n children?: RenderChildren;\n };"},{"name":"ElementConstructor","kind":"type","line":3975,"doc":{"desc":["An element as `$.ui.resolve(e)` hands it out: a constructor from props to","the frozen plain-data element, `children` among the props as JSX passes.","","`const { Box } = $.ui.resolve(e)` then `...` compiles to","`h(Box, { gap: 1 }, ...children)`, and `h` calls a function tag with its","props, so the table's constructors are the JSX tags."],"params":[],"example":[],"returns":[]},"text":" export type ElementConstructor

= (props: P & ElementChildren) => RenderElement;"},{"name":"ElementName","kind":"type","line":3981,"doc":{"desc":["Every element name of every surface: what a table handed out is completed to","(an omitted one draws a fragment; see `ui.resolve`)."],"params":[],"example":[],"returns":[]},"text":" export type ElementName = {\n [P in RenderSurface]: keyof Elements[P];\n }[RenderSurface];"},{"name":"Elements","kind":"interface","line":3998,"doc":{"desc":["Each surface's primitive tags and their prop types, by `e.surface`, for","the surfaces the plugin was compiled against.","","A surface declares its own three (jsx, elements, components): an interface,","so one not listed here adds its table by declaration merging. With the","surface fixed, that table exactly; with none fixed, only what all share."],"params":[],"example":["declare module \"claude-code\" { interface Elements { slack: SlackTable } }"],"returns":[]},"text":" export interface Elements {\n /**\n * Ink's: beside `Box`, `Text`, `Button`, `Link`, `Code` and `Markdown`,\n * which every surface here carries, `Input`, `Select` and `Client`.\n *\n * The one surface with `Raster` and `Image`, and the one without `Svg`.\n */\n terminal: {\n Box: ElementConstructor;\n Text: ElementConstructor;\n Button: ElementConstructor;\n Input: ElementConstructor;\n Select: ElementConstructor;\n Link: ElementConstructor;\n Code: ElementConstructor;\n Markdown: ElementConstructor;\n /**\n * A region one of the plugin's surface modules draws (ClientModule), named\n * by `module`: a string literal, the module's path relative to this file.\n *\n * The engine reads the surface module off the hooks module's source\n * before anything runs, so a variable, a template with a substitution or\n * a computed path as `module` is refused at load, naming the line.\n */\n Client: ElementConstructor;\n Raster: ElementConstructor;\n Image: ElementConstructor;\n };\n /**\n * Claude Code Desktop's: the six every surface here carries, `Input`,\n * `Select`, `Svg` and `Client`.\n */\n desktop: {\n Box: ElementConstructor;\n Text: ElementConstructor;\n Button: ElementConstructor;\n Input: ElementConstructor;\n Select: ElementConstructor;\n Svg: ElementConstructor;\n Link: ElementConstructor;\n Code: ElementConstructor;\n Markdown: ElementConstructor;\n Client: ElementConstructor;\n };\n /**\n * An app is sent an `Input` or `Select` only if it named it in `draws` on\n * its `ui_attach`, and an empty Box otherwise; a hook cannot tell which the\n * app got.\n *\n * On a tool row (`ToolUse`) in mobile apps, a `borderStyle` or\n * `backgroundColor` on the Box that holds the row and something else asks for\n * a card under the row;\n * otherwise a tree that keeps the row usually draws as one quiet line under\n * it, with the rest behind a tap, so plain Text suits a small status.\n */\n mobile: {\n Box: ElementConstructor;\n Text: ElementConstructor;\n Button: ElementConstructor;\n Input: ElementConstructor;\n Select: ElementConstructor;\n Svg: ElementConstructor;\n Link: ElementConstructor;\n Code: ElementConstructor;\n Markdown: ElementConstructor;\n };\n /**\n * The desktop's table without `Client`: a remote `Client`'s module, presses\n * and posts (ui_client_module, ui_client_press, ui_message) name no surface.\n *\n * They are the desktop's alone until those asks name a surface, no limit of\n * the editor's webview.\n */\n vscode: {\n Box: ElementConstructor;\n Text: ElementConstructor;\n Button: ElementConstructor;\n Input: ElementConstructor;\n Select: ElementConstructor;\n Svg: ElementConstructor;\n Link: ElementConstructor;\n Code: ElementConstructor;\n Markdown: ElementConstructor;\n };\n }"},{"name":"ElementTable","kind":"type","line":4087,"doc":{"desc":["The table `ui.resolve` answers for an argument of surface `P`."],"params":[],"example":[],"returns":[]},"text":" export type ElementTable

= Elements[P];"},{"name":"ElicitationHookInput","kind":"type","line":4092,"doc":{"desc":["Hook input for the Elicitation event. Fired when an MCP server requests user input. Hooks can auto-respond (accept/decline) instead of showing the dialog."],"params":[],"example":[],"returns":[]},"text":" type ElicitationHookInput = BaseHookInput & {\n hook_event_name: 'Elicitation';\n mcp_server_name: string;\n message: string;\n mode?: 'form' | 'url';\n url?: string;\n elicitation_id?: string;\n requested_schema?: Record;\n };"},{"name":"ElicitationResultHookInput","kind":"type","line":4105,"doc":{"desc":["Hook input for the ElicitationResult event. Fired after the user responds to an MCP elicitation. Hooks can observe or override the response before it is sent to the server."],"params":[],"example":[],"returns":[]},"text":" type ElicitationResultHookInput = BaseHookInput & {\n hook_event_name: 'ElicitationResult';\n mcp_server_name: string;\n elicitation_id?: string;\n mode?: 'form' | 'url';\n action: 'accept' | 'decline' | 'cancel';\n content?: Record;\n };"},{"name":"EngineCreateInput","kind":"type","line":4122,"doc":{"desc":["The input of `engine.create`: the fold that builds `$`, once per load,","core innermost.","","A hook is written in post-order: `const built = await next(e)` is `$` as","built so far; `return { ...built, voice: { say } }` adds this plugin's noun.","See EngineEventOf's `engine.create` for what a step may and may not do."],"params":[],"example":[],"returns":[]},"text":" export type EngineCreateInput = {\n /**\n * The modules this fold builds, in list order, first outermost (managed\n * plugins first, so an org plugin's withholding wins).\n *\n * The whole set at a load, this plugin alone at its reload, the ones added\n * or changed at a refresh that keeps the rest: a module added later that\n * does not hook this event is built against the table as it stands.\n */\n plugins: readonly string[];\n };"},{"name":"EngineCreateResult","kind":"type","line":4141,"doc":{"desc":["What an `engine.create` hook returns: `$` as built so far with this","plugin's nouns added, less any it withheld.","","Every declared noun is optional here. Between hooks it crosses the chain","as interface descriptors; a hook sees objects (EngineInterfaceBuilt)."],"params":[],"example":[],"returns":[]},"text":" export type EngineCreateResult = Partial & {\n readonly [noun: string]: unknown;\n };"},{"name":"EngineEventOf","kind":"type","line":4156,"doc":{"desc":["The events the engine raises at its call sites, and `engine.create`; the","classic settings hooks' events are ClassicEventOf.","","At every one, a hook that fails (throws, overruns its budget: HookBudget,","answers a wrong shape) is skipped: the hooks beneath and core run in its","place, or its last `next` result stands; the failure is reported by name."],"params":[],"example":[],"returns":[]},"text":" export type EngineEventOf = {\n /**\n * Fires when the engine is about to run a tool. Each `next(e)` runs the\n * hooks beneath, then core (the permission prompt, the tool itself).\n *\n * `{ deny: reason }` refuses and `{ result }` answers in place of `next`: a\n * deny after `next(e)` resolved undoes nothing it ran; returning with `next`\n * pending aborts what runs beneath. Managed-settings hooks' deny comes first.\n *\n * @remarks A guard that fails is skipped and the tool runs, so give it\n * `.catch(($, e, next) => next.called ? next(e) : { deny: \"no\" })`.\n */\n 'tool.call': ToolCallInput;\n /**\n * Fires when the engine decides whether a tool call may run, after the\n * `tool.call` and PreToolUse hooks and before the mode settles an ask.\n *\n * `next(e)` resolves to the engine's verdict (rules, mode, the tool's own\n * check, PreToolUse's decision) and runs no tool: return any `{ decision }`,\n * a deny after it too. `$.tool.check` runs the same chain, executing nothing.\n *\n * @remarks A guard that fails is skipped, leaving the verdict beneath.\n * Nothing has run, so give it `.catch(() => ({ decision: \"deny\" }))`.\n * @example\n * on(\"tool.check\", { tool: \"Read\" }, () => ({ decision: \"allow\" }))\n */\n 'tool.check': ToolCheckInput;\n /**\n * Fires when the engine is about to draw a component: once per input value\n * (props, viewport width), plugin load or `$.ui.invalidate(\"ui.render\")`.\n *\n * A repaint reuses the answer; a clock invalidates. `next(e)` resolves to the\n * drawing: return it, wrap it, draw your own, or rewrite `props`. An invalid\n * tree, or a throw while drawn, draws the engine's; `--plugin-dir` is told.\n *\n * @remarks Also on a write of `$.state` it read while drawn, at the redraw\n * rate; an invalidate is any plugin's whose matcher may select it.\n */\n 'ui.render': RenderInput;\n /**\n * Fires when the plugins load (not per draw), once per surface, component\n * and plugin: `e` names the surface and component, never the props.\n *\n * `next(e)` resolves to the surface's table, which `$.ui.resolve(e)` then\n * reads. Return it, one with an element restyled for every other plugin,\n * or one with a key left out (a fragment there); own table: hook skipped.\n */\n 'ui.resolve': ResolveInput;\n /**\n * Fires when a `Button` a render hook drew is pressed on a surface; `e` is\n * `{ plugin, element, component, surface }`, `element` the button's `key`.\n *\n * `next(e)` runs the hooks beneath, then core: the element's own `onPress`\n * closure, in its plugin's environment, resolving to `{ element }`. Return\n * `next(e)` to let the press through, or `{ element }` to take it.\n */\n 'ui.press': UiPressArgument;\n /**\n * Fires when an `Input` a render hook drew changes or is submitted; `e` is\n * `{ plugin, element, component, surface, kind, value }`.\n *\n * `next(e)` runs the hooks beneath, then the element's own `onInput` or\n * `onSubmit` with `e.value` as the chain left it, resolving to `{ element,\n * value }`; `next({ ...e, value })` rewrites the typing, an answer takes it.\n */\n 'ui.input': UiInputArgument;\n /**\n * Fires when a `Select` a render hook drew is picked from; `e` is\n * `{ plugin, element, component, surface, value }`.\n *\n * `next(e)` runs the hooks beneath, then the element's own `onSelect` with\n * `e.value` as the chain left it, resolving to `{ element, value }`;\n * `next({ ...e, value })` rewrites the pick, an answer takes it.\n */\n 'ui.select': UiSelectArgument;\n /**\n * Fires when a `Client` THIS plugin drew posts from its surface module\n * (`surface.post(data)`); only this plugin's hooks see it.\n *\n * `next.origin` names `client`: `data` came from code. Core answers `{}`;\n * `next({ ...e, data })` rewrites the data; `{ props }` hands the posting\n * instance its next props without a redraw. One per instance per frame.\n */\n 'ui.message': UiMessageArgument;\n /**\n * Fires when a `Client` THIS plugin drew failed on a surface: its module\n * did not load, its drawing failed, or its code failed after it had drawn.\n *\n * Only this plugin's hooks see it; `e.phase` says when, `e.reason` why.\n * Observe only: core answers `{}`. The engine then draws that site again,\n * unasked: fall back by leaving the `Client` out.\n *\n * @remarks A `Client` born in that redraw that fails is heard too, and the\n * engine draws nothing again for it: to go on, ask (`$.ui.invalidate`).\n * @example\n * on(\"ui.fault\", ($, e, next) => ($.ui.log(e.reason), next(e)))\n */\n 'ui.fault': UiFaultInput;\n /**\n * Fires before a site's window moves: the person's wheel or scroll keys on\n * a `Pane` body or the `AbovePrompt` band, at its edges too; `$.ui.scroll`.\n *\n * `next(e)` moves it to `e.offset` and draws: `{}`; `next({ ...e, offset\n * })` elsewhere; no `next` (`{}` or `{ deny }`) leaves it undrawn, so a hook\n * drawing its own rows under a header moves them by `e.by` and invalidates.\n *\n * @example\n * on(\"ui.scroll\", { requestId: \"log\" }, ($, e) => (scrollOwnRows(e.by), {}))\n */\n 'ui.scroll': UiScrollInput;\n /**\n * Fires before a site's focus ring moves: the person's Tab, arrows or click\n * in a `Pane` or the band; an `autoFocus` element taking it; `$.ui.focus`.\n *\n * `next(e)` lands it on `e.element` (absent: one of the engine's stops) and\n * draws: `{}`; `next({ ...e, element })` on another of `e.plugin`'s; no\n * `next` (`{}` or `{ deny }`) keeps it where it was, drawn as it was.\n *\n * @example\n * on(\"ui.focus\", { requestId: \"list\" }, ($, e, next) => (mark(e), next(e)))\n */\n 'ui.focus': UiFocusInput;\n /**\n * Fires when the engine offers an agent type to the model, in the agent\n * listing and again at dispatch; `next(e)` resolves to `{ isOffered: true }`.\n *\n * Return `{ isOffered: false }` to keep the type out of the listing and\n * refuse its dispatch. A hook that fails passes it through.\n *\n * @remarks So give a guard here\n * `.catch(($, e, next) => next.called ? next(e) : { isOffered: false })`.\n * @example\n * on(\"agent.offer\", { agent: \"Plan\" }, () => ({ isOffered: false }))\n */\n 'agent.offer': AgentOfferInput;\n /**\n * Fires when the Agent tool, or a workflow script's `agent()`\n * (`e.workflow`), is about to start an agent, its model not yet resolved.\n *\n * `next(e)` resolves to `{ model }`. Return it, `next({ ...e, model })`,\n * `{ model }` of your own (an alias resolves like the tool's parameter), or\n * `{ deny: reason }`.\n *\n * @remarks A guard that fails is skipped and the subagent starts, so give\n * it `.catch(($, e, next) => next.called ? next(e) : { deny: \"no\" })`.\n */\n 'agent.spawn': AgentSpawnInput;\n /**\n * Fires when a prompt is submitted, before the turn starts. `next(e)` runs\n * the hooks beneath and the UserPromptSubmit settings hooks, then it enters.\n *\n * Rewrite with `next({ ...e, text })` (the user message on screen follows)\n * or, in its place, stop it with `{ drop: reason }`; a broken plugin never\n * blocks one. Typed while a turn ran, it fires at Enter, with that turn's id.\n *\n * @remarks So a guard that fails lets the prompt through, unless given\n * `.catch(($, e, next) => next.called ? next(e) : { drop: \"no\" })`.\n */\n 'prompt.submit': PromptSubmitInput;\n /**\n * Fires when a text is about to be put in the prompt box as the person's\n * draft (a plugin's `$.prompt.fill`); `next(e)` writes it by `e.mode`.\n *\n * `replace` over the draft, `append` after it, `insert` at the cursor;\n * rewrite `text` or `mode` going down, or answer `{ isFilled: false }`\n * without `next` to keep it out, as core does under a dialog or headless.\n *\n * @example\n * on(\"prompt.fill\", ($, e, next) => next({ ...e, text: e.text.trim() }))\n */\n 'prompt.fill': PromptFillInput;\n /**\n * Fires when a text is proposed as the prompt box's dim suggestion, Tab to\n * take: the engine's guess after a turn, or a plugin's `$.prompt.suggest`.\n *\n * `next(e)` shows it: `{ isShown }`. Rewrite with `next({ ...e, text })`,\n * or answer `{ isShown: false }` without `next` to drop it; core answers\n * that too while the box holds text or a turn runs.\n *\n * @example\n * on(\"prompt.suggest\", () => ({ isShown: false }))\n */\n 'prompt.suggest': PromptSuggestInput;\n /**\n * Fires when the person edits the main prompt box: a key the editor took as\n * an edit, or a paste; `next(e)` resolves the box the editor shows.\n *\n * `e` is the draft before and the splice (`start`, `end`, `inputText`); a\n * burst of keys is one edit. Rewrite `inputText` going down or the box\n * coming up; `{ text: e.text, cursor: e.cursor }` without `next` consumes.\n *\n * @example\n * on(\"prompt.edit\", ($, e) => ({ text: e.text, cursor: e.cursor }))\n */\n 'prompt.edit': PromptEditInput;\n /**\n * Fires after the main prompt box's text changed and no `prompt.edit`\n * carried it: a recalled history entry, a clear, a plugin's fill.\n *\n * `e` is the box as it stands and `e.origin` who changed it. Observe only:\n * the change is in the box. One per batch of changes, one at a time.\n *\n * @example\n * on(\"prompt.change\", ($, e, next) => ($.ui.status(e.origin.kind), next(e)))\n */\n 'prompt.change': PromptChangeInput;\n /**\n * Fires as the person types in the main prompt box, for the token at the\n * cursor; `next(e)` resolves to `{ suggestions }`, rows for the typeahead.\n *\n * Nothing waits on it: the engine's own rows draw first and these join\n * beneath them, unhighlighted, for the word still being typed. Taking one\n * writes its `text` over the token. Only while a plugin hooks it.\n *\n * @example\n * on(\"prompt.autocomplete\", () => ({ suggestions: [{ text: \"#123\" }] }))\n */\n 'prompt.autocomplete': PromptAutocompleteInput;\n /**\n * Fires once per named section of the system prompt, when the engine\n * assembles it; `next(e)` resolves to `{ text }` as core computed it.\n *\n * `e.name` is the section's id, on every model the one `prompt.compose`\n * lists. Cached, so keep it steady: after `$.ui.invalidate(\"prompt.section\")`\n * a changed answer goes out next turn over the text the main thread sent,\n * which loses its thinking and the cache. A failed hook passes through.\n *\n * @example\n * on(\"prompt.section\", { name: \"memory\" }, () => ({ text: null }))\n */\n 'prompt.section': PromptSectionInput;\n /**\n * Fires once per conversation, when the engine computes the context blocks\n * its first user message carries; `next(e)` resolves to `{ blocks }`.\n *\n * Append, drop, reorder or rewrite with `next({ ...e, blocks })`; the\n * answer stands until `$.ui.invalidate(\"prompt.context\")` or a re-read\n * (compaction, `/clear`). `PromptContextResult` says what the model is sent.\n *\n * @example\n * on(\"prompt.context\", () => ({ blocks: [] }))\n */\n 'prompt.context': PromptContextInput;\n /**\n * Fires when the engine renders a system prompt; `next(e)` resolves to\n * `{ sections }`, each `{ id, text, scope }`, in the order they are sent.\n *\n * The ids depend on the prompt composed (`lean`, `bare` in `e.traits`): read\n * them off `next(e)`. Append (as `session`), replace, reorder or drop; a list\n * with a `shared` section after a `session` one skips the hook.\n */\n 'prompt.compose': PromptComposeInput;\n /**\n * Fires once per message the engine injects for the model on its own (a\n * reminder, a mode transition, a mentioned file), as a request carries it.\n *\n * `next(e)` resolves to `{ text }`; `{ text: null }` leaves it out. The\n * answer holds per attachment for the process (asked again on resume or\n * `$.ui.invalidate`); the transcript keeps the engine's record.\n *\n * @example\n * on(\"prompt.attachment\", { type: \"todo_reminder\" }, () => ({ text: null }))\n */\n 'prompt.attachment': PromptAttachmentInput;\n /**\n * Fires once per path a prompt names after an `@`, a directory aside,\n * before the engine reads it; `next(e)` reads it and resolves `{ type }`.\n *\n * No `tool.call` is raised for this read. Add `context` to what `next`\n * gave, read another `path` with `next({ ...e, path })`, or answer\n * `{ deny: reason }` so nothing is read.\n *\n * @remarks A guard that fails is skipped and the file is read, so give it\n * `.catch(($, e, next) => next.called ? next(e) : { deny: \"no\" })`.\n * @example\n * on(\"prompt.mention\", { path: /\\.env$/ }, () => ({ deny: \"a secret\" }))\n */\n 'prompt.mention': PromptMentionInput;\n /**\n * Fires when the engine first renders the tool's schema in a session;\n * `next(e)` resolves to `{ description, isDeferred? }`.\n *\n * An MCP tool behind ToolSearch fires twice: its short text, then the one\n * loaded. Cached until `$.ui.invalidate(\"tool.describe\")`: a changed answer\n * for a tool a thread has sent goes out next turn over that text, which\n * loses its thinking and the whole prompt cache.\n *\n * @remarks Twice for an MCP tool behind ToolSearch: its short text, then\n * the one loaded.\n * @remarks An explicit `isDeferred` moves the tool behind ToolSearch (true)\n * or into the prompt's list (false).\n * @example\n * on(\"tool.describe\", { tool: \"Bash\" }, ($, e) => ({ ...e, description }))\n * @example\n * on(\"tool.describe\", { tool: \"Monitor\" }, pin) // {...e, isDeferred: false}\n */\n 'tool.describe': ToolDescribeInput;\n /**\n * Fires when a slash command is about to run (`/name args` typed, or a\n * plugin's `$.command.run`); `next(e)` resolves to `{ text }`, its output.\n *\n * Core is the engine's command (a registered one has none). Rewrite `args`\n * with `next`, or return `{ text }` without it to answer in its place; one\n * after `next` replaces a printed output, not a panel or prompt it opened.\n *\n * @remarks A guard that fails is skipped and the command runs, so give it\n * `.catch(($, e, next) => next.called ? next(e) : { text: \"no\" })`.\n * @example\n * on(\"command.run\", { command: \"hello\" }, () => ({ text: \"hello\" }))\n */\n 'command.run': CommandRunInput;\n /**\n * Fires once per command, when the engine lists it for the typeahead and\n * `/help`; `next(e)` resolves to `{ description, argumentHint, isHidden }`.\n *\n * Listed answers are cached for the session until\n * `$.ui.invalidate(\"command.describe\")`. A hook that fails passes it\n * through.\n *\n * @example\n * on(\"command.describe\", ($, e, next) => next({ ...e, isHidden: true }))\n */\n 'command.describe': CommandDescribeInput;\n /**\n * Fires when a `/config` row is about to change, from the menu or a\n * plugin's `$.config.set`; `next(e)` resolves to `{ value }` once written.\n *\n * Return `{ deny: reason }` to leave the row as it is (the menu says why),\n * or `next({ ...e, value })` to clamp it; a value of the wrong kind for\n * the row is refused. A row a trusted source owns is core's to refuse.\n *\n * @remarks A guard that fails is skipped and the row is written, so give\n * it `.catch(($, e, next) => next.called ? next(e) : { deny: \"no\" })`.\n * @example\n * on(\"config.set\", { key: \"theme\" }, () => ({ deny: \"the theme stays\" }))\n */\n 'config.set': ConfigSetInput;\n /**\n * Fires once per `/config` row, when the menu lists it and for\n * `$.config.list`; `next(e)` resolves to `{ label, description, isHidden }`.\n *\n * Relabel, re-describe or hide with `next({ ...e, isHidden: true })`; the\n * answers are cached until `$.ui.invalidate(\"config.describe\")` or the\n * loaded plugins change. A hook that fails passes the row through.\n *\n * @example\n * on(\"config.describe\", { key: \"tips\" }, hide) // answers isHidden: true\n */\n 'config.describe': ConfigDescribeInput;\n /**\n * Fires when a record is about to be logged to the destination `e.to`\n * names: a built-in's `$.telemetry.log`, or the engine's own events.\n *\n * `e.to` is pinned: a hook rewrites what the record carries, never where\n * it goes. `next(e)` resolves `{ value: undefined }`; `{ deny }` rejects the\n * caller. Beneath the hooks the engine exports its own collector records.\n *\n * @example\n * on(\"telemetry.log\", { to: \"collector\" }, ($, e, next) => next(e))\n */\n 'telemetry.log': TelemetryLogInput;\n /**\n * Fires when one use of a feature is marked (`$.telemetry.mark`), as the\n * CLI's own feature events mark one; always for `anthropic`, no `to`.\n *\n * `next(e)` resolves `{ value: undefined }`; `{ deny }` rejects the caller.\n * The engine does nothing with a mark: the built-ins hooked here do.\n *\n * @example\n * on(\"telemetry.mark\", { kind: \"bad\" }, ($, e, next) => next(e))\n */\n 'telemetry.mark': TelemetryMarkInput;\n /**\n * Fires when the engine expands a skill's prompt for the model (`/name`,\n * the Skill tool, a preload); `next(e)` resolves to `{ text }` as computed.\n *\n * Return `{ text }` with the text the model reads instead. A hook that\n * fails passes it through.\n *\n * @example\n * on(\"skill.prompt\", { skill: \"commit\" }, () => ({ text: \"A haiku.\" }))\n */\n 'skill.prompt': SkillPromptInput;\n /**\n * Fires when the engine composes a git text the model is to write (`kind`:\n * `commit`, `pr`, `exemption`, `remedy`); `next(e)` resolves to `{ text }`.\n *\n * Return `{ text }` with the text the model reads instead. A hook that\n * fails passes it through.\n *\n * @example\n * on(\"attribution.text\", { kind: \"commit\" }, () => ({ text: \"\" }))\n */\n 'attribution.text': AttributionTextInput;\n /**\n * Fires once per process for each loaded plugin, before the first prompt,\n * then once per fresh load of one (never `/clear`); `next(e)` is `{ cwd }`.\n *\n * Observe. The first is awaited: a `$.tool.register` is listed by turn one.\n * A later one runs its hooks alone: an enable, a worker respawn, or a reload\n * (changed modules only; all if one hooks `engine.create`/`plugin.register`).\n *\n * @example\n * on(\"session.start\", ($, e, next) => $.tool.register(t).then(() => next(e)))\n */\n 'session.start': SessionStartInput;\n /**\n * Fires when a delivery reaches the session, before it is queued: a relay's\n * event, a peer's message, a Remote Control prompt, room events; `{ text }`.\n *\n * Rewrite with `next({ ...e, text })`, or return `{ consumed: reason }` to\n * take it: nothing is queued, shown or read by the model. `origin`,\n * `event` and `agentId` pass on as received; `session.send` is its dual.\n *\n * @example\n * on(\"session.receive\", { origin: \"peer\" }, () => ({ consumed: \"muted\" }))\n */\n 'session.receive': SessionReceiveInput;\n /**\n * Fires once per row a conversation of this session keeps (a prompt, a\n * response block, a tool result, a notice), before it is stored.\n *\n * `next({ ...e, message })` rewrites `content`: stored and sent after. The\n * screen, an SDK stream or Remote Control may show the row just before its\n * rewrite; the model and the transcript file never read that form.\n *\n * @example\n * on(\"session.append\", { door: \"tool-result\" }, ($, e, n) => n(scrub(e)))\n */\n 'session.append': SessionAppendInput;\n /**\n * Fires when a plain-text message is about to leave this conversation for\n * another agent or session (the SendMessage tool, or `$.session.send`).\n *\n * `e.origin` says who sends, `e.agentId` which loop. Rewrite `text` or\n * readdress `to` with `next` (a new `to` is judged again); `{ isDelivered:\n * false, reason }` without `next` refuses it. `next(e)` resolves queued.\n *\n * @example\n * on(\"session.send\", ($, e, next) => next({ ...e, text: redact(e.text) }))\n */\n 'session.send': SessionSendInput;\n /**\n * Fires when the conversation is about to be compacted (`/compact`, the\n * threshold, a plugin, or ahead of time); `next(e)` resolves `{ messages }`.\n *\n * Rewrite `instructions` or `messages` on the way down, the messages on\n * the way up, or answer `{ messages }` of your own; `{ skip: reason }`\n * leaves the conversation as it is. `trigger` passes on as received.\n *\n * @example\n * on(\"session.compact\", { trigger: \"precompute\" }, () => ({ skip: \"off\" }))\n */\n 'session.compact': SessionCompactInput;\n /**\n * Fires when a remote client joins the session's roster of attached\n * surfaces: it said so (ui_attach), or it first asked to draw.\n *\n * Observe (a phone joined: draw the lobby); `next(e)` resolves to\n * `{ clientId }`, a different return changes nothing. `$.session.surfaces()`\n * reads the roster; a render hook still reads `e.surface` per ask.\n *\n * @example\n * on(\"session.attach\", { surface: \"mobile\" }, ($, e, next) => next(e))\n */\n 'session.attach': SessionAttachInput;\n /**\n * Fires when a client leaves the roster: it detached, or the session ended\n * with it attached (`e.reason`). Observe; `next(e)` echoes `{ clientId }`.\n *\n * With reason `end` it runs inside `session.end`'s one short bound: there\n * `next.budget` reads that bound and `next.signal` aborts at it.\n */\n 'session.detach': SessionDetachInput;\n /**\n * Fires when the engine measures the session and a unit moved: after each\n * main-thread turn, and when a rate-limit window moves a whole point.\n *\n * Observe; `next(e)` echoes `{ changed }`. `$.session.usage()`'s figures,\n * pushed, not polled: compare them with your own threshold here, call the\n * op for the breakdown. One at a time, a burst folding into one more.\n *\n * @example\n * on(\"session.measure\", ($, e, next) => (toastPast90(e.rateLimits), next(e)))\n */\n 'session.measure': SessionMeasureInput;\n /**\n * Fires once when the session ends (exit, /clear, resume, logout, signal, a\n * `-p` run done), after its SessionEnd settings hooks; `e.reason` says which.\n *\n * `next(e)` runs the engine's end step, `{ sessionId }`; `e.resume.id` is\n * `--resume`'s. Exits stay fast whatever is loaded: the whole chain shares\n * one short wall-clock bound, which `next.budget` reads (SessionEndInput).\n *\n * @example\n * on(\"session.end\", async ($, e, next) => (await save(next.budget), next(e)))\n */\n 'session.end': SessionEndInput;\n /**\n * Fires once per hooks module about to join the chain, at load (the set\n * folded and built, nothing swapped in) and at reload; core allows.\n *\n * Return `{ refuse: reason }` and it never joins: no hook, no noun, no tool\n * of it; the debug log names who refused. Its judges, `$` whole, are the\n * plugins admitted before it and the binary's; judge by `tier` and `uses`.\n *\n * @remarks A judge that fails is skipped and the module joins, so give it\n * `.catch(($, e, next) => next.called ? next(e) : { refuse: \"no\" })`.\n * @example\n * on(\"plugin.register\", { tier: \"user\" }, () => ({ refuse: \"managed only\" }))\n */\n 'plugin.register': PluginRegisterInput;\n /**\n * Fires when a model turn begins, main's or a subagent's (`e.agentId`),\n * before its first model call; `next(e)` resolves to `{ turnId }`.\n *\n * Observe: a different return changes nothing. For the main loop alone,\n * return `next(e)` first when `e.agentId !== undefined`. An agent's start\n * skips the hooks its spawn was nested in, as its `turn.step`s do.\n */\n 'turn.start': TurnStartInput;\n /**\n * Fires when the engine is about to send a model request of a turn, main's\n * or a subagent's (`e.agentId`); `next(e)` resolves to the whole response.\n *\n * `next({ ...e, model })` or `effort` sends another; the turn, the index and\n * the message count are pinned. An answer without `next` sends no request.\n * It streams (StreamNext): the hook's budget counts its own code alone.\n */\n 'turn.step': TurnStepInput;\n /**\n * Fires when a model turn has ended, at the point its duration is reported;\n * `next(e)` resolves to `{ text }`, the answer. `e.reason` says why.\n *\n * Return `{ text }` with a different text to show it beneath the answer (a\n * synopsis, a TL;DR line); the transcript's record is never rewritten. A\n * hook that fails leaves the answer as it was.\n *\n * @remarks Every hook hears an agent's end (`e.agentId`), the spawner's\n * too; a hook that heard the turn's start hears its end after it.\n */\n 'turn.complete': TurnCompleteInput;\n /**\n * Runs while `$` is being built, once per load or reload of this plugin\n * and before any other hook of it; `next(e)` resolves to `$` built so far.\n *\n * A step may ADD nouns and, outside `user`, WITHHOLD them (leave one out, or\n * return without `next`). It fails, and its plugin unloads, when it REPLACES\n * another's; in `user`, also past its own stub, or adding a seated name.\n */\n 'engine.create': EngineCreateInput;\n };"},{"name":"EngineInterface","kind":"interface","line":4720,"doc":{"desc":["`$`, the first parameter of every hook. Frozen; core's interface plus","every noun the plugins' `engine.create` steps added.","","Flat, `.`; it does not carry `on`, since registration happens","before `$` exists. An interface so a plugin types the noun it provides by","declaration merging, the way a jQuery plugin types `$.fn`."],"params":[],"example":["declare module \"claude-code\" { interface EngineInterface { voice: Voice } }"],"returns":[]},"text":" export interface EngineInterface extends CoreEngineInterface {\n }"},{"name":"EngineInterfaceBuilt","kind":"type","line":4731,"doc":{"desc":["What `next(e)` resolves to at `engine.create`: `$` as the steps beneath","built it, typed as `$` is, open to nouns no declaration names yet.","","A withheld noun is on it as a stub (a step inside withheld it, or the","last fold did and this is a reload), and the host refuses an op on one a","step outside withholds later; a typed module bootstraps at load on it."],"params":[],"example":[],"returns":[]},"text":" export type EngineInterfaceBuilt = EngineInterface & {\n readonly [noun: string]: unknown;\n };"},{"name":"EngineResultOf","kind":"type","line":4738,"doc":{"desc":["The engine's events' results."],"params":[],"example":[],"returns":[]},"text":" export type EngineResultOf = {\n /**\n * `{ result, context? }`, `{ deny }`, or core's `{ ref, result }`.\n */\n 'tool.call': ToolCallResult;\n /**\n * `{ decision, reason?, rule?, hook?, setting?, plugin?, ceiling? }`.\n */\n 'tool.check': ToolCheckResult;\n /**\n * The tree to draw; `{ type: \"engine\", ref }` is core's own drawing.\n */\n 'ui.render': RenderElement;\n /**\n * The surface's element table (Elements[e.surface]): constructors from props\n * to a RenderElement.\n */\n 'ui.resolve': ElementTable;\n /**\n * `{ element }`: the element whose handler the press reached.\n */\n 'ui.press': UiPressResult;\n /**\n * `{ element, value }`: the field whose handler the input reached, and\n * the text it received.\n */\n 'ui.input': UiInputResult;\n /**\n * `{ element, value }`: the picker whose handler the pick reached, and\n * the value it received.\n */\n 'ui.select': UiSelectResult;\n /**\n * `{ props? }`: the posting instance's next props, when a hook hands some.\n */\n 'ui.message': UiMessageResult;\n /**\n * `{}`: the fault was heard.\n */\n 'ui.fault': UiFaultResult;\n /**\n * `{}` once the window moved, or `{ deny }`.\n */\n 'ui.scroll': UiScrollResult;\n /**\n * `{}` once the ring moved, or `{ deny }`.\n */\n 'ui.focus': UiFocusResult;\n /**\n * `{ isOffered }`.\n */\n 'agent.offer': AgentOfferResult;\n /**\n * `{ model }` or `{ deny }`.\n */\n 'agent.spawn': AgentSpawnResult;\n /**\n * `{ text, context? }` or `{ drop }`.\n */\n 'prompt.submit': PromptSubmitResult;\n /**\n * `{ isFilled }`.\n */\n 'prompt.fill': PromptFillResult;\n /**\n * `{ isShown }`.\n */\n 'prompt.suggest': PromptSuggestResult;\n /**\n * `{ text, cursor }`, the box the editor shows next.\n */\n 'prompt.edit': PromptEditResult;\n /**\n * `{ text }`.\n */\n 'prompt.change': PromptChangeResult;\n /**\n * `{ suggestions }`, the rows the plugins add to the typeahead.\n */\n 'prompt.autocomplete': PromptAutocompleteResult;\n /**\n * `{ text }` (null leaves the section out).\n */\n 'prompt.section': PromptSectionResult;\n /**\n * `{ blocks }` (a block left out is not sent).\n */\n 'prompt.context': PromptContextResult;\n /**\n * `{ sections }`, every `shared` one ahead of every `session` one (a\n * section left out is not sent).\n */\n 'prompt.compose': PromptComposeResult;\n /**\n * `{ text }` (null leaves the attachment out).\n */\n 'prompt.attachment': PromptAttachmentResult;\n /**\n * `{ type, context? }` (null when nothing was attached) or `{ deny }`.\n */\n 'prompt.mention': PromptMentionResult;\n /**\n * `{ description, isDeferred? }`.\n */\n 'tool.describe': ToolDescribeResult;\n /**\n * `{ text }` (the command's output, when it printed one).\n */\n 'command.run': CommandRunResult;\n /**\n * `{ description, argumentHint, isHidden }`.\n */\n 'command.describe': CommandDescribeResult;\n /**\n * `{ value }` once written, or `{ deny }`.\n */\n 'config.set': ConfigSetResult;\n /**\n * `{ label, description, isHidden }`.\n */\n 'config.describe': ConfigDescribeResult;\n /**\n * `{ value: undefined }`, or `{ deny }`.\n */\n 'telemetry.log': TelemetryLogResult;\n /**\n * `{ value: undefined }`, or `{ deny }`.\n */\n 'telemetry.mark': TelemetryMarkResult;\n /**\n * `{ text }`.\n */\n 'skill.prompt': SkillPromptResult;\n /**\n * `{ text }`.\n */\n 'attribution.text': AttributionTextResult;\n /**\n * `{ cwd }`.\n */\n 'session.start': SessionStartResult;\n /**\n * `{ text }`, or `{ consumed }`.\n */\n 'session.receive': SessionReceiveResult;\n /**\n * `{ message, uuid }`, the row as stored.\n */\n 'session.append': SessionAppendResult;\n /**\n * `{ isDelivered: true }`, or `{ isDelivered: false, reason }`.\n */\n 'session.send': SessionSendResult;\n /**\n * `{ messages, tokensBefore?, tokensAfter? }`, or `{ skip }`.\n */\n 'session.compact': SessionCompactResult;\n /**\n * `{ clientId }`.\n */\n 'session.attach': SessionAttachResult;\n /**\n * `{ clientId }`.\n */\n 'session.detach': SessionDetachResult;\n /**\n * `{ changed }`.\n */\n 'session.measure': SessionMeasureResult;\n /**\n * `{ sessionId }`.\n */\n 'session.end': SessionEndResult;\n /**\n * `{ allow: true }`, or `{ refuse }`.\n */\n 'plugin.register': PluginRegisterResult;\n /**\n * `{ turnId }`.\n */\n 'turn.start': TurnStartResult;\n /**\n * The response: `{ turnId, index, answer, toolUses, stopReason, usage }`,\n * and `serverToolUses` when the API ran tools of its own in the request.\n */\n 'turn.step': TurnStepResult;\n /**\n * `{ text }`.\n */\n 'turn.complete': TurnCompleteResult;\n /**\n * `$` as built so far, with this plugin's interface added and any it\n * withheld left out; `next(e)` resolves to EngineInterfaceBuilt.\n */\n 'engine.create': EngineCreateResult;\n };"},{"name":"EnvSetResult","kind":"type","line":4939,"doc":{"desc":["What `$.env.set` resolves to and what an `env.set` hook's `{ value }`","holds: `{}` once the variable is set or unset, or why it was not."],"params":[],"example":[],"returns":[]},"text":" type EnvSetResult = {\n /**\n * Absent when the write was made; else why not, in one line.\n *\n * In a session that takes its settings from its organization, the engine\n * holds a write a plugin that is not built in stands behind where a\n * person's own settings file could not set the variable there.\n *\n * @remarks The engine's hold resolves; a hook's own `{ deny }` rejects the\n * caller, and one given after `next(e)` was answered fails the hook: deny\n * in its place. A hook above may answer another `{ value }`: no write.\n */\n deny?: string;\n };"},{"name":"EventCalls","kind":"type","line":4962,"doc":{"desc":["The engine's own events as calls on `$`, one signature each:","`$..(input)` resolves to its result, or to its stream.","","The engine raises its events through these same calls; a plugin's call","runs the same chain with the calling hook alone skipped. `input` may leave","out what the engine fills (`tool_use_id`, the parent agent)."],"params":[],"example":[],"returns":[]},"text":" export type EventCalls = {\n tool: {\n call: ToolCallOverloads;\n check: (input: ToolCheckArgs) => Promise;\n describe: (input: ToolDescribeInput) => Promise;\n };\n command: {\n run: (input: CommandRunArgs) => Promise;\n describe: (input: CommandDescribeInput) => Promise;\n };\n config: {\n set: (input: ConfigSetArgs) => Promise;\n describe: (input: ConfigDescribeInput) => Promise;\n };\n prompt: {\n submit: (input: PromptSubmitArgs) => Promise;\n fill: (input: PromptFillArgs) => Promise;\n suggest: (input: PromptSuggestArgs) => Promise;\n section: (input: PromptSectionInput) => Promise;\n context: (input: PromptContextInput) => Promise;\n attachment: (input: PromptAttachmentInput) => Promise;\n mention: (input: PromptMentionInput) => Promise;\n compose: (input?: PromptComposeArgs) => Promise;\n };\n skill: {\n prompt: (input: SkillPromptArgs) => Promise;\n };\n attribution: {\n text: (input: AttributionTextInput) => Promise;\n };\n agent: {\n offer: (input: AgentOfferInput) => Promise;\n spawn: (input: AgentSpawnArgs) => Promise;\n };\n session: {\n start: (input: SessionStartInput) => Promise;\n receive: (input: SessionReceiveInput) => Promise;\n append: (input: SessionAppendInput) => Promise;\n send: (input: SessionSendArgs) => Promise;\n compact: (input?: SessionCompactArgs) => Promise;\n attach: (input: SessionAttachInput) => Promise;\n detach: (input: SessionDetachInput) => Promise;\n measure: (input: SessionMeasureInput) => Promise;\n end: (input: SessionEndInput) => Promise;\n };\n telemetry: {\n log: (input: TelemetryLogArgs) => Promise;\n mark: (input: TelemetryMarkInput) => Promise;\n };\n turn: {\n start: (input: TurnStartInput) => Promise;\n step: (input: TurnStepInput) => HookStream;\n complete: (input: TurnCompleteInput) => Promise;\n };\n ui: {\n render: (input: RenderInput) => Promise;\n resolve: (e: E) => Elements[E['surface']];\n scroll: (input: UiScrollArgs) => Promise;\n focus: (input: UiFocusArgs) => Promise;\n };\n };"},{"name":"EventName","kind":"type","line":5028,"doc":{"desc":["The name of an event: a key of EventOf, the engine's own (CoreEventName)","and the declared plugin nouns' (NounEventName)."],"params":[],"example":[],"returns":[]},"text":" export type EventName = keyof EventOf;"},{"name":"EventOf","kind":"type","line":5038,"doc":{"desc":["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.","","The engine's own events (CoreEventOf: a plugin's `$.fs.write(...)` is","a dispatch the hooks above it see) and the methods of the plugin nouns","declared on EngineInterface (NounEventOf)."],"params":[],"example":[],"returns":[]},"text":" export type EventOf = CoreEventOf & NounEventOf;"},{"name":"EventResult","kind":"type","line":5044,"doc":{"desc":["The result of event `N`: what its hooks return and what their `next(e)`","resolves to."],"params":[],"example":[],"returns":[]},"text":" export type EventResult = ResultOf[N];"},{"name":"Events","kind":"type","line":5061,"doc":{"desc":["The hook signature of each event, `($, e, next)`, as one mapped type over","EventOf; a streaming event's is the generator form (StreamHook).","","With one handler type per event, `Events[E]` for a generic E would be a","union; as one mapped type it stays a single function type the engine","calls without a cast (TS 4.6 correlated unions)."],"params":[["$","the engine interface, frozen, the same object at every invocation; at `engine.create` the empty table, since `$` exists after the fold"],["e","the event's argument, frozen to every depth (`e.command = \"ls\"` is a type error and throws); a rewrite is a copy passed to `next`"],["next","the rest of the chain; a chain a hook raises through `$` skips this hook and runs every other, its plugin's others too"]],"example":[],"returns":[]},"text":" export type Events = {\n [E in keyof EventOf]: E extends StreamingEventName ? StreamHook : ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen>, next: Next) => EventResult | Promise>;\n };"},{"name":"ExitReason","kind":"type","line":5065,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type ExitReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'other';"},{"name":"FileChangedHookInput","kind":"type","line":5067,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type FileChangedHookInput = BaseHookInput & {\n hook_event_name: 'FileChanged';\n file_path: string;\n event: 'change' | 'add' | 'unlink';\n };"},{"name":"Frozen","kind":"type","line":5080,"doc":{"desc":["`T` with every property read-only to every depth, arrays and tuples kept","as declared: how a hook's `e` is typed.","","`e.command = 'x'` is a type error; `next({ ...e, command: 'x' })` compiles.","A string is kept as typed, so a union that names some strings keeps them."],"params":[],"example":[],"returns":[]},"text":" export type Frozen = T extends string | ((...args: never[]) => unknown) ? T : T extends readonly unknown[] ? {\n [K in keyof T]: Frozen;\n } : T extends object ? {\n readonly [K in keyof T]: Frozen;\n } : T;"},{"name":"FsAncestor","kind":"type","line":5090,"doc":{"desc":["One file `$.fs.ancestors` found: the directory it stands in, the name it","was asked for by, and its text as the engine's memory loader reads it."],"params":[],"example":[],"returns":[]},"text":" export type FsAncestor = {\n /**\n * The directory the file stands in, absolute.\n */\n dir: string;\n /**\n * The spelling the caller asked for it by.\n */\n name: string;\n /**\n * The file's text, with what its `@include`s bring after it.\n */\n content: string;\n /**\n * The file and then each file its `@` imports brought, in load order,\n * path and text apiece; `content` is these texts joined.\n */\n parts: readonly FsAncestorPart[];\n };"},{"name":"FsAncestorPart","kind":"type","line":5113,"doc":{"desc":["One file of an ancestor entry: the file itself or one it imported."],"params":[],"example":[],"returns":[]},"text":" export type FsAncestorPart = {\n /**\n * The file's path, absolute.\n */\n path: string;\n /**\n * Its text as the engine's memory loader reads it.\n */\n content: string;\n };"},{"name":"FsAncestorsRequest","kind":"type","line":5132,"doc":{"desc":["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.","","Where a rule or a hold confines the session's reads, a file is found","only where every name its path goes by may be read; under a hold a","folder above the working directory gives only instruction files of its own."],"params":[],"example":[],"returns":[]},"text":" export type FsAncestorsRequest = {\n /**\n * Relative `.md` file names, each looked for in every directory.\n */\n names: readonly string[];\n /**\n * The file the walk goes on down to the directory of, relative to the\n * working directory or absolute; absent, it ends at the working directory.\n *\n * Without `below`, a plain name or one under `.claude`, in the working\n * directory or above it, is judged as the engine's start-up load is; any\n * other file by the main session, and with none bound the call rejects.\n */\n of?: string;\n /**\n * The directory the walk starts beneath, relative to the working directory\n * or absolute; absent, the walk starts at the filesystem root.\n *\n * Only directories strictly inside it are read, each file as the main\n * session's rules on reads judge it, as the engine reads a nested\n * CLAUDE.md; a file not inside it finds nothing.\n */\n below?: string;\n };"},{"name":"FsBytes","kind":"type","line":5161,"doc":{"desc":["What `$.fs.read(path, { as: \"bytes\" })` resolves with: the file's bytes,","base64, since only plain data crosses into a plugin's environment."],"params":[],"example":[],"returns":[]},"text":" export type FsBytes = {\n /**\n * The file's content, standard padded base64;\n * `Uint8Array.fromBase64(base64)` gives the bytes back.\n */\n base64: string;\n };"},{"name":"FsEntry","kind":"type","line":5172,"doc":{"desc":["One entry of `$.fs.list`: the entry itself, a link not followed."],"params":[],"example":[],"returns":[]},"text":" export type FsEntry = {\n /**\n * The entry's name (no directory part).\n */\n name: string;\n /**\n * `file`, `dir`, or `other`, of the entry itself: a symbolic link is\n * `other` (`$.fs.stat` says what it leads to, and with `resolve` where).\n */\n kind: 'file' | 'dir' | 'other';\n /**\n * Bytes, for a file.\n */\n size: number;\n /**\n * Last modification, milliseconds since the epoch, for a file, as\n * `$.fs.stat` spells it; 0 for a directory, a link or any other kind.\n *\n * The listing reads a regular file's size and time in its one call and\n * looks no other entry up: `$.fs.stat` answers a directory's.\n *\n * @example\n * const newest = [...entries].sort((a, b) => b.mtimeMs - a.mtimeMs)[0]\n */\n mtimeMs: number;\n /**\n * True when the entry is a symbolic link.\n */\n isLink: boolean;\n };"},{"name":"FsReadAs","kind":"type","line":5206,"doc":{"desc":["How `$.fs.read` answers: `text` (UTF-8, the default) or `bytes` (base64)."],"params":[],"example":[],"returns":[]},"text":" export type FsReadAs = 'text' | 'bytes';"},{"name":"FsReadBytesOptions","kind":"type","line":5212,"doc":{"desc":["The options of `$.fs.read` that ask for the bytes: the call answers","`{ base64 }`."],"params":[],"example":[],"returns":[]},"text":" export type FsReadBytesOptions = {\n /**\n * `bytes`.\n */\n as: 'bytes';\n };"},{"name":"FsReadCall","kind":"type","line":5223,"doc":{"desc":["`$.fs.read`: the file's text, or with `{ as: \"bytes\" }` its bytes as","`{ base64 }`."],"params":[],"example":[],"returns":[]},"text":" export type FsReadCall = {\n (path: string): Promise;\n (path: string, options: FsReadBytesOptions): Promise;\n (path: string, options: FsReadOptions): Promise;\n };"},{"name":"FsReadOptions","kind":"type","line":5232,"doc":{"desc":["The options of `$.fs.read`."],"params":[],"example":[],"returns":[]},"text":" export type FsReadOptions = {\n /**\n * `bytes` answers `{ base64 }` for a binary file; `text` (the default) the\n * file's text.\n */\n as: FsReadAs;\n };"},{"name":"FsStat","kind":"type","line":5244,"doc":{"desc":["What `$.fs.stat` resolves with: what the path leads to, whether the path","itself is a symbolic link, and where it lands when asked."],"params":[],"example":[],"returns":[]},"text":" export type FsStat = {\n /**\n * `file`, `dir`, or `other`, of what the path leads to: a link is\n * followed, and one that leads nowhere is `other`.\n */\n kind: 'file' | 'dir' | 'other';\n /**\n * Bytes, for a file.\n */\n size: number;\n /**\n * Last modification, milliseconds since the epoch.\n */\n mtimeMs: number;\n /**\n * True when the path itself is a symbolic link; `kind`, `size` and\n * `mtimeMs` then describe what it points at, or the link when that is gone.\n */\n isLink: boolean;\n /**\n * Where the path landed when asked with `{ resolve: true }`: absolute,\n * every symbolic link followed, `.` and `..` folded; else absent.\n *\n * Absent too when the path leads nowhere or a hook above withheld it, so\n * a guard denies without it; and a hard link, a volume or file-id spelling\n * (macOS `/.vol/`) or a case alias keeps its own spelling, `isLink` false.\n *\n * @remarks a deny-list on spellings is thus best effort; an allow-list on\n * `realPath` under a root resolved the same way is the robust guard.\n */\n realPath?: string;\n };"},{"name":"FsStatOptions","kind":"type","line":5280,"doc":{"desc":["The options of `$.fs.stat`."],"params":[],"example":[],"returns":[]},"text":" export type FsStatOptions = {\n /**\n * True to resolve where the path lands as well.\n *\n * The answer then carries `realPath` when the path leads somewhere, at\n * the cost of one more file system call: where it landed then, not a hold\n * on what a tool opens afterwards.\n */\n resolve: boolean;\n };"},{"name":"Glob","kind":"type","line":5298,"doc":{"desc":["Every event (`*`), or every event under a namespace (`classic.*`: each","one whose name starts with `classic.`).","","But a telemetry event, which is hooked by name (`telemetry.log`, or","`telemetry.*` for all): `*` does not select one for an installed plugin."],"params":[],"example":[],"returns":[]},"text":" export type Glob = '*' | `${Namespace}.*`;"},{"name":"GlobHook","kind":"type","line":5308,"doc":{"desc":["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.","","`next.event` says which event a run is; `next.is(pattern, e)` narrows `e`","to one of them. At `engine.create` (a negation may select it) `$` is the","empty table and the hook observes the fold, as a `*` hook does."],"params":[],"example":[],"returns":[]},"text":" export type GlobHook

> = ($: EngineInterface, e: Frozen>, next: GlobNext

) => EventResult | Promise>;"},{"name":"GlobNext","kind":"type","line":5317,"doc":{"desc":["`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.","","`is` narrows `e` to the selected events its pattern names; `event` is one","of the selected names."],"params":[],"example":[],"returns":[]},"text":" export type GlobNext

> = OrderedOverloads & {\n (e: Args): Promise>;\n /**\n * Continues this dispatch at a tier, as Next's `to` (a managed hook's),\n * over the selected events' union for an `e` not yet narrowed.\n */\n readonly to: (e: Args, tier: TargetTier) => Promise>;\n readonly signal: AbortSignal;\n readonly is: >(pattern: M, e: unknown) => e is Frozen>>>;\n readonly event: N;\n readonly origin: Origin;\n readonly trace: readonly TraceEntry, GlobNextResult>[];\n readonly budget: NextBudget;\n };"},{"name":"GlobNextResult","kind":"type","line":5336,"doc":{"desc":["What `next(e)` resolves to in a glob hook before `e` is narrowed: the","NextResult of each selected event, as a union."],"params":[],"example":[],"returns":[]},"text":" type GlobNextResult = {\n [K in N]: NextResult;\n }[N];"},{"name":"Hook","kind":"type","line":5343,"doc":{"desc":["One hook, `($, e, next)`, on event `E`."],"params":[],"example":[],"returns":[]},"text":" export type Hook = Events[E];"},{"name":"HookBudget","kind":"type","line":5356,"doc":{"desc":["The time bounds every hook runs under, in milliseconds: the engine's own","constants are typed by these members, and `next.budget` reads the live one.","","Each bounds the hook's OWN time: the clock stops while a `next(e)` call or","any `$` call of the hook's is in flight (a `$.clock` wait excepted), so a","slow chain beneath or a minute-long `$.model.complete` costs it nothing."],"params":[],"example":["await $.model.complete(ask) // a minute; next.budget.remainingMs unmoved"],"returns":[]},"text":" export type HookBudget = {\n /**\n * A hook's budget per dispatch, from its call to its return; past it the\n * hook is absent (its `.catch` asked, else `next(e)` run on its behalf).\n *\n * A streaming hook's (an async generator) counts only while its own code\n * runs, never at a `yield` or while it reads beneath: on `turn.step` the\n * sum over the response; on `process.spawn` per piece, anew at each pull.\n */\n readonly ms: 10_000;\n /**\n * A `.catch` handler's grace: a fresh budget from the moment it is called,\n * on the same clock (its `next` replay and its `$` calls are free).\n *\n * Past it the hook is absent as if it had no handler; `next.error.budget`\n * and `next.budget.ms` both read it there. `engine.create` has no budget.\n */\n readonly catchMs: 1_000;\n /**\n * How long a hook may keep running after `next.signal` aborted (the person\n * interrupted, a hook above settled first, its own budget ran out).\n *\n * Past it the hook is reported as lingering; the dispatch had already gone\n * on without it when the signal aborted.\n */\n readonly lingerMs: 5_000;\n };"},{"name":"HookFailure","kind":"type","line":5392,"doc":{"desc":["Why a hook failed, as its `.catch` handler reads it on `next.error`: plain","frozen data.","","`throw`: it threw, returned what the site refuses, or its hooks worker","ended under it, `message` saying what; `timeout`: it outran its budget,","`message` then what its last `next()` rejected with, if it did."],"params":[],"example":[],"returns":[]},"text":" export type HookFailure = {\n readonly kind: 'throw' | 'timeout';\n /**\n * What was thrown or why the worker ended, or for a timeout what the last\n * `next()` rejected with; absent for a timeout with nothing rejected.\n */\n readonly message?: string;\n /**\n * The grace the handler runs under, in milliseconds; past it, the hook is\n * absent as if it had no handler.\n */\n readonly budget: number;\n };"},{"name":"HookFor","kind":"type","line":5414,"doc":{"desc":["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.","","One type, so the two-argument `on` stays ONE generic signature: as an","overload set the language service offers no tool-name completions inside","`e.tool === \"`; as an index into a table TS intersects every argument."],"params":[],"example":[],"returns":[]},"text":" export type HookFor

= P extends '*' ? AnyEventHook : P extends EventName ? Events[P] : GlobHook

;"},{"name":"HookInput","kind":"type","line":5416,"doc":{"desc":[],"params":[],"example":[],"returns":[]},"text":" type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PermissionDeniedHookInput | NotificationHookInput | UserPromptSubmitHookInput | UserPromptExpansionHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | StopFailureHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | PreModelSwitchHookInput | PostModelSwitchHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCreatedHookInput | TaskCompletedHookInput | ElicitationHookInput | ElicitationResultHookInput | ConfigChangeHookInput | InstructionsLoadedHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput | CwdChangedHookInput | FileChangedHookInput | DirectoryAddedHookInput | MessageDisplayHookInput;"},{"name":"HookOf","kind":"type","line":5422,"doc":{"desc":["The hook event `E` takes: an async generator over its chunks for a","streaming event (StreamingEventName), `($, e, next) => result` otherwise."],"params":[],"example":[],"returns":[]},"text":" export type HookOf = Events[E];"},{"name":"HooksModule","kind":"type","line":5428,"doc":{"desc":["What a hooks module exports: `register`, and nothing the loader reads","besides."],"params":[],"example":[],"returns":[]},"text":" export type HooksModule = {\n register: Register;\n };"},{"name":"HookStream","kind":"type","line":5440,"doc":{"desc":["What `next(e)` returns on a streaming event: the stream of everything","beneath, chunk by chunk, whose return value is the result from beneath.","","`yield* next(e)` forwards the chunks and evaluates to that result; a","transforming hook reads `for await (const chunk of stream)` and then","`await stream.result`. Each call runs what is beneath afresh."],"params":[],"example":[],"returns":[]},"text":" export type HookStream = AsyncGenerator & {\n /**\n * Settles with what beneath returned once the stream has been read to\n * its end; rejects if the stream is closed before that.\n */\n readonly result: Promise;\n };"},{"name":"HttpInit","kind":"type","line":5451,"doc":{"desc":["Options of `$.http.fetch`."],"params":[],"example":[],"returns":[]},"text":" export type HttpInit = {\n /**\n * `GET` (default), `POST`, ...\n */\n method?: string;\n /**\n * Request headers.\n */\n headers?: Record;\n /**\n * The request body, as text.\n */\n body?: string;\n /**\n * The handle `$.session.authorize()` answered: the engine sets the\n * session's credential header itself, only for a first-party host.\n *\n * It rides https only. While `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`\n * is set, a request that carries it is refused, whichever plugin asks.\n */\n auth?: string;\n /**\n * The absolute path of a Unix domain socket the request goes over instead\n * of TCP (near 100 B at most): one per session, in a private directory.\n *\n * The URL still gives path, query and Host; redirects stay on it; no proxy;\n * `https:` is TLS verified against the URL's host (always, once `auth`\n * rides), so a credential reaches only its host. No relative path, no NUL.\n *\n * @example\n * await $.http.fetch(url, { socketPath: `${runDirectory}/bridge.sock` })\n */\n socketPath?: string;\n };"},{"name":"HttpResponse","kind":"type","line":5489,"doc":{"desc":["What `$.http.fetch` resolves with."],"params":[],"example":[],"returns":[]},"text":" export type HttpResponse = {\n /**\n * The HTTP status code.\n */\n status: number;\n /**\n * True for a 2xx status.\n */\n ok: boolean;\n /**\n * Response headers, lower-cased names.\n */\n headers: Record;\n /**\n * The body, as text.\n */\n text: string;\n };"},{"name":"ImageBlitArgs","kind":"type","line":5519,"doc":{"desc":["A `$.ui.blit` argument swapping one of the caller's mounted keyed Images","to its next picture; every call sends it, so a stream needs no generation.","","The surface writes them with its frames, some sixty a second: byte and","`file` sources fold to the last per frame; every `shm` source reaches the","terminal (it unlinks each), and is denied while frames are not written."],"params":[],"example":["await $.ui.blit({ requestId: 'browser', key: 'view',"," source: { shm: '/tb-4', format: 'rgb', width: 1280, height: 720 } })"],"returns":[]},"text":" export type ImageBlitArgs = {\n /**\n * The site the Image is drawn in, by the `requestId` this plugin draws it\n * under.\n */\n requestId: string;\n /**\n * The Image's `key` in that drawing.\n */\n key: string;\n /**\n * The next picture (ImageSource): bytes, or a name the terminal reads.\n */\n source: ImageSource;\n /**\n * Refused unless it is the mounted Image's width in cells. Absent, that.\n */\n columns?: number;\n /**\n * Refused unless it is the mounted Image's height in cells. Absent, that.\n */\n rows?: number;\n };"},{"name":"ImageProps","kind":"type","line":5559,"doc":{"desc":["The props of `Image`, the terminal surface's picture leaf: pixels over a","box of cells where the terminal can (kitty and Ghostty, or iTerm2 3.5 and","later for `png` and `rgba` bytes under fullscreen rendering; inside tmux","too, for bytes only, with tmux's `allow-passthrough` and `focus-events`","on), the `alt` elsewhere.","","A leaf: no children, `hover` or `onPress`; the cells are text, so the","picture scrolls and clips as a word does. Drawn again with another `source`","it is replaced in place; keyed, `$.ui.blit` swaps it at the frame rate."],"params":[],"example":["const { bytes } = await $.fs.read('chart.png', { as: 'bytes' })","\"p95\"","\"the"],"returns":[]},"text":" export type ImageProps = {\n /**\n * The element's address within the drawing: what `$.ui.blit` names to swap.\n *\n * Unique among the Images of one tree; absent, only a redraw changes it.\n */\n key?: string;\n /**\n * The picture (ImageSource): `{ png }` or `{ rgba, width, height }` bytes,\n * or `{ file, format }` / `{ shm, format, width, height }` read here.\n */\n source: ImageSource;\n /** How many terminal columns wide, 1 to 255; the picture is scaled to fill\n * the box and the site clips what its body cannot show. */\n columns: number;\n /**\n * How many terminal rows tall, 1 to 255.\n */\n rows: number;\n /**\n * What the picture says, drawn dim in its place where the picture cannot\n * be (and read by a screen reader); required, may be a single space.\n */\n alt: string;\n };"},{"name":"ImageSource","kind":"type","line":5602,"doc":{"desc":["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.","","A name is one another process on this machine wrote; the terminal, running","as the person, opens, reads and decodes it itself, so no pixel crosses `$`","and the engine never touches it. One it will not read (not a regular file,","under `/proc`, `/sys` or `/dev`, gone, across ssh) draws a blank box, its","words in the debug log; it unlinks a shared-memory object once read, so","each frame is a fresh one. A source equal to the last drawn sends nothing;","`generation` makes new content under an unchanged name a new source."],"params":[],"example":["{ rgba: pixels.toBase64(), width: 64, height: 32 }","{ file: '/dev/shm/frame-3.rgba', format: 'rgba', width: 640,"," height: 400 }","{ shm: '/tb-view-2', format: 'rgb', width: 1280, height: 720 }"],"returns":[]},"text":" export type ImageSource = {\n /**\n * A whole PNG file, base64.\n */\n png: string;\n } | {\n /**\n * `width * height` RGBA pixels, 4 bytes each, base64.\n */\n rgba: string;\n /**\n * Pixels per row, 1 to 2048.\n */\n width: number;\n /**\n * Rows of pixels, 1 to 2048.\n */\n height: number;\n } | {\n /**\n * The absolute path of a regular file holding a whole PNG, at most\n * 3072 bytes of path; read by the terminal, left in place.\n */\n file: string;\n /**\n * The file is a whole PNG; the terminal decodes it and sizes it itself.\n */\n format: 'png';\n /**\n * A whole number that changes when the file's content does under the\n * same path, so a redraw reads it again; absent, the path alone tells.\n */\n generation?: number;\n } | {\n /**\n * The absolute path of a regular file of `width * height` raw pixels, at\n * most 3072 bytes of path; read by the terminal, left in place.\n *\n * On Linux a file under `/dev/shm` is memory.\n */\n file: string;\n /**\n * `rgba`, 4 bytes a pixel, or `rgb`, 3.\n */\n format: 'rgba' | 'rgb';\n /**\n * Pixels per row, 1 to 4096.\n */\n width: number;\n /**\n * Rows of pixels, 1 to 4096.\n */\n height: number;\n /**\n * A whole number that changes when the file's content does under the\n * same path, so a redraw reads it again; absent, the path alone tells.\n */\n generation?: number;\n } | {\n /**\n * The name of a POSIX shared-memory object of `width * height` raw\n * pixels: `/` then up to 254 of `A-Z a-z 0-9 . _ -` (macOS takes 30).\n *\n * The terminal unlinks it after reading, so a name feeds one Image\n * drawn once and is never sent again on a redraw; POSIX terminals only.\n */\n shm: string;\n /**\n * `rgba`, 4 bytes a pixel, or `rgb`, 3.\n */\n format: 'rgba' | 'rgb';\n /**\n * Pixels per row, 1 to 4096.\n */\n width: number;\n /**\n * Rows of pixels, 1 to 4096.\n */\n height: number;\n /**\n * A whole number that changes when a fresh object reuses a name, so a\n * redraw reads it again; absent, the name alone tells.\n */\n generation?: number;\n };"},{"name":"ImpossibleKeys","kind":"type","line":5695,"doc":{"desc":["The keys of object pattern `P` that object member `E` cannot satisfy, `D`","levels down; `never` when there is none, which is what keeps the member.","","A key `E` does not have (an open record has every string key), or one","whose value `P` narrows to nothing."],"params":[],"example":[],"returns":[]},"text":" type ImpossibleKeys = {\n [K in keyof P]-?: K extends keyof E ? [NarrowedValue, P[K], D>] extends [never] ? K : never : K;\n }[keyof P];"},{"name":"IndexFree","kind":"type","line":5703,"doc":{"desc":["An object with the declared keys of `T` and no other: its string and","number index signatures are left out. What KnownKeys reads the keys of."],"params":[],"example":[],"returns":[]},"text":" type IndexFree = {\n [K in keyof T as string extends K ? never : number extends K ? never : K]: 0;\n };"},{"name":"InputProps","kind":"type","line":5715,"doc":{"desc":["The props of `Input`, every surface's text field: an address, optional","texts, and the closures a change and a submit run. A leaf.","","One line, or with `rows` several. Focused through the same ring as `Button`","(`abovePrompt:focus`); while it has focus every printable key reaches it","alone and Esc returns them. A change and Enter raise `ui.input`."],"params":[],"example":[],"returns":[]},"text":" export type InputProps = {\n /**\n * The element's address: `e.element` at `ui.input`, what a matcher names.\n */\n key: string;\n /**\n * Text drawn before the field.\n */\n label?: string;\n /**\n * Text drawn dim in an empty field.\n */\n placeholder?: string;\n /**\n * The text the field holds when drawn; the person's typing replaces it\n * until the hook draws another.\n */\n value?: string;\n /**\n * What Enter does, in a word or two, drawn beside the field while it has\n * focus (`send`). Defaults to `submit`.\n */\n submitLabel?: string;\n /**\n * How many lines tall the field is, a whole number of at least 1; from 2\n * it holds several lines, as the DOM's `