surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / mods / types / claude-code.d.ts

GitHub Actions (publish-mods)chore: Update mods/ bf2323b · 10 days ago History

13,440 lines · 505.3 KBRaw

1	// Written by Claude Code 2.1.277.
2	// Claude Code function hooks: the plugin API's TypeScript declarations.
3	//
4	// EARLY ACCESS: this surface may change between releases without notice.
5	// Written by `/plugin-types`; regenerate with that command after an update
6	// rather than editing. The first line names the Claude Code version that
7	// wrote it. TypeScript 5.4 or newer reads it. `claude plugin validate <dir>`
8	// is the other half: it reads a plugin's manifest and its hooks module's
9	// source the way the engine will and reports what the module hooks and
10	// calls and everything the engine would refuse, before any session loads it.
11	//
12	// What is here: the module a hooks module may import types from,
13	// import type { Register, On, EngineInterface } from 'claude-code'
14	// (at run time the import is empty), and the globals a hooks module has:
15	// `h` and `Fragment` (what JSX compiles against), the JSX namespace, and
16	// the environment's web APIs (URL, TextEncoder, AbortController,
17	// crypto.subtle, ...). A hooks module runs in an environment of its own:
18	// no DOM, no Node. The module, and every file it imports from the plugin,
19	// is named .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts or .cts (a file named
20	// otherwise is not loaded) and is an ES module whatever its suffix: there
21	// is no `require`. The elements a render hook draws with (`Box`, `Text`,
22	// `Button`, ...) are not globals: they come from the surface's table,
23	// const { Box, Text } = $.ui.resolve(e)
24	//
25	// Also here: 'claude-code/testing', the kit a plugin's *.test.ts and
26	// *.test.tsx files import under `claude plugin test <dir>`, which runs each
27	// in an environment like the one a plugin's hooks run in (no fs, network or
28	// process), the plugin loaded from the folder by the engine's own host:
29	// `test(name, async ($, on) => { ... })`, where `$` is the engine's own
30	// and the hooks `on` registers sit beneath every plugin; with describe,
31	// expect, tier, and `mock`, whose clock, store and env answer those nouns
32	// beneath the plugins from memory. `$.ui.mount` draws a component through
33	// the plugin on the surface the test names (terminal, desktop, vscode or
34	// mobile: never assumed) and hands back the drawing to read and act on by
35	// key: find an element, press a Button, type into an Input, drive a
36	// `Client`'s module (keys, pointer, posts, its frame clock), each act typed
37	// by that surface's element table, so one test body run over several
38	// surfaces covers the mod's hooks and description on each. It exercises
39	// the mod (its hooks, the tree they return under each surface's rules, its
40	// `Client` modules), never a surface's paint (Ink's, the desktop page's):
41	//
42	// test('notes add up on every surface that takes input', async $ => {
43	// for (const surface of ['terminal', 'desktop'] as const) {
44	// const ui = await $.ui.mount({ plugin: 'notes', surface, ...BAND })
45	// await ui.input({ key: 'new', text: 'milk' })
46	// expect((await ui.find({ key: 'count' }))?.text).toBe('1 note')
47	// await ui.key({ key: 'down', in: 'list' })
48	// await ui.unmount()
49	// }
50	// for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
51	// const ui = await $.ui.mount({ plugin: 'notes', surface, ...HINT })
52	// expect(await ui.find({ type: 'Text', text: /notes/ })).toBeDefined()
53	// await ui.press({ key: 'dismiss' })
54	// }
55	// })
56	//
57	// Typing a plugin against it:
58	// export const register: Register = (on, options) => { ... }
59	// or, in a .js module,
60	// /** @type {import('claude-code').Register} */
61	// export const register = (on, options) => { ... }
62	//
63	// A tsconfig.json (or jsconfig.json) that fits a hooks module:
64	// {
65	// "compilerOptions": {
66	// "target": "es2023", "lib": ["es2023"], "types": [],
67	// "module": "esnext", "moduleResolution": "bundler",
68	// "strict": true, "noUncheckedIndexedAccess": true,
69	// "noEmit": true, "skipLibCheck": true,
70	// "jsx": "react", "jsxFactory": "h", "jsxFragmentFactory": "Fragment"
71	// },
72	// "include": [".claude/types", "hooks", "tests"]
73	// }
74	// ".claude/types" is where /plugin-types writes this file and, beside it,
75	// claude-code-mcp.d.ts and claude-code-plugins.d.ts, the index of the
76	// enabled plugins' type contracts, each copied to claude-code-plugins/
77	// <plugin>.d.ts: what a plugin adds to `$` in engine.create, so a plugin
78	// you depend on is typed with nothing copied (the include above takes the
79	// whole folder). "hooks" is the plugin's hooks/ folder and "tests" its test
80	// files. `lib` names no DOM: the environment has none, and its `Text`
81	// would shadow the element.
82	//
83	// A plugin that adds a noun to `$` ships its own contract: a .d.ts its
84	// plugin.json names as "types", exporting the noun's types at its top level
85	// and declaring the noun on the engine's interface,
86	// export type Topo = { ... }
87	// declare module 'claude-code' {
88	// interface EngineInterface { topo: Topo }
89	// }
90	// with no import or reference, its exported names led by the noun's
91	// PascalCase name; the plugin's own hooks module imports them from it.
92
93	declare module 'claude-code' {
94	/**
95	* What an Agent call a plugin raised (`$.tool.call({ tool: "Agent", ... })`)
96	* answers as `result` once the agent settles; `text` is its final answer.
97	*
98	* A plugin's spawn always runs in the background, so the call resolves with
99	* this record and not the Agent tool's own (BuiltinToolResults), which is
100	* what a model's Agent call carries at `tool.call`.
101	*/
102	export type AgentCallRecord = {
103	/**
104	* The spawned agent's id, as `$.agent.list()` names it.
105	*/
106	agentId: string;
107	/**
108	* The model the agent resolved to, when one is known.
109	*/
110	resolvedModel?: string;
111	};
112
113	/**
114	* One agent loop of this session as `$.agent.list()` returns it: a subagent
115	* or an in-process teammate.
116	*/
117	export type AgentInfo = {
118	/**
119	* The agent's id: the same string its loop's `tool.call` events carry as
120	* `agentId`, and a spawn inside it as `parentAgentId`.
121	*/
122	id: string;
123	/**
124	* Its row's label.
125	*/
126	description: string;
127	/**
128	* The agent definition it runs as (`general-purpose`, `Explore`, ...), or
129	* `teammate` for an in-process teammate.
130	*/
131	type: string;
132	/**
133	* `running`, `completed`, `failed`, `killed`, or another of the engine's task
134	* statuses.
135	*/
136	status: string;
137	/**
138	* The id of the subagent whose loop spawned it; absent when the main loop
139	* did.
140	*/
141	parentId?: string;
142	/**
143	* The plugin whose `$.agent.spawn` (or Agent `$.tool.call`) started it;
144	* absent when the model or the person did.
145	*
146	* The origin axis: which plugin caused it, whichever loop that hook ran in.
147	*/
148	spawnedBy?: string;
149	/**
150	* What SendMessage addresses it by (`Agent({ name })`, or the engine's own
151	* for a background agent), when it has one; not `description` or `type`.
152	*/
153	name?: string;
154	};
155
156	/**
157	* Which model loop an event happened in: the loop's agent id inside a
158	* subagent's or a teammate's loop, absent on the main loop.
159	*
160	* The agent axis, not the origin axis: `next.origin` names the plugin whose
161	* hook frame caused the dispatch (the recursion skip), whichever loop it ran
162	* in; `agentId` names the loop, whoever caused the call.
163	*/
164	export type AgentLoop = {
165	/**
166	* The id of the loop this call runs in: for a subagent or a teammate, the
167	* `id` `$.agent.list()` gives it; absent on the main loop.
168	*
169	* A workflow's agents and the engine's own forks (compaction, memory) carry
170	* ids no list names. Pinned: a different value is refused, one left out is
171	* kept. Which loop, not which plugin caused it (that is `next.origin`).
172	*/
173	agentId?: string;
174	};
175
176	/**
177	* The input of `agent.offer`: one agent type, at the moment the engine
178	* offers it to the model.
179	*
180	* Listed for the model (the agent listing) or named by it at dispatch
181	* (`subagent_type`): the same event at each. Model-facing only: a plugin's
182	* own `$.agent.spawn` of a type is no offer, and `agent.spawn` governs it.
183	*/
184	export type AgentOfferInput = {
185	/**
186	* Which type (`Explore`, `Plan`, a plugin's agent); the key a matcher
187	* narrows on.
188	*/
189	agent: string;
190	/**
191	* Its listing line's text as the definition states it (`whenToUse`).
192	*/
193	description: string;
194	/**
195	* Where the definition came from (`built-in`, `plugin`, a settings
196	* source), so a matcher tells a built-in from a user's agent of its name.
197	*/
198	source: string;
199	/**
200	* Who provides this agent: the plugin and its tier; `{ plugin: "engine",
201	* tier: "core" }` for a built-in. Pinned: a rewrite is refused.
202	*/
203	provider: Origin;
204	};
205
206	/**
207	* What an `agent.offer` hook returns: whether the model is offered the agent
208	* type, in its listing and at dispatch.
209	*/
210	export type AgentOfferResult = {
211	isOffered: boolean;
212	};
213
214	/**
215	* `agent.spawn`'s input as the call takes it: what the Agent tool's caller
216	* says; the engine fills the rest.
217	*
218	* A call's spawn runs in the background: it resolves once the subagent
219	* started, and nothing holds it in the foreground.
220	*/
221	export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' \| 'subagentType' \| 'model' \| 'name' \| 'cwd'>>;
222
223	/**
224	* The input of `agent.spawn`: what the Agent tool decided about the
225	* subagent it is about to start, before its model is resolved.
226	*
227	* A hook rewrites content (prompt, description, subagentType, model,
228	* background, cwd), read back as the tool's parameters; tool_use_id, name,
229	* fork, parentModel, permissionMode, parentAgentId and provider are pinned.
230	*/
231	export type AgentSpawnInput = {
232	/**
233	* The Agent tool call this spawn belongs to (for `$.ui.notice`). Pinned:
234	* the spawn's identity.
235	*/
236	tool_use_id: string;
237	/**
238	* The task the subagent is given: the Agent tool's `prompt` parameter. A
239	* rewrite is the prompt the subagent runs with.
240	*/
241	prompt: string;
242	/**
243	* The Agent tool's short `description` of the task (a few words). A rewrite
244	* is what the task shows as.
245	*/
246	description: string;
247	/**
248	* The resolved agent type (`general-purpose`, `Explore`, a plugin's agent,
249	* `fork`). A rewrite names another agent this call can dispatch, exactly.
250	*
251	* That definition is the one spawned; a name matching none refuses the
252	* spawn, and a fork dispatches no other.
253	*/
254	subagentType: string;
255	/**
256	* Who provides this agent: the plugin and its tier; `{ plugin: "engine",
257	* tier: "core" }` for a built-in. Pinned with the spawn's identity.
258	*/
259	provider: Origin;
260	/**
261	* The Agent tool's `model` parameter as given, an alias (`haiku`) or a
262	* full id; undefined lets the agent's own model, then the parent's, decide.
263	*
264	* Ignored for forks, which always inherit. A hook sets this to pick the
265	* subagent's model.
266	*/
267	model?: string;
268	/**
269	* The parent's effective model, what `inherit` resolves to. Pinned: a fact
270	* of the parent (set `model` to change what the subagent runs on).
271	*/
272	parentModel: string;
273	/**
274	* The id of the loop the spawn happens in (its `tool.call` `agentId`; for a
275	* subagent or teammate its `$.agent.list()` id); absent from main.
276	*
277	* Pinned: a different value is refused, one left out is kept. The agent
278	* axis, not the origin: `next.origin` names the plugin whose hook frame
279	* caused the spawn, this names the model loop it happened in.
280	*/
281	parentAgentId?: string;
282	/**
283	* The parent's permission mode (`default`, `acceptEdits`, `plan`, ...), which
284	* the subagent inherits. Pinned: a fact of the parent.
285	*/
286	permissionMode?: string;
287	/**
288	* True when the subagent will run in the background (or remotely). A
289	* rewrite is read back as the call's `run_in_background`.
290	*
291	* The agent's own definition and remote isolation can still force it on,
292	* and disabled background tasks force it off.
293	*/
294	background: boolean;
295	/**
296	* True for a fork of the parent: it inherits the parent's context and model,
297	* and `model` is ignored. Pinned: the spawn's identity.
298	*/
299	fork: boolean;
300	/**
301	* Given by the call (`Agent({ name })`, addressable by SendMessage);
302	* undefined when unnamed. Pinned: the address the parent routes by.
303	*/
304	name?: string;
305	/**
306	* The directory the subagent runs in when the call set one (`cwd`); undefined
307	* means the parent's. A rewrite is where the subagent runs.
308	*/
309	cwd?: string;
310	};
311
312	/**
313	* What an `agent.spawn` hook returns and what `next(e)` resolves to: the
314	* started subagent's `{ model, agentId }`, or `{ deny: reason }`, refusing it.
315	*
316	* It and `$.agent.spawn(input)` resolve once the subagent started; its answer
317	* is its own `turn.complete`, carrying this `agentId`. Keep the id and set
318	* `got[agentId]` to what waits; a `turn.complete` hook resolves it:
319	*
320	* @example
321	* on("turn.complete", ($, e, next) => (got[e.agentId]?.(e.answer), next(e)))
322	*/
323	export type AgentSpawnResult = {
324	/**
325	* What the subagent runs on: from core the resolved id; from a hook an
326	* alias (`haiku`) or an id.
327	*/
328	model: string;
329	/**
330	* The started subagent's id: the same string its loop's `tool.call`
331	* events carry as `agentId` and `$.agent.list()` lists it by.
332	*
333	* Set by core; a hook that answers without `next` started none.
334	*/
335	agentId?: string;
336	deny?: undefined;
337	} \| {
338	/**
339	* Refuses the spawn, so nothing starts; the model sees the text as the
340	* Agent tool's error.
341	*/
342	deny: string;
343	model?: undefined;
344	agentId?: undefined;
345	};
346
347	/**
348	* What `$.agent.register` takes: an agent type this plugin defines, spelled
349	* as an agent definition in settings JSON is, plus its `name`.
350	*
351	* Every field an agent file or `--agents` entry may carry is here and takes
352	* effect as it does there; the engine validates it with the same schema.
353	*/
354	type AgentSpec = {
355	/**
356	* The type's short name (letters, digits, `_`, `-`; up to 64); the type is
357	* `<plugin>:<name>`, as a plugin's agent file `agents/<name>.md` names one.
358	*/
359	name: string;
360	/**
361	* When to delegate to this agent: the line the model reads in its listing
362	* of agent types, and `agent.offer`'s `description`.
363	*/
364	description: string;
365	/**
366	* The agent's system prompt, whole: it replaces the session's.
367	*/
368	prompt: string;
369	/**
370	* What the agent may call, by tool name (`Read`, `Bash`, `mcp__x__y`); a
371	* call to any other is refused. Left out: every tool the parent has.
372	*/
373	tools?: readonly string[];
374	/**
375	* Tools withheld from the agent, by name, out of whatever `tools` allows.
376	*/
377	disallowedTools?: readonly string[];
378	/**
379	* The agent's model: an alias (`haiku`, `sonnet`, `opus`), a full id, or
380	* `inherit` for the parent's. Left out: the session's subagent default.
381	*/
382	model?: string;
383	/**
384	* The agent's effort: a level (`low`, `medium`, `high`, `xhigh`, `max`)
385	* or an integer budget.
386	*/
387	effort?: string \| number;
388	/**
389	* How the agent's permission asks are decided, a mode: `default`,
390	* `acceptEdits`, `plan`, `auto`, `dontAsk` or `bypassPermissions`.
391	*
392	* Left out: the parent's.
393	*/
394	permissionMode?: string;
395	/**
396	* Servers connected over MCP for the agent's run: a configured server's
397	* name, or `{ "<name>": { command, args } }`, one server's config inline.
398	*/
399	mcpServers?: readonly (string \| Record<string, unknown>)[];
400	/**
401	* Settings hooks in force while the agent runs, in settings.json's `hooks`
402	* shape (`{ PreToolUse: [{ matcher, hooks: [...] }] }`).
403	*/
404	hooks?: Record<string, unknown>;
405	/**
406	* The most turns the agent takes before it stops.
407	*/
408	maxTurns?: number;
409	/**
410	* Preloaded into the agent's context before its first turn: skill names.
411	*/
412	skills?: readonly string[];
413	/**
414	* The agent's first user turn; `{{intent}}` in it takes the spawn's prompt.
415	* Left out: the spawn's prompt is the first turn.
416	*/
417	initialPrompt?: string;
418	/**
419	* A persistent memory the agent keeps between runs, and where: `user`,
420	* `project` or `local`.
421	*/
422	memory?: 'user' \| 'project' \| 'local';
423	/**
424	* Set so that every spawn of the agent runs in the background.
425	*/
426	background?: true;
427	/**
428	* Set so that the agent's context carries no CLAUDE.md block (the person's,
429	* the project's, the rules): it takes what it needs from its prompt.
430	*/
431	omitClaudeMd?: true;
432	/**
433	* Where the agent runs apart from the session: `worktree`, a git worktree
434	* of its own; `remote`, a cloud session where the build allows one.
435	*/
436	isolation?: 'worktree' \| 'remote';
437	};
438
439	/**
440	* The hook `on("*", hook)` takes: it runs on every event, plugin nouns no
441	* declaration names included, so `e` is `unknown` and `next` is StarNext.
442	*
443	* Until `next.is(pattern, e)` narrows `e`, all a hook can do with it is pass
444	* it on, time it, log it, or fail it; once narrowed it is an ordinary hook on
445	* those events.
446	*
447	* @param $ the engine interface; at `engine.create` the empty table, so a hook
448	* that reads `$` tests `next.is("engine.create", e)` first
449	*/
450	export type AnyEventHook = ($: EngineInterface, e: unknown, next: StarNext) => unknown;
451
452	/**
453	* Every key of every variant, index signatures included.
454	*/
455	type AnyKeyOf<I> = I extends unknown ? keyof I : never;
456
457	/**
458	* The argument of event `N`: `e` in its hooks, and what its call takes. For a
459	* union of names, the union of their arguments.
460	*/
461	export type Args<N extends EventName = EventName> = EventOf[N];
462
463	/**
464	* Options of `$.ui.ask`.
465	*/
466	export type AskOptions = {
467	/**
468	* 2-4 option labels; fewer than two are padded with Yes/No; free text is the
469	* dialog's Other.
470	*/
471	options?: readonly string[];
472	/**
473	* A short chip beside the question (`Approach`, 12 characters at most).
474	*/
475	header?: string;
476	/**
477	* Allow several options; the answer comes back comma-joined.
478	*/
479	multiSelect?: true;
480	};
481
482	/**
483	* The input of `attribution.text`: one text the engine asks the model to
484	* write into a commit or a pull request, at the moment it is composed.
485	*
486	* Composed for the Bash description, the commit skills, a PR's body, the
487	* pre-ship mandate and the commit gate's deny: the same event at each.
488	*/
489	export type AttributionTextInput = {
490	/**
491	* Which text (`commit`, `pr`, `exemption`, `remedy`); the key a matcher
492	* narrows on.
493	*/
494	kind: AttributionTextKind;
495	/**
496	* As the engine composed it, the settings applied.
497	*/
498	text: string;
499	};
500
501	/**
502	* Which git text `attribution.text` carries: the commit trailer, the PR
503	* footer, the mandate's or the commit gate's sentence naming the exemption.
504	*/
505	export type AttributionTextKind = 'commit' \| 'pr' \| 'exemption' \| 'remedy';
506
507	/**
508	* What an `attribution.text` hook returns: the text the model reads in
509	* that place.
510	*/
511	export type AttributionTextResult = {
512	text: string;
513	};
514
515	/**
516	* What `$.audio.play` plays: a URL the engine fetches, or the bytes.
517	*/
518	export type AudioClip = {
519	/**
520	* A file of the calling plugin's own, relative to the plugin's
521	* directory (`fx/open.wav`); no `.`, no leading slash.
522	*
523	* The engine resolves it and loads the file from disk.
524	*/
525	asset: string;
526	url?: undefined;
527	base64?: undefined;
528	mime?: undefined;
529	} \| {
530	/**
531	* The clip's URL; the engine fetches it (never the plugin).
532	*/
533	url: string;
534	asset?: undefined;
535	base64?: undefined;
536	mime?: undefined;
537	} \| {
538	/**
539	* The clip's bytes, base64.
540	*/
541	base64: string;
542	/**
543	* What the bytes are (`audio/mpeg`, `audio/wav`).
544	*/
545	mime: string;
546	asset?: undefined;
547	url?: undefined;
548	};
549
550	type BackgroundTaskSummary = {
551	id: string;
552	/**
553	* Friendly task-type label (e.g. 'shell', 'subagent', 'monitor', 'workflow'). Falls back to the raw discriminant for unknown types.
554	*/
555	type: string;
556	status: string;
557	/**
558	* Free-text description. Capped at 1000 chars; clipped values append an in-string "... [+N chars]" marker.
559	*/
560	description: string;
561	/**
562	* Shell command line. Only present for 'shell' tasks. Capped at 1000 chars with the same "... [+N chars]" marker.
563	*/
564	command?: string;
565	/**
566	* Subagent type name. Only present for 'subagent' tasks.
567	*/
568	agent_type?: string;
569	/**
570	* MCP server name. Only present for 'monitor' / 'MCP task' tasks.
571	*/
572	server?: string;
573	/**
574	* MCP tool name. Only present for 'monitor' / 'MCP task' tasks.
575	*/
576	tool?: string;
577	/**
578	* Workflow name. Only present for 'workflow' tasks.
579	*/
580	name?: string;
581	};
582
583	type BaseHookInput = {
584	session_id: string;
585	transcript_path: string;
586	cwd: string;
587	/**
588	* 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.
589	*/
590	prompt_id?: string;
591	permission_mode?: string;
592	/**
593	* 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.
594	*/
595	agent_id?: string;
596	/**
597	* 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).
598	*/
599	agent_type?: string;
600	/**
601	* 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.
602	*/
603	effort?: {
604	/**
605	* 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.
606	*/
607	level: string;
608	};
609	};
610
611	/**
612	* The `Box` props a `hover` may override, none of which moves the Box's
613	* siblings, and `scope`, which names the hover group the Box joins.
614	*
615	* `display` is `"flex"` alone, on a Box drawn `display: "none"`: with a
616	* `scope`, every member of the lit group is revealed, in whichever site it
617	* sits, so a pointer on a glyph in the transcript can swap an entry into a
618	* fixed row of the band, or reveal an absolutely positioned card.
619	* `borderStyle` only restyles a border the Box has; the offsets move a Box
620	* drawn `position: "absolute"`, none in the flow. The surface applies a
621	* hover as the pointer moves, so a reveal that moves what the pointer rests
622	* on is drawn once, not in a loop.
623	*/
624	export type BoxHoverProps = {
625	/**
626	* Names a hover group of this plugin's: every element it draws with the
627	* same `scope`, in any site, lights while any is hovered, reveals included.
628	*
629	* A Pane row and a mark on a transcript message can share one. Another
630	* plugin's elements under the same string are a different group. One to
631	* 64 characters, no control characters; no keyed Box needed; no hook runs.
632	*/
633	scope?: string;
634	borderStyle?: string;
635	borderColor?: string;
636	borderDimColor?: boolean;
637	backgroundColor?: string;
638	display?: 'flex';
639	top?: number;
640	left?: number;
641	right?: number;
642	bottom?: number;
643	};
644
645	/**
646	* The props of `Box`: the layout, position, margin, padding and border props
647	* of Ink's Box a tree may set, and the two of hover.
648	*/
649	export type BoxProps = {
650	/**
651	* Makes the Box a hover scope: while the pointer is anywhere over it, its
652	* own `hover` and that of every element beneath it apply.
653	*
654	* A nested Box with a `key` of its own scopes what is beneath it, a placed
655	* card outside its rows included. A key a sibling Box already took, or one
656	* that is no plain string, names no scope: hovers beneath it stay inert.
657	*/
658	key?: string;
659	/**
660	* Style overrides applied by the surface while the pointer is over the
661	* nearest keyed `Box`, this one included, or, given a `scope`, its group.
662	*
663	* No hook runs and nothing crosses to the plugin. To reveal on hover, draw
664	* the Box `display: "none"` with `hover: { display: "flex" }` in a visible
665	* keyed Box or under a `scope`; on a `position: "absolute"` Box, no reflow.
666	*/
667	hover?: BoxHoverProps;
668	/**
669	* `"absolute"` leaves the flow, as in CSS: placed against its parent by
670	* the offsets, no room among its siblings, painted over those before it.
671	*
672	* So showing or moving it (a hover may) moves nothing; the pointer on it is
673	* on its parent. Clipped, pointer and paint, by the region its site is in
674	* (viewport, pane, band), by the site itself on the main screen or export.
675	*
676	* @example <Box key="k"><Text>glyph</Text><Box position="absolute" top={-2}
677	* left={2} display="none" hover={{ display: 'flex' }}>the card</Box></Box>
678	*/
679	position?: 'relative' \| 'absolute';
680	/**
681	* Rows from the parent's top edge, in character cells: an integer,
682	* negative above the edge.
683	*
684	* With `bottom` and no `height` the Box spans the two.
685	*/
686	top?: number;
687	/**
688	* Columns from the parent's left edge, in character cells: an integer,
689	* negative left of the edge.
690	*
691	* With `right` and no `width` the Box spans the two.
692	*/
693	left?: number;
694	/**
695	* Columns from the parent's right edge, in character cells: an integer,
696	* negative right of the edge.
697	*/
698	right?: number;
699	/**
700	* Rows from the parent's bottom edge, in character cells: an integer,
701	* negative below the edge.
702	*/
703	bottom?: number;
704	flexDirection?: 'row' \| 'column' \| 'row-reverse' \| 'column-reverse';
705	flexGrow?: number;
706	flexShrink?: number;
707	flexWrap?: 'nowrap' \| 'wrap' \| 'wrap-reverse';
708	alignItems?: 'flex-start' \| 'center' \| 'flex-end' \| 'stretch';
709	alignSelf?: 'flex-start' \| 'center' \| 'flex-end' \| 'auto';
710	justifyContent?: 'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around' \| 'space-evenly';
711	gap?: number;
712	columnGap?: number;
713	rowGap?: number;
714	width?: number \| string;
715	height?: number \| string;
716	minWidth?: number \| string;
717	minHeight?: number \| string;
718	margin?: number;
719	marginX?: number;
720	marginY?: number;
721	marginTop?: number;
722	marginBottom?: number;
723	marginLeft?: number;
724	marginRight?: number;
725	padding?: number;
726	paddingX?: number;
727	paddingY?: number;
728	paddingTop?: number;
729	paddingBottom?: number;
730	paddingLeft?: number;
731	paddingRight?: number;
732	borderStyle?: string;
733	borderColor?: string;
734	borderDimColor?: boolean;
735	backgroundColor?: string;
736	overflow?: 'visible' \| 'hidden';
737	display?: 'flex' \| 'none';
738	};
739
740	/**
741	* One variant per built-in tool; with none in the table (a plugin author's
742	* project before `/plugin-types` ran), one loose variant over every name.
743	*/
744	export type BuiltinToolCallInput = [BuiltinToolName] extends [never] ? BuiltinToolCallInputFallback : {
745	[N in BuiltinToolName]: ToolInputOf<N, BuiltinToolInputs[N]>;
746	}[BuiltinToolName];
747
748	/**
749	* The built-in branch's answer when no built-in tool is declared: every
750	* name, its args unconstrained.
751	*/
752	type BuiltinToolCallInputFallback = {
753	/**
754	* The name of the tool being called (`Bash`); comparing it narrows `e` once
755	* the table has entries. Reserved: a rewrite of it is ignored by core.
756	*/
757	tool: string;
758	/**
759	* The tool_use block's id: the same at every event of the call and in
760	* `$.ui.notice`. Reserved: a rewrite of it is ignored by core.
761	*/
762	tool_use_id: string;
763	[argument: string]: unknown;
764	};
765
766	/**
767	* The arguments of each built-in tool by name, for declaration merging;
768	* empty until a declaration file adds entries, then `e.tool === "Bash"`
769	* narrows `e` to Bash's arguments.
770	*
771	* `/plugin-types` writes this build's set beneath the engine's declarations
772	* (claude-code.d.ts), from each tool's input schema.
773	*
774	* @example
775	* interface BuiltinToolInputs { Bash: { command: string; timeout?: number } }
776	*/
777	export interface BuiltinToolInputs {
778	}
779
780	/**
781	* The names of the built-in tools.
782	*/
783	export type BuiltinToolName = keyof BuiltinToolInputs & string;
784
785	/**
786	* The structured result of each built-in tool by name, for declaration
787	* merging; empty until a declaration file adds entries, then after
788	* `e.tool === "Bash"` the `result` of `next(e)` is Bash's record.
789	*
790	* `/plugin-types` writes this build's set beneath the engine's declarations
791	* (claude-code.d.ts), from each tool's output schema; a tool without one is
792	* `unknown`.
793	*
794	* @example
795	* interface BuiltinToolResults { Bash: { stdout: string; stderr: string } }
796	*/
797	export interface BuiltinToolResults {
798	}
799
800	/**
801	* The props of `Button`, every surface's pressable leaf: an address, a
802	* label, the closure a press runs, and the label styles a hover overrides.
803	*
804	* The terminal draws `[ label ]` (when `plain`, `1: label` or the label
805	* alone), a desktop a native button; a click, a `hotkey`, the chord for its
806	* `action`, or Enter under the focus raises `ui.press`, its bottom `onPress`.
807	*/
808	export type ButtonProps = {
809	/**
810	* The element's address: `e.element` at `ui.press`, what a matcher names.
811	* Defaults to the label.
812	*/
813	key?: string;
814	/**
815	* The text drawn on the button; or the one string child.
816	*/
817	label?: string;
818	/**
819	* One digit (`"1"`) or one lowercase letter (`"w"`) that presses it while
820	* the plugin's site holds the focus; anything else is refused.
821	*
822	* The band after ctrl+x tab or a click, a focused `Pane`; never from the
823	* composer, save a bare digit in an empty one pressing a band Button, as a
824	* survey is answered. Shift+w matches `"w"`; two on one key, the later wins.
825	*/
826	hotkey?: string;
827	/**
828	* An engine keybinding action (`"app:cycleDiffBase"`) whose chord, as the
829	* person bound it, presses this from the prompt; unknown names refused.
830	*
831	* Chords, or a modified key Global or an active context binds, on the
832	* terminal while mounted, no dialog up and no engine handler of the action
833	* mounted; a pane's over the band's over another's, then the last drawn.
834	*/
835	action?: string;
836	/**
837	* Drawn without chrome: the hotkey in the accent color, a colon, the
838	* label (`1: Yes`), as a survey's row reads; no `hotkey`, the label alone.
839	*
840	* A one-glyph label (`'\u{1F50A}'`, a speaker) is then a control by
841	* itself: the focus and the pointer still invert it, `dimColor` and `hover`
842	* still apply. A desktop draws its native button either way.
843	*/
844	plain?: true;
845	/**
846	* The label drawn dim at rest, as `Text`'s `dimColor`, and at full strength
847	* under the pointer or the focus: a secondary control, a path in a list.
848	*/
849	dimColor?: boolean;
850	/**
851	* The site's focus ring starts here when the site takes the keyboard,
852	* instead of on nothing, as the DOM's `autofocus`: Enter acts on it at once.
853	*
854	* A pane opened with `focus`, or the person's focus chord or click, is the
855	* take. Of several in one site the first drawn wins; it raises `ui.focus`,
856	* origin this plugin. A ring the person has moved stays where it was put.
857	*/
858	autoFocus?: true;
859	/**
860	* Label style overrides (the `Text` set) applied by the surface while the
861	* nearest enclosing keyed `Box`, or given a `scope` its group, is hovered.
862	*
863	* No hook runs and nothing crosses to the plugin; under the pointer itself
864	* the button inverts as it always has. Refused outside a keyed Box unless
865	* it names a `scope`.
866	*/
867	hover?: TextHoverProps;
868	/**
869	* What the press runs, in the plugin's own environment: the bottom of the
870	* `ui.press` chain. The host holds only a handle, for the drawing's life.
871	*/
872	onPress: () => void;
873	};
874
875	/**
876	* The handler `on(...).catch(handler)` takes for a hook of type `F`: the
877	* hook's `($, e, next)`, run afresh when it throws, misreturns or overruns.
878	*
879	* `next` carries `error` and `called` (Caught) and is replay-safe; a return
880	* within the grace is the hook's result, `undefined` the hook absent. On a
881	* streaming event the handler is a generator too, continuing the stream.
882	*/
883	export type CatchHandler<F> = F extends ($: infer D, e: infer E, next: infer N) => infer R ? [R] extends [AsyncGenerator<unknown, unknown, unknown>] ? ($: D, e: E, next: N & Caught) => R : ($: D, e: E, next: N & Caught) => R \| undefined \| Promise<Awaited<R> \| undefined> : never;
884
885	/**
886	* What `next` carries into a `.catch` handler and nowhere else: why the
887	* hook failed, and whether it had called `next` before it did.
888	*
889	* There `next` is replay-safe: when `called`, `next(e)` resolves to what the
890	* hook's last call settled to, nothing beneath running again, the argument
891	* unread; when not, it runs the hooks beneath once and a later call replays.
892	*/
893	export type Caught = {
894	/**
895	* Why the hook failed (HookFailure); undefined on an ordinary hook's
896	* `next`, so its presence says a handler is running.
897	*/
898	readonly error: HookFailure;
899	/**
900	* True when the failed hook had called `next()` or `next.to()` at least
901	* once, settled or in flight; the handler runs once that call settled.
902	*/
903	readonly called: boolean;
904	};
905
906	/**
907	* What a hook on streaming event `N` yields, and what its `next(e)` yields
908	* to it (ChunkOf by name).
909	*/
910	export type Chunk<N extends StreamingEventName = StreamingEventName> = ChunkOf[N];
911
912	/**
913	* The chunk type of each streaming event, by name: what its stream yields.
914	*/
915	export type ChunkOf = {
916	/**
917	* One piece of the model's response (TurnStepChunk).
918	*/
919	'turn.step': TurnStepChunk;
920	};
921
922	/**
923	* What every `turn.step` chunk may carry: the engine's handle on the item
924	* of its own stream the chunk was read off, absent on a chunk a hook made.
925	*
926	* A hook that passes a chunk on, or rewrites it by spreading it, keeps the
927	* handle, and whatever it left unchanged reaches the engine as the engine
928	* streamed it; a chunk built afresh has none and is taken at its word.
929	*/
930	type ChunkRef = {
931	/**
932	* The engine's handle on its own streamed item; opaque, this step's only.
933	*/
934	ref?: number;
935	};
936
937	/**
938	* The name of a classic hook event as a function-hooks event: the settings
939	* hook's own name under `classic` (`classic.Stop`, `classic.PreToolUse`).
940	*/
941	export type ClassicEventName = `classic.${ClassicHookEvent}`;
942
943	/**
944	* The classic (settings) hook events, one per classic event name: `e` is
945	* what the classic hook receives on stdin for that event.
946	*
947	* The chain is [managed settings hooks, ...hooks modules, the other settings
948	* hooks as core], so a managed block ends it above every module. In shape
949	* `classic.PreToolUse` alone differs: its `e` is ToolCallEnvelope, no more.
950	*/
951	export type ClassicEventOf = {
952	[E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? ToolCallEnvelope : ClassicHookInputs[E];
953	};
954
955	/**
956	* The name of a classic hook event: `PreToolUse`, `Stop`, and the rest.
957	*/
958	export type ClassicHookEvent = HookInput['hook_event_name'];
959
960	/**
961	* What a classic hook receives on stdin for each event, by event name: the
962	* Agent SDK's `<Event>HookInput`.
963	*/
964	export type ClassicHookInputs = {
965	[I in HookInput as I['hook_event_name']]: I;
966	};
967
968	/**
969	* Everything a classic hook event's answer can carry, named as the classic
970	* hook's JSON output names it; each event reads its subset (ClassicResultOf).
971	*
972	* The settings hooks below fold into one of these (last write wins, contexts
973	* concatenate); a hooks module returns `next(e)`, a copy with fields changed,
974	* or its own. A field of the wrong shape fails the hook, which is skipped.
975	*/
976	export type ClassicResult = {
977	/**
978	* `decision: "block"` with this text as `reason` (a command hook's exit
979	* code 2): the event's block, veto or re-prompt.
980	*/
981	block?: string;
982	/**
983	* `continue: false`: the session stops after this event.
984	*/
985	preventContinuation?: true;
986	/**
987	* Shown when `preventContinuation` stops the session (`stopReason`).
988	*/
989	stopReason?: string;
990	/**
991	* `hookSpecificOutput.additionalContext`, one entry per hook: text handed
992	* to the model with the event.
993	*/
994	additionalContext?: string[];
995	/**
996	* `hookSpecificOutput.sessionTitle` (UserPromptSubmit, SessionStart).
997	*/
998	sessionTitle?: string;
999	/**
1000	* `hookSpecificOutput.suppressOriginalPrompt` (UserPromptSubmit,
1001	* UserPromptExpansion).
1002	*/
1003	suppressOriginalPrompt?: true;
1004	/**
1005	* `hookSpecificOutput.initialUserMessage` (SessionStart).
1006	*/
1007	initialUserMessage?: string;
1008	/**
1009	* `hookSpecificOutput.watchPaths` (SessionStart).
1010	*/
1011	watchPaths?: string[];
1012	/**
1013	* `hookSpecificOutput.reloadSkills` (SessionStart).
1014	*/
1015	reloadSkills?: true;
1016	/**
1017	* `hookSpecificOutput.permissionDecision` (PreModelSwitch).
1018	*/
1019	permissionDecision?: 'allow' \| 'deny' \| 'ask';
1020	/**
1021	* `hookSpecificOutput.permissionDecisionReason` (PreModelSwitch).
1022	*/
1023	permissionDecisionReason?: string;
1024	/**
1025	* `hookSpecificOutput.decision` (PermissionRequest).
1026	*/
1027	decision?: PermissionRequestDecision;
1028	/**
1029	* `hookSpecificOutput.updatedToolOutput` (PostToolUse): replaces what the
1030	* model sees of the tool's result.
1031	*/
1032	updatedToolOutput?: unknown;
1033	/**
1034	* `hookSpecificOutput.updatedMCPToolOutput` (PostToolUse, MCP tools only).
1035	*/
1036	updatedMCPToolOutput?: unknown;
1037	/**
1038	* `hookSpecificOutput.retry` (PermissionDenied).
1039	*/
1040	retry?: true;
1041	/**
1042	* `hookSpecificOutput.displayContent` (MessageDisplay).
1043	*/
1044	displayContent?: string;
1045	/**
1046	* `hookSpecificOutput.worktreePath` (WorktreeCreate; a command hook prints
1047	* it): the worktree the hook created, absolute or relative to its cwd.
1048	*
1049	* Left unset, the session creates its git worktree as it would unhooked.
1050	*/
1051	worktreePath?: string;
1052	};
1053
1054	/**
1055	* The event-specific fields of ClassicResult each classic event reads (its
1056	* `hookSpecificOutput`), by event; an event absent here reads none of them.
1057	*
1058	* `block`, `preventContinuation` and `stopReason` are every event's.
1059	*/
1060	export type ClassicResultFields = {
1061	UserPromptSubmit: 'additionalContext' \| 'sessionTitle' \| 'suppressOriginalPrompt';
1062	UserPromptExpansion: 'additionalContext' \| 'suppressOriginalPrompt';
1063	SessionStart: 'additionalContext' \| 'initialUserMessage' \| 'sessionTitle' \| 'watchPaths' \| 'reloadSkills';
1064	Setup: 'additionalContext';
1065	PreModelSwitch: 'permissionDecision' \| 'permissionDecisionReason';
1066	PostModelSwitch: 'additionalContext';
1067	SubagentStart: 'additionalContext';
1068	PostToolUse: 'additionalContext' \| 'updatedToolOutput' \| 'updatedMCPToolOutput';
1069	PostToolUseFailure: 'additionalContext';
1070	PostToolBatch: 'additionalContext';
1071	Stop: 'additionalContext';
1072	SubagentStop: 'additionalContext';
1073	PermissionDenied: 'retry';
1074	PermissionRequest: 'decision';
1075	MessageDisplay: 'displayContent';
1076	WorktreeCreate: 'worktreePath';
1077	};
1078
1079	/**
1080	* What each classic hook event's hook returns and its `next(e)` resolves to:
1081	* the event's own subset of ClassicResult.
1082	*
1083	* `classic.PreToolUse` keeps its `allow` / `ask` / `deny` result
1084	* (PreToolUseResult).
1085	*/
1086	export type ClassicResultOf = {
1087	[E in ClassicHookEvent as `classic.${E}`]: E extends 'PreToolUse' ? PreToolUseResult : Pick<ClassicResult, 'block' \| 'preventContinuation' \| 'stopReason' \| (E extends keyof ClassicResultFields ? ClassicResultFields[E] : never)>;
1088	};
1089
1090	/**
1091	* Options of `$.model.classify`.
1092	*/
1093	export type ClassifyOptions = {
1094	/**
1095	* An alias (`haiku`) or a full model id; default the engine's small fast
1096	* model.
1097	*/
1098	model?: string;
1099	};
1100
1101	/**
1102	* The element table a surface module draws with, `surface.elements`: the
1103	* terminal's (Elements) less `Client` (none nests), `Raster` and `Image`.
1104	*
1105	* What `$.ui.resolve(e)` is to a hooks module; a Button, Input or Select
1106	* keeps its handler here. A tree of them keeps every tree's bounds (20,000
1107	* nodes, 32 deep, 100,000 characters serialized) or the instance unmounts.
1108	*/
1109	export type ClientElements = Omit<Elements['terminal'], 'Client' \| 'Raster' \| 'Image'>;
1110
1111	/**
1112	* One key the person pressed while a `Client` had the focus, as
1113	* `surface.onKey` hands it. Escape never arrives: it returns the focus.
1114	*/
1115	export type ClientKeyEvent = {
1116	/**
1117	* A special key's name (`up`, `down`, `left`, `right`, `return`, `tab`,
1118	* `backspace`, `delete`, `pageup`, `home`, ...) or the character typed.
1119	*/
1120	key: string;
1121	/**
1122	* Modifier keys held with it, each present only when true.
1123	*/
1124	ctrl?: true;
1125	shift?: true;
1126	meta?: true;
1127	};
1128
1129	/**
1130	* The component a surface module exports (default, or its one PascalCase
1131	* export): from props and surface to the tree drawn (no nested `Client`).
1132	*
1133	* Runs on the drawing thread, a second per call at most; `h` and `Fragment`
1134	* are the environment's, so nothing of the module's takes those names. A
1135	* throw, an overrun or a tree past the bounds (ClientElements) unmounts it.
1136	*
1137	* @example
1138	* const Tag: ClientModule<string> = (t, s) => s.elements.Text({ children: t })
1139	*/
1140	export type ClientModule<P extends JsonValue = JsonValue, S = unknown> = (props: P, surface: ClientSurface<S>) => RenderElement;
1141
1142	/**
1143	* One pointer event over a `Client`'s region, as `surface.onPointer` hands
1144	* it: region-relative cells, and the sub-cell position where known.
1145	*
1146	* After a `down` in the region the instance holds the pointer until the
1147	* `up`: every `move` reaches it, past the edges too (negative, or beyond
1148	* `columns`/`rows`), and the transcript neither selects nor scrolls.
1149	*/
1150	export type ClientPointerEvent = {
1151	type: ClientPointerType;
1152	/**
1153	* The column under the pointer, 0 at the region's left edge; on `enter`
1154	* and `leave`, the last column a move reported.
1155	*/
1156	x: number;
1157	/**
1158	* The row under the pointer, 0 at the region's top edge.
1159	*/
1160	y: number;
1161	/**
1162	* The same position with the fraction of a cell kept (`x: 12`, `fine.x:
1163	* 12.375`), where the surface knows it: a terminal that reports pixels.
1164	*
1165	* kitty, Ghostty, iTerm2, WezTerm and foot do; tmux passes none through.
1166	* Absent elsewhere and on `enter`/`leave`; present, a `move` comes within
1167	* a cell too. What a module showing another program's pixels forwards.
1168	*
1169	* @example
1170	* surface.onPointer(e => click((e.fine?.x ?? e.x + 0.5) * pixelsPerCell))
1171	*/
1172	fine?: {
1173	x: number;
1174	y: number;
1175	};
1176	/**
1177	* Which button is down (`down`, `move` while held) or came up (`up`);
1178	* absent on a hover `move`, `enter` and `leave`.
1179	*/
1180	button?: 'left' \| 'middle' \| 'right';
1181	/**
1182	* Modifier keys the terminal reported held, each present only when true.
1183	*/
1184	shift?: true;
1185	alt?: true;
1186	ctrl?: true;
1187	};
1188
1189	/**
1190	* What the pointer did over a `Client`'s region: a button went down, the
1191	* pointer moved, the button came up, or the pointer crossed the region's edge.
1192	*/
1193	export type ClientPointerType = 'down' \| 'move' \| 'up' \| 'enter' \| 'leave';
1194
1195	/**
1196	* The props of `Client`: which of the plugin's surface modules draws here,
1197	* under what key, with what data, in how much room.
1198	*/
1199	export type ClientProps = {
1200	/**
1201	* The instance's address within the drawing: two `Client`s of one plugin in
1202	* one tree take two keys. What `e.element` carries at `ui.message`.
1203	*
1204	* The engine keeps the instance (its local state, its timers) across the
1205	* plugin's redraws while a `Client` under this key stays in the tree.
1206	*/
1207	key: string;
1208	/**
1209	* The surface module's path, a string literal relative to this file:
1210	* `module: "./<name>.tsx"` (or `.jsx`, `.ts`, `.js`, `.mjs`).
1211	*
1212	* Read off the source: a variable there is refused at load, as is a path
1213	* outside the plugin or naming no file. Its default export draws, else
1214	* its one PascalCase export; loaded, the tree carries the plugin's path.
1215	*/
1216	module: string;
1217	/**
1218	* Plain data (JsonValue) handed to the module function; a new value on a
1219	* redraw reaches the running instance, its state kept.
1220	*
1221	* Bounded as a tree's text is; not a channel for closures.
1222	* Typed `unknown` so a matcher over a tree stays shallow.
1223	*/
1224	props?: unknown;
1225	/**
1226	* Columns the instance's region takes: a count, or a percentage of the
1227	* parent. Absent, the region is as wide as what the module draws.
1228	*/
1229	width?: number \| string;
1230	/**
1231	* Rows the instance's region takes: a count, or a percentage of the parent.
1232	* Absent, the region is as tall as what the module draws.
1233	*/
1234	height?: number \| string;
1235	/**
1236	* How the region grows into free room along the parent's direction, as a
1237	* Box's `flexGrow`.
1238	*/
1239	flexGrow?: number;
1240	};
1241
1242	/**
1243	* What a surface module's function receives as its second argument: its
1244	* elements, the instance's local state, its region, input, clock and port.
1245	*
1246	* Called again (same `surface`, same `state`) on new props, after
1247	* `setState`, and on a resize; what it returns is drawn in the region. No
1248	* `$` here: the hooks module has it, and `post` is the way to reach it.
1249	*/
1250	export type ClientSurface<S = unknown> = {
1251	/**
1252	* The surface's element table (ClientElements), the tags the module draws
1253	* with: `const { Box, Text } = surface.elements`. No `Client` in it.
1254	*/
1255	readonly elements: ClientElements;
1256	/**
1257	* The instance's local state: `undefined` until the first `setState`.
1258	* Kept across the plugin's redraws; dropped with the instance.
1259	*/
1260	readonly state: S \| undefined;
1261	/**
1262	* Replaces the local state and schedules one more call of the function on
1263	* the next frame; several calls before it coalesce into one redraw.
1264	*
1265	* A `setState` on each of three renders in a row with no key, pointer,
1266	* tick, press or props between is a render loop: the instance unmounts.
1267	*/
1268	setState: (next: S) => void;
1269	/**
1270	* The region's width in cells, as last laid out (0 before the first
1271	* layout).
1272	*/
1273	readonly columns: number;
1274	/**
1275	* The region's height in cells, as last laid out (0 before the first
1276	* layout).
1277	*/
1278	readonly rows: number;
1279	/**
1280	* Calls `fn` every `ms` milliseconds on the surface's frame clock until
1281	* the returned function is called or the instance unmounts.
1282	*
1283	* Start it once (while `state` is still undefined), not on every call.
1284	*/
1285	every: (ms: number, fn: () => void) => () => void;
1286	/**
1287	* Sets the instance's pointer listener (one; a later call replaces it)
1288	* and returns what clears it. See ClientPointerEvent for capture.
1289	*/
1290	onPointer: (fn: (event: ClientPointerEvent) => void) => () => void;
1291	/**
1292	* Sets the instance's key listener (one; a later call replaces it),
1293	* reached while a click has given it the focus; Escape returns that.
1294	*/
1295	onKey: (fn: (event: ClientKeyEvent) => void) => () => void;
1296	/**
1297	* Sends plain data to the plugin's hooks module: `e.data` of a
1298	* `ui.message` only that plugin's hooks see, one per frame at most.
1299	*
1300	* A later post in the same frame replaces an undelivered one; a hook
1301	* answering `{ props }` hands this instance its next props. At most
1302	* 20,000 values, 32 deep, 100,000 characters, or the post is not sent.
1303	*/
1304	post: (data: JsonValue) => void;
1305	};
1306
1307	/**
1308	* The argument of the `$.clock` waits (`sleep`, `after`, `every`): how long,
1309	* in milliseconds, before the dispatch resolves.
1310	*/
1311	type ClockWait = {
1312	/**
1313	* The wait, a non-negative number of milliseconds.
1314	*/
1315	ms: number;
1316	};
1317
1318	/**
1319	* The props of `Code`, source text every surface draws with the engine's own
1320	* highlighter: coloured tokens, a line gutter on request, or a unified diff.
1321	*
1322	* A leaf: no children. `source` is the element's data as a string is a
1323	* Text's, bounded and free of control characters the same way; the colour
1324	* on screen is the engine's, never the plugin's.
1325	*/
1326	export type CodeProps = {
1327	/**
1328	* The text drawn: source code, or under `format: 'diff'` one or more
1329	* unified-diff hunks.
1330	*
1331	* At most 10000 characters; tab and newline are the only control
1332	* characters it may hold.
1333	*/
1334	source: string;
1335	/**
1336	* A highlighter language id or alias (`typescript`, `ts`, `py`), a
1337	* plugin-contributed grammar's included.
1338	*
1339	* Absent, the language is inferred from `path`; when neither resolves,
1340	* the text is drawn plain.
1341	*/
1342	language?: string;
1343	/**
1344	* A file path the language is inferred from when `language` is absent:
1345	* its extension or name, else a shebang on the first line.
1346	*
1347	* Drawn nowhere and never read: nothing touches the disk.
1348	*/
1349	path?: string;
1350	/**
1351	* The 1-based number of the first line of `source`: present, a dim
1352	* right-aligned gutter numbers the lines from it; absent, no gutter.
1353	*
1354	* Ignored under `format: 'diff'`, whose hunks carry their own numbers.
1355	*/
1356	startLine?: number;
1357	/**
1358	* `'source'` (the default) draws `source` as code; `'diff'` reads it as
1359	* unified-diff hunks and draws gutters, markers, add and remove colouring.
1360	*
1361	* A hunk is `@@ -a,b +c,d @@` then lines starting ` `, `+` or `-`; a
1362	* leading `---`/`+++` pair and `\ No newline at end of file` are read
1363	* past. A source that does not parse as hunks is refused.
1364	*/
1365	format?: 'source' \| 'diff';
1366	/**
1367	* What a line wider than the room does, in Text's `wrap` vocabulary:
1368	* `'wrap'` (the default) continues it on rows under the gutter.
1369	*
1370	* `'truncate-end'` cuts it at the edge with an ellipsis; Text's other
1371	* spellings are refused, since a gutter leaves them no sense here.
1372	*/
1373	wrap?: 'wrap' \| 'truncate-end';
1374	};
1375
1376	/**
1377	* The input of `command.describe`: how one slash command presents in the
1378	* typeahead and `/help`, at the moment the engine lists it.
1379	*/
1380	export type CommandDescribeInput = {
1381	/**
1382	* Names the command without its slash; the key a matcher narrows on. A
1383	* rewrite is refused.
1384	*/
1385	command: string;
1386	/**
1387	* The one-line description the menu shows, as the command declares it.
1388	*/
1389	description: string;
1390	/**
1391	* The hint drawn dim after the name (`[name]`), when the command has one.
1392	*/
1393	argumentHint?: string;
1394	/**
1395	* Whether the typeahead and `/help` leave the command out; a hidden
1396	* command still runs when typed in full.
1397	*/
1398	isHidden: boolean;
1399	/**
1400	* Whether the command declares it runs at once when typed mid-turn,
1401	* instead of waiting for the turn to end.
1402	*
1403	* One that decides per invocation reads false. Read only: not part of
1404	* what a hook answers, and a rewrite is refused.
1405	*/
1406	immediate: boolean;
1407	/**
1408	* Who provides this command: the plugin and its tier; `{ plugin: "engine",
1409	* tier: "core" }` for a built-in. Pinned: a rewrite is refused.
1410	*/
1411	provider: Origin;
1412	};
1413
1414	/**
1415	* What a `command.describe` hook returns: the description, hint and hidden
1416	* flag the menu uses; the name, `immediate` and `provider` stay as they were.
1417	*/
1418	export type CommandDescribeResult = Omit<CommandDescribeInput, 'command' \| 'immediate' \| 'provider'>;
1419
1420	/**
1421	* One slash command as `$.command.list()` returns it.
1422	*/
1423	export type CommandInfo = {
1424	/**
1425	* What the person runs it by, without the slash.
1426	*/
1427	name: string;
1428	/**
1429	* The one line the typeahead shows for it.
1430	*/
1431	description: string;
1432	/**
1433	* Where it comes from (CommandSource).
1434	*/
1435	source: CommandSource;
1436	/**
1437	* Which plugin added it, when `source` is `plugin` and the engine knows:
1438	* the one that registered it, or whose manifest carries it.
1439	*/
1440	plugin?: string;
1441	};
1442
1443	/**
1444	* Where a command's answer will show: which of the terminal's two layouts
1445	* the surface renders, and how wide it is when the command runs.
1446	*
1447	* A fact the engine stamps on `command.run`, so a command that draws (opens
1448	* a pane, prints a wide table) can suit the room it has: the fullscreen
1449	* layout docks a pane beside the transcript from 110 columns, the main
1450	* screen places it inline above the prompt at any width.
1451	*/
1452	export type CommandPresentation = {
1453	/**
1454	* True under the fullscreen (alternate-screen) layout; false on the main
1455	* screen (`CLAUDE_CODE_NO_FLICKER=0`, tmux by default) and headless.
1456	*
1457	* The fact `RenderViewport`'s `isFullscreen` carries on every terminal
1458	* drawing, from the same source: the two agree.
1459	*/
1460	isFullscreen: boolean;
1461	/**
1462	* The terminal's width in cells as the command runs; 80 where no terminal
1463	* has measured (headless with no tty).
1464	*/
1465	columns: number;
1466	};
1467
1468	/**
1469	* `command.run`'s input as a plugin's `$.command.run` takes it: `args` may
1470	* be left out (`/command`, bare); `origin` and `presentation` the engine sets.
1471	*/
1472	export type CommandRunArgs = Omit<CommandRunInput, 'origin' \| 'args' \| 'presentation'> & {
1473	/**
1474	* Everything after the name, as the person would type it; left out, `""`.
1475	*/
1476	args?: string;
1477	};
1478
1479	/**
1480	* The input of `command.run`: one slash command about to run, the way the
1481	* person typed it (`/name args`), and where the run came from.
1482	*/
1483	export type CommandRunInput = {
1484	/**
1485	* Names the command without its slash (`compact`, `hello`), aliases and
1486	* folds resolved; the key a matcher narrows on. A rewrite is refused.
1487	*/
1488	command: string;
1489	/**
1490	* Everything after the name, as typed (`""` when nothing was); a hook
1491	* rewrites it with `next({ ...e, args })`.
1492	*/
1493	args: string;
1494	/**
1495	* Where the run came from, in `prompt.submit`'s words (PromptOrigin):
1496	* the person's Enter (`composer`), the bridge, the SDK, or a plugin.
1497	*
1498	* A plugin's `$.command.run` reads `{ kind: 'plugin', name }`. `next(e)`
1499	* passes it on as received.
1500	*/
1501	origin: PromptOrigin;
1502	/**
1503	* Where the command's answer will show (CommandPresentation): the
1504	* fullscreen layout or the main screen, and the terminal's width.
1505	*
1506	* Pinned: the engine stamps it, `next(e)` passes it on, a rewrite that
1507	* leaves it out keeps it and one that changes it is refused.
1508	*/
1509	presentation: CommandPresentation;
1510	};
1511
1512	/**
1513	* What a `command.run` hook returns and what `next(e)` and `$.command.run`
1514	* resolve to: the command's output text and the notes it leaves the model.
1515	*
1516	* From core, `text` is what the command printed (a `local` command's
1517	* returned text; a panel command may print nothing), `context` what it
1518	* recorded for the model beside that, and `ref` names the run.
1519	*
1520	* A hook's own answer without `next` runs no command: its `text` is shown
1521	* as the command's output, under the names of the plugins hooking the
1522	* command unless each is bundled with Claude Code, whose answer reads as
1523	* the built-in command's own, and its `context` is recorded after it.
1524	*
1525	* Both are the plugin's to size, as a core command's output is; what bounds
1526	* them is what bounds any transcript row where a surface draws it.
1527	*/
1528	export type CommandRunResult = {
1529	/**
1530	* The command's output as a transcript line, or undefined when the
1531	* command showed nothing as text (a panel, a prompt for the model).
1532	*/
1533	text?: string;
1534	/**
1535	* What the model reads after the command's output and the person never
1536	* sees, each entry one hidden user message recorded after the output row.
1537	*
1538	* From core, the notes the command left the model, absent when none. Kept
1539	* whole from `next`: left out after `next`, the last answer's notes ride
1540	* along; written, it keeps every entry that answer had (none empty).
1541	*/
1542	context?: readonly string[];
1543	/**
1544	* Set by core on what `next(e)` resolves to: names the engine's run of
1545	* the command (its result stays on the host side).
1546	*
1547	* A hook that returns the object it got makes the engine use that run
1548	* verbatim. Absent on a hook's own `{ text }` and on `$.command.run`'s.
1549	*/
1550	ref?: number;
1551	};
1552
1553	/**
1554	* Where a slash command comes from, as `$.command.list()` tells them apart.
1555	*
1556	* `builtin` ships with Claude Code; `plugin` is a plugin's markdown command,
1557	* skill or `$.command.register`; `user` is the user's or project's own
1558	* file; `mcp` an MCP server's prompt.
1559	*/
1560	export type CommandSource = 'builtin' \| 'plugin' \| 'user' \| 'mcp';
1561
1562	/**
1563	* What `$.command.register` takes: the slash command this plugin serves.
1564	*/
1565	export type CommandSpec = {
1566	/**
1567	* The command's name without the slash (letters, digits, `_`, `-`; up to
1568	* 64); the person runs it as `/<name>`.
1569	*/
1570	name: string;
1571	/**
1572	* The one line the typeahead and `/help` show for it.
1573	*/
1574	description: string;
1575	/**
1576	* The hint drawn dim after the name (`[name]`), when it takes arguments.
1577	*/
1578	argumentHint?: string;
1579	/**
1580	* Set so that `/<name>` typed while a turn is in flight runs at once
1581	* instead of waiting for the turn to end, as it does when left out.
1582	*
1583	* Its `command.run` hook then runs while a turn may still be streaming and
1584	* must not assume the turn's state (what the transcript holds, whether a
1585	* tool is mid-call); its `{ text }` prints as an idle run's does.
1586	*/
1587	immediate?: true;
1588	};
1589
1590	type ConfigChangeHookInput = BaseHookInput & {
1591	hook_event_name: 'ConfigChange';
1592	source: 'user_settings' \| 'project_settings' \| 'local_settings' \| 'policy_settings' \| 'skills';
1593	file_path?: string;
1594	};
1595
1596	/**
1597	* The input of `config.describe`: how one `/config` row presents, at the
1598	* moment the menu lists it (and for `$.config.list`).
1599	*/
1600	export type ConfigDescribeInput = {
1601	/**
1602	* Names the row, as `config.set`'s `key` does; the key a matcher narrows
1603	* on. Pinned: a rewrite is refused.
1604	*/
1605	key: string;
1606	/**
1607	* What the menu draws for the row, before its value.
1608	*/
1609	label: string;
1610	/**
1611	* The help text beneath the label, when the row has one (a plugin
1612	* field's `description`); absent for the panel's own rows.
1613	*/
1614	description?: string;
1615	/**
1616	* Whether the menu leaves the row out; a hidden row still answers
1617	* `$.config.set` and `/config key=value`.
1618	*/
1619	isHidden: boolean;
1620	/**
1621	* Who owns the row, as `config.set`'s `provider`. Pinned.
1622	*/
1623	provider: Origin;
1624	};
1625
1626	/**
1627	* What a `config.describe` hook returns: the label, help text and hidden
1628	* flag the menu uses; the key and provider stay as they were.
1629	*/
1630	export type ConfigDescribeResult = Omit<ConfigDescribeInput, 'key' \| 'provider'>;
1631
1632	/**
1633	* How a `/config` row takes its value: `boolean` toggles, `choice` picks one
1634	* of its `options`, `text` takes a string, `number` a number.
1635	*/
1636	export type ConfigKind = 'boolean' \| 'choice' \| 'text' \| 'number';
1637
1638	/**
1639	* Where a `config.set` came from, in `prompt.submit`'s words: the person
1640	* in the `/config` menu (`composer`), the bridge, or a plugin, named.
1641	*
1642	* Set by the engine; `next(e)` passes it on as received and none sets it.
1643	*/
1644	export type ConfigOrigin = {
1645	/**
1646	* The person's own change in the `/config` menu (a toggle, a pick, a
1647	* typed value), or their `/config key=value`.
1648	*/
1649	kind: 'composer';
1650	} \| {
1651	/**
1652	* A `/config key=value` that arrived over the Remote Control bridge (a
1653	* phone or web client, or a relay): not attestably the owner's hand.
1654	*/
1655	kind: 'bridge';
1656	} \| {
1657	/**
1658	* A plugin's `$.config.set`; that plugin's own hooks do not see it.
1659	*/
1660	kind: 'plugin';
1661	/**
1662	* The calling plugin's name.
1663	*/
1664	name: string;
1665	};
1666
1667	/**
1668	* One `/config` row as `$.config.list()` returns it: what the menu would
1669	* draw now, after every `config.describe` hook, a hidden row left out.
1670	*/
1671	export type ConfigRow = {
1672	/**
1673	* Names the row: the panel's id for a built-in, `<plugin>.<field>` for a
1674	* plugin's `userConfig` field; what `$.config.set` takes.
1675	*/
1676	key: string;
1677	/**
1678	* What the menu draws for the row, before its value.
1679	*/
1680	label: string;
1681	/**
1682	* The help text under the label, when the row has one.
1683	*/
1684	description?: string;
1685	/**
1686	* How the row takes its value (ConfigKind).
1687	*/
1688	kind: ConfigKind;
1689	/**
1690	* What the row holds now.
1691	*/
1692	value: ConfigValue;
1693	/**
1694	* The values a `choice` row takes, in order (a plugin string field's
1695	* declared `options` for its row); absent otherwise.
1696	*/
1697	options?: readonly string[];
1698	/**
1699	* Who owns the row: the engine for the panel's own, else the plugin.
1700	*/
1701	provider: Origin;
1702	/**
1703	* Whether a trusted source (managed settings, the organization's policy)
1704	* owns the value, so the menu shows it and refuses a change.
1705	*/
1706	isLocked: boolean;
1707	};
1708
1709	/**
1710	* `config.set`'s input as a plugin's `$.config.set(args)` takes it: the
1711	* row's key and the value; the engine fills the rest.
1712	*/
1713	export type ConfigSetArgs = Pick<ConfigSetInput, 'key' \| 'value'>;
1714
1715	/**
1716	* The input of `config.set`: one `/config` row about to change, from the
1717	* menu or a plugin's `$.config.set`, with what it holds now and who owns it.
1718	*/
1719	export type ConfigSetInput = {
1720	/**
1721	* Names the row: the panel's own id for a built-in (`theme`, `verbose`,
1722	* `autoCompact`), `<plugin>.<field>` for a plugin's `userConfig` field.
1723	*
1724	* The key a matcher narrows on; pinned: a rewrite is refused.
1725	*/
1726	key: string;
1727	/**
1728	* What the row is being set to; `next({ ...e, value })` clamps or
1729	* replaces it, held to the row's kind (a toggle takes a boolean).
1730	*/
1731	value: ConfigValue;
1732	/**
1733	* What the row holds before the change, as the menu shows it. Pinned.
1734	*/
1735	previous: ConfigValue;
1736	/**
1737	* Who owns the row: `{ plugin: "engine", tier: "core" }` for the panel's
1738	* own, the plugin and its tier for a `userConfig` field. Pinned.
1739	*/
1740	provider: Origin;
1741	/**
1742	* Where the change came from (ConfigOrigin): the person in the menu
1743	* (`composer`) or a plugin's `$.config.set`. Pinned.
1744	*/
1745	origin: ConfigOrigin;
1746	};
1747
1748	/**
1749	* What a `config.set` hook returns and what `next(e)` resolves to:
1750	* `{ value }` once written, or `{ deny: reason }`, the row left as it was.
1751	*
1752	* The menu shows a deny's reason beside the row; a plugin's `$.config.set`
1753	* resolves with it.
1754	*/
1755	export type ConfigSetResult = {
1756	value: ConfigValue;
1757	deny?: undefined;
1758	} \| {
1759	deny: string;
1760	value?: undefined;
1761	};
1762
1763	/**
1764	* A `/config` row's value as a hook and `$.config` see it: a toggle's
1765	* boolean, a choice's or a text's string, a number, or a list of strings.
1766	*/
1767	export type ConfigValue = boolean \| string \| number \| readonly string[];
1768
1769	/**
1770	* One custom agent whose description the Agent tool's prompt carries;
1771	* built-in agents are left out.
1772	*/
1773	export type ContextAgent = {
1774	/**
1775	* The agent's type, as the Agent tool names it.
1776	*/
1777	agentType: string;
1778	/**
1779	* Where it was defined, by the engine's word (`projectSettings`,
1780	* `userSettings`, `plugin`); the display label is the renderer's.
1781	*/
1782	source: string;
1783	/**
1784	* The description's estimated tokens.
1785	*/
1786	tokens: number;
1787	};
1788
1789	/**
1790	* The token counts the last API response of the live window reported, as
1791	* the API spells them; the breakdown's `Messages` row is reconciled to it.
1792	*/
1793	export type ContextApiUsage = {
1794	/**
1795	* Uncached input tokens the response was answered over.
1796	*/
1797	input_tokens: number;
1798	/**
1799	* Tokens the response generated.
1800	*/
1801	output_tokens: number;
1802	/**
1803	* Input tokens written to the prompt cache by the request.
1804	*/
1805	cache_creation_input_tokens: number;
1806	/**
1807	* Input tokens read from the prompt cache by the request.
1808	*/
1809	cache_read_input_tokens: number;
1810	};
1811
1812	/**
1813	* How a context breakdown is counted: `full` with the token-count API per
1814	* category, `summary` from the last response's usage and local estimates.
1815	*
1816	* The SDK's `get_context_usage` takes the same two words as its `detail`.
1817	*/
1818	export type ContextBreakdownDetail = 'summary' \| 'full';
1819
1820	/**
1821	* One row of the breakdown, as /context lists it beside the grid (`System
1822	* prompt`, `Messages`, `Free space`, `Autocompact buffer`).
1823	*/
1824	export type ContextCategory = {
1825	/**
1826	* The row's label as /context prints it.
1827	*/
1828	name: string;
1829	/**
1830	* The row's estimated tokens; a `deferred` row's do not count toward the
1831	* total.
1832	*/
1833	tokens: number;
1834	/**
1835	* The theme colour /context draws the row and its squares in, by its key
1836	* in the theme (`promptBorder`, `inactive`, `permission`).
1837	*/
1838	color: string;
1839	/**
1840	* Whether the row is tool schemas loaded on demand, which the grid leaves
1841	* out; the same fact as `kind` `deferred`.
1842	*/
1843	isDeferred: boolean;
1844	/**
1845	* What the row is (ContextCategoryKind), stamped by the engine.
1846	*/
1847	kind: ContextCategoryKind;
1848	};
1849
1850	/**
1851	* What a breakdown row is; branch on this, never on the row's `name`.
1852	*
1853	* `used` content occupies the window, `free` is the window left, `buffer`
1854	* the compaction reserve, `deferred` tool schemas loaded on demand and
1855	* outside the window.
1856	*/
1857	export type ContextCategoryKind = 'used' \| 'free' \| 'buffer' \| 'deferred';
1858
1859	/**
1860	* One square of the grid /context draws: which row it belongs to and how
1861	* full it is.
1862	*/
1863	export type ContextGridSquare = {
1864	/**
1865	* The theme colour of the square's row, by its key in the theme.
1866	*/
1867	color: string;
1868	/**
1869	* Whether the square holds any of its row's tokens.
1870	*/
1871	isFilled: boolean;
1872	/**
1873	* The `name` of the row the square belongs to (`Free space` for the
1874	* window left).
1875	*/
1876	categoryName: string;
1877	/**
1878	* The row's tokens, repeated on each of its squares.
1879	*/
1880	tokens: number;
1881	/**
1882	* The row's share of the window as a whole percentage, repeated likewise.
1883	*/
1884	percentage: number;
1885	/**
1886	* How full this one square is, 0 to 1: a row's last square is the partial
1887	* one (/context draws it hollow under 0.7).
1888	*/
1889	squareFullness: number;
1890	};
1891
1892	/**
1893	* One MCP tool's schema as the context carries it.
1894	*/
1895	export type ContextMcpTool = {
1896	/**
1897	* The tool's wire name (`mcp__linear__create_issue`).
1898	*/
1899	name: string;
1900	/**
1901	* The server it belongs to, as /mcp lists it.
1902	*/
1903	serverName: string;
1904	/**
1905	* The schema's estimated tokens.
1906	*/
1907	tokens: number;
1908	/**
1909	* Whether the schema is inside the window now: always, unless tool
1910	* schemas load on demand and this one has not been searched for yet.
1911	*/
1912	isLoaded: boolean;
1913	};
1914
1915	/**
1916	* One memory file the context carries (a CLAUDE.md, a rules file, an
1917	* auto-memory entry).
1918	*/
1919	export type ContextMemoryFile = {
1920	/**
1921	* The file's path, absolute.
1922	*/
1923	path: string;
1924	/**
1925	* The display label of where it was loaded from (`Project`, `User`,
1926	* `Local`, `Managed`, `AutoMem`).
1927	*/
1928	type: string;
1929	/**
1930	* The file's estimated tokens.
1931	*/
1932	tokens: number;
1933	};
1934
1935	/**
1936	* One skill whose listing the context carries.
1937	*/
1938	export type ContextSkill = {
1939	/**
1940	* The skill's name as `/skills` lists it.
1941	*/
1942	name: string;
1943	/**
1944	* Where it came from, by the engine's word (`userSettings`, `plugin`,
1945	* `built-in`, `mcp`, `syncedSkills`); the display label is the renderer's.
1946	*/
1947	source: string;
1948	/**
1949	* The providing plugin's name, when the skill comes from one.
1950	*/
1951	pluginName?: string;
1952	/**
1953	* The listing's estimated tokens.
1954	*/
1955	tokens: number;
1956	};
1957
1958	/**
1959	* The skills the context lists for the model: how many there are, how many
1960	* fit the listing's budget, and each one's share.
1961	*/
1962	export type ContextSkills = {
1963	/**
1964	* How many skills the session has.
1965	*/
1966	totalSkills: number;
1967	/**
1968	* How many the listing included within its token budget.
1969	*/
1970	includedSkills: number;
1971	/**
1972	* The listing's tokens in all.
1973	*/
1974	tokens: number;
1975	/**
1976	* One entry per listed skill.
1977	*/
1978	skillFrontmatter: ContextSkill[];
1979	};
1980
1981	/**
1982	* The slash commands the Skill tool's prompt lists, counted.
1983	*/
1984	export type ContextSlashCommands = {
1985	/**
1986	* How many commands the session has.
1987	*/
1988	totalCommands: number;
1989	/**
1990	* How many the listing included.
1991	*/
1992	includedCommands: number;
1993	/**
1994	* The listing's tokens in all.
1995	*/
1996	tokens: number;
1997	};
1998
1999	/**
2000	* How the window the breakdown measures against was settled; /context
2001	* prints its `Auto-compact window` line off this.
2002	*
2003	* `auto` is the model's own limit; the rest name a compaction window by who
2004	* set it: the `CLAUDE_CODE_AUTO_COMPACT_WINDOW` variable, the settings, the
2005	* account, an experiment, the model's default, or an unrecognised model's.
2006	*/
2007	export type ContextWindowSource = 'env' \| 'settings' \| 'clientdata' \| 'experiment' \| 'model-default' \| 'unknown-model' \| 'auto';
2008
2009	/**
2010	* The plugin's identity (`plugin`) and the nouns core contributes to `$` as
2011	* the innermost step of the `engine.create` fold.
2012	*
2013	* A plugin's finished `$` (EngineInterface) has every core noun an outer
2014	* step did not withhold, and every noun the plugins' steps added.
2015	*/
2016	export interface CoreEngineInterface {
2017	/**
2018	* This plugin, as loaded: its manifest name and its directory.
2019	*/
2020	plugin: {
2021	/**
2022	* From plugin.json; debug-log and `$.ui.log` lines carry it.
2023	*/
2024	name: string;
2025	/**
2026	* The plugin's directory (the one holding plugin.json), absolute.
2027	*/
2028	root: string;
2029	};
2030	/**
2031	* Display: a line under an open dialog, a redraw or a repaint, a
2032	* transcript or debug line, panes the surface places, a window or ring.
2033	*/
2034	ui: {
2035	/**
2036	* Shows `text` as one line under the dialog open for `tool_use_id`, or
2037	* removes the line when `text` is undefined.
2038	*
2039	* Core removes the line when the call resolves. A call that is not open
2040	* is refused, as is another plugin's `$.tool.call` run.
2041	*
2042	* @param tool_use_id the call whose open dialog gets the line
2043	* @param text the line to show; undefined removes it
2044	* @example
2045	* $.ui.notice(e.tool_use_id, "checked by my-plugin"); return next(e)
2046	*/
2047	notice: (tool_use_id: string, text: string \| undefined) => void;
2048	/**
2049	* Re-runs an event whose results the engine caches: `ui.render` draws the
2050	* instances this plugin may draw again; the others drop the cached answers.
2051	*
2052	* A render hook whose state changed (a countdown) calls it for a redraw, at
2053	* most ten a second, thirty for the shown pane and the band (calls sooner
2054	* fold); a prompt section, context or attachment hook: dropped next turn.
2055	*
2056	* @param event `ui.render`, or a cached-answer event: `prompt.section`,
2057	* `prompt.context`, `prompt.attachment`, `tool/command/config.describe`
2058	*/
2059	invalidate: (event: InvalidatableEventName) => void;
2060	/**
2061	* Repaints a mounted `Raster` this plugin's own render hook drew with new
2062	* cells, or swaps a keyed `Image` it drew to a new source; no redraw.
2063	*
2064	* The surface paints the cells or source at its next frame, so blits
2065	* between frames fold into one: up to 120 a second taken, some sixty
2066	* shown. An Image swap sends one small command; a resize is a redraw.
2067	*
2068	* @param args `requestId` (the site), `key`, and `cells` (RasterProps) or
2069	* `source` (ImageSource); `columns`, `rows` (the mounted size)
2070	* @returns `{}` once the cells or source are its next frame, or `{ deny }`
2071	* (not mounted, not this plugin's, another size, cells that do
2072	* not decode, a bad source, or an Image drawing its alt there:
2073	* no placeholder images, or a file this terminal cannot read)
2074	* @example
2075	* $.clock.every(33, () => $.ui.blit({ requestId, key, cells: frame() }))
2076	* @example
2077	* await $.ui.blit({ requestId: 'browser', key: 'view',
2078	* source: { shm: name, format: 'rgb', width, height } })
2079	*/
2080	blit: (args: UiBlitArgs) => Promise<UiBlitResult>;
2081	/**
2082	* The elements of the surface `e` is drawn on (Elements[e.surface]): a
2083	* frozen table of constructors, the JSX tags a render hook draws with.
2084	*
2085	* A read, not a dispatch: the engine ran `ui.resolve` (the other hooks,
2086	* then core) at load, per surface and component. Narrowed `e.surface`:
2087	* that table exactly; unnarrowed: the union, so shared names type-check.
2088	*
2089	* @param e this hook's own `ui.render` argument (its surface and
2090	* component pick the table)
2091	* @returns the surface's frozen element table (`Elements[e.surface]`)
2092	* @example
2093	* const { Box, Text } = $.ui.resolve(e)
2094	* return <Box>{await next(e)}<Text dimColor>done</Text></Box>
2095	*/
2096	resolve: <E extends ResolveInput>(e: E) => Elements[E['surface']];
2097	/**
2098	* Appends one line to the transcript, drawn like a system notice (dim;
2099	* not sent to the model), or with `{ to: "debug" }` to the debug log alone.
2100	*
2101	* A row of its own at the next frame, in logging order; a `-p` or SDK
2102	* host receives it as `ui_log`; the debug log has every line under this
2103	* plugin's name. Raised as `ui.log`: a hook above may rewrite `e.to`.
2104	*
2105	* @param text the line's text
2106	* @param options `to`: `transcript` (the default) or `debug`
2107	* @example
2108	* $.ui.log(`prompt from ${e.origin.kind}: ${e.text.length} chars`)
2109	* @example
2110	* $.ui.log(`cache miss for ${e.tool_use_id}`, { to: "debug" })
2111	*/
2112	log: (text: string, options?: UiLogOptions) => void;
2113	/**
2114	* Asks the user `question` in the engine's own AskUserQuestion dialog and
2115	* resolves to the label they chose, or the text typed under "Other".
2116	*
2117	* A `tool.call` of `AskUserQuestion` through every hook but the calling
2118	* one, drawn by `ui.render` on `AskUserQuestion`; a multi-select answer is
2119	* comma-joined. Rejects when dismissed, and in a `-p` run (no one to ask).
2120	*
2121	* @param question the question, ending in a question mark
2122	* @param options 2-4 option labels, or `{ options, header, multiSelect }`
2123	* @returns the label chosen, the chosen labels comma-joined, or free text
2124	* typed under "Other" (so compare it with the labels exactly)
2125	* @example
2126	* const mood = await $.ui.ask("How careful?", ["Bold", "Careful"])
2127	*/
2128	ask: (question: string, options?: readonly string[] \| AskOptions) => Promise<string>;
2129	/**
2130	* Shows `text` on the notification bar under the prompt for a few
2131	* seconds, the way the engine's own "context left" notice appears.
2132	*
2133	* It leaves the transcript and the model untouched.
2134	*
2135	* @param text the line to show; an unpaired surrogate half in it is drawn
2136	* as U+FFFD
2137	* @param options `timeoutMs`: how long it stays (default 4000)
2138	* @example
2139	* $.ui.toast(`turn took ${Math.round(e.durationMs / 1000)} s`)
2140	*/
2141	toast: (text: string, options?: ToastOptions) => void;
2142	/**
2143	* Pins `text` as this plugin's status line under the prompt, beside the
2144	* engine's own pinned notices, until the next call replaces it.
2145	*
2146	* One per plugin; `undefined` removes it.
2147	*
2148	* @param text the line to keep on screen (an unpaired surrogate half is
2149	* drawn as U+FFFD); undefined clears it
2150	* @example
2151	* $.ui.status("thinking..."); return next(e)
2152	*/
2153	status: (text: string \| undefined) => void;
2154	/**
2155	* Opens a pane: a framed region the surface places, whose body this
2156	* plugin draws by hooking `ui.render` for `{ component: "Pane" }`.
2157	*
2158	* One instance per id (`requestId`): opening an open id retitles it; a hook
2159	* on `ui.open` may refuse it. The keyboard is the person's; unasked, it
2160	* waits undrawn below 144 columns (110 once asked), judged at each open.
2161	*
2162	* @param pane `id` (1-64 of letters, digits, `_`, `-`), `title`, `focus`,
2163	* `closeOnEscape` and `holdToasts` (a dialog), `rows` / `columns` wanted
2164	* @returns settles once the pane is open (or retitled)
2165	* @example
2166	* await $.ui.open({ id: "clock", title: "Clock" })
2167	* @example
2168	* await $.ui.open({ id: "ask", focus: true, closeOnEscape: true, rows: 9 })
2169	*/
2170	open: (pane: PaneOpenArgs) => Promise<void>;
2171	/**
2172	* Closes one of the open panes; an id that is not open is left alone.
2173	*
2174	* Every close raises `ui.close`, `e.origin` naming whose it is: this call
2175	* (`plugin`), the person's mark or key (`person`), an unload (`unload`).
2176	* A hook answering without `next` keeps the pane open, save on an unload.
2177	*
2178	* @param pane `id`: the id the pane was opened under
2179	* @returns settles once the pane is gone or a hook answered for it;
2180	* rejects on a hook's `{ deny }`
2181	* @example
2182	* onPress: () => $.ui.close({ id: "clock" })
2183	*/
2184	close: (pane: PaneCloseArgs) => Promise<void>;
2185	/**
2186	* Lists this plugin's own open panes (UiPane): each one's id and title,
2187	* and whether it is shown, holds the keyboard, and is placed.
2188	*
2189	* The engine's record, not the module's: a module reloaded while its
2190	* pane stayed up finds it here. Another plugin's panes are not listed.
2191	*
2192	* @returns the panes in open order, placed ones first; empty with none
2193	* @example
2194	* const isUp = (await $.ui.panes()).some(pane => pane.id === "clock")
2195	* if (!isUp) await $.ui.open({ id: "clock", title: "Clock" })
2196	*/
2197	panes: () => Promise<readonly UiPane[]>;
2198	/**
2199	* Scrolls something into view as the DOM's `scrollIntoView` would: a
2200	* render instance by `requestId`, an element by `key`, a site's edge.
2201	*
2202	* A site of this plugin's (its pane, the band it draws into) moves under
2203	* the event `ui.scroll`, origin `plugin`. A transcript row moves only
2204	* while this call answers the person's own input, where one scrolls.
2205	*
2206	* @param args `to` (what), `in` (which site, required for `start` and
2207	* `end`), `block` (where it lands; `nearest` by default)
2208	* @returns `{}` once it moved, or `{ deny }` saying why not
2209	* @example
2210	* onPress: () => $.ui.scroll({ in: "log", to: "end" })
2211	*/
2212	scroll: (args: UiScrollArgs) => Promise<UiScrollResult>;
2213	/**
2214	* Moves the focus ring of one of this plugin's sites onto an element it
2215	* drew there, as the DOM's `element.focus()`, while it holds the keys.
2216	*
2217	* Raised as the event `ui.focus`, origin `plugin`; the engine's inverse
2218	* marks the element. The keyboard is the person's to give: a site not
2219	* holding it, or holding it on another plugin's element, is `{ deny }`.
2220	*
2221	* @param args `requestId` (which site: a pane's id, the band's) and `key`
2222	* (the element's, as drawn)
2223	* @returns `{}` once it moved, or `{ deny }` saying why not
2224	* @example
2225	* onPress: () => $.ui.focus({ requestId: "files", key: "row:0" })
2226	*/
2227	focus: (args: UiFocusArgs) => Promise<UiFocusResult>;
2228	};
2229	/**
2230	* Completions through the session's own client and credentials.
2231	*/
2232	model: {
2233	/**
2234	* Runs one text completion through the session's own API client and
2235	* resolves to the reply's text.
2236	*
2237	* No tools, no history, no system prompt beyond the CLI's identity block
2238	* and `request.system`.
2239	*
2240	* @param request the model (an alias such as `haiku`, or a full id,
2241	* resolved like a `--model` value), the prompt, and a token cap
2242	* @returns the reply's text
2243	* @example
2244	* const reply = await $.model.complete({ model: "haiku", prompt: "Hi." })
2245	*/
2246	complete: (request: ModelCompleteRequest) => Promise<string>;
2247	/**
2248	* Runs one tool-less completion over the session's OWN transcript, sharing
2249	* the main thread's prompt cache; the reply's text and the fork's usage.
2250	*
2251	* Not `complete`: sharing the cache prefix means the model and system
2252	* prompt are the session's, read from its last turn's cache-safe snapshot,
2253	* and tools are denied. Null on a cold snapshot or an API error.
2254	*
2255	* @param request the one user message the fork answers
2256	* @returns the reply's text with the fork's usage, or null on a cold
2257	* snapshot or an API error
2258	* @example
2259	* const reply = await $.model.fork({ prompt: "One line to learn?" })
2260	* if (reply !== null) $.ui.log(`${reply.usage.output_tokens} tokens`)
2261	*/
2262	fork: (request: ModelForkRequest) => Promise<ModelForkResult \| null>;
2263	/**
2264	* Picks one of `labels` for `text` with one completion over
2265	* `$.model.complete` and a fixed classifier prompt.
2266	*
2267	* `text` is data; the model answers with a label alone. It resolves
2268	* `undefined` when the answer named none of `labels`. A failed request,
2269	* an abort or a reply with no text rejects, naming the cause.
2270	*
2271	* @param text what to classify
2272	* @param labels the labels to choose from (2 or more)
2273	* @param options `model`: an alias or id; default the engine's small
2274	* fast model
2275	* @returns the label the model named, or undefined when it named none;
2276	* rejects when the request fails or the reply has no text
2277	* @example
2278	* const kind = await $.model.classify(e.text, ["bug", "feature"])
2279	* if (kind === undefined) return next(e)
2280	*/
2281	classify: (text: string, labels: readonly string[], options?: ClassifyOptions) => Promise<string \| undefined>;
2282	};
2283	/**
2284	* Sound: clip playback and platform speech.
2285	*/
2286	audio: {
2287	/**
2288	* Plays one audio clip, starting now; clips are not queued, so two calls
2289	* play together (a bed under speech).
2290	*
2291	* `{ asset }` is the plugin's own file, loaded by the engine and played
2292	* through the platform's player (`afplay` on macOS). Resolves when
2293	* playback ends; rejects, naming the cause, when the clip cannot play.
2294	*
2295	* @param clip the plugin's own file (`{ asset }`), a URL the engine
2296	* fetches, or the bytes as base64 with their MIME type
2297	* @param options `shouldLoop`, `gain`, and an AbortSignal that stops the
2298	* clip
2299	*/
2300	play: (clip: AudioClip, options?: PlayOptions) => Promise<void>;
2301	/**
2302	* Speaks `text` with the platform's own synthesizer (`say` on macOS).
2303	* Plain text.
2304	*
2305	* Utterances are queued among themselves; clips are not. Resolves when
2306	* the utterance has ended; rejects, naming the cause, when there is no
2307	* synthesizer, the voice is not installed, or the utterance failed.
2308	*
2309	* @param text what to say, as plain text
2310	* @param options `voice`: the system voice's exact name (`Samantha`);
2311	* absent, the synthesizer's default
2312	* @returns which synthesizer spoke, once the utterance has ended
2313	*/
2314	speak: (text: string, options?: SpeakOptions) => Promise<SpeakResult>;
2315	};
2316	/**
2317	* The engine's connected MCP servers.
2318	*/
2319	mcp: {
2320	/**
2321	* Calls `tool` on one of the engine's connected MCP servers with the
2322	* engine's own connection and credentials.
2323	*
2324	* A `cached` server is dialed on first use. No permission prompt: the
2325	* plugin's call, seen by the hooks above it, is the grant. Positional, not
2326	* the `{ tool: "mcp__server__tool", ... }` shape a `tool.call` hook sees.
2327	*
2328	* @param server the server's name as /mcp lists it (`claude.ai Gmail`;
2329	* the tool-name spelling `claude_ai_Gmail` is accepted too)
2330	* @param tool the tool's name on that server (`create_draft`)
2331	* @param args the tool's arguments; none when absent
2332	* @returns the tool's result as MCP returns it: `content` blocks and
2333	* `isError`
2334	* @example
2335	* const { content } = await $.mcp.call("claude.ai Gmail", "create_draft", {
2336	* to: "team@example.com",
2337	* subject: "Release notes",
2338	* })
2339	*/
2340	call: (server: string, tool: string, args?: Record<string, unknown>) => Promise<McpToolResult>;
2341	};
2342	/**
2343	* The running session, read as plain data, and compacting it.
2344	*/
2345	session: {
2346	/**
2347	* Returns the transcript so far, one entry per user or assistant
2348	* message; progress rows, `$.ui.log` lines and notices are not messages.
2349	*
2350	* Each entry is a SessionMessage, `{ role, text, toolUses }` (a user
2351	* message may add `toolResults`; a `toolUses` entry adds its `result` and
2352	* `text` once answered). A long transcript answers its newest 4096.
2353	*
2354	* @example
2355	* const last = (await $.session.messages()).at(-1)
2356	*/
2357	messages: () => Promise<SessionMessage[]>;
2358	/**
2359	* Returns the directory the session runs in, absolute.
2360	*/
2361	cwd: () => Promise<string>;
2362	/**
2363	* Returns the session's project root, absolute: where it started, or
2364	* where `/cd`, a host's directory change or a worktree move took it.
2365	*
2366	* A shell `cd` during the session does not move it; nested instruction
2367	* files are read only beneath it.
2368	*/
2369	root: () => Promise<string>;
2370	/**
2371	* Returns the main loop's model, as `/model` shows it.
2372	*/
2373	model: () => Promise<string>;
2374	/**
2375	* Returns how many prompts the user has sent this session (user turns in
2376	* the transcript).
2377	*/
2378	turns: () => Promise<number>;
2379	/**
2380	* Returns the session's id (the transcript file's name).
2381	*/
2382	id: () => Promise<string>;
2383	/**
2384	* Returns the git repository the session runs in, read from the working
2385	* copy on each call; null when the directory is not inside one.
2386	*
2387	* @example
2388	* const repo = await $.session.repo(); const publicRepo = !repo?.internal
2389	*/
2390	repo: () => Promise<SessionRepo \| null>;
2391	/**
2392	* Returns every surface the session draws on, each once: `terminal` under
2393	* the REPL first, then the remote ones in the order they attached.
2394	*
2395	* A session may draw on several at once (a terminal and two phones):
2396	* clients attach (`session.attach`) and detach, and a render hook still
2397	* reads `e.surface` per ask. Empty in a plain -p run; never rejects.
2398	*
2399	* @example
2400	* const inApp = (await $.session.surfaces()).some(s => s !== "terminal")
2401	*/
2402	surfaces: () => Promise<readonly RenderSurface[]>;
2403	/**
2404	* Returns the first of `$.session.surfaces()`, or null where nothing
2405	* draws.
2406	*
2407	* @deprecated use `surfaces()`; a session may draw on several surfaces at
2408	* once
2409	*/
2410	surface: () => Promise<RenderSurface \| null>;
2411	/**
2412	* Returns the context window's fill, the rate-limit windows and the
2413	* cost, as the status line has them; with `breakdown`, by category too.
2414	*
2415	* The plain call costs nothing; `"full"` counts each category with the
2416	* token-count API as /context does, `"summary"` estimates locally, and
2417	* `context.breakdown` comes back in the SDK's `get_context_usage` shape.
2418	*
2419	* @param args `{ breakdown, columns }`: how the breakdown is counted and
2420	* the width its grid is drawn in; nothing for the status line's figures
2421	* @returns `{ context, rateLimits, cost }` as the status line has them
2422	* @example
2423	* const { context } = await $.session.usage()
2424	* if ((context.percent ?? 0) >= 85) await $.session.compact()
2425	* @example
2426	* const usage = await $.session.usage({ breakdown: "full", columns })
2427	* for (const row of usage.context.breakdown?.gridRows ?? []) draw(row)
2428	*/
2429	usage: (args?: SessionUsageArgs) => Promise<SessionUsage>;
2430	/**
2431	* Returns the version of the engine the session runs on, the release it
2432	* is built from, and when it was built.
2433	*
2434	* The same three values the engine's own analytics rows carry, answered
2435	* in every mode and build; `base` is absent when the version is not
2436	* spelled as a release, `builtAt` in a run from source that stamps none.
2437	*
2438	* @returns `{ version, base, builtAt }`: the full version, its release
2439	* (`2.1.280`, or `2.1.280-dev` for a development build) and an
2440	* ISO 8601 build time
2441	* @example
2442	* const { version, base, builtAt } = await $.session.version()
2443	* row.env = { version, version_base: base, build_time: builtAt }
2444	* @example
2445	* const isDevelopmentBuild = (await $.session.version()).base?.endsWith("-dev")
2446	*/
2447	version: () => Promise<SessionVersion>;
2448	/**
2449	* Compacts the conversation: the event `session.compact` with `trigger`
2450	* `plugin`, the same call `/compact` makes, between turns.
2451	*
2452	* It runs through every hook but the calling one, then core: a summary
2453	* and the kept messages in the transcript's place. Resolves `{ skip }`
2454	* when a hook vetoed it; rejects while a turn runs.
2455	*
2456	* @example
2457	* const { skip } = await $.session.compact({ instructions: "the plan" })
2458	*/
2459	compact: EventCalls['session']['compact'];
2460	/**
2461	* Appends a row to a conversation of the session: the event
2462	* `session.append`, the engine's own call for every row it keeps.
2463	*
2464	* A user-role row the person does not see as typed or a notice, of text
2465	* blocks alone in this release (else refused with the reason): listed at
2466	* once. `{ deny: reason }` when a plugin above refused it, nothing stored.
2467	*
2468	* @example
2469	* await $.session.append({ message: { type: "user", content: [note] } })
2470	*/
2471	append: (args: SessionAppendArgs) => Promise<SessionAppendResult>;
2472	/**
2473	* Holds the session's Anthropic credential on the host and answers an
2474	* opaque handle and its kind; the secret never reaches the plugin.
2475	*
2476	* The handle is spent through `$.http.fetch(url, { auth: handle })`,
2477	* which sets the credential header, only for a first-party host. Null
2478	* where the build or the provider has no first-party credential to hold.
2479	*
2480	* @example
2481	* await $.http.fetch(url, { auth: (await $.session.authorize())?.handle })
2482	*/
2483	authorize: () => Promise<SessionAuthorization>;
2484	};
2485	/**
2486	* The running model turn: ending it.
2487	*/
2488	turn: {
2489	/**
2490	* Cancels the running model turn: the one whose id `turn.start` handed
2491	* this plugin, its running tools stopped, no interruption marker.
2492	*
2493	* The event `turn.abort`, seen by the hooks above; the prompt this
2494	* plugin submits next is the context. Rejects, naming both ids, when
2495	* `turnId` is not the running turn's; a hook may end its own turn.
2496	*
2497	* @param input `turnId`: the id `turn.start` carried
2498	* @example
2499	* on("turn.start", ($, e, next) => { held = e.turnId; return next(e) })
2500	*/
2501	abort: (input: OpEventOf['turn.abort']) => Promise<void>;
2502	};
2503	/**
2504	* Submitting a prompt the model reads as a user turn, and the person's
2505	* prompt box: read as it stands, written, or proposed into.
2506	*/
2507	prompt: {
2508	/**
2509	* Submits a prompt: the event `prompt.submit`, the same call the engine
2510	* makes for a typed prompt; `input.text` runs when the session is idle.
2511	*
2512	* It goes through every hook but the calling one (the plugin's others
2513	* see it) with `e.origin` `{ kind: 'plugin', name }`, the name the
2514	* model reads it under unless a hook leaves it out of its answer.
2515	*
2516	* @example
2517	* void $.prompt.submit({ text: "List the TODOs you just mentioned." })
2518	*/
2519	submit: EventCalls['prompt']['submit'];
2520	/**
2521	* Returns the prompt box as it stands, the draft typed so far and the
2522	* cursor's offset into it, so a `fill` can keep what the person typed.
2523	*
2524	* Never rejects: `{ text: '', cursor: 0 }` where the session draws no box
2525	* (a -p run, an SDK host) or none is mounted yet.
2526	*
2527	* @example
2528	* const { text, cursor } = await $.prompt.read()
2529	*/
2530	read: () => Promise<PromptBox>;
2531	/**
2532	* Puts `input.text` in the prompt box as the draft, by `mode`: `replace`
2533	* (the default) over it, `append` after it, `insert` at the cursor.
2534	*
2535	* The event `prompt.fill` through the other plugins' hooks; `isFilled:
2536	* false` under a dialog or headless. To hand the model text WITH the next
2537	* prompt instead, a `prompt.submit` hook adds `context` (second example).
2538	*
2539	* @example
2540	* await $.prompt.fill({ text: `> ${quote}\n`, mode: "insert" })
2541	* @example
2542	* ($, e, next) => next({ ...e, context: [...(e.context ?? []), hunk] })
2543	*/
2544	fill: (input: PromptFillArgs) => Promise<PromptFilled>;
2545	/**
2546	* Proposes `input.text` as the prompt box's dim suggestion, Tab to take:
2547	* the event `prompt.suggest`, as the engine's own guess after a turn.
2548	*
2549	* It goes through every other plugin's hook with `e.origin` `{ kind:
2550	* 'plugin', name }`, the engine's own suggestions on or off; `{ isShown:
2551	* false }` while the box holds text, a turn runs, or headless (no box).
2552	*
2553	* @example
2554	* void $.prompt.suggest({ text: "run the tests you just wrote" })
2555	*/
2556	suggest: EventCalls['prompt']['suggest'];
2557	/**
2558	* Returns the system prompt's sections for `facts`: the event
2559	* `prompt.compose`, the call the engine makes for every prompt it sends.
2560	*
2561	* A fact left out is the session's own (its model, its tools). Through
2562	* every other plugin's hook, over the engine's own composition; composed
2563	* for nobody to send, so nothing the session holds is written.
2564	*
2565	* @example
2566	* const ids = (await $.prompt.compose()).sections.map(s => s.id)
2567	*/
2568	compose: EventCalls['prompt']['compose'];
2569	};
2570	/**
2571	* The tools the model has in this session, and running one.
2572	*/
2573	tool: {
2574	/**
2575	* Returns the tools the model can call now, built-in and MCP alike, in
2576	* the order the model sees them.
2577	*
2578	* @example
2579	* const names = (await $.tool.list()).map(t => t.name)
2580	*/
2581	list: () => Promise<ToolInfo[]>;
2582	/**
2583	* Calls a tool: the event `tool.call`, the same call the engine makes for
2584	* the model's tool calls, under a `tool_use_id` of its own.
2585	*
2586	* It runs through every hook but the calling one (the plugin's others
2587	* see it), the permission check and its dialog, then the tool. Rejects
2588	* when no tool has that name or the call is aborted.
2589	*
2590	* @example
2591	* const { text } = await $.tool.call({ tool: "Read", file_path: "a.md" })
2592	*/
2593	call: EventCalls['tool']['call'];
2594	/**
2595	* Asks the engine's permission decision for a tool call now: the event
2596	* `tool.check`, resolved to its verdict (`{ decision, reason?, ... }`).
2597	*
2598	* The hooks run (the calling hook's own frame skipped, `next.origin` this
2599	* plugin, no `tool_use_id`); nothing runs, no dialog opens, no PreToolUse
2600	* hook or classifier is asked.
2601	*
2602	* @example
2603	* const { decision } = await $.tool.check({ tool: "Read", input })
2604	*/
2605	check: EventCalls['tool']['check'];
2606	/**
2607	* Declares a tool the model can call from the next prompt on: the name,
2608	* description and input schema of `mcp__<plugin>__<name>`.
2609	*
2610	* Serve it with a `tool.call` hook on `{ tool: "mcp__<plugin>__<name>" }`
2611	* that returns the result (a call no hook answers fails); a name registered
2612	* again is replaced. Rejects until the session binds, at `session.start`.
2613	*
2614	* @param tool `name`, `description` (what the model reads), `inputSchema`
2615	* (a JSON schema object; default `{ type: "object" }`)
2616	* @returns `{ tool }`, the registered tool's full name
2617	* `mcp__<plugin>__<name>`
2618	* @example
2619	* await $.tool.register({ name: "weather", description: "Weather." })
2620	*/
2621	register: (tool: ToolSpec) => Promise<OpValueOf['tool.register']>;
2622	};
2623	/**
2624	* The slash commands the person can run in this session, and running one.
2625	*/
2626	command: {
2627	/**
2628	* Returns the slash commands the person can run now, built-in, plugin
2629	* and MCP alike, in the order the typeahead lists them.
2630	*
2631	* @example
2632	* const names = (await $.command.list()).map(c => c.name)
2633	*/
2634	list: () => Promise<CommandInfo[]>;
2635	/**
2636	* Runs a slash command as if the person typed `/command args`: the
2637	* event `command.run`, queued and run once the session is idle.
2638	*
2639	* It runs through every hook but the calling one with `e.origin`
2640	* `{ kind: 'plugin', name }`, its lines in the transcript. Rejects an
2641	* unknown name, and inside a hook the turn is waiting on.
2642	*
2643	* @example
2644	* const { text } = await $.command.run({ command: "status" })
2645	*/
2646	run: EventCalls['command']['run'];
2647	/**
2648	* Declares the slash command `/<name>` for this session, listed in the
2649	* typeahead from the next keystroke on.
2650	*
2651	* Serve it with a `command.run` hook on `{ command: "<name>" }` that
2652	* returns `{ text }`; a run no hook answers says so as its output.
2653	* Registering a name again replaces it; a built-in's name is refused.
2654	*
2655	* @param command `name`, `description` (what the menu shows),
2656	* `argumentHint` (dim after the name), `immediate` (runs mid-turn)
2657	* @returns `{ command }`, the registered name
2658	* @example
2659	* await $.command.register({ name: "hello", description: "Says hi." })
2660	*/
2661	register: (command: CommandSpec) => Promise<OpValueOf['command.register']>;
2662	};
2663	/**
2664	* Every row of the settings menu (`/config`), the panel's own and each
2665	* enabled plugin's `userConfig` fields alike: listing and changing them.
2666	*/
2667	config: {
2668	/**
2669	* Returns the rows the `/config` menu would draw now, in its order,
2670	* each with its current value, its kind, its owner and its lock.
2671	*
2672	* After every `config.describe` hook: a hidden row is left out, a
2673	* relabelled one carries the new label.
2674	*
2675	* @example
2676	* const theme = (await $.config.list()).find(row => row.key === "theme")
2677	*/
2678	list: () => Promise<ConfigRow[]>;
2679	/**
2680	* Changes one row as if the person did in the menu: the event
2681	* `config.set` with `origin` `{ kind: 'plugin', name }`, then the writer.
2682	*
2683	* Through the other plugins' hooks, this plugin's own skipped; `{ deny }`
2684	* when a hook refused, the value does not fit, a trusted source owns the
2685	* row or only its dialog changes it. Rejects a key no row has.
2686	*
2687	* @param args `key` (as `list` names it) and `value` (the row's kind)
2688	* @returns `{ value }` once written, or `{ deny }`
2689	* @example
2690	* const { deny } = await $.config.set({ key: "verbose", value: true })
2691	*/
2692	set: EventCalls['config']['set'];
2693	};
2694	/**
2695	* Subagents.
2696	*/
2697	agent: {
2698	/**
2699	* Spawns a subagent: the event `agent.spawn`, the same call the engine
2700	* makes when the Agent tool starts one; the engine fills the rest.
2701	*
2702	* It runs every hook but the calling one, then the Agent tool in the
2703	* background under this call's origin: `{ model, agentId }` once the
2704	* subagent started (its answer is its `turn.complete`), or `{ deny }`.
2705	*
2706	* @example
2707	* const { agentId } = await $.agent.spawn({ prompt: "Read README.md." })
2708	*/
2709	spawn: EventCalls['agent']['spawn'];
2710	/**
2711	* Returns the session's subagents so far, the ones the model spawned and
2712	* the ones plugins did alike.
2713	*/
2714	list: () => Promise<AgentInfo[]>;
2715	/**
2716	* Defines an agent type the Agent tool dispatches from the next turn on,
2717	* named `<plugin>:<name>`: the event `agent.register`.
2718	*
2719	* Every field takes effect as in an agent file; re-registered, a name is
2720	* replaced; unloaded, a plugin's types go. `agent.offer` hides it from
2721	* the model alone; any plugin's `$.agent.spawn` answers to `agent.spawn`.
2722	*
2723	* @param spec `name`, `description` (when to delegate), `prompt` (its
2724	* system prompt), and any other field of an agent definition
2725	* @returns `{ agent }`, the full name; rejects until the session binds,
2726	* on a spec the schema refuses (its reason), on a hook's deny
2727	* @example
2728	* await $.agent.register({ name: "runner", description: "Runs a spec",
2729	* prompt: RUNNER_PROMPT, tools: ["Read", "Bash"], omitClaudeMd: true })
2730	* @example
2731	* // runner-only: hidden from the model, spawned by this plugin's tool,
2732	* // answered by the subagent's turn.complete (matched by agentId)
2733	* on("agent.offer", { agent: "lab:runner" }, () => ({ isOffered: false }))
2734	* on("tool.call", { tool: "mcp__lab__run" }, async ($, e) => {
2735	* const { agentId, deny } = await $.agent.spawn({
2736	* subagentType: "lab:runner", prompt: e.spec, description: "run" })
2737	* return { result: deny ?? (await answerOf(agentId)) }
2738	* })
2739	*/
2740	register: (spec: AgentSpec) => Promise<OpValueOf['agent.register']>;
2741	};
2742	/**
2743	* The file system as the engine's own process reaches it; a relative path
2744	* is under the session's working directory, and text is UTF-8.
2745	*
2746	* An absolute path is used as given; where one may go is an `fs.*` hook's
2747	* to say. A read or write over 4 MiB rejects, a foreign network location
2748	* as spelled rejects untouched, and an OS refusal rejects with its errno.
2749	*/
2750	fs: {
2751	/**
2752	* Reads a file and returns its text, or with `{ as: "bytes" }` its bytes
2753	* as `{ base64 }`.
2754	*
2755	* Rejects when missing, or over 4 MiB, which bounds what one read copies
2756	* into the plugin's environment. A file the plugin ships is under
2757	* `$.plugin.root`.
2758	*
2759	* @param path relative to the working directory, or absolute
2760	* @param options `as`: `"text"` (the default) or `"bytes"`
2761	* @returns the file's text, or `{ base64 }`
2762	* @example
2763	* const readme = await $.fs.read("README.md")
2764	* @example
2765	* const { base64 } = await $.fs.read(
2766	* `${$.plugin.root}/hooks/weights.bin`, { as: "bytes" })
2767	* const weights = Uint8Array.fromBase64(base64)
2768	*/
2769	read: FsReadCall;
2770	/**
2771	* Writes `text` to a file, creating it and its directories as needed.
2772	*
2773	* @param path relative to the working directory, or absolute
2774	* @param text the whole new content
2775	*/
2776	write: (path: string, text: string) => Promise<void>;
2777	/**
2778	* Lists a directory: `{ name, kind, size, isLink }` per entry, by name,
2779	* each entry as it stands (a symbolic link is `other` with `isLink`).
2780	*
2781	* @param path the directory's path; absent, the working directory
2782	* @returns the entries, `{ name, kind, size, isLink }` each
2783	*/
2784	list: (path?: string) => Promise<FsEntry[]>;
2785	/**
2786	* Returns whether the path exists; rejects only a network location as
2787	* spelled, which no `fs` call reaches.
2788	*/
2789	exists: (path: string) => Promise<boolean>;
2790	/**
2791	* Returns `{ kind, size, mtimeMs, isLink }` of the path: what it leads to,
2792	* and whether it is itself a symbolic link. Rejects when missing.
2793	*
2794	* With `{ resolve: true }` also `realPath`, where the path lands, absent
2795	* when it leads nowhere; a guard matches it and denies without it, since a
2796	* spelling it cannot resolve (`~`, a file not there yet) the tool may open.
2797	*
2798	* @param path relative to the working directory, or absolute
2799	* @param options `resolve`: also answer `realPath` (one more file system
2800	* call)
2801	* @returns the stat, `realPath` with it when asked and resolvable; rejects
2802	* `ENOENT` for a missing path
2803	* @example
2804	* // ROOT was resolved the same way and SEP is its separator; an
2805	* // allow-list under it is the robust guard, a deny-list on spellings
2806	* // only best effort (a hard link or a case alias keeps its own)
2807	* on("tool.call", { tool: "Read" }, async ($, e, next) => {
2808	* const stat = await $.fs.stat(e.file_path, { resolve: true })
2809	* .catch(() => undefined)
2810	* const real = stat?.realPath
2811	* const isInside = real !== undefined && real.startsWith(ROOT + SEP)
2812	* return isInside ? next(e) : { deny: "outside the project" }
2813	* })
2814	* @example
2815	* // a Write may name a file not there yet: `placed` answers where the
2816	* // path lands or undefined, and the guard denies on undefined or
2817	* // outside ROOT. Unplaceable by spelling first, with no file system
2818	* // call (drive-relative `D:x`, a `\\` or `//` network or device path,
2819	* // a name that is empty, ".", ".." or itself `C:...`); then the file
2820	* // if it stats; else its folder, cut after the last separator and
2821	* // keeping it so a drive or share root stays that root, plus the name
2822	* const placed = async (path) => {
2823	* const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"))
2824	* const name = path.slice(cut + 1)
2825	* const isPlaceable = !/^[A-Za-z]:(?![\\/])/.test(path) &&
2826	* !/^[\\/][\\/]/.test(path) && !/^[A-Za-z]:/.test(name) &&
2827	* name !== "" && name !== "." && name !== ".."
2828	* if (!isPlaceable) return undefined
2829	* const own = await $.fs.stat(path, { resolve: true })
2830	* .catch(() => undefined)
2831	* if (own) return own.realPath
2832	* const folder = cut < 0 ? "." : path.slice(0, cut + 1)
2833	* const dir = await $.fs.stat(folder, { resolve: true })
2834	* .catch(() => undefined)
2835	* return dir?.realPath === undefined ? undefined
2836	* : `${dir.realPath.replace(/[\\/]$/, "")}${SEP}${name}`
2837	* }
2838	* const real = await placed(e.file_path)
2839	* const isInside = real !== undefined && real.startsWith(ROOT + SEP)
2840	* return isInside ? next(e) : { deny: "cannot place it, or outside" }
2841	*/
2842	stat: (path: string, options?: FsStatOptions) => Promise<FsStat>;
2843	/**
2844	* Reads the named instruction files in every directory above the
2845	* session's original working directory, the way the engine reads CLAUDE.md.
2846	*
2847	* Root first, each `{ dir, name, content }` that exists, the content
2848	* with its `@include`s after it; `of` and `below` together are the
2849	* engine's own walk for a nested CLAUDE.md between root and read file.
2850	*
2851	* @param request `names`, relative `.md` file names (no `..`); `of`, the
2852	* file walked down to; `below`, the directory the walk stays inside
2853	* @returns the files found, root first
2854	* @example
2855	* const found = await $.fs.ancestors({ names: ["AGENTS.md"] })
2856	* const stack = await $.fs.ancestors({ names: ["AGENTS.md"], of: path })
2857	* const nested = await $.fs.ancestors({
2858	* names: ["AGENTS.md"],
2859	* of: e.file_path,
2860	* below: await $.session.root(),
2861	* })
2862	*/
2863	ancestors: (request: FsAncestorsRequest) => Promise<readonly FsAncestor[]>;
2864	};
2865	/**
2866	* This plugin's own key-value store, kept between sessions and hot
2867	* reloads; values are JSON data.
2868	*
2869	* A JSON file of the plugin's own under the user's Claude Code
2870	* configuration directory.
2871	*/
2872	store: {
2873	/**
2874	* Returns the value under `key`, or `undefined` when unset.
2875	*
2876	* @example
2877	* const count = Number((await $.store.get("count")) ?? 0) + 1
2878	*/
2879	get: (key: string) => Promise<unknown>;
2880	/**
2881	* Sets `key` to `value`, which must be JSON data.
2882	*
2883	* `get` reads back `JSON.parse(JSON.stringify(value))`: a Date is its ISO
2884	* string, an `undefined` field is dropped, a Map or Set is `{}`. Rejects
2885	* a function, a cycle, or a store over 4 MiB of JSON text in all.
2886	*/
2887	set: (key: string, value: unknown) => Promise<void>;
2888	/**
2889	* Removes `key` from the store.
2890	*/
2891	delete: (key: string) => Promise<void>;
2892	/**
2893	* Returns every key set, in insertion order.
2894	*/
2895	keys: () => Promise<string[]>;
2896	};
2897	/**
2898	* The time and timers, each an event through the host: `clock.now` reads
2899	* the time; `clock.sleep`, `after` and `every` wait until it has passed.
2900	*
2901	* A timer's callback is the plugin's own function, kept in its environment
2902	* and run there when the wait resolves; a hot reload of the plugin cancels
2903	* its pending waits with the old environment.
2904	*/
2905	clock: {
2906	/**
2907	* Resolves milliseconds since the epoch, now.
2908	*
2909	* @example
2910	* const startedAt = await $.clock.now()
2911	*/
2912	now: () => Promise<number>;
2913	/**
2914	* Resolves after `ms` milliseconds; rejects at once when `signal` aborts.
2915	*
2916	* @param ms how long, in milliseconds
2917	* @param options `signal`: ends the wait early with a rejection (pass
2918	* `next.signal` so a hook's wait ends with its dispatch)
2919	* @example
2920	* await $.clock.sleep(500, { signal: next.signal })
2921	*/
2922	sleep: (ms: number, options?: SleepOptions) => Promise<void>;
2923	/**
2924	* Calls `fn` once after `ms` milliseconds; `cancel()` before then stops it.
2925	*
2926	* One `clock.after` dispatch: `fn` runs when it resolves, and never when
2927	* a hook refuses it.
2928	*/
2929	after: TimerCall;
2930	/**
2931	* Calls `fn` every `ms` milliseconds (at least 1) until `cancel()`.
2932	*
2933	* One `clock.every` dispatch per period: `fn` runs when it resolves and
2934	* the next period is asked; a refused period ends the interval.
2935	*
2936	* @example
2937	* const tick = $.clock.every(1000, () => $.ui.status("polling"))
2938	*/
2939	every: TimerCall;
2940	};
2941	/**
2942	* The network, through the host.
2943	*/
2944	http: {
2945	/**
2946	* Fetches `url` through the host (never the plugin's own network) and
2947	* resolves `{ status, ok, headers, text }` once the body is read.
2948	*
2949	* http or https, to whatever the host process can reach, unless the
2950	* administrator's policy switches refuse it; an `auth` handle from
2951	* `$.session.authorize()` rides https only, to a first-party host.
2952	*
2953	* @param url the URL (http or https)
2954	* @param init `{ method, headers, body, auth, socketPath }` (body a
2955	* string; socketPath a Unix socket to go over instead of TCP)
2956	* @returns `{ status, ok, headers, text }` once the body is read
2957	* @example
2958	* const { ok, text } = await $.http.fetch("https://example.com/status")
2959	* @example
2960	* await $.http.fetch("http://bridge/reload", {
2961	* method: "POST",
2962	* socketPath: `${runDirectory}/bridge.sock`,
2963	* })
2964	*/
2965	fetch: (url: string, init?: HttpInit) => Promise<HttpResponse>;
2966	};
2967	/**
2968	* Commands on the host, run as the user the session runs as. CLI only.
2969	*
2970	* Local execution, not a network path: what a command of its own reaches
2971	* is its own, as for the Bash tool and a settings `command` hook.
2972	*/
2973	process: {
2974	/**
2975	* Runs a command on the host by its argument vector (no shell) and
2976	* resolves `{ exitCode, stdout, stderr }` once it exits, any exit code.
2977	*
2978	* One shot: the whole output is read, so a background process left
2979	* writing holds the call until the timeout. Rejects when the command
2980	* cannot start or is still running then. Git runs with repo hooks off.
2981	*
2982	* @param argv the command and its arguments, `argv[0]` the executable
2983	* @param init `{ cwd, env, stdin, timeoutMs }` (cwd the session's by
2984	* default; timeout 30 s by default, ten minutes at most)
2985	* @returns `{ exitCode, stdout, stderr }` once the child exits
2986	* @example
2987	* const { exitCode, stdout } = await $.process.run(["git", "status"])
2988	*/
2989	run: (argv: readonly string[], init?: ProcessRunInit) => Promise<ProcessRunResult>;
2990	};
2991	/**
2992	* What the settings files, `--settings` and managed policy hold, as the
2993	* engine runs under it; read only.
2994	*
2995	* Every key crosses as the source holds it, `env` and the helper commands
2996	* included: nothing is filtered. The OAuth session and the global config
2997	* (~/.claude.json) are not settings and are never read.
2998	*/
2999	settings: {
3000	/**
3001	* Resolves with the settings merged over every source, as the engine
3002	* reads them, or with one source's settings as loaded (`{ source }`).
3003	*
3004	* A snapshot in plain data each call; a source with no file answers
3005	* `{}`. The sources (SettingsSource) rise in precedence from `user` to
3006	* `policy`: the merge takes a key from the last source that has it.
3007	*
3008	* @param args `{ source }` to read one source; nothing for the merge
3009	* @returns the settings object, keyed as a settings.json is
3010	* @example
3011	* const { permissions } = await $.settings.read()
3012	* const policy = await $.settings.read({ source: "policy" })
3013	*/
3014	read: (args?: SettingsReadArgs) => Promise<Settings>;
3015	};
3016	/**
3017	* The environment of this process, the one every Bash child, MCP server
3018	* and `$.process.run` command started after inherits.
3019	*
3020	* `get` and `set` take the variable's name as a string literal, so what a
3021	* module reads and writes is read off its source: `claude plugin validate`
3022	* lists the names, and a name the module does not spell is refused.
3023	*/
3024	env: {
3025	/**
3026	* Resolves with the variable's value, or `undefined` when it is unset.
3027	*
3028	* `name` must be a string literal; `claude plugin validate` lists the
3029	* names your module reads and writes.
3030	*
3031	* @example
3032	* const home = await $.env.get("HOME")
3033	*/
3034	get: (name: string) => Promise<string \| undefined>;
3035	/**
3036	* Sets the variable for this process and everything it starts after, or
3037	* unsets it when `value` is `undefined`.
3038	*
3039	* `name` must be a string literal; `claude plugin validate` lists the
3040	* names your module reads and writes.
3041	*
3042	* @example
3043	* await $.env.set("GIT_PAGER", "cat")
3044	*/
3045	set: (name: string, value: string \| undefined) => Promise<void>;
3046	};
3047	}
3048
3049	/**
3050	* The name of an event the engine defines itself (a key of CoreEventOf);
3051	* EventName adds the declared plugin nouns' events.
3052	*/
3053	type CoreEventName = keyof CoreEventOf;
3054
3055	/**
3056	* The argument of each event the engine defines itself: its call sites'
3057	* (EngineEventOf), the classic hooks' (ClassicEventOf), the calls on `$`.
3058	*/
3059	type CoreEventOf = EngineEventOf & ClassicEventOf & OpEventOf;
3060
3061	type CwdChangedHookInput = BaseHookInput & {
3062	hook_event_name: 'CwdChanged';
3063	old_cwd: string;
3064	new_cwd: string;
3065	};
3066
3067	type DirectoryAddedHookInput = BaseHookInput & {
3068	hook_event_name: 'DirectoryAdded';
3069	/**
3070	* Absolute path of the directory that was added.
3071	*/
3072	directory: string;
3073	/**
3074	* How the directory was added: "slash_command" for /add-dir, "register_repo_root" for the SDK control_request.
3075	*/
3076	source: 'slash_command' \| 'register_repo_root';
3077	};
3078
3079	/**
3080	* The `children` field every element constructor's props carry, appended
3081	* beside its own props type: one child, or a list that may nest.
3082	*
3083	* JSX types a lone child as the child itself (`<Text dimColor>done</Text>`
3084	* passes the string, `<Text>{count}</Text>` the number), and a mapped list
3085	* beside a sibling as a nested list (`<Box>{rows.map(row)}<Text>ok</Text>`).
3086	*/
3087	export type ElementChildren = {
3088	children?: RenderChildren;
3089	};
3090
3091	/**
3092	* An element as `$.ui.resolve(e)` hands it out: a constructor from props to
3093	* the frozen plain-data element, `children` among the props as JSX passes.
3094	*
3095	* `const { Box } = $.ui.resolve(e)` then `<Box gap={1}>...</Box>` compiles to
3096	* `h(Box, { gap: 1 }, ...children)`, and `h` calls a function tag with its
3097	* props, so the table's constructors are the JSX tags.
3098	*/
3099	export type ElementConstructor<P> = (props: P & ElementChildren) => RenderElement;
3100
3101	/**
3102	* Every element name of every surface: what a table handed out is completed to
3103	* (an omitted one draws a fragment; see `ui.resolve`).
3104	*/
3105	export type ElementName = {
3106	[P in RenderSurface]: keyof Elements[P];
3107	}[RenderSurface];
3108
3109	/**
3110	* The element constructors each surface draws, by `e.surface`: what
3111	* `$.ui.resolve(e)` returns and a `ui.resolve` hook passes on; no globals.
3112	*
3113	* All carry `Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`; every remote
3114	* surface `Svg`; all but mobile `Input` and `Select`; terminal and desktop
3115	* `Client`; terminal `Raster` and `Image`. Narrowed on `e.surface`, that table.
3116	*/
3117	export type Elements = {
3118	terminal: {
3119	Box: ElementConstructor<BoxProps>;
3120	Text: ElementConstructor<TextProps>;
3121	Button: ElementConstructor<ButtonProps>;
3122	Input: ElementConstructor<InputProps>;
3123	Select: ElementConstructor<SelectProps>;
3124	Link: ElementConstructor<LinkProps>;
3125	Code: ElementConstructor<CodeProps>;
3126	Markdown: ElementConstructor<MarkdownProps>;
3127	/**
3128	* A region one of the plugin's surface modules draws (ClientModule), named
3129	* by `module`: a string literal, the module's path relative to this file.
3130	*
3131	* The engine reads the surface module off the hooks module's source
3132	* before anything runs, so a variable, a template with a substitution or
3133	* a computed path as `module` is refused at load, naming the line.
3134	*/
3135	Client: ElementConstructor<ClientProps>;
3136	Raster: ElementConstructor<RasterProps>;
3137	Image: ElementConstructor<ImageProps>;
3138	};
3139	desktop: {
3140	Box: ElementConstructor<BoxProps>;
3141	Text: ElementConstructor<TextProps>;
3142	Button: ElementConstructor<ButtonProps>;
3143	Input: ElementConstructor<InputProps>;
3144	Select: ElementConstructor<SelectProps>;
3145	Svg: ElementConstructor<SvgProps>;
3146	Link: ElementConstructor<LinkProps>;
3147	Code: ElementConstructor<CodeProps>;
3148	Markdown: ElementConstructor<MarkdownProps>;
3149	Client: ElementConstructor<ClientProps>;
3150	};
3151	/**
3152	* No `Input` or `Select`: the control protocol carries presses (ui_press)
3153	* but no ui_input or ui_select yet; not a limit of the device.
3154	*
3155	* The table grows when those messages exist.
3156	*/
3157	mobile: {
3158	Box: ElementConstructor<BoxProps>;
3159	Text: ElementConstructor<TextProps>;
3160	Button: ElementConstructor<ButtonProps>;
3161	Svg: ElementConstructor<SvgProps>;
3162	Link: ElementConstructor<LinkProps>;
3163	Code: ElementConstructor<CodeProps>;
3164	Markdown: ElementConstructor<MarkdownProps>;
3165	};
3166	/**
3167	* The desktop's table without `Client`: a remote `Client`'s module, presses
3168	* and posts (ui_client_module, ui_client_press, ui_message) name no surface.
3169	*
3170	* They are the desktop's alone today, not a limit of the editor's webview:
3171	* the table gains `Client` when those asks name a surface.
3172	*/
3173	vscode: {
3174	Box: ElementConstructor<BoxProps>;
3175	Text: ElementConstructor<TextProps>;
3176	Button: ElementConstructor<ButtonProps>;
3177	Input: ElementConstructor<InputProps>;
3178	Select: ElementConstructor<SelectProps>;
3179	Svg: ElementConstructor<SvgProps>;
3180	Link: ElementConstructor<LinkProps>;
3181	Code: ElementConstructor<CodeProps>;
3182	Markdown: ElementConstructor<MarkdownProps>;
3183	};
3184	};
3185
3186	/**
3187	* The table `ui.resolve` answers for an argument of surface `P`.
3188	*/
3189	export type ElementTable<P extends RenderSurface = RenderSurface> = Elements[P];
3190
3191	/**
3192	* 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.
3193	*/
3194	type ElicitationHookInput = BaseHookInput & {
3195	hook_event_name: 'Elicitation';
3196	mcp_server_name: string;
3197	message: string;
3198	mode?: 'form' \| 'url';
3199	url?: string;
3200	elicitation_id?: string;
3201	requested_schema?: Record<string, unknown>;
3202	};
3203
3204	/**
3205	* 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.
3206	*/
3207	type ElicitationResultHookInput = BaseHookInput & {
3208	hook_event_name: 'ElicitationResult';
3209	mcp_server_name: string;
3210	elicitation_id?: string;
3211	mode?: 'form' \| 'url';
3212	action: 'accept' \| 'decline' \| 'cancel';
3213	content?: Record<string, unknown>;
3214	};
3215
3216	/**
3217	* The input of `engine.create`: the fold that builds `$`, once per load,
3218	* core innermost.
3219	*
3220	* A hook is written in post-order: `const built = await next(e)` is `$` as
3221	* built so far; `return { ...built, voice: { say } }` adds this plugin's noun.
3222	* See EngineEventOf's `engine.create` for what a step may and may not do.
3223	*/
3224	export type EngineCreateInput = {
3225	/**
3226	* The modules this fold builds, in list order, first outermost (managed
3227	* plugins first, so an org plugin's withholding wins).
3228	*
3229	* The whole set at a load, this plugin alone at its reload, the ones added
3230	* or changed at a refresh that keeps the rest: a module added later that
3231	* does not hook this event is built against the table as it stands.
3232	*/
3233	plugins: readonly string[];
3234	};
3235
3236	/**
3237	* What an `engine.create` hook returns: `$` as built so far with this
3238	* plugin's nouns added, less any it withheld.
3239	*
3240	* Every declared noun is optional here. Between hooks it crosses the chain
3241	* as interface descriptors; a hook sees objects (EngineInterfaceBuilt).
3242	*/
3243	export type EngineCreateResult = Partial<EngineInterface> & {
3244	readonly [noun: string]: unknown;
3245	};
3246
3247	/**
3248	* The events the engine raises at its call sites, and `engine.create`; the
3249	* classic settings hooks' events are ClassicEventOf.
3250	*
3251	* At every one, a hook that fails (throws, overruns its budget: HookBudget,
3252	* answers a wrong shape) is skipped: the hooks beneath and core run in its
3253	* place, or its last `next` result stands; the failure is reported by name.
3254	*/
3255	export type EngineEventOf = {
3256	/**
3257	* Fires when the engine is about to run a tool. `next(e)` runs the hooks
3258	* beneath, then core (the permission prompt, the tool itself).
3259	*
3260	* Return `{ deny: reason }` to refuse or `{ result }` to answer yourself; a
3261	* hook that returns while its `next` is pending aborts what runs beneath.
3262	* The managed-settings hooks run first: their deny is the call's result.
3263	*/
3264	'tool.call': ToolCallInput;
3265	/**
3266	* Fires when the engine decides whether a tool call may run, after the
3267	* `tool.call` and PreToolUse hooks and before the mode settles an ask.
3268	*
3269	* `next(e)` resolves to the engine's verdict (rules, mode, the tool's own
3270	* check, PreToolUse's decision); return any `{ decision }`. `$.tool.check`
3271	* runs the same chain and executes nothing.
3272	*
3273	* @example
3274	* on("tool.check", { tool: "Read" }, () => ({ decision: "allow" }))
3275	*/
3276	'tool.check': ToolCheckInput;
3277	/**
3278	* Fires when the engine is about to draw a component: once per input value
3279	* (props, viewport width), plugin load or `$.ui.invalidate("ui.render")`.
3280	*
3281	* A repaint reuses the answer; a clock invalidates. `next(e)` resolves to the
3282	* drawing: return it, wrap it, draw your own, or rewrite `props`. A tree that
3283	* does not validate draws the engine's own; `--plugin-dir` is told why.
3284	*/
3285	'ui.render': RenderInput;
3286	/**
3287	* Fires when the plugins load (not per draw), once per surface, component
3288	* and plugin: `e` names the surface and component, never the props.
3289	*
3290	* `next(e)` resolves to the surface's table, which `$.ui.resolve(e)` then
3291	* reads. Return it, one with an element restyled for every other plugin,
3292	* or one with a key left out (a fragment there); own table: hook skipped.
3293	*/
3294	'ui.resolve': ResolveInput;
3295	/**
3296	* Fires when a `Button` a render hook drew is pressed on a surface; `e` is
3297	* `{ plugin, element, component, surface }`, `element` the button's `key`.
3298	*
3299	* `next(e)` runs the hooks beneath, then core: the element's own `onPress`
3300	* closure, in its plugin's environment, resolving to `{ element }`. Return
3301	* `next(e)` to let the press through, or `{ element }` to take it.
3302	*/
3303	'ui.press': UiPressArgument;
3304	/**
3305	* Fires when an `Input` a render hook drew changes or is submitted; `e` is
3306	* `{ plugin, element, component, surface, kind, value }`.
3307	*
3308	* `next(e)` runs the hooks beneath, then the element's own `onInput` or
3309	* `onSubmit` with `e.value` as the chain left it, resolving to `{ element,
3310	* value }`; `next({ ...e, value })` rewrites the typing, an answer takes it.
3311	*/
3312	'ui.input': UiInputArgument;
3313	/**
3314	* Fires when a `Select` a render hook drew is picked from; `e` is
3315	* `{ plugin, element, component, surface, value }`.
3316	*
3317	* `next(e)` runs the hooks beneath, then the element's own `onSelect` with
3318	* `e.value` as the chain left it, resolving to `{ element, value }`;
3319	* `next({ ...e, value })` rewrites the pick, an answer takes it.
3320	*/
3321	'ui.select': UiSelectArgument;
3322	/**
3323	* Fires when a `Client` THIS plugin drew posts from its surface module
3324	* (`surface.post(data)`); only this plugin's hooks see it.
3325	*
3326	* `next.origin` names `client`: `data` came from code. Core answers `{}`;
3327	* `next({ ...e, data })` rewrites the data; `{ props }` hands the posting
3328	* instance its next props without a redraw. One per instance per frame.
3329	*/
3330	'ui.message': UiMessageArgument;
3331	/**
3332	* Fires before a site's window moves: the person's wheel or scroll keys on
3333	* a `Pane` body or the `AbovePrompt` band, at its edges too; `$.ui.scroll`.
3334	*
3335	* `next(e)` moves it to `e.offset` and draws: `{}`; `next({ ...e, offset
3336	* })` elsewhere; no `next` (`{}` or `{ deny }`) leaves it undrawn, so a hook
3337	* drawing its own rows under a header moves them by `e.by` and invalidates.
3338	*
3339	* @example
3340	* on("ui.scroll", { requestId: "log" }, ($, e) => (scrollOwnRows(e.by), {}))
3341	*/
3342	'ui.scroll': UiScrollInput;
3343	/**
3344	* Fires before a site's focus ring moves: the person's Tab, arrows or click
3345	* in a `Pane` or the band; an `autoFocus` element taking it; `$.ui.focus`.
3346	*
3347	* `next(e)` lands it on `e.element` (absent: one of the engine's stops) and
3348	* draws: `{}`; `next({ ...e, element })` on another of `e.plugin`'s; no
3349	* `next` (`{}` or `{ deny }`) keeps it where it was, drawn as it was.
3350	*
3351	* @example
3352	* on("ui.focus", { requestId: "list" }, ($, e, next) => (mark(e), next(e)))
3353	*/
3354	'ui.focus': UiFocusInput;
3355	/**
3356	* Fires when the engine offers an agent type to the model, in the agent
3357	* listing and again at dispatch; `next(e)` resolves to `{ isOffered: true }`.
3358	*
3359	* Return `{ isOffered: false }` to keep the type out of the listing and
3360	* refuse its dispatch. A hook that fails passes it through.
3361	*
3362	* @example
3363	* on("agent.offer", { agent: "Plan" }, () => ({ isOffered: false }))
3364	*/
3365	'agent.offer': AgentOfferInput;
3366	/**
3367	* Fires when the Agent tool is about to start a subagent, everything
3368	* decided and its model not yet resolved.
3369	*
3370	* `next(e)` resolves to `{ model }`. Return it, `next({ ...e, model })`,
3371	* `{ model }` of your own (an alias resolves like the tool's parameter), or
3372	* `{ deny: reason }`.
3373	*/
3374	'agent.spawn': AgentSpawnInput;
3375	/**
3376	* Fires when a prompt is submitted, before the turn starts. `next(e)` runs
3377	* the hooks beneath and the UserPromptSubmit settings hooks.
3378	*
3379	* Rewrite with `next({ ...e, text })` (the user message on screen follows)
3380	* or stop it with `{ drop: reason }`; a broken plugin never blocks a prompt.
3381	* A prompt typed while a turn ran fires at Enter, with that turn's id.
3382	*/
3383	'prompt.submit': PromptSubmitInput;
3384	/**
3385	* Fires when a text is about to be put in the prompt box as the person's
3386	* draft (a plugin's `$.prompt.fill`); `next(e)` writes it by `e.mode`.
3387	*
3388	* `replace` over the draft, `append` after it, `insert` at the cursor;
3389	* rewrite `text` or `mode` going down, or answer `{ isFilled: false }`
3390	* without `next` to keep it out, as core does under a dialog or headless.
3391	*
3392	* @example
3393	* on("prompt.fill", ($, e, next) => next({ ...e, text: e.text.trim() }))
3394	*/
3395	'prompt.fill': PromptFillInput;
3396	/**
3397	* Fires when a text is proposed as the prompt box's dim suggestion, Tab to
3398	* take: the engine's guess after a turn, or a plugin's `$.prompt.suggest`.
3399	*
3400	* `next(e)` shows it: `{ isShown }`. Rewrite with `next({ ...e, text })`,
3401	* or answer `{ isShown: false }` without `next` to drop it; core answers
3402	* that too while the box holds text or a turn runs.
3403	*
3404	* @example
3405	* on("prompt.suggest", { origin: { kind: "suggestion" } }, hide)
3406	*/
3407	'prompt.suggest': PromptSuggestInput;
3408	/**
3409	* Fires when the person edits the main prompt box: a key the editor took as
3410	* an edit, or a paste; `next(e)` resolves the box the editor shows.
3411	*
3412	* `e` is the draft before and the splice (`start`, `end`, `inputText`); a
3413	* burst of keys is one edit. Rewrite `inputText` going down or the box
3414	* coming up; `{ text: e.text, cursor: e.cursor }` without `next` consumes.
3415	*
3416	* @example
3417	* on("prompt.edit", ($, e, next) => next({ ...e, inputText: up(e) }))
3418	*/
3419	'prompt.edit': PromptEditInput;
3420	/**
3421	* Fires once per named section of the system prompt, when the engine
3422	* assembles it; `next(e)` resolves to `{ text }` as core computed it.
3423	*
3424	* Sections are cached by name for the session until
3425	* `$.ui.invalidate("prompt.section")`: an unstable answer spends the
3426	* model's prompt cache on every call. A hook that fails passes it through.
3427	*
3428	* @example
3429	* on("prompt.section", { name: "memory" }, () => ({ text: null }))
3430	*/
3431	'prompt.section': PromptSectionInput;
3432	/**
3433	* Fires once per conversation, when the engine computes the context blocks
3434	* its first user message carries; `next(e)` resolves to `{ blocks }`.
3435	*
3436	* Append, drop, reorder or rewrite with `next({ ...e, blocks })`; the
3437	* engine renders what comes back, in order, until
3438	* `$.ui.invalidate("prompt.context")` or a re-read (compaction, `/clear`).
3439	*
3440	* @example
3441	* on("prompt.context", () => ({ blocks: [] }))
3442	*/
3443	'prompt.context': PromptContextInput;
3444	/**
3445	* Fires when the engine renders a system prompt; `next(e)` resolves to
3446	* `{ sections }`, each `{ id, text, scope }`, in the order they are sent.
3447	*
3448	* The bottom is the engine's own composition (`intro`, `tools`, `memory`,
3449	* ...). Append, replace by id, reorder or drop what `next(e)` answered;
3450	* answer without `next` to replace it all. The engine places each cache mark.
3451	*
3452	* @example
3453	* on("prompt.compose", async ($, e, next) => dropped(await next(e), "tone"))
3454	*/
3455	'prompt.compose': PromptComposeInput;
3456	/**
3457	* Fires once per message the engine injects for the model on its own (a
3458	* reminder, a mode transition, a mentioned file), as a request carries it.
3459	*
3460	* `next(e)` resolves to `{ text }`; `{ text: null }` leaves it out. The
3461	* answer holds per attachment for the process (asked again on resume or
3462	* `$.ui.invalidate`); the transcript keeps the engine's record.
3463	*
3464	* @example
3465	* on("prompt.attachment", { type: "todo_reminder" }, () => ({ text: null }))
3466	*/
3467	'prompt.attachment': PromptAttachmentInput;
3468	/**
3469	* Fires once per tool, when the engine first renders the tool's schema in
3470	* a session; `next(e)` resolves to `{ description, isDeferred? }`.
3471	*
3472	* Cached for the session until `$.ui.invalidate("tool.describe")`: an
3473	* unstable answer spends the model's prompt cache. An explicit `isDeferred`
3474	* moves the tool behind ToolSearch (true) or into the prompt's list (false).
3475	*
3476	* @example
3477	* on("tool.describe", { tool: "Bash" }, ($, e) => ({ ...e, description }))
3478	* @example
3479	* on("tool.describe", { tool: "Monitor" }, pin) // {...e, isDeferred: false}
3480	*/
3481	'tool.describe': ToolDescribeInput;
3482	/**
3483	* Fires when a slash command is about to run (`/name args` typed, or a
3484	* plugin's `$.command.run`); `next(e)` resolves to `{ text }`, its output.
3485	*
3486	* Core is the engine's command (a registered one has none). Rewrite `args`
3487	* with `next`, or return `{ text }` without it to answer in its place; one
3488	* after `next` replaces a printed output, not a panel or prompt it opened.
3489	*
3490	* @example
3491	* on("command.run", { command: "hello" }, () => ({ text: "hello" }))
3492	*/
3493	'command.run': CommandRunInput;
3494	/**
3495	* Fires once per command, when the engine lists it for the typeahead and
3496	* `/help`; `next(e)` resolves to `{ description, argumentHint, isHidden }`.
3497	*
3498	* Listed answers are cached for the session until
3499	* `$.ui.invalidate("command.describe")`. A hook that fails passes it
3500	* through.
3501	*
3502	* @example
3503	* on("command.describe", ($, e, next) => next({ ...e, isHidden: true }))
3504	*/
3505	'command.describe': CommandDescribeInput;
3506	/**
3507	* Fires when a `/config` row is about to change, from the menu or a
3508	* plugin's `$.config.set`; `next(e)` resolves to `{ value }` once written.
3509	*
3510	* Return `{ deny: reason }` to leave the row as it is (the menu says why),
3511	* or `next({ ...e, value })` to clamp it; a value of the wrong kind for
3512	* the row is refused. A row a trusted source owns is core's to refuse.
3513	*
3514	* @example
3515	* on("config.set", { key: "theme" }, () => ({ deny: "the theme stays" }))
3516	*/
3517	'config.set': ConfigSetInput;
3518	/**
3519	* Fires once per `/config` row, when the menu lists it and for
3520	* `$.config.list`; `next(e)` resolves to `{ label, description, isHidden }`.
3521	*
3522	* Relabel, re-describe or hide with `next({ ...e, isHidden: true })`; the
3523	* answers are cached until `$.ui.invalidate("config.describe")` or the
3524	* loaded plugins change. A hook that fails passes the row through.
3525	*
3526	* @example
3527	* on("config.describe", { key: "tips" }, hide) // answers isHidden: true
3528	*/
3529	'config.describe': ConfigDescribeInput;
3530	/**
3531	* Fires when the engine expands a skill's prompt for the model (`/name`,
3532	* the Skill tool, a preload); `next(e)` resolves to `{ text }` as computed.
3533	*
3534	* Return `{ text }` with the text the model reads instead. A hook that
3535	* fails passes it through.
3536	*
3537	* @example
3538	* on("skill.prompt", { skill: "commit" }, () => ({ text: "A haiku." }))
3539	*/
3540	'skill.prompt': SkillPromptInput;
3541	/**
3542	* Fires when the engine composes a git text the model is to write (`kind`:
3543	* `commit`, `pr`, `exemption`, `remedy`); `next(e)` resolves to `{ text }`.
3544	*
3545	* Return `{ text }` with the text the model reads instead. A hook that
3546	* fails passes it through.
3547	*
3548	* @example
3549	* on("attribution.text", { kind: "commit" }, () => ({ text: "" }))
3550	*/
3551	'attribution.text': AttributionTextInput;
3552	/**
3553	* Fires once per process for each loaded plugin, before the first prompt,
3554	* then once per fresh load of one (never `/clear`); `next(e)` is `{ cwd }`.
3555	*
3556	* Observe. The first is awaited: a `$.tool.register` is listed by turn one.
3557	* A later one runs its hooks alone: an enable, a worker respawn, or a reload
3558	* (changed modules only; all if one hooks `engine.create`/`plugin.register`).
3559	*
3560	* @example
3561	* on("session.start", ($, e, next) => $.tool.register(t).then(() => next(e)))
3562	*/
3563	'session.start': SessionStartInput;
3564	/**
3565	* Fires when a delivery reaches the session (a relay's event, a peer's
3566	* message, a Remote Control prompt), before it is queued; `{ text }`.
3567	*
3568	* Rewrite with `next({ ...e, text })`, or return `{ consumed: reason }` to
3569	* take it: nothing is queued, shown or read by the model. `origin` and
3570	* `event` pass on as received; `session.send`, its dual, is reserved.
3571	*
3572	* @example
3573	* on("session.receive", { origin: "peer" }, () => ({ consumed: "muted" }))
3574	*/
3575	'session.receive': SessionReceiveInput;
3576	/**
3577	* Fires once per row a conversation of this session keeps (a prompt, a
3578	* response block, a tool result, a notice), before it is stored.
3579	*
3580	* `next({ ...e, message })` rewrites `content`: stored and sent after. The
3581	* screen, an SDK stream or Remote Control may show the row just before its
3582	* rewrite; the model and the transcript file never read that form.
3583	*
3584	* @example
3585	* on("session.append", { door: "tool-result" }, ($, e, n) => n(scrub(e)))
3586	*/
3587	'session.append': SessionAppendInput;
3588	/**
3589	* Fires when the conversation is about to be compacted (`/compact`, the
3590	* threshold, a plugin, or ahead of time); `next(e)` resolves `{ messages }`.
3591	*
3592	* Rewrite `instructions` or `messages` on the way down, the messages on
3593	* the way up, or answer `{ messages }` of your own; `{ skip: reason }`
3594	* leaves the conversation as it is. `trigger` passes on as received.
3595	*
3596	* @example
3597	* on("session.compact", { trigger: "precompute" }, () => ({ skip: "off" }))
3598	*/
3599	'session.compact': SessionCompactInput;
3600	/**
3601	* Fires when a remote client joins the session's roster of attached
3602	* surfaces: it said so (ui_attach), or it first asked to draw.
3603	*
3604	* Observe (a phone joined: draw the lobby); `next(e)` resolves to
3605	* `{ clientId }`, a different return changes nothing. `$.session.surfaces()`
3606	* reads the roster; a render hook still reads `e.surface` per ask.
3607	*
3608	* @example
3609	* on("session.attach", { surface: "mobile" }, ($, e, next) => next(e))
3610	*/
3611	'session.attach': SessionAttachInput;
3612	/**
3613	* Fires when a client leaves the roster: it detached, or the session ended
3614	* with it attached (`e.reason`). Observe; `next(e)` echoes `{ clientId }`.
3615	*/
3616	'session.detach': SessionDetachInput;
3617	/**
3618	* Fires when the engine measures the session and a unit moved: after each
3619	* main-thread turn, and when a rate-limit window moves a whole point.
3620	*
3621	* Observe; `next(e)` echoes `{ changed }`. `$.session.usage()`'s figures,
3622	* pushed, not polled: compare them with your own threshold here, call the
3623	* op for the breakdown. One at a time, a burst folding into one more.
3624	*
3625	* @example
3626	* on("session.measure", ($, e, next) => (toastPast90(e.rateLimits), next(e)))
3627	*/
3628	'session.measure': SessionMeasureInput;
3629	/**
3630	* Fires once when the session ends (exit, /clear, resume, logout, signal, a
3631	* `-p` run done), after its SessionEnd settings hooks; `e.reason` says which.
3632	*
3633	* `e.resume.id` is `--resume`'s id; `next(e)` runs the engine's end step for
3634	* the plugins (at an exit the attached clients leave): `{ sessionId }`. The
3635	* SessionEnd bound afresh, 1.5 s by default; a `kill -9` raises nothing.
3636	*
3637	* @example
3638	* on("session.end", async ($, e, next) => (await keep(e.resume), next(e)))
3639	*/
3640	'session.end': SessionEndInput;
3641	/**
3642	* Fires once per hooks module about to join the chain, at load (the set
3643	* folded and built, nothing swapped in) and at reload; core allows.
3644	*
3645	* Return `{ refuse: reason }` and it never joins: no hook, no noun, no tool
3646	* of it; the transcript names who refused. Its judges, `$` whole, are the
3647	* plugins admitted before it and the binary's; judge by `tier` and `uses`.
3648	*
3649	* @example
3650	* on("plugin.register", { tier: "user" }, () => ({ refuse: "managed only" }))
3651	*/
3652	'plugin.register': PluginRegisterInput;
3653	/**
3654	* Fires when a model turn begins, before its first model call; `next(e)`
3655	* resolves to `{ turnId }`. Observe: a different return changes nothing.
3656	*/
3657	'turn.start': TurnStartInput;
3658	/**
3659	* Fires when the engine is about to send a model request of a turn, main's
3660	* or a subagent's (`e.agentId`); `next(e)` resolves to the whole response.
3661	*
3662	* `next({ ...e, model })` or `effort` sends another; the turn, the index and
3663	* the message count are pinned. An answer without `next` sends no request.
3664	* It streams (StreamNext): the hook's budget counts its own code alone.
3665	*/
3666	'turn.step': TurnStepInput;
3667	/**
3668	* Fires when a model turn has ended, at the point its duration is reported;
3669	* `next(e)` resolves to `{ text }`, the answer. `e.reason` says why.
3670	*
3671	* Return `{ text }` with a different text to show it beneath the answer (a
3672	* synopsis, a TL;DR line); the transcript's record is never rewritten. A
3673	* hook that fails leaves the answer as it was.
3674	*/
3675	'turn.complete': TurnCompleteInput;
3676	/**
3677	* Runs while `$` is being built, once per load or reload of this plugin
3678	* and before any other hook of it; `next(e)` resolves to `$` built so far.
3679	*
3680	* A step may ADD nouns and WITHHOLD nouns (leave one out, or return without
3681	* `next`); it may NOT REPLACE one another step added: the step fails, named
3682	* with both plugins. A step that fails unloads its plugin; `$` is rebuilt.
3683	*/
3684	'engine.create': EngineCreateInput;
3685	};
3686
3687	/**
3688	* `$`, the first parameter of every hook. Frozen; core's interface plus
3689	* every noun the plugins' `engine.create` steps added.
3690	*
3691	* Flat, `<noun>.<event>`; it does not carry `on`, since registration happens
3692	* before `$` exists. An interface so a plugin types the noun it provides by
3693	* declaration merging, the way a jQuery plugin types `$.fn`.
3694	*
3695	* @example
3696	* declare module "claude-code" { interface EngineInterface { voice: Voice } }
3697	*/
3698	export interface EngineInterface extends CoreEngineInterface {
3699	}
3700
3701	/**
3702	* What `next(e)` resolves to at `engine.create`: `$` as the steps beneath
3703	* built it, typed as `$` is, open to nouns no declaration names yet.
3704	*
3705	* A withheld noun is on it as a stub (a step inside withheld it, or the
3706	* last fold did and this is a reload), and the host refuses an op on one a
3707	* step outside withholds later; a typed module bootstraps at load on it.
3708	*/
3709	export type EngineInterfaceBuilt = EngineInterface & {
3710	readonly [noun: string]: unknown;
3711	};
3712
3713	/**
3714	* The engine's events' results.
3715	*/
3716	export type EngineResultOf = {
3717	/**
3718	* `{ result, context? }`, `{ deny }`, or core's `{ ref, result }`.
3719	*/
3720	'tool.call': ToolCallResult;
3721	/**
3722	* `{ decision, reason?, rule?, hook?, setting?, decider?, ceiling? }`.
3723	*/
3724	'tool.check': ToolCheckResult;
3725	/**
3726	* The tree to draw; `{ type: "engine", ref }` is core's own drawing.
3727	*/
3728	'ui.render': RenderElement;
3729	/**
3730	* The surface's element table (Elements[e.surface]): constructors from props
3731	* to a RenderElement.
3732	*/
3733	'ui.resolve': ElementTable;
3734	/**
3735	* `{ element }`: the element whose handler the press reached.
3736	*/
3737	'ui.press': UiPressResult;
3738	/**
3739	* `{ element, value }`: the field whose handler the input reached, and
3740	* the text it received.
3741	*/
3742	'ui.input': UiInputResult;
3743	/**
3744	* `{ element, value }`: the picker whose handler the pick reached, and
3745	* the value it received.
3746	*/
3747	'ui.select': UiSelectResult;
3748	/**
3749	* `{ props? }`: the posting instance's next props, when a hook hands some.
3750	*/
3751	'ui.message': UiMessageResult;
3752	/**
3753	* `{}` once the window moved, or `{ deny }`.
3754	*/
3755	'ui.scroll': UiScrollResult;
3756	/**
3757	* `{}` once the ring moved, or `{ deny }`.
3758	*/
3759	'ui.focus': UiFocusResult;
3760	/**
3761	* `{ isOffered }`.
3762	*/
3763	'agent.offer': AgentOfferResult;
3764	/**
3765	* `{ model }` or `{ deny }`.
3766	*/
3767	'agent.spawn': AgentSpawnResult;
3768	/**
3769	* `{ text, context? }` or `{ drop }`.
3770	*/
3771	'prompt.submit': PromptSubmitResult;
3772	/**
3773	* `{ isFilled }`.
3774	*/
3775	'prompt.fill': PromptFillResult;
3776	/**
3777	* `{ isShown }`.
3778	*/
3779	'prompt.suggest': PromptSuggestResult;
3780	/**
3781	* `{ text, cursor }`, the box the editor shows next.
3782	*/
3783	'prompt.edit': PromptEditResult;
3784	/**
3785	* `{ text }` (null leaves the section out).
3786	*/
3787	'prompt.section': PromptSectionResult;
3788	/**
3789	* `{ blocks }` (a block left out is not sent).
3790	*/
3791	'prompt.context': PromptContextResult;
3792	/**
3793	* `{ sections }`, every `shared` one ahead of every `session` one (a
3794	* section left out is not sent).
3795	*/
3796	'prompt.compose': PromptComposeResult;
3797	/**
3798	* `{ text }` (null leaves the attachment out).
3799	*/
3800	'prompt.attachment': PromptAttachmentResult;
3801	/**
3802	* `{ description, isDeferred? }`.
3803	*/
3804	'tool.describe': ToolDescribeResult;
3805	/**
3806	* `{ text }` (the command's output, when it printed one).
3807	*/
3808	'command.run': CommandRunResult;
3809	/**
3810	* `{ description, argumentHint, isHidden }`.
3811	*/
3812	'command.describe': CommandDescribeResult;
3813	/**
3814	* `{ value }` once written, or `{ deny }`.
3815	*/
3816	'config.set': ConfigSetResult;
3817	/**
3818	* `{ label, description, isHidden }`.
3819	*/
3820	'config.describe': ConfigDescribeResult;
3821	/**
3822	* `{ text }`.
3823	*/
3824	'skill.prompt': SkillPromptResult;
3825	/**
3826	* `{ text }`.
3827	*/
3828	'attribution.text': AttributionTextResult;
3829	/**
3830	* `{ cwd }`.
3831	*/
3832	'session.start': SessionStartResult;
3833	/**
3834	* `{ text }`, or `{ consumed }`.
3835	*/
3836	'session.receive': SessionReceiveResult;
3837	/**
3838	* `{ message, uuid }`, the row as stored.
3839	*/
3840	'session.append': SessionAppendResult;
3841	/**
3842	* `{ messages, tokensBefore?, tokensAfter? }`, or `{ skip }`.
3843	*/
3844	'session.compact': SessionCompactResult;
3845	/**
3846	* `{ clientId }`.
3847	*/
3848	'session.attach': SessionAttachResult;
3849	/**
3850	* `{ clientId }`.
3851	*/
3852	'session.detach': SessionDetachResult;
3853	/**
3854	* `{ changed }`.
3855	*/
3856	'session.measure': SessionMeasureResult;
3857	/**
3858	* `{ sessionId }`.
3859	*/
3860	'session.end': SessionEndResult;
3861	/**
3862	* `{ allow: true }`, or `{ refuse }`.
3863	*/
3864	'plugin.register': PluginRegisterResult;
3865	/**
3866	* `{ turnId }`.
3867	*/
3868	'turn.start': TurnStartResult;
3869	/**
3870	* The response: `{ turnId, index, answer, toolUses, stopReason, usage }`.
3871	*/
3872	'turn.step': TurnStepResult;
3873	/**
3874	* `{ text }`.
3875	*/
3876	'turn.complete': TurnCompleteResult;
3877	/**
3878	* `$` as built so far, with this plugin's interface added and any it
3879	* withheld left out; `next(e)` resolves to EngineInterfaceBuilt.
3880	*/
3881	'engine.create': EngineCreateResult;
3882	};
3883
3884	/**
3885	* The engine's own events as calls on `$`, one signature each:
3886	* `$.<noun>.<event>(input)` resolves to its result, or to its stream.
3887	*
3888	* The engine raises its events through these same calls; a plugin's call
3889	* runs the same chain with the calling hook alone skipped. `input` may leave
3890	* out what the engine fills (`tool_use_id`, the parent agent).
3891	*/
3892	export type EventCalls = {
3893	tool: {
3894	call: ToolCallOverloads;
3895	check: (input: ToolCheckArgs) => Promise<ToolCheckResult>;
3896	describe: (input: ToolDescribeInput) => Promise<ToolDescribeResult>;
3897	};
3898	command: {
3899	run: (input: CommandRunArgs) => Promise<CommandRunResult>;
3900	describe: (input: CommandDescribeInput) => Promise<CommandDescribeResult>;
3901	};
3902	config: {
3903	set: (input: ConfigSetArgs) => Promise<ConfigSetResult>;
3904	describe: (input: ConfigDescribeInput) => Promise<ConfigDescribeResult>;
3905	};
3906	prompt: {
3907	submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;
3908	fill: (input: PromptFillArgs) => Promise<PromptFillResult>;
3909	suggest: (input: PromptSuggestArgs) => Promise<PromptSuggestResult>;
3910	section: (input: PromptSectionInput) => Promise<PromptSectionResult>;
3911	context: (input: PromptContextInput) => Promise<PromptContextResult>;
3912	attachment: (input: PromptAttachmentInput) => Promise<PromptAttachmentResult>;
3913	compose: (input?: PromptComposeArgs) => Promise<PromptComposeResult>;
3914	};
3915	skill: {
3916	prompt: (input: SkillPromptInput) => Promise<SkillPromptResult>;
3917	};
3918	attribution: {
3919	text: (input: AttributionTextInput) => Promise<AttributionTextResult>;
3920	};
3921	agent: {
3922	offer: (input: AgentOfferInput) => Promise<AgentOfferResult>;
3923	spawn: (input: AgentSpawnArgs) => Promise<AgentSpawnResult>;
3924	};
3925	session: {
3926	start: (input: SessionStartInput) => Promise<SessionStartResult>;
3927	receive: (input: SessionReceiveInput) => Promise<SessionReceiveResult>;
3928	append: (input: SessionAppendInput) => Promise<SessionAppendResult>;
3929	compact: (input?: SessionCompactArgs) => Promise<SessionCompactResult>;
3930	attach: (input: SessionAttachInput) => Promise<SessionAttachResult>;
3931	detach: (input: SessionDetachInput) => Promise<SessionDetachResult>;
3932	measure: (input: SessionMeasureInput) => Promise<SessionMeasureResult>;
3933	end: (input: SessionEndInput) => Promise<SessionEndResult>;
3934	};
3935	turn: {
3936	start: (input: TurnStartInput) => Promise<TurnStartResult>;
3937	step: (input: TurnStepInput) => HookStream<TurnStepChunk, TurnStepResult>;
3938	complete: (input: TurnCompleteInput) => Promise<TurnCompleteResult>;
3939	};
3940	ui: {
3941	render: <C extends RenderComponent>(input: RenderInput<C>) => Promise<RenderElement>;
3942	resolve: <E extends ResolveInput>(e: E) => Elements[E['surface']];
3943	scroll: (input: UiScrollArgs) => Promise<UiScrollResult>;
3944	focus: (input: UiFocusArgs) => Promise<UiFocusResult>;
3945	};
3946	};
3947
3948	/**
3949	* The name of an event: a key of EventOf, the engine's own (CoreEventName)
3950	* and the declared plugin nouns' (NounEventName).
3951	*/
3952	export type EventName = keyof EventOf;
3953
3954	/**
3955	* The argument of each event, by event name: what a hook receives as `e`
3956	* and what the call on `$` takes. Plain data, frozen to every depth.
3957	*
3958	* The engine's own events (CoreEventOf: a plugin's `$.fs.write(...)` is
3959	* a dispatch the hooks above it see) and the methods of the plugin nouns
3960	* declared on EngineInterface (NounEventOf).
3961	*/
3962	export type EventOf = CoreEventOf & NounEventOf;
3963
3964	/**
3965	* The result of event `N`: what its hooks return and what their `next(e)`
3966	* resolves to.
3967	*/
3968	export type EventResult<N extends EventName = EventName> = ResultOf[N];
3969
3970	/**
3971	* The hook signature of each event, `($, e, next)`, as one mapped type over
3972	* EventOf; a streaming event's is the generator form (StreamHook).
3973	*
3974	* With one handler type per event, `Events[E]` for a generic E would be a
3975	* union; as one mapped type it stays a single function type the engine
3976	* calls without a cast (TS 4.6 correlated unions).
3977	*
3978	* @param $ the engine interface, frozen, the same object at every invocation;
3979	* at `engine.create` the empty table, since `$` exists after the fold
3980	* @param e the event's argument, frozen to every depth (`e.command = "ls"`
3981	* is a type error and throws); a rewrite is a copy passed to `next`
3982	* @param next the rest of the chain; a chain a hook raises through `$` skips
3983	* this hook and runs every other, its plugin's others too
3984	*/
3985	export type Events = {
3986	[E in keyof EventOf]: E extends StreamingEventName ? StreamHook<E> : ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> \| Promise<EventResult<E>>;
3987	};
3988
3989	type ExitReason = 'clear' \| 'resume' \| 'logout' \| 'prompt_input_exit' \| 'other';
3990
3991	type FileChangedHookInput = BaseHookInput & {
3992	hook_event_name: 'FileChanged';
3993	file_path: string;
3994	event: 'change' \| 'add' \| 'unlink';
3995	};
3996
3997	/**
3998	* `T` with every property read-only to every depth, arrays and tuples kept
3999	* as declared: how a hook's `e` is typed.
4000	*
4001	* `e.command = 'x'` is a type error; `next({ ...e, command: 'x' })` compiles.
4002	*/
4003	export type Frozen<T> = T extends (...args: never[]) => unknown ? T : T extends readonly unknown[] ? {
4004	[K in keyof T]: Frozen<T[K]>;
4005	} : T extends object ? {
4006	readonly [K in keyof T]: Frozen<T[K]>;
4007	} : T;
4008
4009	/**
4010	* One file `$.fs.ancestors` found: the directory it stands in, the name it
4011	* was asked for by, and its text as the engine's memory loader reads it.
4012	*/
4013	export type FsAncestor = {
4014	/**
4015	* The directory the file stands in, absolute.
4016	*/
4017	dir: string;
4018	/**
4019	* The spelling the caller asked for it by.
4020	*/
4021	name: string;
4022	/**
4023	* The file's text, with what its `@include`s bring after it.
4024	*/
4025	content: string;
4026	/**
4027	* The file and then each file its `@` imports brought, in load order,
4028	* path and text apiece; `content` is these texts joined.
4029	*/
4030	parts: readonly FsAncestorPart[];
4031	};
4032
4033	/**
4034	* One file of an ancestor entry: the file itself or one it imported.
4035	*/
4036	export type FsAncestorPart = {
4037	/**
4038	* The file's path, absolute.
4039	*/
4040	path: string;
4041	/**
4042	* Its text as the engine's memory loader reads it.
4043	*/
4044	content: string;
4045	};
4046
4047	/**
4048	* The argument of `$.fs.ancestors`: the file names to look for in each
4049	* directory, the file to walk down to, and the directory to walk beneath.
4050	*/
4051	export type FsAncestorsRequest = {
4052	/**
4053	* Relative `.md` file names, each looked for in every directory.
4054	*/
4055	names: readonly string[];
4056	/**
4057	* The file the walk goes on down to the directory of, relative to the
4058	* working directory or absolute; absent, it ends at the working directory.
4059	*/
4060	of?: string;
4061	/**
4062	* The directory the walk starts beneath, relative to the working directory
4063	* or absolute; absent, the walk starts at the filesystem root.
4064	*
4065	* Only directories strictly inside it are read, so with `of` a file under
4066	* the project root the walk reads the directories between the two, as the
4067	* engine reads a nested CLAUDE.md; a file not inside it finds nothing.
4068	*/
4069	below?: string;
4070	};
4071
4072	/**
4073	* What `$.fs.read(path, { as: "bytes" })` resolves with: the file's bytes,
4074	* base64, since only plain data crosses into a plugin's environment.
4075	*/
4076	export type FsBytes = {
4077	/**
4078	* The file's content, standard padded base64;
4079	* `Uint8Array.fromBase64(base64)` gives the bytes back.
4080	*/
4081	base64: string;
4082	};
4083
4084	/**
4085	* One entry of `$.fs.list`: the entry itself, a link not followed.
4086	*/
4087	export type FsEntry = {
4088	/**
4089	* The entry's name (no directory part).
4090	*/
4091	name: string;
4092	/**
4093	* `file`, `dir`, or `other`, of the entry itself: a symbolic link is
4094	* `other` (`$.fs.stat` says what it leads to, and with `resolve` where).
4095	*/
4096	kind: 'file' \| 'dir' \| 'other';
4097	/**
4098	* Bytes, for a file.
4099	*/
4100	size: number;
4101	/**
4102	* True when the entry is a symbolic link.
4103	*/
4104	isLink: boolean;
4105	};
4106
4107	/**
4108	* How `$.fs.read` answers: `text` (UTF-8, the default) or `bytes` (base64).
4109	*/
4110	export type FsReadAs = 'text' \| 'bytes';
4111
4112	/**
4113	* The options of `$.fs.read` that ask for the bytes: the call answers
4114	* `{ base64 }`.
4115	*/
4116	export type FsReadBytesOptions = {
4117	/**
4118	* `bytes`.
4119	*/
4120	as: 'bytes';
4121	};
4122
4123	/**
4124	* `$.fs.read`: the file's text, or with `{ as: "bytes" }` its bytes as
4125	* `{ base64 }`.
4126	*/
4127	export type FsReadCall = {
4128	(path: string): Promise<string>;
4129	(path: string, options: FsReadBytesOptions): Promise<FsBytes>;
4130	(path: string, options: FsReadOptions): Promise<string \| FsBytes>;
4131	};
4132
4133	/**
4134	* The options of `$.fs.read`.
4135	*/
4136	export type FsReadOptions = {
4137	/**
4138	* `bytes` answers `{ base64 }` for a binary file; `text` (the default) the
4139	* file's text.
4140	*/
4141	as: FsReadAs;
4142	};
4143
4144	/**
4145	* What `$.fs.stat` resolves with: what the path leads to, whether the path
4146	* itself is a symbolic link, and where it lands when asked.
4147	*/
4148	export type FsStat = {
4149	/**
4150	* `file`, `dir`, or `other`, of what the path leads to: a link is
4151	* followed, and one that leads nowhere is `other`.
4152	*/
4153	kind: 'file' \| 'dir' \| 'other';
4154	/**
4155	* Bytes, for a file.
4156	*/
4157	size: number;
4158	/**
4159	* Last modification, milliseconds since the epoch.
4160	*/
4161	mtimeMs: number;
4162	/**
4163	* True when the path itself is a symbolic link; `kind`, `size` and
4164	* `mtimeMs` then describe what it points at, or the link when that is gone.
4165	*/
4166	isLink: boolean;
4167	/**
4168	* Where the path landed when asked with `{ resolve: true }`: absolute,
4169	* every symbolic link followed, `.` and `..` folded; else absent.
4170	*
4171	* Absent too when the path leads nowhere or a hook above withheld it, so
4172	* a guard denies without it; and a hard link, a volume or file-id spelling
4173	* (macOS `/.vol/`) or a case alias keeps its own spelling, `isLink` false.
4174	*
4175	* @remarks a deny-list on spellings is thus best effort; an allow-list on
4176	* `realPath` under a root resolved the same way is the robust guard.
4177	*/
4178	realPath?: string;
4179	};
4180
4181	/**
4182	* The options of `$.fs.stat`.
4183	*/
4184	export type FsStatOptions = {
4185	/**
4186	* True to resolve where the path lands as well.
4187	*
4188	* The answer then carries `realPath` when the path leads somewhere, at
4189	* the cost of one more file system call: where it landed then, not a hold
4190	* on what a tool opens afterwards.
4191	*/
4192	resolve: boolean;
4193	};
4194
4195	/**
4196	* Every event (``), or every event under a namespace (`classic.`: each
4197	* one whose name starts with `classic.`).
4198	*/
4199	export type Glob = '' \| `${Namespace}.`;
4200
4201	/**
4202	* The hook `on(pattern, hook)` takes for a glob or a negation: one function
4203	* placed on every selected event, `e` and the result typed as their union.
4204	*
4205	* `next.event` says which event a run is; `next.is(pattern, e)` narrows `e`
4206	* to one of them. At `engine.create` (a negation may select it) `$` is the
4207	* empty table and the hook observes the fold, as a `*` hook does.
4208	*/
4209	export type GlobHook<P extends Pattern, N extends EventName = Selected<P>> = ($: EngineInterface, e: Frozen<Args<N>>, next: GlobNext<P>) => EventResult<N> \| Promise<EventResult<N>>;
4210
4211	/**
4212	* `next` in a hook on a glob or a negation: an overload per selected event,
4213	* then one over their union for an `e` not yet narrowed.
4214	*
4215	* `is` narrows `e` to the selected events its pattern names; `event` is one
4216	* of the selected names.
4217	*/
4218	export type GlobNext<P extends Pattern, N extends EventName = Selected<P>> = OrderedOverloads<N> & {
4219	(e: Args<N>): Promise<GlobNextResult<N>>;
4220	/**
4221	* Continues this dispatch at a tier, as Next's `to` (a managed hook's),
4222	* over the selected events' union for an `e` not yet narrowed.
4223	*/
4224	readonly to: (e: Args<N>, tier: TargetTier) => Promise<GlobNextResult<N>>;
4225	readonly signal: AbortSignal;
4226	readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<Args<Extract<N, Selected<M>>>>;
4227	readonly event: N;
4228	readonly origin: Origin;
4229	readonly trace: readonly TraceEntry<N, Args<N>, GlobNextResult<N>>[];
4230	readonly budget: NextBudget;
4231	};
4232
4233	/**
4234	* What `next(e)` resolves to in a glob hook before `e` is narrowed: the
4235	* NextResult of each selected event, as a union.
4236	*/
4237	type GlobNextResult<N extends EventName> = {
4238	[K in N]: NextResult<K>;
4239	}[N];
4240
4241	/**
4242	* One hook, `($, e, next)`, on event `E`.
4243	*/
4244	export type Hook<E extends EventName = EventName> = Events[E];
4245
4246	/**
4247	* The time bounds every hook runs under, in milliseconds: the engine's own
4248	* constants are typed by these members, and `next.budget` reads the live one.
4249	*
4250	* Each bounds the hook's OWN time: the clock stops while a `next(e)` call or
4251	* any `$` call of the hook's is in flight (a `$.clock` wait excepted), so a
4252	* slow chain beneath or a minute-long `$.model.complete` costs it nothing.
4253	*
4254	* @example
4255	* await $.model.complete(ask) // a minute; next.budget.remainingMs unmoved
4256	*/
4257	export type HookBudget = {
4258	/**
4259	* A hook's budget per dispatch, from its call to its return; past it the
4260	* hook is absent (its `.catch` asked, else `next(e)` run on its behalf).
4261	*
4262	* A streaming hook's (`turn.step`, an async generator) spans its whole
4263	* run and counts only while its own code runs: never at a `yield`, never
4264	* while it reads the stream beneath. Not per chunk: the sum of its work.
4265	*/
4266	readonly ms: 10_000;
4267	/**
4268	* A `.catch` handler's grace: a fresh budget from the moment it is called,
4269	* on the same clock (its `next` replay and its `$` calls are free).
4270	*
4271	* Past it the hook is absent as if it had no handler; `next.error.budget`
4272	* and `next.budget.ms` both read it there. `engine.create` has no budget.
4273	*/
4274	readonly catchMs: 1_000;
4275	/**
4276	* How long a hook may keep running after `next.signal` aborted (the person
4277	* interrupted, a hook above settled first, its own budget ran out).
4278	*
4279	* Past it the hook is reported as lingering; the dispatch had already gone
4280	* on without it when the signal aborted.
4281	*/
4282	readonly lingerMs: 5_000;
4283	};
4284
4285	/**
4286	* Why a hook failed, as its `.catch` handler reads it on `next.error`: plain
4287	* frozen data.
4288	*
4289	* `throw`: the hook threw, or returned what the site refuses, `message`
4290	* saying what; `timeout`: it outran its budget, `message` then what its last
4291	* `next()` rejected with, if it did. `budget` is the handler's own grace.
4292	*/
4293	export type HookFailure = {
4294	readonly kind: 'throw' \| 'timeout';
4295	/**
4296	* The thrown error's message, or for a timeout what the hook's last
4297	* `next()` rejected with; absent for a timeout with nothing rejected.
4298	*/
4299	readonly message?: string;
4300	/**
4301	* The grace the handler runs under, in milliseconds; past it, the hook is
4302	* absent as if it had no handler.
4303	*/
4304	readonly budget: number;
4305	};
4306
4307	/**
4308	* The hook type per pattern: an event's own (Events), `*`'s (AnyEventHook),
4309	* or a glob's over the events it selects (GlobHook), as one conditional type.
4310	*
4311	* One type, so the two-argument `on` stays ONE generic signature: as an
4312	* overload set the language service offers no tool-name completions inside
4313	* `e.tool === "`; as an index into a table TS intersects every argument.
4314	*/
4315	export type HookFor<P extends Pattern> = P extends '*' ? AnyEventHook : P extends EventName ? Events[P] : GlobHook<P>;
4316
4317	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;
4318
4319	/**
4320	* The hook event `E` takes: an async generator over its chunks for a
4321	* streaming event (`turn.step`), `($, e, next) => result` for every other.
4322	*/
4323	export type HookOf<E extends EventName> = Events[E];
4324
4325	/**
4326	* What a hooks module exports: `register`, and nothing the loader reads
4327	* besides.
4328	*/
4329	export type HooksModule = {
4330	register: Register;
4331	};
4332
4333	/**
4334	* What `next(e)` returns on a streaming event: the stream of everything
4335	* beneath, chunk by chunk, whose return value is the result from beneath.
4336	*
4337	* `yield* next(e)` forwards the chunks and evaluates to that result; a
4338	* transforming hook reads `for await (const chunk of stream)` and then
4339	* `await stream.result`. Each call runs what is beneath afresh.
4340	*/
4341	export type HookStream<C, R> = AsyncGenerator<C, R> & {
4342	/**
4343	* Settles with what beneath returned once the stream has been read to
4344	* its end; rejects if the stream is closed before that.
4345	*/
4346	readonly result: Promise<R>;
4347	};
4348
4349	/**
4350	* Options of `$.http.fetch`.
4351	*/
4352	export type HttpInit = {
4353	/**
4354	* `GET` (default), `POST`, ...
4355	*/
4356	method?: string;
4357	/**
4358	* Request headers.
4359	*/
4360	headers?: Record<string, string>;
4361	/**
4362	* The request body, as text.
4363	*/
4364	body?: string;
4365	/**
4366	* The handle `$.session.authorize()` answered: the engine sets the
4367	* session's credential header itself, only for a first-party host.
4368	*/
4369	auth?: string;
4370	/**
4371	* The absolute path of a Unix domain socket the request goes over instead
4372	* of TCP (near 100 B at most): one per session, in a private directory.
4373	*
4374	* The URL still gives path, query and Host; redirects stay on it; no proxy;
4375	* `https:` is TLS verified against the URL's host (always, once `auth`
4376	* rides), so a credential reaches only its host. No relative path, no NUL.
4377	*
4378	* @example
4379	* await $.http.fetch(url, { socketPath: `${runDirectory}/bridge.sock` })
4380	*/
4381	socketPath?: string;
4382	};
4383
4384	/**
4385	* What `$.http.fetch` resolves with.
4386	*/
4387	export type HttpResponse = {
4388	/**
4389	* The HTTP status code.
4390	*/
4391	status: number;
4392	/**
4393	* True for a 2xx status.
4394	*/
4395	ok: boolean;
4396	/**
4397	* Response headers, lower-cased names.
4398	*/
4399	headers: Record<string, string>;
4400	/**
4401	* The body, as text.
4402	*/
4403	text: string;
4404	};
4405
4406	/**
4407	* A `$.ui.blit` argument swapping one of the caller's mounted keyed Images
4408	* to its next picture; every call sends it, so a stream needs no generation.
4409	*
4410	* The surface writes them with its frames, some sixty a second: byte and
4411	* `file` sources fold to the last per frame; every `shm` source reaches the
4412	* terminal (it unlinks each), and is denied while frames are not written.
4413	*
4414	* @example await $.ui.blit({ requestId: 'browser', key: 'view',
4415	* source: { shm: '/tb-4', format: 'rgb', width: 1280, height: 720 } })
4416	*/
4417	export type ImageBlitArgs = {
4418	/**
4419	* The site the Image is drawn in, by the `requestId` this plugin draws it
4420	* under.
4421	*/
4422	requestId: string;
4423	/**
4424	* The Image's `key` in that drawing.
4425	*/
4426	key: string;
4427	/**
4428	* The next picture (ImageSource): bytes, or a name the terminal reads.
4429	*/
4430	source: ImageSource;
4431	/**
4432	* Refused unless it is the mounted Image's width in cells. Absent, that.
4433	*/
4434	columns?: number;
4435	/**
4436	* Refused unless it is the mounted Image's height in cells. Absent, that.
4437	*/
4438	rows?: number;
4439	};
4440
4441	/**
4442	* The props of `Image`, the terminal surface's picture leaf: pixels over a
4443	* box of cells where the terminal can (kitty, Ghostty), the `alt` elsewhere.
4444	*
4445	* A leaf: no children, `hover` or `onPress`; the cells are text, so the
4446	* picture scrolls and clips as a word does. Drawn again with another `source`
4447	* it is replaced in place; keyed, `$.ui.blit` swaps it at the frame rate.
4448	*
4449	* @example const { bytes } = await $.fs.read('chart.png', { as: 'bytes' })
4450	* <Image source={{ png: bytes.toBase64() }} columns={40} rows={12} alt="p95" />
4451	* @example <Image key="view" source={{ shm: '/tb-7', format: 'rgb', width: 960,
4452	* height: 600 }} columns={80} rows={25} alt="the page" />
4453	*/
4454	export type ImageProps = {
4455	/**
4456	* The element's address within the drawing: what `$.ui.blit` names to swap.
4457	*
4458	* Unique among the Images of one tree; absent, only a redraw changes it.
4459	*/
4460	key?: string;
4461	/**
4462	* The picture (ImageSource): `{ png }` or `{ rgba, width, height }` bytes,
4463	* or `{ file, format }` / `{ shm, format, width, height }` read here.
4464	*/
4465	source: ImageSource;
4466	/** How many terminal columns wide, 1 to 255; the picture is scaled to fill
4467	* the box and the site clips what its body cannot show. */
4468	columns: number;
4469	/**
4470	* How many terminal rows tall, 1 to 255.
4471	*/
4472	rows: number;
4473	/**
4474	* What the picture says, drawn dim in its place where the picture cannot
4475	* be (and read by a screen reader); required, may be a single space.
4476	*/
4477	alt: string;
4478	};
4479
4480	/**
4481	* The picture an `Image` shows: base64 bytes the plugin holds (at most 2 MiB
4482	* decoded), or the name of a file or POSIX shared-memory object it does not.
4483	*
4484	* A name is one another process on this machine wrote; the terminal, running
4485	* as the person, opens, reads and decodes it itself, so no pixel crosses `$`
4486	* and the engine never touches it. One it will not read (not a regular file,
4487	* under `/proc`, `/sys` or `/dev`, gone, across ssh) draws a blank box, its
4488	* words in the debug log; it unlinks a shared-memory object once read, so
4489	* each frame is a fresh one. A source equal to the last drawn sends nothing;
4490	* `generation` makes new content under an unchanged name a new source.
4491	*
4492	* @example { rgba: pixels.toBase64(), width: 64, height: 32 }
4493	* @example { file: '/dev/shm/frame-3.rgba', format: 'rgba', width: 640,
4494	* height: 400 }
4495	* @example { shm: '/tb-view-2', format: 'rgb', width: 1280, height: 720 }
4496	*/
4497	export type ImageSource = {
4498	/**
4499	* A whole PNG file, base64.
4500	*/
4501	png: string;
4502	} \| {
4503	/**
4504	* `width * height` RGBA pixels, 4 bytes each, base64.
4505	*/
4506	rgba: string;
4507	/**
4508	* Pixels per row, 1 to 2048.
4509	*/
4510	width: number;
4511	/**
4512	* Rows of pixels, 1 to 2048.
4513	*/
4514	height: number;
4515	} \| {
4516	/**
4517	* The absolute path of a regular file holding a whole PNG, at most
4518	* 3072 bytes of path; read by the terminal, left in place.
4519	*/
4520	file: string;
4521	/**
4522	* The file is a whole PNG; the terminal decodes it and sizes it itself.
4523	*/
4524	format: 'png';
4525	/**
4526	* A whole number that changes when the file's content does under the
4527	* same path, so a redraw reads it again; absent, the path alone tells.
4528	*/
4529	generation?: number;
4530	} \| {
4531	/**
4532	* The absolute path of a regular file of `width * height` raw pixels, at
4533	* most 3072 bytes of path; read by the terminal, left in place.
4534	*
4535	* On Linux a file under `/dev/shm` is memory.
4536	*/
4537	file: string;
4538	/**
4539	* `rgba`, 4 bytes a pixel, or `rgb`, 3.
4540	*/
4541	format: 'rgba' \| 'rgb';
4542	/**
4543	* Pixels per row, 1 to 4096.
4544	*/
4545	width: number;
4546	/**
4547	* Rows of pixels, 1 to 4096.
4548	*/
4549	height: number;
4550	/**
4551	* A whole number that changes when the file's content does under the
4552	* same path, so a redraw reads it again; absent, the path alone tells.
4553	*/
4554	generation?: number;
4555	} \| {
4556	/**
4557	* The name of a POSIX shared-memory object of `width * height` raw
4558	* pixels: `/` then up to 254 of `A-Z a-z 0-9 . _ -` (macOS takes 30).
4559	*
4560	* The terminal unlinks it after reading, so a name feeds one Image
4561	* drawn once and is never sent again on a redraw; POSIX terminals only.
4562	*/
4563	shm: string;
4564	/**
4565	* `rgba`, 4 bytes a pixel, or `rgb`, 3.
4566	*/
4567	format: 'rgba' \| 'rgb';
4568	/**
4569	* Pixels per row, 1 to 4096.
4570	*/
4571	width: number;
4572	/**
4573	* Rows of pixels, 1 to 4096.
4574	*/
4575	height: number;
4576	/**
4577	* A whole number that changes when a fresh object reuses a name, so a
4578	* redraw reads it again; absent, the name alone tells.
4579	*/
4580	generation?: number;
4581	};
4582
4583	/**
4584	* The keys of object pattern `P` that object member `E` cannot satisfy, `D`
4585	* levels down; `never` when there is none, which is what keeps the member.
4586	*
4587	* A key `E` does not have (an open record has every string key), or one
4588	* whose value `P` narrows to nothing.
4589	*/
4590	type ImpossibleKeys<E, P, D extends readonly unknown[]> = {
4591	[K in keyof P]-?: K extends keyof E ? [NarrowedValue<Exclude<E[K], undefined>, P[K], D>] extends [never] ? K : never : K;
4592	}[keyof P];
4593
4594	/**
4595	* The props of `Input`, every surface's one-line text field: an address,
4596	* optional texts, and the closures a change and a submit run. A leaf.
4597	*
4598	* Focused through the same ring as `Button` (`abovePrompt:focus`); while it
4599	* has focus every printable key reaches it alone and Esc returns them; a
4600	* change and Enter raise `ui.input`, whose bottom is `onInput` / `onSubmit`.
4601	*/
4602	export type InputProps = {
4603	/**
4604	* The element's address: `e.element` at `ui.input`, what a matcher names.
4605	*/
4606	key: string;
4607	/**
4608	* Text drawn before the field.
4609	*/
4610	label?: string;
4611	/**
4612	* Text drawn dim in an empty field.
4613	*/
4614	placeholder?: string;
4615	/**
4616	* The text the field holds when drawn; the person's typing replaces it
4617	* until the hook draws another.
4618	*/
4619	value?: string;
4620	/**
4621	* What Enter does, in a word or two, drawn beside the field while it has
4622	* focus (`send`). Defaults to `submit`.
4623	*/
4624	submitLabel?: string;
4625	/**
4626	* The site's focus ring starts here when the site takes the keyboard,
4627	* instead of on nothing, as the DOM's `autofocus`: Enter acts on it at once.
4628	*
4629	* A pane opened with `focus`, or the person's focus chord or click, is the
4630	* take. Of several in one site the first drawn wins; it raises `ui.focus`,
4631	* origin this plugin. A ring the person has moved stays where it was put.
4632	*/
4633	autoFocus?: true;
4634	/**
4635	* Runs on every change of the text, in the plugin's own environment: the
4636	* bottom of a `ui.input` chain of kind `change`.
4637	*/
4638	onInput?: (value: string, e: UiInputArgument) => void;
4639	/**
4640	* Runs on Enter with the text, in the plugin's own environment: the bottom
4641	* of a `ui.input` chain of kind `submit`. No model turn unless it asks one.
4642	*/
4643	onSubmit: (value: string, e: UiInputArgument) => void;
4644	};
4645
4646	/**
4647	* Every tier an instruction file can belong to, for checking a hook's
4648	* answer; the kind type is derived from this list.
4649	*/
4650	const INSTRUCTION_FILE_KINDS: readonly ["managed", "user", "project", "local", "memory"];
4651
4652	/**
4653	* One instruction file behind the `claudeMd` block: where it was read, its
4654	* tier, its text as loaded, and the file that `@`-imported it if one did.
4655	*/
4656	export type InstructionFile = {
4657	/**
4658	* The file's path, absolute.
4659	*/
4660	path: string;
4661	/**
4662	* Its tier.
4663	*/
4664	kind: InstructionFileKind;
4665	/**
4666	* The text as loaded (comments and frontmatter already stripped).
4667	*/
4668	content: string;
4669	/**
4670	* The path of the file whose `@` import brought this one, when one did.
4671	*/
4672	parent?: string;
4673	};
4674
4675	/**
4676	* What tier an instruction file belongs to: the organization's managed
4677	* policy, the person's own, the project's checked-in or private ones, memory.
4678	*/
4679	export type InstructionFileKind = (typeof INSTRUCTION_FILE_KINDS)[number];
4680
4681	type InstructionsLoadedHookInput = BaseHookInput & {
4682	hook_event_name: 'InstructionsLoaded';
4683	file_path: string;
4684	memory_type: 'User' \| 'Project' \| 'Local' \| 'Managed';
4685	load_reason: 'session_start' \| 'nested_traversal' \| 'path_glob_match' \| 'include' \| 'compact';
4686	globs?: string[];
4687	trigger_file_path?: string;
4688	parent_file_path?: string;
4689	};
4690
4691	/**
4692	* What `$.ui.invalidate` takes: a render event, or one of the six events
4693	* whose answers the engine caches for the session.
4694	*/
4695	export type InvalidatableEventName = RenderEventName \| 'prompt.section' \| 'prompt.context' \| 'prompt.attachment' \| 'tool.describe' \| 'command.describe' \| 'config.describe';
4696
4697	/**
4698	* Whether tag key `K` selects members of `I`: it does when each member gives
4699	* it ONE literal (`component: "ToolUse"` on the ToolUse variant).
4700	*
4701	* A key that is the same union on every member is a filter at runtime; it
4702	* is left out of the selection so that it cannot defeat the narrowing the
4703	* other keys give.
4704	*/
4705	type IsDiscriminant<I, K> = I extends unknown ? K extends KnownKeys<I> ? IsSingleLiteral<I[K]> : true : never;
4706
4707	/**
4708	* Whether `V` is made of literals only: `"a" \| "b"` is, `string` is not.
4709	*/
4710	type IsLiteralValued<V> = string extends V ? false : number extends V ? false : boolean extends V ? false : [V] extends [string \| number \| boolean] ? true : false;
4711
4712	/**
4713	* Whether `V` is exactly one string, number or boolean literal.
4714	*/
4715	type IsSingleLiteral<V> = [V] extends [string \| number \| boolean] ? IsUnion<V> extends true ? false : true : false;
4716
4717	/**
4718	* Whether `T` is a union of two or more members.
4719	*/
4720	type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
4721
4722	/**
4723	* Plain data: what JSON holds, and what crosses between a plugin's hooks
4724	* module and its surface module whole (a `Client`'s props, a post's data).
4725	*
4726	* A function, a class instance, `undefined` or a cycle is not plain data;
4727	* the engine refuses one where it checks, and drops it where it clones.
4728	*/
4729	export type JsonValue = string \| number \| boolean \| null \| readonly JsonValue[] \| {
4730	readonly [key: string]: JsonValue;
4731	};
4732
4733	/**
4734	* What `next` takes in a matched hook: the variants of `e` the matcher can
4735	* match (KeptMembers), as declared, so a rewrite of a pinned field passes.
4736	*/
4737	type KeptEvent<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? KeptMembers<Args<N>, M> : never : never;
4738
4739	/**
4740	* The members of the argument union `E` matcher `P` can match, as declared;
4741	* what `next` takes, so a rewrite may change a field the matcher pinned.
4742	*
4743	* A member is dropped when `P` names a key it lacks, or gives a key, at any
4744	* depth, a value none of that key's values can equal (ImpossibleKeys).
4745	*/
4746	type KeptMembers<E, P> = E extends unknown ? [ImpossibleKeys<E, P, []>] extends [never] ? E : never : never;
4747
4748	/**
4749	* The declared keys of `T`, the string and number index signatures left out.
4750	*/
4751	type KnownKeys<T> = keyof {
4752	[K in keyof T as string extends K ? never : number extends K ? never : K]: 0;
4753	};
4754
4755	/**
4756	* The events whose overload must come after the rest, lest it shadow them.
4757	*
4758	* `classic.PreToolUse` shares `tool.call`'s envelope, `turn.abort` every
4759	* turn event's `turnId`, and an object of any shape is assignable to NoArgs.
4760	*/
4761	type LateOverload = 'classic.PreToolUse' \| 'turn.abort' \| NoArgsEvent;
4762
4763	/**
4764	* The props of `Link`, a hyperlink every surface draws: an OSC 8 span on the
4765	* terminal (else its text then the URL in dim), an anchor on desktop.
4766	*
4767	* An inline element: its children are the text, strings and inline
4768	* elements; absent children the `label`, absent both the URL. The engine
4769	* bounds `href` before the tree crosses.
4770	*/
4771	export type LinkProps = {
4772	/**
4773	* Where the link goes: an `https:` URL (or `http://localhost`), at most
4774	* 2048 characters of printable ASCII, spelled as `new URL(href).href`.
4775	*
4776	* No `user@host` part, no raw `@`, space or non-ASCII letter (encode them);
4777	* anything else refuses the tree the Link is in.
4778	*/
4779	href: string;
4780	/**
4781	* The text drawn when the element has no children; absent both, the URL
4782	* itself is the text.
4783	*/
4784	label?: string;
4785	};
4786
4787	/**
4788	* What a matcher value selects by: itself, or `unknown` for a RegExp, which
4789	* selects nothing.
4790	*/
4791	type Literal<X> = X extends RegExp ? unknown : X;
4792
4793	/**
4794	* What a `Markdown` carries across the boundary: its address, text, dimness
4795	* and which links it answers; `onLinkPress` stays behind, a `press` instead.
4796	*/
4797	export type MarkdownLeafProps = {
4798	/**
4799	* The element's address: what `e.element` carries and what a matcher
4800	* names; present whenever the element carries a `press`.
4801	*/
4802	key?: string;
4803	/**
4804	* The markdown drawn, bounded as a Text's string is.
4805	*/
4806	text: string;
4807	/**
4808	* The whole block dim, as `Text`'s `dimColor`; absent draws as false.
4809	*/
4810	dimColor?: boolean;
4811	/**
4812	* Which links a press belongs to, by `href` as written; absent, with a
4813	* `press`, every link drawn. Compared with the pressed target only.
4814	*/
4815	pressableLinks?: readonly string[];
4816	};
4817
4818	/**
4819	* The props of `Markdown`, a block of markdown every surface draws as it
4820	* draws an assistant reply's text: its own renderer, links, tables, fences.
4821	*
4822	* A leaf: no children. `text` is the element's data as a `Text`'s string is,
4823	* bounded the same way. With `onLinkPress` the links it draws are the
4824	* plugin's to answer: a press on one raises `ui.press` addressed to `key`.
4825	*/
4826	export type MarkdownProps = {
4827	/**
4828	* The element's address: `e.element` at `ui.press`, what a matcher names.
4829	* Required with `onLinkPress`, since a press needs one; else optional.
4830	*/
4831	key?: string;
4832	/**
4833	* The markdown drawn, as an assistant reply would write it.
4834	*
4835	* At most 10000 characters, tab and newline its only control characters;
4836	* a link whose scheme is not `https:`, `http:` or `file:` draws as text,
4837	* never clickable. Not drawn around the approval dialog.
4838	*/
4839	text: string;
4840	/**
4841	* The whole block dim, as `Text`'s `dimColor`: a thought, an aside.
4842	*/
4843	dimColor?: boolean;
4844	/**
4845	* What a press on a link in `text` runs, in the plugin's own environment:
4846	* the bottom of a `ui.press` chain whose `e.link` names the link.
4847	*
4848	* A press is a plain single click where the surface reports clicks (the
4849	* fullscreen terminal): it opens nothing and lands once no double-click
4850	* followed; a ctrl, alt or terminal-kept cmd click opens it as before.
4851	*/
4852	onLinkPress?: (link: PressedLink, e: UiPressArgument) => void;
4853	/**
4854	* Which links in `text` a press belongs to, by `href` as the markdown
4855	* writes it; absent, every link drawn. Only with `onLinkPress`.
4856	*
4857	* A link left out keeps the surface's own behaviour. At most 256 entries
4858	* of at most 2048 characters; compared with the pressed link's target,
4859	* never opened.
4860	*/
4861	pressableLinks?: readonly string[];
4862	};
4863
4864	/**
4865	* The argument a matched hook receives: `e` narrowed by `M` (Narrowed), per
4866	* event the registration covers.
4867	*/
4868	export type MatchedEvent<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? Narrowed<Args<N>, M> : never : never;
4869
4870	/**
4871	* The hook `on(pattern, matcher, hook)` takes: `($, e, next)` with `e`
4872	* narrowed by the matcher (MatchedEvent), and a tagged result the same way.
4873	*
4874	* On a streaming event it is the generator form (MatchedStreamHook). `next`
4875	* takes the variants the matcher keeps, as declared (KeptEvent); `next.is`
4876	* names the events the registration covers and narrows as the matcher does.
4877	*/
4878	export type MatchedHook<P extends Pattern, M> = P extends StreamingEventName ? MatchedStreamHook<P, M> : ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {
4879	[K in MatchedNames<P, M>]: Narrowed<Args<K>, M>;
4880	}>) => MatchedResult<P, M> \| Promise<MatchedResult<P, M>>;
4881
4882	/**
4883	* The events a matched registration on `P` covers: the event named, or for a
4884	* glob every selected event whose input has each key the matcher names.
4885	*/
4886	type MatchedNames<P, M = never> = P extends EventName ? P : {
4887	[N in Selected<P & string>]: [M] extends [never] ? N : keyof M extends AnyKeyOf<Args<N>> ? N : never;
4888	}[Selected<P & string>];
4889
4890	/**
4891	* What a matched hook returns: the event's result, narrowed by `M` where the
4892	* result is a union tagged by the matcher's tag keys.
4893	*/
4894	export type MatchedResult<P extends Pattern, M> = MatchedNames<P, M> extends infer N extends EventName ? N extends unknown ? Select<EventResult<N>, Selection<Args<N>, M>> : never : never;
4895
4896	/**
4897	* The hook `on(event, matcher, hook)` takes on a streaming event: the
4898	* generator form, `e` narrowed by the matcher, `next(e)` the stream beneath.
4899	*/
4900	export type MatchedStreamHook<P extends StreamingEventName, M> = ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: MatchedStreamNext<P, M>) => StreamHookBody<Chunk<P>, MatchedResult<P, M>>;
4901
4902	/**
4903	* What a matched streaming hook's `next.is(pattern, e)` narrows `e` to:
4904	* the streaming event's argument narrowed by the matcher.
4905	*/
4906	type MatchedStreamNarrowings<P extends StreamingEventName, M> = {
4907	[K in P]: Narrowed<Args<K>, M>;
4908	};
4909
4910	/**
4911	* A matched streaming hook's `next`: the variants the matcher keeps, the
4912	* result tagged the same way, `next.is` narrowing as the matcher does.
4913	*/
4914	type MatchedStreamNext<P extends StreamingEventName, M> = StreamNext<P, KeptEvent<P, M>, MatchedResult<P, M>, MatchedStreamNarrowings<P, M>>;
4915
4916	/**
4917	* What `on(event, matcher, hook)` takes for an argument of type `I`: the
4918	* shape of the `e` the hook wants, a partial of it at any depth.
4919	*
4920	* A leaf is `===` or a RegExp (`{ command: /^p4 / }`); an array is any-of;
4921	* an object is a partial of an OBJECT, so `{ command: { startsWith } }` is
4922	* a type error where `e` is typed and free where it is `unknown`.
4923	*/
4924	export type Matcher<I, All = I> = I extends unknown ? {
4925	readonly [K in KnownKeys<I>]?: MatcherValue<I[K], MatcherValueOf<All, K>>;
4926	} & (string extends keyof I ? OpenMatcher<I, All> : unknown) : never;
4927
4928	/**
4929	* Any matcher at all, for a field typed `unknown` (a tool's input, a
4930	* result's output): the kinds the engine accepts, unchecked there.
4931	*
4932	* The four kinds: a scalar is `===`; a RegExp tests the value as a string
4933	* (`{ command: /^p4 / }`); an array matches if any element does; an object
4934	* is a partial of an object. `{ startsWith: 'p4' }` never matches a string.
4935	*/
4936	type MatcherData = string \| number \| boolean \| null \| RegExp \| readonly MatcherData[] \| {
4937	readonly [key: string]: MatcherData;
4938	};
4939
4940	/**
4941	* The declared keys of every variant of `I` (index signatures aside).
4942	*/
4943	type MatcherKeys<I> = I extends unknown ? KnownKeys<I> : never;
4944
4945	/**
4946	* What matches one value of type `V`, by the runtime's kinds:
4947	* a scalar leaf takes the value or a RegExp; an object, a partial of it.
4948	*
4949	* For an array, what matches one ELEMENT of it, since a pattern against an
4950	* array value holds when some element matches; for `unknown`, any matcher.
4951	* A scalar matches by `===`, a RegExp tests the value as a string.
4952	*/
4953	type MatcherOne<V> = unknown extends V ? MatcherData : V extends readonly (infer Item)[] ? MatcherOne<Item> : V extends string \| number \| boolean \| null ? V \| RegExp : V extends object ? Matcher<V> : V extends undefined ? never : unknown;
4954
4955	/**
4956	* What a matcher gives a key whose value is `V` on this variant and `Across`
4957	* over every variant: one MatcherOne, or an array of them matched as one-of.
4958	*
4959	* The one-of is typed over every variant, so `{ tool: ['Bash', 'Read'] }`
4960	* types on the Bash variant; with a nested pattern beside it, the pattern is
4961	* checked against a variant the one-of names, not against each of them.
4962	*/
4963	type MatcherValue<V, Across = V> = MatcherOne<V> \| readonly MatcherOne<Across>[];
4964
4965	/**
4966	* The type of key `K` across the variants of `I` that declare it.
4967	*/
4968	type MatcherValueOf<I, K> = I extends unknown ? K extends KnownKeys<I> ? I[K] : never : never;
4969
4970	/**
4971	* One block of an MCP result: `type` and the fields that kind of block carries.
4972	*/
4973	export type McpContentBlock = {
4974	/**
4975	* The block's kind: `text`, `image`, `audio`, `resource`, `resource_link`.
4976	*/
4977	type: string;
4978	/**
4979	* Set on a `text` block.
4980	*/
4981	text?: string;
4982	/**
4983	* Set on a `resource_link` (or embedded `resource`) block.
4984	*/
4985	uri?: string;
4986	/**
4987	* Declared by an image, audio or resource block.
4988	*/
4989	mimeType?: string;
4990	[field: string]: unknown;
4991	};
4992
4993	/**
4994	* The MCP server serving this tool, for `mcp__*` tools: `name` is the server's config key (for `source: "sdk"`, exactly the name the SDK host registered in `sdkMcpServers` / `mcp_set_servers`; for any other source, the key as authored in that configuration - untrusted text, the same value `mcp_status` and system/init report, to be escaped before display), `source` is where its definition came from - `sdk` (an in-process server the SDK host runs; only the host can register one, so a configured server of the same name never reads `sdk`), `plugin` (a server a plugin ships or registers at runtime), or a config scope (`user`, `project`, `local`, `dynamic` for --mcp-config / `mcp_set_servers` process servers, `managed`, `enterprise`, `claudeai`, `agent`). Key trust on `source`, not on the name or the tool-name prefix. Absent for non-MCP tools.
4995	*/
4996	type McpServerProvenance = {
4997	name: string;
4998	/**
4999	* sdk \| plugin \| user \| project \| local \| dynamic \| managed \| enterprise \| claudeai \| agent - an open set; treat unknown values as an unrecognized configured source, never as sdk.
5000	*/
5001	source: string;
5002	};
5003
5004	/**
5005	* The MCP branch of a `tool.call` hook's `e` (and of `$.tool.call`'s input):
5006	* one variant per declared tool, else the loose McpToolCallInputFallback.
5007	*
5008	* `$.mcp.call(server, tool, args)` takes none of these: its parameters are
5009	* positional, the server and tool by name, then the arguments object.
5010	*/
5011	export type McpToolCallInput = [keyof McpToolInputs] extends [never] ? McpToolCallInputFallback : {
5012	[N in keyof McpToolInputs & string]: ToolInputOf<N, McpToolInputs[N] & Record<string, unknown>>;
5013	}[keyof McpToolInputs & string];
5014
5015	/**
5016	* The `e` a `tool.call` (or `classic.PreToolUse`) hook receives for an MCP
5017	* tool while no MCP tool is declared: every `mcp__*` name, loose arguments.
5018	*
5019	* McpToolInputs has no entries until `/plugin-types` writes the connected
5020	* tools' declarations; also the `input` of `$.tool.call({ tool:
5021	* "mcp__<server>__<tool>", ... })`. Not `$.mcp.call`'s, which is positional:
5022	*
5023	* @example
5024	* on("tool.call", { tool: "mcp__gh__issue" }, ($, e, next) => audit(e.title))
5025	*/
5026	type McpToolCallInputFallback = {
5027	/**
5028	* The name of the tool being called (`mcp__<server>__<tool>`); comparing
5029	* it narrows `e`. Reserved: a rewrite of it is ignored by core.
5030	*/
5031	tool: McpToolName;
5032	/**
5033	* The tool_use block's id: the same at every event of the call and in
5034	* `$.ui.notice`. Reserved: a rewrite of it is ignored by core.
5035	*/
5036	tool_use_id: string;
5037	[argument: string]: unknown;
5038	};
5039
5040	/**
5041	* The inputs of the MCP tools this project knows, keyed by full tool name,
5042	* for declaration merging; empty by default, then every MCP tool is loose.
5043	*
5044	* A `.d.ts` in the plugin author's project (written by `/plugin-types <dir>`
5045	* from the connected servers' JSON Schemas, or by hand) adds entries under
5046	* `declare module "claude-code"`; `e.tool === <name>` then narrows to them.
5047	*
5048	* @example
5049	* interface McpToolInputs { "mcp__my_server__send": { to: string } }
5050	*/
5051	export interface McpToolInputs {
5052	}
5053
5054	/**
5055	* The name of an MCP tool as the engine spells it: `mcp__<server>__<tool>`.
5056	*/
5057	export type McpToolName = `mcp__${string}__${string}`;
5058
5059	/**
5060	* An MCP tools/call result as the SDK returns it, plain data.
5061	*/
5062	export type McpToolResult = {
5063	/**
5064	* The result's content blocks, in order (text, image, resource,
5065	* resource_link, ...).
5066	*/
5067	content: McpContentBlock[];
5068	/**
5069	* True when the server reported the call as failed; the blocks then describe
5070	* the error.
5071	*/
5072	isError: boolean;
5073	/**
5074	* The server's structured result, when its tool declares an output schema.
5075	*/
5076	structuredContent?: unknown;
5077	};
5078
5079	/**
5080	* Hook input for the MessageDisplay event. Fired with each batch of newly completed lines while an assistant message streams. Display-only: the stored message and what the model sees are untouched.
5081	*/
5082	type MessageDisplayHookInput = BaseHookInput & {
5083	hook_event_name: 'MessageDisplay';
5084	/**
5085	* UUID of the current turn.
5086	*/
5087	turn_id: string;
5088	/**
5089	* UUID of the assistant message being displayed. Stable across every flush of the same message. Not the API msg_... id.
5090	*/
5091	message_id: string;
5092	/**
5093	* Zero-based index of this delta within the message. Increments by one per flush.
5094	*/
5095	index: number;
5096	/**
5097	* True on the message's last flush. Exactly one flush per message has it.
5098	*/
5099	final: boolean;
5100	/**
5101	* The newly completed lines since the prior flush. Always whole lines, except on the final flush which may end mid-line. The delta of the final flush is empty when the message ends on a newline; treat final as the end-of-message signal regardless.
5102	*/
5103	delta: string;
5104	};
5105
5106	/**
5107	* What `$.model.complete` takes.
5108	*/
5109	export type ModelCompleteRequest = {
5110	/**
5111	* An alias (`haiku`) or a full model id; resolved and allowlist-checked like
5112	* a `--model` value.
5113	*/
5114	model: string;
5115	/**
5116	* The one user message; the reply's text comes back.
5117	*/
5118	prompt: string;
5119	/**
5120	* Precedes the completion as its system prompt, after the CLI's identity
5121	* block. Default none.
5122	*/
5123	system?: string;
5124	/**
5125	* The reply's token cap: any positive integer up to what one reply can
5126	* hold, the model's own output limit or 64000, whichever is lower.
5127	*
5128	* Default 1024. The reply comes back whole, not streamed, and a provider
5129	* ends such a request at ten minutes, hence the 64000. One past the limit
5130	* is refused, naming it.
5131	*/
5132	maxTokens?: number;
5133	};
5134
5135	/**
5136	* What `$.model.fork` takes.
5137	*/
5138	export type ModelForkRequest = {
5139	/**
5140	* The one user message, appended to the session's own transcript.
5141	*
5142	* The reply's text and usage come back, or null on an API error or a cold
5143	* transcript.
5144	*/
5145	prompt: string;
5146	};
5147
5148	/**
5149	* What `$.model.fork` resolves to when the fork answered: the reply's text
5150	* and what the fork cost.
5151	*/
5152	export type ModelForkResult = {
5153	/**
5154	* The non-error replies' text, joined by newlines.
5155	*/
5156	text: string;
5157	/**
5158	* The fork's token counts, so a plugin can account for what it spent.
5159	*/
5160	usage: ModelForkUsage;
5161	};
5162
5163	/**
5164	* What one fork cost, as the API counted it: the four token counts of the
5165	* fork's completions summed.
5166	*/
5167	export type ModelForkUsage = {
5168	input_tokens: number;
5169	output_tokens: number;
5170	cache_read_input_tokens: number;
5171	cache_creation_input_tokens: number;
5172	};
5173
5174	/**
5175	* The prefixes a glob may name: one or more whole leading segments of an
5176	* event name (`tool` of `tool.call`), derived, plugin nouns included.
5177	*/
5178	export type Namespace<N extends string = EventName> = N extends `${infer Head}.${infer Rest}` ? Head \| `${Head}.${Namespace<Rest>}` : never;
5179
5180	/**
5181	* How many object or array levels a matcher narrows `e` through, counted as
5182	* a tuple's length: the runtime's own limit, which refuses a deeper matcher.
5183	*
5184	* Past it a field keeps its declared type; nothing becomes `any`.
5185	*/
5186	type NarrowDepth = 8;
5187
5188	/**
5189	* `e` in a matched hook: the members of the argument union `E` matcher `P`
5190	* can match, each with the keys `P` names narrowed to what a match implies.
5191	*
5192	* A scalar narrows to the literal, a one-of to what its alternatives give,
5193	* an object key recursively, an array some element of which must match to
5194	* a non-empty tuple; other keys, `unknown` and RegExp-matched fields keep.
5195	*/
5196	export type Narrowed<E, P> = E extends unknown ? NarrowedMember<E, P, []> : never;
5197
5198	/**
5199	* A value of declared type `V` under a one-of, folded over the tuple into
5200	* `Found`: the union of what each alternative narrows `V` to (NarrowedByOne).
5201	*
5202	* An alternative that cannot match adds nothing, so a one-of none of whose
5203	* alternatives can is `never`; a one-of typed as a plain array rather than
5204	* a tuple narrows by the union of its elements at once.
5205	*/
5206	type NarrowedByAny<V, Alternatives extends readonly unknown[], D extends readonly unknown[], Found = never> = Alternatives extends readonly [infer First, ...infer Rest] ? NarrowedByAny<V, Rest, D, Found \| NarrowedByOne<V, First, D>> : Alternatives extends readonly [] ? Found : Found \| NarrowedByOne<V, Alternatives[number], D>;
5207
5208	/**
5209	* A value of declared type `V` under one matcher node `Q` that is not a
5210	* one-of, member of `V` by member; a member that cannot match is `never`.
5211	*
5212	* An array some element of which must match becomes NonEmpty; a RegExp
5213	* keeps the member; an object pattern recurses into an object member, one
5214	* level down; a scalar keeps a member as narrow, and replaces a wider one.
5215	*/
5216	type NarrowedByOne<V, Q, D extends readonly unknown[]> = V extends readonly (infer Item)[] ? [NarrowedValue<Item, Q, [...D, unknown]>] extends [never] ? never : NonEmpty<V, Item> : Q extends RegExp ? V : Q extends object ? V extends object ? NarrowedMember<V, Q, [...D, unknown]> : never : V extends Q ? V : Q extends V ? Q : never;
5217
5218	/**
5219	* One object member `E` under object pattern `P`, `D` levels down: `never`
5220	* when a key of `P` is impossible on it (ImpossibleKeys), else `E` narrowed.
5221	*
5222	* Each key `P` names is narrowed (NarrowedValue); every other key, and each
5223	* key's optionality, stays as declared.
5224	*/
5225	type NarrowedMember<E, P, D extends readonly unknown[]> = [
5226	ImpossibleKeys<E, P, D>
5227	] extends [never] ? {
5228	[K in keyof E]: K extends keyof P ? NarrowedValue<E[K], P[K], D> : E[K];
5229	} : never;
5230
5231	/**
5232	* A value of declared type `V` where the matcher gives `Q`, `D` levels
5233	* down: NarrowedByAny under a one-of (an array), NarrowedByOne otherwise.
5234	*
5235	* As declared once `D` reaches NarrowDepth, or for a field typed `unknown`
5236	* (a tool's input), which no pattern narrows.
5237	*/
5238	type NarrowedValue<V, Q, D extends readonly unknown[]> = D['length'] extends NarrowDepth ? V : unknown extends V ? V : Q extends readonly unknown[] ? NarrowedByAny<V, Q, D> : NarrowedByOne<V, Q, D>;
5239
5240	/**
5241	* `!` before a name or a glob: every event except the ones it selects. `!*`
5242	* would select none, so it is no pattern.
5243	*/
5244	type Negation = `!${Exclude<EventName \| Glob, '*'>}`;
5245
5246	/**
5247	* The rest of the chain, as one hook receives it: made once per dispatch per
5248	* hook, frozen; `next(e)` resolves to the downstream result.
5249	*
5250	* Each call runs the hooks below again; core is the last, and below it `next`
5251	* rejects. Called with no argument it rejects, naming the hook. A hook that
5252	* returns without calling it ends the chain; returning nothing is a failure.
5253	*
5254	* @template S what `next.is(pattern, e)` narrows `e` to, per event: the event's
5255	* argument, or, under a matcher, that argument narrowed by it (MatchedHook)
5256	* @template T the tool `e` names, when it names one: on `tool.call` it types
5257	* the result (NextResultFor); an `e` without `tool` takes the line beneath
5258	*/
5259	export type Next<N extends EventName = EventName, E = Args<N>, O = NextResult<N>, S extends {
5260	[K in N]?: unknown;
5261	} = {
5262	[K in N]: Args<K>;
5263	}> = {
5264	<T extends string>(e: E & ToolNamed<T>): Promise<NextResultFor<N, O, T>>;
5265	(e: E): Promise<O>;
5266	/**
5267	* Continues this dispatch at a tier: `next(e)` with every link between
5268	* this hook's own tier and that one skipped, by tier and narrowing only.
5269	*
5270	* A managed hook's: prepend may name append, builtin or core, append core;
5271	* it never skips a tier with more authority, so no user hook skips the
5272	* org's. A literal on the hook's own `next`; skipped links are traced.
5273	*/
5274	readonly to: {
5275	<T extends string>(e: E & ToolNamed<T>, tier: TargetTier): Promise<NextResultFor<N, O, T>>;
5276	(e: E, tier: TargetTier): Promise<O>;
5277	};
5278	/**
5279	* Aborts when the call this dispatch belongs to is abandoned: the user
5280	* interrupted, a hook above settled first, or this hook ran out of budget.
5281	*
5282	* Anything the hook started (timers, requests) should stop on it. It is an
5283	* AbortSignal of the plugin's own environment, driven by the chain's.
5284	*/
5285	readonly signal: AbortSignal;
5286	/**
5287	* Whether this dispatch's event is selected by `pattern` (a name, a glob,
5288	* a negation), as a type predicate on `e`: `next.is("tool.call", e)`.
5289	*
5290	* Under a matcher the narrowing includes it. `pattern` names events this
5291	* hook covers (PatternOver); a name outside them is a compile error.
5292	*/
5293	readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<S[Extract<N, Selected<M>>]>;
5294	/**
5295	* The name of this dispatch's event, as a value, for a glob hook to log or
5296	* switch on.
5297	*/
5298	readonly event: N;
5299	/**
5300	* Who raised this dispatch: the calling plugin's name and the tier it sits
5301	* in (Origin); the engine reads `{ plugin: "engine", tier: "core" }`.
5302	*
5303	* Set by the host alone, from the environment the call came from (its own
5304	* MessagePort) and that plugin's seat; nothing a plugin writes reaches it.
5305	* Every hook of one dispatch sees the same origin, and `next.to` keeps it.
5306	*
5307	* @example
5308	* return next.origin.tier === "prepend" ? next.to(e, "append") : next(e)
5309	*/
5310	readonly origin: Origin;
5311	/**
5312	* What settled beneath this hook on its latest `next()` call, the one
5313	* started last: an entry per link beneath, nearest first, the engine's last.
5314	*
5315	* Empty before `next` is called; filled even when `next` rejected; a link
5316	* still running joins in place later, nothing listed leaves; it ends short
5317	* of the engine at a link that answered its last call itself. Data, frozen.
5318	*/
5319	readonly trace: readonly TraceEntry<N, E, O>[];
5320	/**
5321	* How much time this hook runs under and how much is left (NextBudget),
5322	* read fresh on each access; HookBudget says what the clock counts.
5323	*
5324	* It stands still while a `next` or `$` call of the hook's is in flight;
5325	* in a `.catch` handler it is the grace, `ms` being `next.error.budget`.
5326	*
5327	* @example
5328	* if (next.budget.remainingMs < 2_000) return next(e) // skip the polish
5329	*/
5330	readonly budget: NextBudget;
5331	};
5332
5333	/**
5334	* The budget the code reading `next.budget` runs under: the whole allowance
5335	* and what is left of it now, plain data read fresh on each access.
5336	*
5337	* In a hook `ms` is HookBudget's `ms`; in a `.catch` handler its `catchMs`
5338	* (equal to `next.error.budget`); on a `next` nothing meters (the engine's
5339	* own, a test's root one) `ms` is 0 and `remainingMs` Infinity.
5340	*
5341	* @example
5342	* if (next.budget.remainingMs < 2_000) return next(e) // skip the slow path
5343	*/
5344	export type NextBudget = {
5345	/**
5346	* The whole budget in milliseconds; 0 where nothing meters this `next`.
5347	*/
5348	readonly ms: number;
5349	/**
5350	* What is left of it now, in milliseconds, never below 0; Infinity where
5351	* nothing meters. It stands still while a `next` or `$` call is in flight.
5352	*/
5353	readonly remainingMs: number;
5354	};
5355
5356	/**
5357	* What `next(e)` resolves to for event `N`: the event's result, except at
5358	* `engine.create`, where the steps beneath return `$` as built so far.
5359	*
5360	* A withheld noun is on that `$` as a stub, so the built table is typed
5361	* whole where what a hook returns (EngineCreateResult) is partial.
5362	*/
5363	export type NextResult<N extends EventName> = N extends 'engine.create' ? EngineInterfaceBuilt : EventResult<N>;
5364
5365	/**
5366	* What `next(e)` resolves to once `e.tool` is the literal `T`: on `tool.call`
5367	* the result typed for that tool; on every other event, `O` as declared.
5368	*
5369	* `result` is Bash's record after `e.tool === "Bash"`; an un-narrowed `e`
5370	* names every tool, and `result` stays `unknown`.
5371	*/
5372	export type NextResultFor<N extends EventName, O, T extends string> = [
5373	N
5374	] extends ['tool.call'] ? ToolCallResult<T> : O;
5375
5376	/**
5377	* The argument of a call on `$` that takes nothing (`$.session.cwd()`): an
5378	* object with no keys.
5379	*/
5380	type NoArgs = Record<never, never>;
5381
5382	/**
5383	* The events whose argument is exactly NoArgs (`session.cwd`, a declared
5384	* plugin noun's `() => ...`); their overloads come last (LateOverload).
5385	*/
5386	type NoArgsEvent = {
5387	[N in EventName]: Args<N> extends NoArgs ? NoArgs extends Args<N> ? N : never : never;
5388	}[EventName];
5389
5390	/**
5391	* What an `engine.create` hook receives as `$`: nothing. Every property
5392	* reads as `never`, so `$.model` inside the hook is a compile error.
5393	*/
5394	export type NoEngineInterface = {
5395	readonly [noun: string]: never;
5396	};
5397
5398	/**
5399	* Array type `V`, of element `Item`, once some element of it is known to
5400	* match: a tuple of at least one `Item`, readonly when `V` is.
5401	*
5402	* So `e` still passes wherever the declared array is taken; a `V` that is
5403	* already a non-empty tuple is kept as it is.
5404	*/
5405	type NonEmpty<V, Item> = V extends readonly [unknown, ...unknown[]] ? V : V extends Item[] ? [Item, ...Item[]] : readonly [Item, ...Item[]];
5406
5407	type NotificationHookInput = BaseHookInput & {
5408	hook_event_name: 'Notification';
5409	message: string;
5410	title?: string;
5411	notification_type: string;
5412	};
5413
5414	/**
5415	* The declared plugin nouns' methods as event rows (NounEventRow), one per
5416	* `<noun>.<method>` that is a function; a member that is not is no event.
5417	*/
5418	type NounEvent = {
5419	[K in PluginNoun]: {
5420	[M in keyof EngineInterface[K] & string]: EngineInterface[K][M] extends (...args: infer Parameters) => infer Result ? NounEventRow<`${K}.${M}`, Parameters extends readonly [] ? NoArgs : Parameters[0], Awaited<Result>> : never;
5421	}[keyof EngineInterface[K] & string];
5422	}[PluginNoun];
5423
5424	/**
5425	* The name of a declared plugin noun's event (`voice.speak`).
5426	*/
5427	type NounEventName = keyof NounEventOf & string;
5428
5429	/**
5430	* The events of the plugin nouns declared on EngineInterface, by name: the
5431	* argument of each `<noun>.<method>`. Empty until a plugin declares a noun.
5432	*
5433	* @example
5434	* declare module "claude-code" { interface EngineInterface { voice: Voice } }
5435	*/
5436	export type NounEventOf = {
5437	[E in NounEvent as E['name']]: E['args'];
5438	};
5439
5440	/**
5441	* The result of a declared plugin noun's event as its hooks see it:
5442	* `{ value }` (the method's answer) or `{ deny }`.
5443	*/
5444	type NounEventResult<N extends NounEventName> = ValueOrDeny<NounValueOf[N]>;
5445
5446	/**
5447	* One method of a declared plugin noun as an event row: its event's name,
5448	* argument (the method's first parameter) and value (its awaited result).
5449	*/
5450	type NounEventRow<Name extends string, Args, Value> = {
5451	name: Name;
5452	args: Args;
5453	value: Value;
5454	};
5455
5456	/**
5457	* What each declared plugin noun's method answers (the `value` of its
5458	* event's result), by event name.
5459	*/
5460	type NounValueOf = {
5461	[E in NounEvent as E['name']]: E['value'];
5462	};
5463
5464	/**
5465	* Registers `hook` on the events `pattern` selects: one by name, every one
5466	* under a namespace (`classic.`), all (``), or all but some (`!tool.*`).
5467	*
5468	* One function stands on every selected event (`next.event` says which),
5469	* under a matcher for the inputs it matches; a plugin's registrations nest
5470	* in order, first outermost; a repeat throws. Returns the Registration.
5471	*
5472	* @see HookBudget the time each hook has per dispatch (its own time: waits
5473	* on `next` and `$` are free), read live from `next.budget`
5474	*/
5475	export type On = {
5476	<P extends Pattern>(pattern: P, hook: NoInfer<HookFor<P>>): Registration<HookFor<P>>;
5477	<P extends Pattern, const M extends Matcher<Args<MatchedNames<P>>>>(pattern: P, matcher: M, hook: NoInfer<MatchedHook<P, M>>): Registration<MatchedHook<P, M>>;
5478	};
5479
5480	/**
5481	* The part of a transcript message the surface that drew it has on screen:
5482	* units `first` to `last` of the message's `of`, counted from its start.
5483	*
5484	* The terminal counts the rows the site laid out, from its first (the blank
5485	* row the engine draws above a message is its row 0; a hook's tree starts at
5486	* its own); other surfaces count in their unit, so compare `first / of` there.
5487	*
5488	* @remarks While `null` the terminal holds the site at the rows it last laid
5489	* out (a scroller's geometry needs real rows); on screen, draw anything.
5490	* @example if (e.props.onScreen) shown.set(e.requestId, e.props.onScreen)
5491	* else shown.delete(e.requestId) // the band's legend lists `shown`
5492	*/
5493	type OnScreen = {
5494	/**
5495	* The unit inside the viewport, from 0: on the terminal, `7` when the
5496	* message's top seven rows are scrolled away.
5497	*/
5498	first: number;
5499	/**
5500	* The unit inside the viewport, inclusive; at least `first`.
5501	*/
5502	last: number;
5503	/**
5504	* The message's whole extent in the same unit, as laid out (a hook's tree
5505	* taller than the engine's counts its own rows); more than `last`.
5506	*
5507	* One surface's numbers say nothing of another's: what the phone shows the
5508	* terminal may not, and each `ui.render` carries its own surface's.
5509	*/
5510	of: number;
5511	};
5512
5513	/**
5514	* The keys a variant with a string index signature (an MCP tool's input)
5515	* takes beyond its own: another variant's key as typed there; others free.
5516	*
5517	* So a misspelt value for a key some variant declares (`command: 5`) is
5518	* refused on every variant, not admitted by the open one.
5519	*/
5520	type OpenMatcher<I, All> = {
5521	readonly [K in Exclude<MatcherKeys<All>, KnownKeys<I>>]?: MatcherValue<MatcherValueOf<All, K>>;
5522	} & Readonly<Record<string, unknown>>;
5523
5524	/**
5525	* The name of a call on `$` the host serves, as an event.
5526	*/
5527	export type OpEventName = keyof OpEventOf;
5528
5529	/**
5530	* The calls on `$` the host serves, as events: `e` is the call's argument as
5531	* it crosses to the host, and every one is hookable by name and by `on("*")`.
5532	*
5533	* A hook above the caller passes it on, rewrites it, refuses it with
5534	* `{ deny }` or answers with `{ value }`; core is the host's implementation.
5535	* The calling hook alone is skipped, and `next.origin` names the caller.
5536	*/
5537	export type OpEventOf = {
5538	/**
5539	* The argument of `$.model.complete(request)`.
5540	*/
5541	'model.complete': ModelCompleteRequest;
5542	/**
5543	* The argument of `$.model.classify(text, labels, options)`.
5544	*/
5545	'model.classify': {
5546	text: string;
5547	labels: readonly string[];
5548	options?: ClassifyOptions;
5549	};
5550	/**
5551	* The argument of `$.model.fork(request)`.
5552	*/
5553	'model.fork': ModelForkRequest;
5554	/**
5555	* The clip and how to play it (`shouldLoop`, `gain`); the signal does not
5556	* cross.
5557	*/
5558	'audio.play': {
5559	clip: AudioClip;
5560	shouldLoop: boolean;
5561	gain?: number;
5562	};
5563	/**
5564	* The argument of `$.audio.speak(text, { voice })`.
5565	*/
5566	'audio.speak': SpeakRequest;
5567	/**
5568	* The argument of `$.mcp.call(server, tool, args)`.
5569	*/
5570	'mcp.call': {
5571	server: string;
5572	tool: string;
5573	args: Record<string, unknown>;
5574	};
5575	/**
5576	* The argument of `$.session.cwd()`.
5577	*/
5578	'session.cwd': NoArgs;
5579	/**
5580	* The argument of `$.session.root()`.
5581	*/
5582	'session.root': NoArgs;
5583	/**
5584	* The argument of `$.session.model()`.
5585	*/
5586	'session.model': NoArgs;
5587	/**
5588	* The argument of `$.session.turns()`.
5589	*/
5590	'session.turns': NoArgs;
5591	/**
5592	* The argument of `$.session.id()`.
5593	*/
5594	'session.id': NoArgs;
5595	/**
5596	* The argument of `$.session.messages()`.
5597	*/
5598	'session.messages': NoArgs;
5599	/**
5600	* The argument of `$.session.repo()`.
5601	*/
5602	'session.repo': NoArgs;
5603	/**
5604	* The argument of `$.session.surface()`.
5605	*
5606	* @deprecated with `$.session.surface()`; hook `session.surfaces`
5607	*/
5608	'session.surface': NoArgs;
5609	/**
5610	* The argument of `$.session.surfaces()`.
5611	*/
5612	'session.surfaces': NoArgs;
5613	/**
5614	* The argument of `$.session.authorize()`.
5615	*/
5616	'session.authorize': NoArgs;
5617	/**
5618	* The argument of `$.session.usage({ breakdown, columns })`.
5619	*/
5620	'session.usage': SessionUsageArgs;
5621	/**
5622	* The argument of `$.session.version()`.
5623	*/
5624	'session.version': NoArgs;
5625	/**
5626	* The argument of `$.turn.abort({ turnId })`.
5627	*/
5628	'turn.abort': {
5629	turnId: string;
5630	};
5631	/**
5632	* The argument of `$.prompt.read()`.
5633	*/
5634	'prompt.read': NoArgs;
5635	/**
5636	* The argument of `$.tool.list()`.
5637	*/
5638	'tool.list': NoArgs;
5639	/**
5640	* The argument of `$.tool.register(spec)`.
5641	*/
5642	'tool.register': Required<ToolSpec>;
5643	/**
5644	* The argument of `$.command.list()`.
5645	*/
5646	'command.list': NoArgs;
5647	/**
5648	* The argument of `$.command.register(spec)`.
5649	*/
5650	'command.register': CommandSpec;
5651	/**
5652	* The argument of `$.config.list()`.
5653	*/
5654	'config.list': NoArgs;
5655	/**
5656	* The argument of `$.agent.list()`.
5657	*/
5658	'agent.list': NoArgs;
5659	/**
5660	* The argument of `$.agent.register(spec)`: the agent type as the plugin
5661	* defined it. A hook above rewrites any of it; the type stays the caller's.
5662	*/
5663	'agent.register': AgentSpec;
5664	/**
5665	* The argument of `$.ui.toast(text, { timeoutMs })`.
5666	*/
5667	'ui.toast': {
5668	text: string;
5669	timeoutMs?: number;
5670	};
5671	/**
5672	* The argument of `$.ui.status(text)`; `text` undefined clears the line.
5673	*/
5674	'ui.status': {
5675	text: string \| undefined;
5676	};
5677	/**
5678	* The argument of `$.ui.log(text, { to })`; `to` is always present
5679	* (UiLogSink), and `next({ ...e, to: "debug" })` keeps a line off screen.
5680	*/
5681	'ui.log': {
5682	text: string;
5683	to: UiLogSink;
5684	};
5685	/**
5686	* The argument of `$.ui.notice(tool_use_id, text)`.
5687	*/
5688	'ui.notice': {
5689	tool_use_id: string;
5690	text: string \| undefined;
5691	};
5692	/**
5693	* The argument of `$.ui.invalidate(event)`.
5694	*/
5695	'ui.invalidate': {
5696	event: InvalidatableEventName;
5697	};
5698	/**
5699	* The argument of `$.ui.open({ id, title, focus })`; a hook above the
5700	* opener may retitle it or refuse it with `{ deny }`, never rename it.
5701	*/
5702	'ui.open': PaneOpenArgs;
5703	/**
5704	* The argument of `$.ui.close({ id })` with `origin` `plugin`; the engine
5705	* raises it too, for the person (`person`) and an unload (`unload`).
5706	*/
5707	'ui.close': PaneCloseInput;
5708	/**
5709	* The argument of `$.ui.panes()`.
5710	*/
5711	'ui.panes': NoArgs;
5712	/**
5713	* The argument of `$.ui.blit(...)`: a Raster's `cells` or a keyed Image's
5714	* `source`; a hook above may rewrite either with `next`, or `{ deny }`.
5715	*/
5716	'ui.blit': UiBlitArgs;
5717	/**
5718	* The argument of `$.fs.read(path, { as })`: `as` is `text` unless the
5719	* caller asked for `bytes`.
5720	*/
5721	'fs.read': {
5722	path: string;
5723	as: FsReadAs;
5724	};
5725	/**
5726	* The argument of `$.fs.write(path, text)`.
5727	*/
5728	'fs.write': {
5729	path: string;
5730	text: string;
5731	};
5732	/**
5733	* The argument of `$.fs.list(path)`.
5734	*/
5735	'fs.list': {
5736	path: string;
5737	};
5738	/**
5739	* The argument of `$.fs.exists(path)`.
5740	*/
5741	'fs.exists': {
5742	path: string;
5743	};
5744	/**
5745	* The argument of `$.fs.stat(path, { resolve })`: `resolve` is false
5746	* unless the caller asked where the path lands.
5747	*/
5748	'fs.stat': {
5749	path: string;
5750	resolve: boolean;
5751	};
5752	/**
5753	* The argument of `$.fs.ancestors({ names, of, below })`.
5754	*/
5755	'fs.ancestors': FsAncestorsRequest;
5756	/**
5757	* The argument of `$.store.get(key)`.
5758	*/
5759	'store.get': {
5760	key: string;
5761	};
5762	/**
5763	* The argument of `$.store.set(key, value)`.
5764	*/
5765	'store.set': {
5766	key: string;
5767	value: unknown;
5768	};
5769	/**
5770	* The argument of `$.store.delete(key)`.
5771	*/
5772	'store.delete': {
5773	key: string;
5774	};
5775	/**
5776	* The argument of `$.store.keys()`.
5777	*/
5778	'store.keys': NoArgs;
5779	/**
5780	* The argument of `$.clock.now()`.
5781	*/
5782	'clock.now': NoArgs;
5783	/**
5784	* The argument of `$.clock.sleep(ms, { signal })`; the signal does not
5785	* cross, it aborts the dispatch.
5786	*/
5787	'clock.sleep': ClockWait;
5788	/**
5789	* The argument of `$.clock.after(ms, fn)`: the wait before `fn`, which
5790	* stays in the plugin's environment and runs once the dispatch resolves.
5791	*/
5792	'clock.after': ClockWait;
5793	/**
5794	* The argument of `$.clock.every(ms, fn)`, dispatched once per period:
5795	* `fn` runs each time a dispatch resolves, and the next period is asked.
5796	*/
5797	'clock.every': ClockWait;
5798	/**
5799	* The argument of `$.http.fetch(url, init)`.
5800	*/
5801	'http.fetch': {
5802	url: string;
5803	init?: HttpInit;
5804	};
5805	/**
5806	* The argument of `$.process.run(argv, init)`.
5807	*/
5808	'process.run': {
5809	argv: readonly string[];
5810	init?: ProcessRunInit;
5811	};
5812	/**
5813	* The argument of `$.settings.read({ source })`.
5814	*/
5815	'settings.read': SettingsReadArgs;
5816	/**
5817	* The argument of `$.env.get(name)`; `name` is identity, pinned.
5818	*/
5819	'env.get': {
5820	name: string;
5821	};
5822	/**
5823	* The argument of `$.env.set(name, value)`; `name` is identity, pinned,
5824	* and no `value` unsets.
5825	*/
5826	'env.set': {
5827	name: string;
5828	value?: string;
5829	};
5830	};
5831
5832	/**
5833	* The result of a call on `$` as its event's hooks see it: `{ value }` (the
5834	* call's answer) or `{ deny }`.
5835	*/
5836	export type OpEventResult<N extends OpEventName = OpEventName> = ValueOrDeny<OpValueOf[N]>;
5837
5838	/**
5839	* What each call on `$` answers (the `value` of its event's result), by event
5840	* name.
5841	*/
5842	export type OpValueOf = {
5843	'model.complete': string;
5844	'model.classify': string \| undefined;
5845	'model.fork': ModelForkResult \| null;
5846	'audio.play': void;
5847	'audio.speak': SpeakResult;
5848	'mcp.call': McpToolResult;
5849	'session.cwd': string;
5850	'session.root': string;
5851	'session.model': string;
5852	'session.turns': number;
5853	'session.id': string;
5854	'session.messages': SessionMessage[];
5855	'session.repo': SessionRepo \| null;
5856	'session.surface': RenderSurface \| null;
5857	'session.surfaces': readonly RenderSurface[];
5858	/**
5859	* The credential handle, or null where the build or the provider has no
5860	* first-party credential to hold.
5861	*/
5862	'session.authorize': SessionAuthorization;
5863	'session.usage': SessionUsage;
5864	/**
5865	* The engine's version, its release, and its build time when stamped.
5866	*/
5867	'session.version': SessionVersion;
5868	'turn.abort': void;
5869	/**
5870	* The box as it stands; the empty box where the session draws none.
5871	*/
5872	'prompt.read': PromptBox;
5873	'tool.list': ToolInfo[];
5874	'tool.register': {
5875	tool: string;
5876	};
5877	'command.list': CommandInfo[];
5878	'command.register': {
5879	command: string;
5880	};
5881	'config.list': ConfigRow[];
5882	'agent.list': AgentInfo[];
5883	'agent.register': {
5884	agent: string;
5885	};
5886	'ui.toast': void;
5887	'ui.status': void;
5888	'ui.log': void;
5889	'ui.notice': void;
5890	'ui.invalidate': void;
5891	'ui.open': void;
5892	'ui.close': void;
5893	/**
5894	* The calling plugin's open panes, placed then unplaced, in open order.
5895	*/
5896	'ui.panes': readonly UiPane[];
5897	'ui.blit': UiBlitResult;
5898	/**
5899	* The text; `{ base64 }` when asked for bytes.
5900	*/
5901	'fs.read': string \| FsBytes;
5902	'fs.write': void;
5903	'fs.list': FsEntry[];
5904	'fs.exists': boolean;
5905	'fs.stat': FsStat;
5906	'fs.ancestors': readonly FsAncestor[];
5907	'store.get': unknown;
5908	'store.set': void;
5909	'store.delete': void;
5910	'store.keys': string[];
5911	/**
5912	* Milliseconds since the epoch.
5913	*/
5914	'clock.now': number;
5915	'clock.sleep': void;
5916	'clock.after': void;
5917	'clock.every': void;
5918	'http.fetch': HttpResponse;
5919	'process.run': ProcessRunResult;
5920	'settings.read': Settings;
5921	'env.get': string \| undefined;
5922	'env.set': void;
5923	};
5924
5925	/**
5926	* One call signature per event in `Names`, intersected, the ambiguous ones
5927	* (LateOverload) after the rest: `next` for a hook covering several events.
5928	*
5929	* An empty group contributes nothing (Overloads<never> is unknown).
5930	*/
5931	type OrderedOverloads<Names extends EventName> = Overloads<Exclude<Names, LateOverload>> & Overloads<Extract<Names, 'classic.PreToolUse'>> & Overloads<Extract<Names, 'turn.abort'>> & Overloads<Extract<Names, NoArgsEvent>>;
5932
5933	/**
5934	* Who raised a dispatch, as `next.origin` holds it: the calling plugin's
5935	* name and the tier it sits in; the engine reads `engine` in `core`.
5936	*
5937	* The same pair a `next.trace` entry names its link by, and an event's
5938	* `provider` its subject's definer by. Set by the host from where the call
5939	* came from and where that plugin was seated; nothing a plugin writes.
5940	*/
5941	export type Origin = {
5942	/**
5943	* Whose hook made the `$` call, by name; `"engine"` for a call site,
5944	* `"client"` for a `Client` surface module's `ui.message` post.
5945	*/
5946	readonly plugin: string;
5947	/**
5948	* Where that plugin sits among the chain's tiers (Tier); `"core"` for the
5949	* engine, the owning plugin's for a `client` post.
5950	*/
5951	readonly tier: Tier;
5952	};
5953
5954	/**
5955	* One call signature per event in `Names`, intersected into an overload set.
5956	*/
5957	type Overloads<Names extends EventName> = UnionToIntersection<{
5958	[N in Names]: (e: Args<N>) => Promise<NextResult<N>>;
5959	}[Names]>;
5960
5961	/**
5962	* The argument of `$.ui.close`: the pane to close (`{ id }`). `origin` is
5963	* the engine's to set: a plugin's call reads `plugin` at the hooks.
5964	*/
5965	export type PaneCloseArgs = Omit<PaneCloseInput, 'origin'>;
5966
5967	/**
5968	* The input of `ui.close`: the pane closing and why (PaneCloseOrigin).
5969	* Closing an id that is not open does nothing.
5970	*/
5971	export type PaneCloseInput = {
5972	/**
5973	* What `$.ui.open` named the pane; pinned: `next(e)` passes it on.
5974	*/
5975	id: string;
5976	/**
5977	* Who closes it, set by the engine: a hook that answers without `next`
5978	* keeps the pane open on `plugin` and `person`, never on `unload`.
5979	*/
5980	origin: PaneCloseOrigin;
5981	};
5982
5983	/**
5984	* Why a pane closes, as the engine stamped it at `ui.close`.
5985	*
5986	* `unload` drops a pane nothing draws any more (its plugin unloaded, or its
5987	* drawing threw): it is gone before the hooks hear of it, and its opener's
5988	* hooks do not run. `next(e)` passes the origin on as received; none sets it.
5989	*/
5990	export type PaneCloseOrigin = {
5991	/**
5992	* `plugin`, a plugin's `$.ui.close`; `person`, the person's close mark or
5993	* close key; `unload`, the engine's own.
5994	*/
5995	kind: 'plugin' \| 'person' \| 'unload';
5996	};
5997
5998	/**
5999	* The argument of `$.ui.open`: which pane, its title, whether it asks the
6000	* person's keyboard, its dialog manners, its size: rows inline, columns docked.
6001	*
6002	* An open answering the person's input (a command or prompt they entered, a
6003	* press) is placed at any width; one the plugin makes on its own waits
6004	* undrawn below 144 terminal columns, 110 once they asked for that id.
6005	*/
6006	export type PaneOpenArgs = {
6007	/**
6008	* Names the pane: 1-64 of letters, digits, `_` and `-`. One pane per id:
6009	* opening an open id delivers the new title, never a second instance.
6010	*
6011	* Pinned at the hooks: `next(e)` passes it on; the title and focus rewrite.
6012	*/
6013	id: string;
6014	/**
6015	* The pane's tab while more than one pane is open (with one, no title is
6016	* drawn), and the `title` its hook sees; the id when omitted.
6017	*
6018	* An unpaired surrogate half (a `.slice()` through an emoji) is drawn as
6019	* U+FFFD; a control character is refused.
6020	*/
6021	title?: string;
6022	/**
6023	* A request, not a grant: the surface focuses (and raises) the pane only
6024	* while the prompt has the keys over an empty composer.
6025	*
6026	* An element of the band or a pane the person holds, text in the
6027	* composer, a dialog or a survey each refuse it: the pane opens without
6028	* the keyboard.
6029	*/
6030	focus?: true;
6031	/**
6032	* While the pane holds the keyboard, the key that hands it back (Escape)
6033	* also closes it as the person's close does: `ui.close`, origin `person`.
6034	*
6035	* So does Escape at an idle, empty prompt once the prompt has the keys
6036	* again (the person typed, or `focus` was refused); over text, a running
6037	* turn, a dialog, a footer selection, a viewed agent's transcript or a
6038	* prompt mode of its own the key stays theirs.
6039	*
6040	* A hook may refuse that close and keep it open. Left out, Escape returns
6041	* the keys to the prompt and the pane stays. Each open sets it anew, as it
6042	* sets the title.
6043	*/
6044	closeOnEscape?: true;
6045	/**
6046	* While the pane is on screen the surface holds its transient toasts (the
6047	* notification line under the prompt) and shows them once it closes.
6048	*
6049	* As it does behind the engine's own side panel; pinned warnings still
6050	* show. Left out, toasts show as they come. Each open sets it anew.
6051	*/
6052	holdToasts?: true;
6053	/**
6054	* The body rows the pane's content wants while seated inline above the
6055	* prompt: it opens that tall, up to what the layout spares, not a third.
6056	*
6057	* A request, not a grant: a size the person dragged or keyed the block
6058	* to wins, this session's or a kept one, and the dock ignores it. A
6059	* positive whole number; left out, a third. Each open sets it anew.
6060	*/
6061	rows?: number;
6062	/**
6063	* The body columns the pane's content wants while docked beside a
6064	* fullscreen transcript: the dock opens that wide, floor to ceiling.
6065	*
6066	* A request, not a grant: a width the person dragged or keyed the dock
6067	* to wins, this session's or a kept one, and the inline block ignores
6068	* it. A positive whole number; left out, the share. Each open sets it anew.
6069	*
6070	* @example
6071	* await $.ui.open({ id: "browser", focus: true, rows: 24, columns: 100 })
6072	*/
6073	columns?: number;
6074	};
6075
6076	/**
6077	* What `on(pattern, hook)` and `next.is(pattern, e)` take: an event's name,
6078	* a glob (``, `classic.`), or a negation of either (`!tool.describe`).
6079	*/
6080	export type Pattern = EventName \| Glob \| Negation;
6081
6082	/**
6083	* The patterns `next.is` takes in a hook covering the events `N`: their
6084	* names, `*`, a glob over one of their namespaces, or a negation.
6085	*
6086	* A name none of them has is a compile error, as is a glob over a namespace
6087	* none is under; a negation that selects none of them narrows `e` to never.
6088	*/
6089	type PatternOver<N extends EventName> = N \| '' \| `${Namespace<N>}.` \| Negation;
6090
6091	type PermissionBehavior = 'allow' \| 'deny' \| 'ask';
6092
6093	type PermissionDeniedHookInput = BaseHookInput & {
6094	hook_event_name: 'PermissionDenied';
6095	tool_name: string;
6096	tool_input: unknown;
6097	tool_use_id: string;
6098	reason: string;
6099	mcp_server?: McpServerProvenance;
6100	};
6101
6102	/**
6103	* Permission mode for controlling how tool executions are handled. 'default' - Standard behavior, prompts for dangerous operations. 'acceptEdits' - Auto-accept file edit operations. 'bypassPermissions' - Bypass all permission checks (requires allowDangerouslySkipPermissions). 'plan' - Planning mode, no actual tool execution. 'dontAsk' - Don't prompt for permissions, deny if not pre-approved. 'auto' - Use a model classifier to approve/deny permission prompts.
6104	*/
6105	type PermissionMode = 'default' \| 'acceptEdits' \| 'bypassPermissions' \| 'plan' \| 'dontAsk' \| 'auto';
6106
6107	/**
6108	* A `classic.PermissionRequest` answer's `decision`, as the classic hook's
6109	* `hookSpecificOutput.decision`: allow (with a rewrite or rules) or deny.
6110	*/
6111	export type PermissionRequestDecision = {
6112	behavior: 'allow';
6113	updatedInput?: Record<string, unknown>;
6114	updatedPermissions?: PermissionUpdates;
6115	} \| {
6116	behavior: 'deny';
6117	message?: string;
6118	interrupt?: true;
6119	};
6120
6121	type PermissionRequestHookInput = BaseHookInput & {
6122	hook_event_name: 'PermissionRequest';
6123	tool_name: string;
6124	tool_input: unknown;
6125	permission_suggestions?: PermissionUpdate[];
6126	mcp_server?: McpServerProvenance;
6127	};
6128
6129	type PermissionRuleValue = {
6130	toolName: string;
6131	ruleContent?: string;
6132	};
6133
6134	type PermissionUpdate = {
6135	type: 'addRules';
6136	rules: PermissionRuleValue[];
6137	behavior: PermissionBehavior;
6138	destination: PermissionUpdateDestination;
6139	} \| {
6140	type: 'replaceRules';
6141	rules: PermissionRuleValue[];
6142	behavior: PermissionBehavior;
6143	destination: PermissionUpdateDestination;
6144	} \| {
6145	type: 'removeRules';
6146	rules: PermissionRuleValue[];
6147	behavior: PermissionBehavior;
6148	destination: PermissionUpdateDestination;
6149	} \| {
6150	type: 'setMode';
6151	mode: PermissionMode;
6152	destination: PermissionUpdateDestination;
6153	} \| {
6154	type: 'addDirectories';
6155	directories: string[];
6156	destination: PermissionUpdateDestination;
6157	} \| {
6158	type: 'removeDirectories';
6159	directories: string[];
6160	destination: PermissionUpdateDestination;
6161	};
6162
6163	type PermissionUpdateDestination = 'userSettings' \| 'projectSettings' \| 'localSettings' \| 'session' \| 'cliArg';
6164
6165	/**
6166	* The permission rules a PermissionRequest allow may add: the shape of the
6167	* request's own `permission_suggestions` (the SDK's PermissionUpdate list).
6168	*/
6169	type PermissionUpdates = NonNullable<ClassicHookInputs['PermissionRequest']['permission_suggestions']>;
6170
6171	/**
6172	* How `$.audio.play` plays a clip: looped until `signal` aborts, or once.
6173	*
6174	* A loop needs the signal that ends it; a single play takes one as an option.
6175	*/
6176	export type PlayOptions = {
6177	/**
6178	* Repeat the clip until `signal` aborts (the promise then resolves).
6179	*/
6180	shouldLoop: true;
6181	/**
6182	* Linear gain, from 0 to 4; default 1.
6183	*/
6184	gain?: number;
6185	/**
6186	* Stops the clip: playback ends at once and the promise resolves.
6187	*/
6188	signal: AbortSignal;
6189	} \| {
6190	/**
6191	* Play once.
6192	*/
6193	shouldLoop?: false;
6194	/**
6195	* Linear gain, from 0 to 4; default 1.
6196	*/
6197	gain?: number;
6198	/**
6199	* Stops the clip early, as above.
6200	*/
6201	signal?: AbortSignal;
6202	};
6203
6204	/**
6205	* The nouns a plugin declared on `$` by merging into EngineInterface; never
6206	* one the engine's own events are under (`tool`, `session`, `ui`).
6207	*/
6208	type PluginNoun = Exclude<keyof EngineInterface & string, keyof CoreEngineInterface \| Namespace<CoreEventName>>;
6209
6210	/**
6211	* A plugin's options as `register(on, options)` receives them: the values of
6212	* the fields its manifest's `userConfig` declares, defaults filled in.
6213	*
6214	* Stored in settings.json `pluginConfigs[<plugin>].options` (sensitive ones
6215	* in secure storage), validated against the declared `type` before the module
6216	* loads; a required field with no value fails the load, naming the field. A
6217	* string field that declares `options` holds one of them: `/config` draws it
6218	* as a picker over them, and a stored value outside them counts as unset, so
6219	* its default applies. A `--plugin-dir` plugin's key is its plugin.json
6220	* `<name>` (or `<name>@inline`).
6221	*/
6222	export type PluginOptions = Readonly<Record<string, string \| number \| boolean \| readonly string[]>>;
6223
6224	/**
6225	* The input of `plugin.register`: one hooks module the engine is about to
6226	* load, read off its manifest and its scanned source. Every field is pinned.
6227	*
6228	* `tier` and `uses` are the host's reading of the module, what a gate holds
6229	* it to; `name`, `root`, `version` and `provenance` are its own word (its
6230	* manifest, its place), so a rule keyed on them is one a rename walks past.
6231	*/
6232	export type PluginRegisterInput = {
6233	/**
6234	* The plugin's name, as its own plugin.json declares it.
6235	*/
6236	name: string;
6237	/**
6238	* Where its hooks would stand among the chain's tiers (Tier); never
6239	* `core`, the engine's own.
6240	*/
6241	tier: Exclude<Tier, 'core'>;
6242	/**
6243	* The plugin's directory (the one holding plugin.json), absolute.
6244	*/
6245	root: string;
6246	/**
6247	* Its manifest's `version`, when it states one.
6248	*/
6249	version?: string;
6250	/**
6251	* Where the plugin came from, as the loader keys it: `<name>@<marketplace>`
6252	* installed, `<name>@inline` by `--plugin-dir`, `<name>@builtin` bundled.
6253	*/
6254	provenance: string;
6255	/**
6256	* What the module hooks and calls, as scanned (PluginRegisterUses).
6257	*/
6258	uses: PluginRegisterUses;
6259	};
6260
6261	/**
6262	* What a `plugin.register` hook returns and what `next(e)` resolves to:
6263	* `{ allow: true }` from core, or `{ refuse: reason }`.
6264	*/
6265	export type PluginRegisterResult = {
6266	/**
6267	* The module loads: its `engine.create` step runs and its hooks join.
6268	*/
6269	allow: true;
6270	refuse?: undefined;
6271	} \| {
6272	/**
6273	* The module does not load: no step, no hooks, no tools or commands;
6274	* the transcript names the plugin that refused and this reason.
6275	*/
6276	refuse: string;
6277	allow?: undefined;
6278	};
6279
6280	/**
6281	* What a hooks module uses, as the host scanned its source before loading it:
6282	* the same lists `claude plugin validate` prints and the host's rule reads.
6283	*
6284	* Exact, since a module that spells `on`, `$` or `$.env` other than literally
6285	* does not load.
6286	*/
6287	export type PluginRegisterUses = {
6288	/**
6289	* The patterns its `on(...)` registrations name, as written (`tool.call`,
6290	* ``, `classic.`, `!tool.describe`), in registration order, each once.
6291	*/
6292	events: readonly string[];
6293	/**
6294	* What it calls on `$`, spelled `noun.method` (`fs.write`, `http.fetch`),
6295	* sorted, each once.
6296	*/
6297	calls: readonly string[];
6298	/**
6299	* The environment variables its `$.env.get` and `$.env.set` calls name;
6300	* absent when it calls neither.
6301	*/
6302	env?: {
6303	/**
6304	* The names its `$.env.get` calls spell, sorted, each once.
6305	*/
6306	reads: readonly string[];
6307	/**
6308	* The names its `$.env.set` calls spell, sorted, each once.
6309	*/
6310	writes: readonly string[];
6311	};
6312	};
6313
6314	/**
6315	* Whose element: the plugin whose hook drew it, stamped by the runtime as the
6316	* tree leaves it; a Box's or Text's `group`, a Client's or Raster's own.
6317	*
6318	* A Button's `press` names its plugin the same way, beside its handle. Two
6319	* plugins under one `hover.scope` string never share a group.
6320	*/
6321	type PluginStamp = {
6322	plugin: string;
6323	};
6324
6325	type PostCompactHookInput = BaseHookInput & {
6326	hook_event_name: 'PostCompact';
6327	trigger: 'manual' \| 'auto';
6328	/**
6329	* The conversation summary produced by compaction
6330	*/
6331	compact_summary: string;
6332	};
6333
6334	type PostModelSwitchHookInput = (BaseHookInput & {
6335	hook_event_name: 'PostModelSwitch';
6336	}) & {
6337	/**
6338	* Resolved model id the session was running before the switch
6339	*/
6340	from_model: string;
6341	/**
6342	* Resolved model id the session runs after the switch
6343	*/
6344	to_model: string;
6345	/**
6346	* What was asked for (alias such as "opus", a full id, or null for "default")
6347	*/
6348	requested_model: string \| null;
6349	/**
6350	* command: /model <name>, the /config Model row, or enabling fast mode when that promotes the model; picker: an interactive model picker; sdk: headless set_model (SDK, Remote Control, IDE); auto: automatic fallback or other programmatic change; resume: model restored while resuming a session
6351	*/
6352	source: 'command' \| 'picker' \| 'sdk' \| 'auto' \| 'resume';
6353	/**
6354	* Prompt tokens the next request re-sends: the last main-thread response's input + cache_read + cache_creation + output tokens (0 before the first response; for a server-side tool loop, its last iteration's window, not the summed totals)
6355	*/
6356	context_tokens: number;
6357	/**
6358	* Whether the current model's prompt cache is likely still warm (a switch then forfeits it)
6359	*/
6360	prompt_cache_warm: boolean;
6361	cache_ttl: '5m' \| '1h';
6362	/**
6363	* Estimated cost of re-caching context_tokens on to_model at its cache-write rate - the managed modelPricing when set, otherwise list price; excludes the response
6364	*/
6365	estimated_cache_write_usd: number;
6366	/**
6367	* configured: priced at the managed modelPricing setting; catalog: list price; default: to_model unknown, the default tier was assumed
6368	*/
6369	pricing: 'configured' \| 'catalog' \| 'default';
6370	};
6371
6372	/**
6373	* Hook input for the PostToolBatch event. Fired once after every tool call in a batch has resolved, before the next model request. PostToolUse fires per-tool and may run concurrently for parallel tool calls; PostToolBatch fires exactly once with the full batch.
6374	*/
6375	type PostToolBatchHookInput = BaseHookInput & {
6376	hook_event_name: 'PostToolBatch';
6377	tool_calls: PostToolBatchToolCall[];
6378	};
6379
6380	type PostToolBatchToolCall = {
6381	tool_name: string;
6382	tool_input: unknown;
6383	tool_use_id: string;
6384	tool_response?: unknown;
6385	};
6386
6387	type PostToolUseFailureHookInput = BaseHookInput & {
6388	hook_event_name: 'PostToolUseFailure';
6389	tool_name: string;
6390	tool_input: unknown;
6391	tool_use_id: string;
6392	error: string;
6393	is_interrupt?: boolean;
6394	/**
6395	* Tool execution time in milliseconds. Excludes permission-prompt and hook time.
6396	*/
6397	duration_ms?: number;
6398	mcp_server?: McpServerProvenance;
6399	};
6400
6401	type PostToolUseHookInput = BaseHookInput & {
6402	hook_event_name: 'PostToolUse';
6403	tool_name: string;
6404	tool_input: unknown;
6405	tool_response: unknown;
6406	tool_use_id: string;
6407	/**
6408	* Tool execution time in milliseconds. Excludes permission-prompt and hook time.
6409	*/
6410	duration_ms?: number;
6411	mcp_server?: McpServerProvenance;
6412	};
6413
6414	type PreCompactHookInput = BaseHookInput & {
6415	hook_event_name: 'PreCompact';
6416	trigger: 'manual' \| 'auto';
6417	custom_instructions: string \| null;
6418	};
6419
6420	type PreModelSwitchHookInput = (BaseHookInput & {
6421	hook_event_name: 'PreModelSwitch';
6422	}) & {
6423	/**
6424	* Resolved model id the session was running before the switch
6425	*/
6426	from_model: string;
6427	/**
6428	* Resolved model id the session runs after the switch
6429	*/
6430	to_model: string;
6431	/**
6432	* What was asked for (alias such as "opus", a full id, or null for "default")
6433	*/
6434	requested_model: string \| null;
6435	/**
6436	* command: /model <name>, the /config Model row, or enabling fast mode when that promotes the model; picker: an interactive model picker; sdk: headless set_model (SDK, Remote Control, IDE)
6437	*/
6438	source: 'command' \| 'picker' \| 'sdk';
6439	/**
6440	* Prompt tokens the next request re-sends: the last main-thread response's input + cache_read + cache_creation + output tokens (0 before the first response; for a server-side tool loop, its last iteration's window, not the summed totals)
6441	*/
6442	context_tokens: number;
6443	/**
6444	* Whether the current model's prompt cache is likely still warm (a switch then forfeits it)
6445	*/
6446	prompt_cache_warm: boolean;
6447	cache_ttl: '5m' \| '1h';
6448	/**
6449	* Estimated cost of re-caching context_tokens on to_model at its cache-write rate - the managed modelPricing when set, otherwise list price; excludes the response
6450	*/
6451	estimated_cache_write_usd: number;
6452	/**
6453	* configured: priced at the managed modelPricing setting; catalog: list price; default: to_model unknown, the default tier was assumed
6454	*/
6455	pricing: 'configured' \| 'catalog' \| 'default';
6456	};
6457
6458	/**
6459	* The link a press landed on: one a `Markdown` drew, pressed where the
6460	* surface reports presses (a plain click in the fullscreen terminal).
6461	*
6462	* What the surface knows of the cell pressed, not which occurrence: two
6463	* links written with one target read the same here.
6464	*/
6465	export type PressedLink = {
6466	/**
6467	* The link's target as the surface drew it: for an `https:` link, the
6468	* href as the markdown wrote it.
6469	*/
6470	href: string;
6471	};
6472
6473	/**
6474	* The decision of a `classic.PreToolUse` result: `allow`, `ask`, `deny`, or
6475	* none.
6476	*/
6477	export type PreToolUseDecision = {
6478	/**
6479	* Lets the call run without a permission prompt (the managed-settings
6480	* hooks ran first; a deny from them ended the chain above).
6481	*/
6482	allow: true;
6483	ask?: undefined;
6484	deny?: undefined;
6485	} \| {
6486	/**
6487	* Asks the user before the call runs; the text is shown as the reason.
6488	*/
6489	ask: string;
6490	allow?: undefined;
6491	deny?: undefined;
6492	} \| {
6493	/**
6494	* Refuses the call; the model receives the text as the reason.
6495	*/
6496	deny: string;
6497	allow?: undefined;
6498	ask?: undefined;
6499	} \| {
6500	allow?: undefined;
6501	ask?: undefined;
6502	deny?: undefined;
6503	};
6504
6505	type PreToolUseHookInput = BaseHookInput & {
6506	hook_event_name: 'PreToolUse';
6507	tool_name: string;
6508	tool_input: unknown;
6509	tool_use_id: string;
6510	mcp_server?: McpServerProvenance;
6511	};
6512
6513	/**
6514	* What a `classic.PreToolUse` hook returns: one of `allow`, `ask`, `deny`,
6515	* or none of them, which passes the call on to the normal permission flow.
6516	*/
6517	export type PreToolUseResult = PreToolUseDecision & {
6518	/**
6519	* Replaces the tool's arguments; validated against the tool's schema before
6520	* the tool runs.
6521	*/
6522	updatedInput?: Record<string, unknown>;
6523	/**
6524	* Extra context handed to the model with the call, one entry per note.
6525	*/
6526	additionalContext?: string[];
6527	};
6528
6529	/**
6530	* Options of `$.process.run`.
6531	*/
6532	export type ProcessRunInit = {
6533	/**
6534	* The child's working directory, relative to the session's or absolute;
6535	* absent, the session's working directory.
6536	*/
6537	cwd?: string;
6538	/**
6539	* Variables set over the host process's own environment.
6540	*/
6541	env?: Record<string, string>;
6542	/**
6543	* Text written to the child's standard input, then closed.
6544	*/
6545	stdin?: string;
6546	/**
6547	* How long the child may run before it is killed and the call rejects,
6548	* in milliseconds; 30 seconds when absent, ten minutes at most.
6549	*/
6550	timeoutMs?: number;
6551	};
6552
6553	/**
6554	* What `$.process.run` resolves with once the child has exited.
6555	*/
6556	export type ProcessRunResult = {
6557	/**
6558	* The child's exit status; a child ended by a signal reads as 1.
6559	*/
6560	exitCode: number;
6561	/**
6562	* What the child wrote to standard output, as text, cut at the output
6563	* limit.
6564	*/
6565	stdout: string;
6566	/**
6567	* What the child wrote to standard error, as text, cut at the output
6568	* limit.
6569	*/
6570	stderr: string;
6571	};
6572
6573	/**
6574	* The input of `prompt.attachment`: one message the engine injects into the
6575	* conversation for the model on its own, as a request is about to carry it.
6576	*
6577	* A reminder, a mode transition, a listing, a mentioned file, a hook's
6578	* context: the person never typed it and mostly never sees it. Only an
6579	* attachment that carries text for the model is raised.
6580	*/
6581	export type PromptAttachmentInput = {
6582	/**
6583	* As the engine names the attachment's kind; the key a matcher narrows on.
6584	* Pinned. Builds add and retire kinds: match by name.
6585	*
6586	* Among them `todo_reminder`, `plan_mode`, `plan_mode_exit`, `auto_mode`,
6587	* `auto_mode_exit`, `instructions`, `nested_memory`, `skill_listing`,
6588	* `deferred_tools_delta`, `edited_text_file`, `file`, `queued_command`.
6589	*/
6590	type: string;
6591	/**
6592	* What the model reads for this attachment, inside the engine's framing;
6593	* rewritable with `next({ ...e, text })`.
6594	*
6595	* The `<system-reminder>` wrapper (or the system channel that replaces it)
6596	* goes around what the chain answers, never inside it. An attachment
6597	* rendered as several text blocks hands them joined by newlines.
6598	*/
6599	text: string;
6600	/**
6601	* Who authored the text (PromptAttachmentOrigin): the engine, a settings
6602	* hook, or a plugin's chain context.
6603	*
6604	* Pinned: a different value is refused, one left out is kept.
6605	*/
6606	origin: PromptAttachmentOrigin;
6607	/**
6608	* The loop whose request carries the attachment: a subagent's id, the `id`
6609	* `$.agent.list()` gives it and its `tool.call`s carry; absent on main.
6610	*
6611	* Pinned: a different value is refused, one left out is kept. A subagent
6612	* a hook spawned through `$.agent.spawn` is resolved past that hook.
6613	*/
6614	agentId?: string;
6615	};
6616
6617	/**
6618	* Who authored the text an injected attachment carries, as the engine knows
6619	* it from the attachment itself; a closed set, pinned on the event.
6620	*
6621	* A hooks module reads `e.origin.kind` to tell the engine's own prose from a
6622	* settings hook's output or another plugin's context. `next(e)` passes it on
6623	* as received; one left out is put back; no hook sets one.
6624	*/
6625	export type PromptAttachmentOrigin = {
6626	/**
6627	* The engine's own prose or framing: a reminder, a mode transition, a
6628	* listing, a notice, an announced context block.
6629	*
6630	* A file the person mentioned, as the engine presents it, and a prompt
6631	* or notification delivered into a running turn are the engine's too.
6632	*/
6633	kind: 'engine';
6634	} \| {
6635	/**
6636	* A settings hook's output the engine injects for the model: its
6637	* additional context, a blocking error's note, a stopped continuation.
6638	*/
6639	kind: 'hook';
6640	/**
6641	* The settings hook event that produced it (`SessionStart`,
6642	* `UserPromptSubmit`, `PostToolUse`, ...).
6643	*/
6644	event: string;
6645	} \| {
6646	/**
6647	* Text a plugin's hook attached through a chain's `context`
6648	* (`prompt.submit`, `tool.call`), as the model reads it.
6649	*/
6650	kind: 'plugin';
6651	/**
6652	* The chain's event that attached it.
6653	*/
6654	event: string;
6655	};
6656
6657	/**
6658	* What a `prompt.attachment` hook returns: the text the model reads for that
6659	* attachment, or null to leave the attachment out of the request.
6660	*/
6661	export type PromptAttachmentResult = {
6662	text: string \| null;
6663	};
6664
6665	/**
6666	* The person's prompt box as it stands: the draft and where the cursor is in
6667	* it; what `$.prompt.read()` resolves and `$.prompt.fill` hands back.
6668	*
6669	* No selection: the terminal's box has none of its own, and a surface that
6670	* binds one adds it here.
6671	*/
6672	export type PromptBox = {
6673	/**
6674	* The draft as typed so far; `''` where the session draws no box.
6675	*/
6676	text: string;
6677	/**
6678	* Where the next typed character lands: an offset into `text` in UTF-16
6679	* code units, 0 at the start, `text.length` at the end.
6680	*/
6681	cursor: number;
6682	};
6683
6684	/**
6685	* What a plugin passes `$.prompt.compose`: the facts it wants composed for,
6686	* each one it leaves out read off the session (its model, its tools).
6687	*/
6688	export type PromptComposeArgs = Partial<PromptComposeInput>;
6689
6690	/**
6691	* The input of `prompt.compose`: the facts a system prompt is composed from,
6692	* each already resolved by the engine, at the moment it renders one.
6693	*/
6694	export type PromptComposeInput = {
6695	/**
6696	* The id of the model the request is for; pinned, the field a matcher
6697	* narrows on.
6698	*/
6699	model: string;
6700	/**
6701	* The model whose prompt is rendered: `model`, unless the engine renders
6702	* another model's prompt for it (a model it holds no prompt of its own for).
6703	*/
6704	promptModel: string;
6705	/**
6706	* Where the session draws at this render, as `$.session.surfaces()`
6707	* answers: `terminal` first under the REPL; empty where nothing draws.
6708	*/
6709	surfaces: readonly RenderSurface[];
6710	/**
6711	* The names of the tools the request offers the model; the engine's own
6712	* composition reads them against the session's, an unknown name ignored.
6713	*/
6714	tools: readonly string[];
6715	/**
6716	* What the person chose in place of the default way of answering, and
6717	* whether it keeps the coding instructions; null for the default style.
6718	*/
6719	outputStyle: {
6720	name: string;
6721	isKeepingCodingInstructions: boolean;
6722	} \| null;
6723	traits: readonly PromptComposeTrait[];
6724	};
6725
6726	/**
6727	* What a `prompt.compose` hook returns: the sections of the system prompt,
6728	* in order, every `shared` one ahead of every `session` one.
6729	*
6730	* A section left out is not sent; a hook that never calls `next` answers
6731	* the whole list. The engine joins each side, places the cache boundary
6732	* between them and every cache marker itself.
6733	*/
6734	export type PromptComposeResult = {
6735	sections: readonly PromptComposeSection[];
6736	};
6737
6738	/**
6739	* Which side of the prompt cache's boundary a section of the system prompt
6740	* sits on: `shared` before it, `session` after it.
6741	*
6742	* `shared` is text that reads the same for every person on this build and
6743	* model: it is sent in the block the API may cache across organizations.
6744	* `session` is text that varies with the person, the machine or the session.
6745	*
6746	* The engine places the one boundary and every cache marker itself,
6747	* whatever a list says; `shared` text that varies hits that cache for nobody.
6748	*/
6749	export type PromptComposeScope = 'shared' \| 'session';
6750
6751	/**
6752	* One section of the system prompt as `prompt.compose` answers it: a stable
6753	* id, the text the model reads, and the side of the cache boundary it is on.
6754	*
6755	* @example
6756	* const POLICY = { id: "acme:policy", text: "# Policy\n...", scope: "session" }
6757	*/
6758	export type PromptComposeSection = {
6759	/**
6760	* What a hook above finds the section by, to replace, move or drop it;
6761	* never empty, and unique in one list.
6762	*
6763	* A section a plugin adds is named `<plugin>:<name>`; the bare names are
6764	* the engine's own composition's (`intro`, `tools`, `memory`, ...).
6765	*/
6766	id: string;
6767	/**
6768	* The section's text, sent as written; sections on one side of the
6769	* boundary are joined by a blank line, in the list's order.
6770	*/
6771	text: string;
6772	scope: PromptComposeScope;
6773	};
6774
6775	/**
6776	* One branch the engine's own composition of the system prompt takes on the
6777	* request or the session before it computes any section: a closed set.
6778	*
6779	* `bare`: the session runs with the one-line prompt (`--bare`). `lean`: the
6780	* prompt model takes the short body. `sdk-preset`: the SDK's `claude_code`
6781	* preset, whose per-person sections ride the first user message instead.
6782	*
6783	* `teammate`: an in-process teammate's render of its lead's prompt.
6784	* `analysis`: a render that measures the prompt (`/context`) and sends
6785	* nothing. `print`: a session with no terminal behind it (`-p`, the SDK).
6786	*
6787	* `skills`: the Skill tool has commands to list. `send-user-message`: the
6788	* session speaks to the person through a message tool.
6789	*
6790	* Rewritten going down, `sdk-preset`, `teammate` and `analysis` steer the
6791	* engine's composition; the rest it derives itself, so they tell a hook what
6792	* it will do. What one section's own text turns on (a flag) is not here.
6793	*/
6794	export type PromptComposeTrait = 'bare' \| 'lean' \| 'sdk-preset' \| 'teammate' \| 'analysis' \| 'print' \| 'skills' \| 'send-user-message';
6795
6796	/**
6797	* One block of the context the first user message carries: a name the
6798	* engine keys it by and the text under it.
6799	*/
6800	export type PromptContextBlock = {
6801	/**
6802	* The key the block renders under (`# name`): `claudeMd`, `userEmail`,
6803	* `attachedProject`, `currentDate`, or a plugin's own.
6804	*
6805	* The field a matcher narrows on; unique among one context's blocks.
6806	*/
6807	name: string;
6808	/**
6809	* The block's text; `claudeMd`'s is the instruction files framed as the
6810	* engine frames them, empty when it announces none.
6811	*/
6812	text: string;
6813	};
6814
6815	/**
6816	* The context blocks of a conversation's first user message, in the order
6817	* the engine renders them: what `prompt.context` takes and answers alike.
6818	*/
6819	export type PromptContextBlocks = {
6820	/**
6821	* From core: `claudeMd` (when instruction files are loaded), `userEmail`,
6822	* `attachedProject`, `currentDate`, each only when present.
6823	*/
6824	blocks: readonly PromptContextBlock[];
6825	};
6826
6827	/**
6828	* The input of `prompt.context`: the context blocks the engine prepends to a
6829	* conversation's first user message, and the files behind `claudeMd`.
6830	*/
6831	export type PromptContextInput = {
6832	/**
6833	* From core: `claudeMd` (when instruction files are loaded), `userEmail`,
6834	* `attachedProject`, `currentDate`, each only when present.
6835	*/
6836	blocks: readonly PromptContextBlock[];
6837	/**
6838	* The files behind `claudeMd`, in the order it renders them, `@` imports
6839	* included; empty when it renders none.
6840	*
6841	* Undefined when a hook above rewrote the `claudeMd` text: the files
6842	* behind that text are then unknown, and a hook adds none of its own.
6843	*/
6844	instructionFiles?: readonly InstructionFile[];
6845	};
6846
6847	/**
6848	* What a `prompt.context` hook returns: the blocks the conversation
6849	* carries, in order; one left out is not sent.
6850	*/
6851	export type PromptContextResult = {
6852	/**
6853	* What the conversation carries, in order.
6854	*/
6855	blocks: readonly PromptContextBlock[];
6856	/**
6857	* The files now behind `claudeMd`; left out, the ones from below stand.
6858	*
6859	* Kept in step with the `claudeMd` text at every link: a changed list
6860	* renders the text the next reader gets, a rewritten text makes the files
6861	* unknown from there on. Every kind is the hook's to add, drop or rewrite.
6862	*/
6863	instructionFiles?: readonly InstructionFile[];
6864	};
6865
6866	/**
6867	* The input of `prompt.edit` (prompt-edit/): one edit the person makes in the
6868	* prompt box, as the draft before it and the splice the editor made of it.
6869	*/
6870	export type PromptEditInput = {
6871	/**
6872	* Who edits (PromptEditOrigin): the person at the composer. Pinned:
6873	* `next(e)` passes it on as received.
6874	*/
6875	origin: PromptEditOrigin;
6876	/**
6877	* The one key that made the edit, in `Client` `onKey`'s shape, when one
6878	* did; absent for a paste and for a burst of keys folded into one edit.
6879	*
6880	* Pinned: which key the person pressed is a fact, not the hook's to change.
6881	*/
6882	key?: ClientKeyEvent;
6883	/**
6884	* The draft before the edit. `next({ ...e, text })` applies the edit to
6885	* another draft instead.
6886	*/
6887	text: string;
6888	/**
6889	* Where the person's caret stood in `text` before the edit, 0 to
6890	* `text.length`.
6891	*/
6892	cursor: number;
6893	/**
6894	* Where in `text` the edit begins: the start of the span it replaces, or
6895	* where what was typed goes in; a bare cursor move begins where it lands.
6896	*/
6897	start: number;
6898	/**
6899	* Where the replaced span of `text` ends: `start` for an insertion or a
6900	* move, past it for a deletion (Backspace, a kill).
6901	*/
6902	end: number;
6903	/**
6904	* What goes in between `start` and `end`: the typed or pasted text, `''` for
6905	* a deletion or a move.
6906	*
6907	* `next({ ...e, inputText })` puts in another; the cursor lands after it.
6908	*/
6909	inputText: string;
6910	};
6911
6912	/**
6913	* Who edits the prompt box at `prompt.edit`, as the engine stamps it where
6914	* the edit starts; a closed set a matcher narrows on.
6915	*
6916	* `next(e)` passes it on as received; no hook sets one.
6917	*/
6918	export type PromptEditOrigin = {
6919	/**
6920	* The person, typing or pasting into the main prompt box.
6921	*/
6922	kind: 'composer';
6923	};
6924
6925	/**
6926	* What a `prompt.edit` hook returns and what `next(e)` resolves to: the box
6927	* after the edit (PromptBox), which the editor then shows.
6928	*
6929	* From core, `e.text` with the splice applied and the cursor after what went
6930	* in. Rewrite it (`{ ...r, text, cursor }`) to change what lands; answer
6931	* `{ text: e.text, cursor: e.cursor }` without `next` to consume the key.
6932	*/
6933	export type PromptEditResult = PromptBox;
6934
6935	/**
6936	* `prompt.fill`'s input as a plugin's `$.prompt.fill(args)` takes it: no
6937	* `origin` (the engine sets the calling plugin's), `mode` optional.
6938	*/
6939	export type PromptFillArgs = {
6940	/**
6941	* What the box is to take (PromptFillInput `text`).
6942	*/
6943	text: string;
6944	/**
6945	* Where it goes (PromptFillMode); `replace` when left out.
6946	*/
6947	mode?: PromptFillMode;
6948	};
6949
6950	/**
6951	* What `$.prompt.fill` resolves to: whether the box took the text, and the
6952	* box afterwards (PromptBox) as the caller's own `$.prompt.read()` reads it.
6953	*
6954	* The box goes to a plugin whose module calls `$.prompt.read`, through the
6955	* hooks on it; one that never does, or is refused there, gets the empty box.
6956	*/
6957	export type PromptFilled = {
6958	/**
6959	* True once the box holds the text; false where no box could take it or a
6960	* hook kept it out (PromptFillResult).
6961	*/
6962	isFilled: boolean;
6963	/**
6964	* The draft after the fill; unchanged when `isFilled` is false; `''` where
6965	* no box is drawn or the caller may not read it (see above).
6966	*/
6967	text: string;
6968	/**
6969	* Where the person types next: an offset into `text`, past the fill's text
6970	* for `insert`, at the end for `replace` and `append`.
6971	*/
6972	cursor: number;
6973	};
6974
6975	/**
6976	* The input of `prompt.fill` (prompt-fill/): a text about to be put in the
6977	* prompt box as the person's draft, over it, after it, or at the cursor.
6978	*/
6979	export type PromptFillInput = {
6980	/**
6981	* What the box takes; the person edits it or presses Enter.
6982	* `next({ ...e, text })` writes another.
6983	*/
6984	text: string;
6985	/**
6986	* Where the text goes (PromptFillMode): over the draft, after it, or in at
6987	* the cursor. `next({ ...e, mode })` moves it; left out of a rewrite, kept.
6988	*/
6989	mode: PromptFillMode;
6990	/**
6991	* Who writes (PromptFillOrigin), set by the engine where the write
6992	* starts. Pinned: `next(e)` passes it on as received.
6993	*/
6994	origin: PromptFillOrigin;
6995	};
6996
6997	/**
6998	* Where a `prompt.fill` puts its text: over the whole draft, after it, or
6999	* into it at the cursor.
7000	*
7001	* `replace` empties the box first and leaves the cursor at the text's end;
7002	* `append` keeps the draft and adds the text after it, cursor at the end;
7003	* `insert` splices the text in at the cursor and moves the cursor past it,
7004	* so what the person had typed stays on either side.
7005	*/
7006	export type PromptFillMode = 'replace' \| 'append' \| 'insert';
7007
7008	/**
7009	* Who writes the prompt box at `prompt.fill`, as the engine stamps it where
7010	* the write starts; a closed set a matcher narrows on.
7011	*
7012	* `next(e)` passes it on as received; no hook sets one.
7013	*/
7014	export type PromptFillOrigin = {
7015	/**
7016	* The engine writing the box on its own account; reserved for its own
7017	* sites, none of which raises `prompt.fill` as shipped.
7018	*/
7019	kind: 'engine';
7020	} \| {
7021	/**
7022	* A plugin's `$.prompt.fill`.
7023	*/
7024	kind: 'plugin';
7025	/**
7026	* The filling plugin's name.
7027	*/
7028	name: string;
7029	};
7030
7031	/**
7032	* What a `prompt.fill` hook returns and what `next(e)` resolves to: whether
7033	* the text went into the prompt box.
7034	*/
7035	export type PromptFillResult = {
7036	/**
7037	* True once the box holds the text; false where no box can take it (a
7038	* dialog holds the keys, a headless session has none).
7039	*
7040	* A hook answering `{ isFilled: false }` without `next` keeps the text
7041	* out.
7042	*/
7043	isFilled: boolean;
7044	};
7045
7046	/**
7047	* Where a `prompt.submit` submission came from, as the engine knows it at
7048	* the site it was queued from; a closed set, never a text prefix.
7049	*
7050	* A hooks module reads `e.origin.kind` to tell the user's own Enter from a
7051	* notification, a peer session, a schedule or another plugin. `next(e)`
7052	* passes it on as received; an answer may leave it out; no hook sets one.
7053	*/
7054	export type PromptOrigin = {
7055	/**
7056	* The user's own gesture at the terminal, as the engine stamped it
7057	* (never presumed from an unstamped command).
7058	*
7059	* Enter at the prompt, typed or queued, or a click on a transcript
7060	* link; a channel the engine cannot attest (a same-user socket) is
7061	* never stamped, and arrives as `unclassified`.
7062	*/
7063	kind: 'composer';
7064	} \| {
7065	/**
7066	* The user's message through the Remote Control bridge (a phone or
7067	* web client).
7068	*/
7069	kind: 'bridge';
7070	} \| {
7071	/**
7072	* The SDK host's own turn (`claude -p`, the Agent SDK), not typed at
7073	* a terminal.
7074	*/
7075	kind: 'sdk';
7076	} \| {
7077	/**
7078	* A background task's notification, dequeued when the session went
7079	* idle or delivered into a running turn (`turnId` set).
7080	*/
7081	kind: 'task-notification';
7082	} \| {
7083	/**
7084	* A scheduled task, routine or /loop firing its stored prompt.
7085	*/
7086	kind: 'scheduled-trigger';
7087	} \| {
7088	/**
7089	* Another Claude session's message ("Another Claude session sent a
7090	* message"), as a turn of its own or delivered into a running one.
7091	*/
7092	kind: 'peer';
7093	} \| {
7094	/**
7095	* Another session's SendMessage delivery, model-authored and framed
7096	* as a notification.
7097	*/
7098	kind: 'peer-send-message';
7099	} \| {
7100	/**
7101	* A delivery a coordinating session composed for one of its threads.
7102	*/
7103	kind: 'projects-relay';
7104	} \| {
7105	/**
7106	* A message from a channel an MCP server relays (Slack, Telegram).
7107	*/
7108	kind: 'channel';
7109	/**
7110	* The channel server's name.
7111	*/
7112	server: string;
7113	} \| {
7114	/**
7115	* A coordinating session's hand-off to a worker session.
7116	*/
7117	kind: 'coordinator';
7118	} \| {
7119	/**
7120	* A background observer agent's report to the agent it observes.
7121	*/
7122	kind: 'observer';
7123	} \| {
7124	/**
7125	* An activity digest delivered to an observer agent.
7126	*/
7127	kind: 'observer-activity';
7128	} \| {
7129	/**
7130	* A programmatic follow-up to a user's UI action, user-initiated but
7131	* not typed this turn.
7132	*/
7133	kind: 'auto-continuation';
7134	} \| {
7135	/**
7136	* A turn with no provenance the engine can name: one the ingress
7137	* could not classify, or a command queued with no stamp at all.
7138	*
7139	* An idle notice or a delivery receipt the engine queued isMeta with
7140	* no stamp is one too; the engine frames that shape as a non-user
7141	* source.
7142	*/
7143	kind: 'unclassified';
7144	} \| {
7145	/**
7146	* The session's owner pinging it from Slack.
7147	*/
7148	kind: 'slack-ping';
7149	} \| {
7150	/**
7151	* A plugin's `$.prompt.submit`; the model reads the prompt under the
7152	* plugin's name unless a hook leaves the origin out of its answer.
7153	*/
7154	kind: 'plugin';
7155	/**
7156	* The submitting plugin's name.
7157	*/
7158	name: string;
7159	};
7160
7161	/**
7162	* The input of `prompt.section`: one named section of the system prompt, at
7163	* the moment the engine assembles it.
7164	*/
7165	export type PromptSectionInput = {
7166	/**
7167	* As the engine names the section (`env_info_simple`, `memory`, ...); the
7168	* key a matcher narrows on.
7169	*/
7170	name: string;
7171	/**
7172	* The section's text as core computed it, or null when core omits it.
7173	*/
7174	text: string \| null;
7175	};
7176
7177	/**
7178	* What a `prompt.section` hook returns: the text the prompt carries for that
7179	* section, or null to leave it out.
7180	*/
7181	export type PromptSectionResult = {
7182	text: string \| null;
7183	};
7184
7185	/**
7186	* `prompt.submit`'s input as a plugin's call takes it: `origin`, `turnId`
7187	* and `wait` are the engine's to set, `context` the hooks' to attach.
7188	*
7189	* `origin` is the calling plugin's name; `turnId` is the turn a prompt typed
7190	* mid-turn ran over; `wait` is false, as a plugin's prompt runs once idle.
7191	*/
7192	export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' \| 'turnId' \| 'wait' \| 'context'>;
7193
7194	/**
7195	* A pasted or attached non-text item of a submitted prompt; its kind, never
7196	* its bytes.
7197	*/
7198	export type PromptSubmitAttachment = {
7199	/**
7200	* The item's kind.
7201	*/
7202	type: 'image' \| 'audio' \| 'document';
7203	/**
7204	* The item's MIME type (`image/png`), when known.
7205	*/
7206	mediaType?: string;
7207	/**
7208	* The pasted file's name, when it had one.
7209	*/
7210	filename?: string;
7211	};
7212
7213	/**
7214	* The input of `prompt.submit`: the prompt as typed, after the input became
7215	* a user message and before it enters the session.
7216	*/
7217	export type PromptSubmitInput = {
7218	/**
7219	* The prompt's text as it will reach the model (pastes already expanded).
7220	*/
7221	text: string;
7222	/**
7223	* Present only when the submission carried images or other non-text items.
7224	*/
7225	attachments?: readonly PromptSubmitAttachment[];
7226	/**
7227	* What the model reads beside the prompt and the user never sees, each
7228	* entry one block after the prompt as typed; absent as the engine raises it.
7229	*
7230	* A hook attaches on the way down: `next({ ...e, context: [...(e.context
7231	* ?? []), mine] })`, keeping which it likes; none empty, any length: past
7232	* 100,000 characters (200,000 together) the model reads a head and path.
7233	*/
7234	context?: readonly string[];
7235	/**
7236	* The id of the model turn that was running when the prompt was submitted
7237	* (`turn.start`'s `turnId`): typed over that turn, or delivered into it.
7238	*
7239	* A queued delivery (a peer session's message) reaches the model inside a
7240	* running turn. Absent for a prompt submitted while the session was idle,
7241	* and for a plugin's own (`$.prompt.submit`), which runs once it is idle.
7242	*/
7243	turnId?: string;
7244	/**
7245	* Whether the user asked the prompt to wait its turn (`chat:queueSubmit`,
7246	* `ctrl+x enter` by default): true for that submission, false otherwise.
7247	*
7248	* The engine queues every prompt typed mid-turn either way; the flag is
7249	* for hooks, so one that cancels the running turn on a plain Enter can
7250	* leave a waiting prompt alone. False for a prompt a plugin submitted.
7251	*/
7252	wait: boolean;
7253	/**
7254	* Where the submission came from (PromptOrigin), set by the engine where
7255	* it was queued: the user's Enter, a notification, a peer, a plugin.
7256	*
7257	* `next(e)` passes it on as received; no hook may set one.
7258	*/
7259	origin: PromptOrigin;
7260	};
7261
7262	/**
7263	* What a `prompt.submit` hook returns and what `next(e)` resolves to: the
7264	* prompt that entered, `{ text, context?, origin? }`, or `{ drop: reason }`.
7265	*
7266	* `next(e)` resolves once the prompt entered the session and its turn
7267	* started, or it was queued behind the running one; not when the turn ends,
7268	* which is `turn.complete`. A hook answering without `next` enters nothing.
7269	*/
7270	export type PromptSubmitResult = {
7271	/**
7272	* The prompt that entered; from core, the text that arrived at the
7273	* bottom. A rewrite passes it down, `next({ ...e, text })`.
7274	*/
7275	text: string;
7276	/**
7277	* What entered beside the prompt for the model, never shown the user:
7278	* from core, the context that arrived (`e.context`).
7279	*
7280	* Each entry is one block after the prompt as typed. A hook attaches
7281	* context on the way down; one put here after `next` resolved is not
7282	* attached (the prompt had entered), and is logged.
7283	*/
7284	context?: readonly string[];
7285	/**
7286	* Where the prompt entered from: from core, `e.origin` as received;
7287	* absent, the prompt is the user's own.
7288	*
7289	* A hook may put back the origin it received; it may not set another.
7290	*/
7291	origin?: PromptOrigin;
7292	drop?: undefined;
7293	} \| {
7294	/**
7295	* The prompt did not enter: a hook's refusal, answered without `next`,
7296	* or a settings hook's block beneath.
7297	*
7298	* The text is shown to the user as the reason.
7299	*/
7300	drop: string;
7301	text?: undefined;
7302	context?: undefined;
7303	origin?: undefined;
7304	};
7305
7306	/**
7307	* `prompt.suggest`'s input as a plugin's `$.prompt.suggest(args)` takes it:
7308	* `origin` is the engine's to set (the calling plugin's name).
7309	*/
7310	export type PromptSuggestArgs = Omit<PromptSuggestInput, 'origin'>;
7311
7312	/**
7313	* The input of `prompt.suggest` (prompt-suggest/): a text about to be shown
7314	* dim in the empty prompt box, for Tab (or the right arrow) to take.
7315	*/
7316	export type PromptSuggestInput = {
7317	/**
7318	* The proposed prompt: shown, not written; taking it puts it in the box
7319	* for editing. `next({ ...e, text })` proposes another.
7320	*/
7321	text: string;
7322	/**
7323	* Who proposes (PromptSuggestOrigin), set by the engine where the
7324	* proposal starts. Pinned: `next(e)` passes it on as received.
7325	*/
7326	origin: PromptSuggestOrigin;
7327	};
7328
7329	/**
7330	* Who proposes the text at `prompt.suggest`, as the engine stamps it where
7331	* the proposal starts; a closed set a matcher narrows on.
7332	*
7333	* `next(e)` passes it on as received; no hook sets one.
7334	*/
7335	export type PromptSuggestOrigin = {
7336	/**
7337	* The engine's own guess at the person's next prompt, generated after
7338	* a turn (the prompt-suggestion service).
7339	*/
7340	kind: 'suggestion';
7341	} \| {
7342	/**
7343	* A plugin's `$.prompt.suggest`.
7344	*/
7345	kind: 'plugin';
7346	/**
7347	* The proposing plugin's name.
7348	*/
7349	name: string;
7350	};
7351
7352	/**
7353	* What a `prompt.suggest` hook returns and what `next(e)` resolves to:
7354	* whether the text is now the box's dim suggestion.
7355	*/
7356	export type PromptSuggestResult = {
7357	/**
7358	* True once the box has the suggestion to show, at once or as soon as a
7359	* dialog gives the box back; false where it cannot show.
7360	*
7361	* It cannot while the box holds text, a turn runs, the text is blank, or
7362	* the session is headless. A hook answering `{ isShown: false }` without
7363	* `next` keeps it from showing.
7364	*/
7365	isShown: boolean;
7366	};
7367
7368	/**
7369	* A `$.ui.blit` argument repainting one of the caller's mounted Rasters.
7370	*
7371	* `columns` and `rows`, when given, must be the mounted size (a resize is a
7372	* redraw, `$.ui.invalidate("ui.render")`, not a blit).
7373	*/
7374	export type RasterBlitArgs = {
7375	/**
7376	* The site the Raster is drawn in, by the `requestId` this plugin draws
7377	* it under: one of its panes' ids, a tool row's `tool_use_id`, the band's.
7378	*/
7379	requestId: string;
7380	/**
7381	* The Raster's `key` in that drawing.
7382	*/
7383	key: string;
7384	/**
7385	* The new cells, encoded as the element's `cells` are (RasterProps), for
7386	* the mounted `columns * rows`.
7387	*/
7388	cells: string;
7389	/**
7390	* The width the cells are laid out for; refused unless it is the mounted
7391	* Raster's. Absent, the mounted width.
7392	*/
7393	columns?: number;
7394	/**
7395	* The height the cells are laid out for; refused unless it is the mounted
7396	* Raster's. Absent, the mounted height.
7397	*/
7398	rows?: number;
7399	};
7400
7401	/**
7402	* The props of `Raster`, the terminal surface's cell-grid leaf: a fixed box
7403	* of cells, each a glyph, a foreground and a background, packed in `cells`.
7404	*
7405	* A leaf: no children, `hover` or `onPress` yet; repainted in place by
7406	* `$.ui.blit`. Terminal only for now (elsewhere a fragment); its palette
7407	* paints 1024 distinct color pairs at once and the rest as their nearest.
7408	*/
7409	export type RasterProps = {
7410	/**
7411	* The element's address within the drawing: what `$.ui.blit` names to
7412	* repaint it, unique among the Rasters of one tree.
7413	*/
7414	key: string;
7415	/**
7416	* How many terminal columns wide, 1 to 512; the site clips what its body
7417	* cannot show.
7418	*/
7419	columns: number;
7420	/**
7421	* How many terminal rows tall, 1 to 256.
7422	*/
7423	rows: number;
7424	/**
7425	* Every cell, row-major: standard padded base64 of `columns * rows`
7426	* little-endian u32 triplets `[codePoint, foreground, background]`.
7427	*
7428	* A code point is one printable width-1 BMP character (blocks, box drawing,
7429	* braille too), or the tree is refused naming the cell's index; a color is
7430	* `0x00RRGGBB`, or `0x01000000` (bit 24 alone) for the terminal's default.
7431	*
7432	* @example const words = Uint32Array.of(0x2588, 0xff8800, 0x01000000)
7433	* const cells = new Uint8Array(words.buffer).toBase64() // one orange cell
7434	*/
7435	cells: string;
7436	};
7437
7438	/**
7439	* The hooks module's entry: `export function register(on, options)`. `on`
7440	* registers hooks; `options` is the plugin's configuration (PluginOptions).
7441	*
7442	* The options are fixed for this activation: a change to them reloads the
7443	* plugin and `register` runs again with the new object. Hooks close over it.
7444	* Its return is dropped, a promise awaited: `on => on(...)` is a module.
7445	*
7446	* @example
7447	* on("tool.call", ($, e, next) => e.tool === "Bash" ? { deny: "no" } : next(e))
7448	*/
7449	export type Register = (on: On, options: PluginOptions) => unknown;
7450
7451	/**
7452	* What `on(...)` returns for a hook of type `F`: the registration, which
7453	* takes one `.catch` (CatchHandler); without it a failed hook is absent.
7454	*
7455	* A second `.catch` on one registration throws, as does one after
7456	* register() returned and one on `engine.create`, whose hook has no budget
7457	* and whose failure is the load's.
7458	*/
7459	export type Registration<F> = {
7460	/**
7461	* Sets the handler run when the hook throws or overruns its budget; its
7462	* answer within the grace stands as the hook's result for the dispatch.
7463	*
7464	* The budget is HookBudget's `ms` and the grace its `catchMs`, both on
7465	* the clock that stops while the code waits on `next` or `$`.
7466	*/
7467	readonly catch: (handler: CatchHandler<F>) => void;
7468	};
7469
7470	/**
7471	* What an element takes as `children`, as JSX passes them: a node, a number
7472	* (drawn as its string), a value the factory drops, or a list that may nest.
7473	*
7474	* `false`, `null` and `undefined` are dropped, so `{ok && <Text>hi</Text>}`
7475	* and `{n > 0 ? <Text>{n}</Text> : null}` type; a mapped list beside a
7476	* sibling nests. The element holds the flat, normalized list of RenderNode.
7477	*/
7478	export type RenderChildren = RenderNode \| number \| boolean \| null \| undefined \| readonly RenderChildren[];
7479
7480	/**
7481	* Everything `ui.render` can draw: one name per component that has a render
7482	* site; a matcher narrows on it.
7483	*
7484	* The permission dialog is drawn by the engine alone, since its answer
7485	* authorises an action; a plugin adds context with `$.ui.notice`. `Pane` is
7486	* the one component whose instances a plugin opens (`$.ui.open`).
7487	*/
7488	export type RenderComponent = 'AskUserQuestion' \| 'UserMessage' \| 'AssistantMessage' \| 'ToolUse' \| 'ToolResult' \| 'ToolGroup' \| 'ToolProgress' \| 'CommandOutput' \| 'Spinner' \| 'TurnDuration' \| 'InfoNotice' \| 'SessionMode' \| 'PromptHint' \| 'AbovePrompt' \| 'Pane';
7489
7490	/**
7491	* What a render hook returns, and what `next(e)` resolves to: a plain-data
7492	* tree of elements (a Box or Text is a StyledElement), strings as children.
7493	*
7494	* Props are an allowlisted subset of Ink's Box/Text props (the ones
7495	* ElementProps declares); a tree with any other prop fails validation as a
7496	* whole and the engine's own component is drawn with the original props.
7497	*/
7498	export type RenderElement = StyledElement<'Box', BoxHoverProps> \| StyledElement<'Text', TextHoverProps> \| {
7499	/**
7500	* A button, on every surface: `[ label ]` on the terminal, a native
7501	* button on a desktop; a press raises `ui.press` (`e.element` the key).
7502	*
7503	* Built by `<Button>` or the table's `t.Button`. The `onPress` closure
7504	* stays in the plugin's own environment under `press.handle`; the host
7505	* holds the handle for the lifetime of the drawing. A leaf: no children.
7506	*/
7507	type: 'Button';
7508	props: {
7509	/**
7510	* The element's address: what `e.element` carries and what a matcher
7511	* names (`{ element: "explain" }`).
7512	*/
7513	key: string;
7514	/**
7515	* The text drawn on the button.
7516	*/
7517	label: string;
7518	/**
7519	* One digit (`"1"`) or one lowercase letter (`"w"`) that presses it
7520	* while the plugin's site holds the focus; anything else is refused.
7521	*
7522	* The band after ctrl+x tab or a click, a focused `Pane`: on keydown,
7523	* lowercased; never from the composer, save a bare digit in an empty
7524	* one pressing a band Button. Two on one hotkey: the later wins.
7525	*/
7526	hotkey?: string;
7527	/**
7528	* An engine keybinding action (`"app:cycleDiffBase"`) whose chord
7529	* presses the Button from the prompt; an unknown name is refused.
7530	*
7531	* Chords, or a modified key Global or an active context binds, on
7532	* the terminal while mounted, no dialog up, no engine handler of it
7533	* mounted; a pane's over the band's over another's, the last drawn.
7534	*/
7535	action?: string;
7536	/**
7537	* Drawn without chrome: the hotkey in the accent color, a colon,
7538	* then the label (`1: Yes`); without a `hotkey`, the label alone.
7539	*
7540	* The focus still inverts it. In JSX the label may be the one string
7541	* child (`<Button hotkey="1" plain onPress={...}>Yes</Button>`); the
7542	* key defaults to the label.
7543	*/
7544	plain?: true;
7545	/**
7546	* The label dim at rest, as `Text`'s `dimColor`, and at full strength
7547	* under the pointer or the focus; absent draws as false.
7548	*/
7549	dimColor?: TextProps['dimColor'];
7550	/**
7551	* The site's ring starts on this element when the site takes the
7552	* keyboard; the first drawn of several. Absent draws as before.
7553	*/
7554	autoFocus?: true;
7555	};
7556	/**
7557	* Where the handler lives: the plugin whose hook drew the element, and
7558	* the handle its environment keeps the `onPress` closure under.
7559	*
7560	* The runtime stamps the plugin as the tree leaves that hook.
7561	*/
7562	press: {
7563	plugin: string;
7564	handle: number;
7565	};
7566	/**
7567	* Label style overrides (the Text set) the surface applies while the
7568	* nearest keyed Box, or the group `scope` names, is hovered; plain data.
7569	*/
7570	hover?: TextHoverProps;
7571	} \| {
7572	/**
7573	* A one-line text field on every surface; a change and Enter raise
7574	* `ui.input` (`e.element` the key, `e.kind` which, `e.value` the text).
7575	*
7576	* Built by `<Input>` or the table's `t.Input`. The `onInput` and
7577	* `onSubmit` closures stay in the plugin's own environment under
7578	* `press.handle`, held as a Button's is. A leaf: no children.
7579	*/
7580	type: 'Input';
7581	props: {
7582	/**
7583	* The element's address: what `e.element` carries and what a matcher
7584	* names (`{ element: "reply" }`).
7585	*/
7586	key: string;
7587	/**
7588	* Text drawn before the field.
7589	*/
7590	label?: string;
7591	/**
7592	* Text drawn dim in an empty field.
7593	*/
7594	placeholder?: string;
7595	/**
7596	* The text the field holds when drawn.
7597	*/
7598	value?: string;
7599	/**
7600	* What Enter does, drawn beside the field while it has focus.
7601	*/
7602	submitLabel?: string;
7603	/**
7604	* The site's ring starts on this element when the site takes the
7605	* keyboard; the first drawn of several. Absent draws as before.
7606	*/
7607	autoFocus?: true;
7608	};
7609	/**
7610	* Where the handlers live: the plugin whose hook drew the element, and
7611	* the handle its environment keeps the closures under.
7612	*
7613	* The runtime stamps the plugin as the tree leaves that hook.
7614	*/
7615	press: {
7616	plugin: string;
7617	handle: number;
7618	};
7619	children?: undefined;
7620	} \| {
7621	/**
7622	* A one-of-several picker on every surface; a pick raises `ui.select`
7623	* (`e.element` the key, `e.value` the option's value).
7624	*
7625	* Built by `<Select>` or the table's `t.Select`. The `onSelect` closure
7626	* stays in the plugin's own environment under `press.handle`, held as
7627	* a Button's is. A leaf: no children.
7628	*/
7629	type: 'Select';
7630	props: {
7631	/**
7632	* The element's address: what `e.element` carries and what a matcher
7633	* names (`{ element: "peer" }`).
7634	*/
7635	key: string;
7636	/**
7637	* Text drawn before the current value.
7638	*/
7639	label?: string;
7640	/**
7641	* What can be picked, in the order drawn: each a value and the text
7642	* drawn for it.
7643	*/
7644	options: readonly SelectOption[];
7645	/**
7646	* Which option is selected when drawn.
7647	*/
7648	value?: string;
7649	/**
7650	* The site's ring starts on this element when the site takes the
7651	* keyboard; the first drawn of several. Absent draws as before.
7652	*/
7653	autoFocus?: true;
7654	};
7655	/**
7656	* Where the handler lives: the plugin whose hook drew the element, and
7657	* the handle its environment keeps the closure under.
7658	*
7659	* The runtime stamps the plugin as the tree leaves that hook.
7660	*/
7661	press: {
7662	plugin: string;
7663	handle: number;
7664	};
7665	children?: undefined;
7666	} \| {
7667	/**
7668	* A hyperlink every surface draws: an OSC 8 span on the terminal (its
7669	* text then the URL in dim where unsupported), an anchor on desktop.
7670	*
7671	* Inline: its children are the text, strings and inline elements;
7672	* absent children the label, absent both the URL. `href` is `https:`
7673	* (or `http://localhost`) and bounded, or the tree is refused.
7674	*/
7675	type: 'Link';
7676	props: LinkProps;
7677	children?: RenderNode[];
7678	} \| {
7679	/**
7680	* Source code every surface draws with the engine's highlighter, tokens
7681	* coloured by language; under `format: 'diff'`, unified-diff hunks.
7682	*
7683	* A leaf: a dim gutter numbers the lines from `startLine`; a diff has
7684	* both gutters, markers, add and remove backgrounds. `source` is
7685	* bounded as a Text's string is, or the tree is refused.
7686	*/
7687	type: 'Code';
7688	props: CodeProps;
7689	children?: undefined;
7690	} \| {
7691	/**
7692	* A block of markdown every surface draws as it draws an assistant
7693	* reply's text: its own renderer, theme, hyperlinks and highlighting.
7694	*
7695	* Built by `<Markdown>` or the table's `t.Markdown`. A leaf: `text` is
7696	* bounded as a Text's string is, or the tree is refused. Without a
7697	* `press` its links are the surface's own, opened as it opens links.
7698	*/
7699	type: 'Markdown';
7700	props: MarkdownLeafProps;
7701	children?: undefined;
7702	} \| {
7703	/**
7704	* A `Markdown` whose plugin answers the links it drew (`onLinkPress`):
7705	* a press on one raises `ui.press` with `e.link`, the surface opens none.
7706	*/
7707	type: 'Markdown';
7708	props: MarkdownLeafProps;
7709	/**
7710	* Where the `onLinkPress` handler lives: the plugin whose hook drew
7711	* the element, and the handle its environment keeps the closure under.
7712	*
7713	* The runtime stamps the plugin as the tree leaves that hook.
7714	*/
7715	press: {
7716	plugin: string;
7717	handle: number;
7718	};
7719	children?: undefined;
7720	} \| {
7721	/**
7722	* A region one of the plugin's SURFACE MODULES, named by path, draws and
7723	* handles input for on the drawing thread, without `$` (ClientModule).
7724	*
7725	* `Client` from the table. One instance per plugin, drawing and `key`
7726	* lives while the node stays in the tree, and talks to the plugin's
7727	* hooks through `ui.message`. The desktop carries it as data.
7728	*/
7729	type: 'Client';
7730	props: ClientProps;
7731	/**
7732	* Whose surface module `props.module` names: the plugin whose hook
7733	* drew the element, stamped by the runtime as the tree leaves it.
7734	*/
7735	client: {
7736	plugin: string;
7737	};
7738	children?: undefined;
7739	} \| {
7740	/**
7741	* A vector drawing, the remote surfaces' alone: the SVG markup is the
7742	* element's data, drawn in an isolated box, off the page.
7743	*
7744	* A leaf: hooks above wrap or replace it whole, nothing reaches inside;
7745	* a press other plugins should see goes on an enclosing Button. On a
7746	* surface whose table lacks it the tree is refused.
7747	*/
7748	type: 'Svg';
7749	props: SvgProps;
7750	children?: undefined;
7751	} \| {
7752	/**
7753	* A grid of terminal cells, the terminal surface's alone: each cell a
7754	* glyph, a foreground and a background, packed in `props.cells`.
7755	*
7756	* A leaf, one node however many cells; hooks above wrap or replace it
7757	* whole. A mounted one is repainted in place by its plugin's
7758	* `$.ui.blit`. On a surface whose table lacks it the tree is refused.
7759	*/
7760	type: 'Raster';
7761	props: RasterProps;
7762	/**
7763	* Whose Raster: the plugin whose hook drew the element, stamped by the
7764	* runtime as the tree leaves it; the one plugin whose blit reaches it.
7765	*/
7766	raster: {
7767	plugin: string;
7768	};
7769	children?: undefined;
7770	} \| {
7771	/**
7772	* A picture, the terminal surface's alone: `props.source` drawn over a
7773	* box of cells where the terminal can, `props.alt` where it cannot.
7774	*
7775	* A leaf: hooks above wrap or replace it whole; a press other plugins
7776	* should see goes on an enclosing Button; keyed, its plugin's
7777	* `$.ui.blit` swaps it. On a surface without it the tree is refused.
7778	*/
7779	type: 'Image';
7780	props: ImageProps;
7781	/**
7782	* Whose Image: the plugin whose hook drew the element, stamped by the
7783	* runtime as the tree leaves it; the one plugin whose blit reaches it.
7784	*/
7785	image: {
7786	plugin: string;
7787	};
7788	children?: undefined;
7789	} \| {
7790	/**
7791	* The component core draws itself, with the props held under `ref`.
7792	*/
7793	type: 'engine';
7794	/**
7795	* Which drawing: the number core answered from `next(e)`, under which
7796	* it holds the props it received; 0 draws the original props.
7797	*/
7798	ref: number;
7799	};
7800
7801	/**
7802	* The render event: `ui.render`, one event for every component that has a
7803	* render site.
7804	*/
7805	export type RenderEventName = 'ui.render';
7806
7807	/**
7808	* The input of `ui.render`: a union discriminated by `component`, one member
7809	* per RenderComponent and per RenderSurface.
7810	*/
7811	export type RenderInput<C extends RenderComponent = RenderComponent, P extends RenderSurface = RenderSurface> = C extends RenderComponent ? P extends RenderSurface ? RenderInputOf<C, P> : never : never;
7812
7813	/**
7814	* One `ui.render` input, for a component narrowed to one surface.
7815	*/
7816	export type RenderInputOf<C extends RenderComponent, P extends RenderSurface> = {
7817	/**
7818	* Where the tree will be drawn; one literal per member, so
7819	* `if (e.surface === "terminal")` narrows `e` and `$.ui.resolve(e)`.
7820	*
7821	* Over the wire it is what the client declared, a rendering fact and not a
7822	* trust signal: do not key policy on it.
7823	*/
7824	surface: P;
7825	/**
7826	* Which component this instance is; the key a matcher narrows on.
7827	*/
7828	component: C;
7829	/**
7830	* The instance: the tool_use_id for a dialog or tool row, the message id
7831	* for a message, the agent id for a spinner.
7832	*
7833	* Two drawings of one component are two instances.
7834	*/
7835	requestId: string;
7836	/**
7837	* The size of what the surface draws into, in character cells, and whether
7838	* its layout docks a pane; absent where no surface has measured.
7839	*
7840	* Part of the envelope: a rewrite keeps it. On the terminal, the interactive
7841	* screen's, where a change of width re-draws every hooked site once the
7842	* resize settles; on a remote surface, what it reported.
7843	*/
7844	viewport?: RenderViewport;
7845	/**
7846	* The component's plain-data props.
7847	*/
7848	props: RenderPropsOf[C];
7849	};
7850
7851	/**
7852	* A node of a render tree: an element, or a string (text).
7853	*/
7854	export type RenderNode = RenderElement \| string;
7855
7856	/**
7857	* The plain-data props of each renderable component, as `ui.render` sees
7858	* them under `e.props`; a hook rewrites them with `next({ ...e, props })`.
7859	*
7860	* A rewrite is validated by the component and an invalid one draws the
7861	* original. This table is the plugin-facing render contract; the author's
7862	* file notes which surfaces raise each member (RENDER_SURFACES_OF).
7863	*/
7864	export type RenderPropsOf = {
7865	/**
7866	* The dialog the AskUserQuestion tool opens.
7867	*
7868	* Raised on every surface.
7869	*/
7870	AskUserQuestion: {
7871	/**
7872	* The name of the tool whose call opened the dialog (`AskUserQuestion`).
7873	*/
7874	tool: string;
7875	/**
7876	* The tool's `questions` input, as the dialog will draw them; a rewrite
7877	* must still fit the tool's schema or the original is drawn.
7878	*/
7879	questions: unknown[];
7880	/**
7881	* The call's `metadata.source` (who asked) when the model gave one.
7882	* Analytics only; never drawn.
7883	*/
7884	metadataSource?: string;
7885	};
7886	/**
7887	* A user-role transcript row: the person's prompt (`> ...`), a background
7888	* task's notification, or a message another agent, teammate or session sent.
7889	*
7890	* `origin`, `task` and `from` tell them apart and are read-only; a rewrite
7891	* of `text` draws in the row alone: the stored message, and the model's
7892	* framing of another party's words as that party's, stay as they were.
7893	*
7894	* Raised on every surface.
7895	*/
7896	UserMessage: {
7897	/**
7898	* What the row shows: the prompt as typed, a notification's summary, or
7899	* a message's body less the engine's framing (summary line included).
7900	*
7901	* A rewrite is printable, bounded text and draws where the engine draws
7902	* the body; a teammate block of several frames or with a summary line
7903	* keeps the engine's drawing, one string not being those parts.
7904	*/
7905	text: string;
7906	/**
7907	* Where the stored message came from, as `prompt.submit` named it: the
7908	* composer's, a task notification's, a peer's, a channel's, a plugin's.
7909	*
7910	* `unclassified` for a teammate's (its drain stamps none) and for a
7911	* message stored before stamps. Read-only.
7912	*/
7913	origin: PromptOrigin;
7914	/**
7915	* Whether the view draws the row in full: the ctrl+o transcript,
7916	* `--verbose`, a surface with no ctrl+o (an export). Read-only.
7917	*
7918	* False, a message row is one dim line naming its sender; a hook that
7919	* draws a compact row of its own passes when true, so ctrl+o shows all.
7920	*/
7921	isExpanded: boolean;
7922	/**
7923	* What a notification row (`origin.kind` `task-notification`) reports
7924	* on: its background task; absent on every other row. Read-only.
7925	*/
7926	task?: UserMessageTask;
7927	/**
7928	* Who sent the message the row carries: another agent of this session, a
7929	* teammate, another session, a channel; absent otherwise. Read-only.
7930	*/
7931	from?: UserMessageFrom;
7932	/**
7933	* Which of its rows the transcript's viewport shows now: `null` while
7934	* drawn outside it, absent where the surface does not say. Read-only.
7935	*
7936	* Reported once drawn and again when it changes: on a scroll, for the
7937	* messages at the viewport's edges only. A rewrite carries it on as
7938	* received; one that changes or drops it is refused.
7939	*/
7940	onScreen?: OnScreen \| null;
7941	};
7942	/**
7943	* One text block of an assistant reply in the transcript; a rewrite
7944	* changes the drawing and leaves the stored message alone (ctrl+o).
7945	*
7946	* Raised on every surface.
7947	*/
7948	AssistantMessage: {
7949	/**
7950	* The block's text, markdown, as the transcript will draw it.
7951	*/
7952	text: string;
7953	/**
7954	* True on the block that draws the bullet opening a reply.
7955	*/
7956	isFirstOfReply: boolean;
7957	/**
7958	* Which of its rows the transcript's viewport shows now: `null` while
7959	* drawn outside it, absent where the surface does not say. Read-only.
7960	*
7961	* Reported once drawn and again when it changes: on a scroll, for the
7962	* messages at the viewport's edges only. A rewrite carries it on as
7963	* received; one that changes or drops it is refused.
7964	*/
7965	onScreen?: OnScreen \| null;
7966	};
7967	/**
7968	* A tool call's row in the transcript (`Bash(ls -la)` and its result); the
7969	* call was decided by `tool.call`, so a rewrite here changes the row alone.
7970	*
7971	* Raised on every surface.
7972	*/
7973	ToolUse: {
7974	/**
7975	* The id `tool.call` carried for this call (`e.tool_use_id` there); the
7976	* same value as the row's `requestId`, where it is looked for. Read-only.
7977	*/
7978	tool_use_id: string;
7979	/**
7980	* Which one the row draws (`Bash`, `Read`, a plugin's tool), as
7981	* `tool.call` named it.
7982	*/
7983	tool: string;
7984	/**
7985	* The call's input, as the model sent it.
7986	*/
7987	input: unknown;
7988	/**
7989	* True while the call is still running.
7990	*/
7991	isRunning: boolean;
7992	/**
7993	* True when the call ended in an error (a refusal at the dialog is one).
7994	*/
7995	isErrored: boolean;
7996	/**
7997	* True when an abort ended the call: the user's Esc or a plugin's
7998	* `$.turn.abort` cut it while it ran, or dropped it before it ran.
7999	*
8000	* The row draws `Interrupted` for it, as the transcript marker does.
8001	*/
8002	isInterrupted: boolean;
8003	/**
8004	* The stored result once the call has resolved (`{ stdout, stderr, ... }`
8005	* for Bash: `BuiltinToolResults[tool]`); undefined while it runs.
8006	*
8007	* For a call that errored, was refused or an abort cut, it is the text
8008	* the model read (an `isInterrupted` call: the abort's own). An expanded
8009	* group's rows draw it inline; a standalone row's is its own `ToolResult`.
8010	*/
8011	output?: unknown;
8012	/**
8013	* Which of its rows the transcript's viewport shows now: `null` while
8014	* drawn outside it, absent where the surface does not say. Read-only.
8015	*
8016	* Reported once drawn and again when it changes: on a scroll, for the
8017	* messages at the viewport's edges only. A rewrite carries it on as
8018	* received; one that changes or drops it is refused.
8019	*/
8020	onScreen?: OnScreen \| null;
8021	};
8022	/**
8023	* The result block drawn under a standalone tool row in the transcript,
8024	* which the tool's own result renderer draws from `output`.
8025	*
8026	* A rewrite of `output` is checked against the tool's output schema (one
8027	* that does not fit draws nothing; one the renderer cannot read hits the
8028	* row's error boundary). The stored result is untouched.
8029	*
8030	* Raised on every surface.
8031	*/
8032	ToolResult: {
8033	/**
8034	* The id `tool.call` carried for the call this result belongs to
8035	* (`e.tool_use_id` there); the same value as `requestId`. Read-only.
8036	*/
8037	tool_use_id: string;
8038	/**
8039	* Which one the result belongs to (`Bash`, `Read`, a plugin's tool).
8040	* Read-only.
8041	*/
8042	tool: string;
8043	/**
8044	* The tool's own result object (`{ stdout, stderr, interrupted, ... }` for
8045	* Bash), the same one `ToolUse.output` carries; a rewrite is drawn.
8046	*
8047	* A built-in tool's is `BuiltinToolResults[tool]`, the record
8048	* `tool.call` resolved as `result`.
8049	*/
8050	output: unknown;
8051	/**
8052	* True when the call ended in an error, which draws the error text and not
8053	* `output`. Read-only.
8054	*/
8055	isErrored: boolean;
8056	/**
8057	* Which of its rows the transcript's viewport shows now: `null` while
8058	* drawn outside it, absent where the surface does not say. Read-only.
8059	*
8060	* Reported once drawn and again when it changes: on a scroll, for the
8061	* messages at the viewport's edges only. A rewrite carries it on as
8062	* received; one that changes or drops it is refused.
8063	*/
8064	onScreen?: OnScreen \| null;
8065	};
8066	/**
8067	* A run of tool calls the transcript folds into one count line (`Read 3
8068	* files, ran 2 shell commands`): reads, searches, listings.
8069	*
8070	* A hook that sets `isExpanded` unfolds the group where it is, and each row
8071	* it unfolds into is a `ToolUse` drawing a `ToolUse` hook then sees.
8072	*
8073	* Raised on every surface.
8074	*/
8075	ToolGroup: {
8076	/**
8077	* In the order the model made them.
8078	*/
8079	calls: ReadonlyArray<ToolGroupCall>;
8080	/**
8081	* True while the group is the live one: a call in it may still be
8082	* running and the model's next call may join it.
8083	*/
8084	isActive: boolean;
8085	/**
8086	* Whether each call draws as its own `ToolUse` row (true under
8087	* `--verbose` and in the ctrl+o transcript) or the group draws one line.
8088	*
8089	* The one prop of the three a rewrite changes on the screen.
8090	*/
8091	isExpanded: boolean;
8092	/**
8093	* Which of its rows the transcript's viewport shows now: `null` while
8094	* drawn outside it, absent where the surface does not say. Read-only.
8095	*
8096	* Reported once drawn and again when it changes: on a scroll, for the
8097	* messages at the viewport's edges only. A rewrite carries it on as
8098	* received; one that changes or drops it is refused.
8099	*/
8100	onScreen?: OnScreen \| null;
8101	};
8102	/**
8103	* The output row a slash command printed in the transcript, under its echo
8104	* (`/cost`'s lines, the `text` a `command.run` hook answered).
8105	*
8106	* What the run resolved as text, a `local` command's or a plugin's alike. A
8107	* rewrite of `text` draws there and the stored row keeps what the model
8108	* reads; a hook's own tree draws in the row's place, the transcript's width.
8109	*
8110	* Raised on every surface.
8111	*/
8112	CommandOutput: {
8113	/**
8114	* Which one printed the row, as `command.run` named it (no slash); a
8115	* hook on its own command matches by it.
8116	*
8117	* Read-only: a rewrite carries it on as received; one that changes or
8118	* drops it is refused and the engine draws its own row.
8119	*/
8120	command: string;
8121	/**
8122	* The arguments the run had, as the echo above the row shows them
8123	* (`***` for a command that marks its arguments sensitive). Read-only.
8124	*/
8125	args: string;
8126	/**
8127	* The row's text: what the command printed, or the `text` a hook
8128	* answered under its plugin's name; markdown, as the row draws it.
8129	*/
8130	text: string;
8131	/**
8132	* True when the row is the run's error line (a command that threw),
8133	* which draws in the error colour and not dim. Read-only.
8134	*/
8135	isErrored: boolean;
8136	/**
8137	* Which of its rows the transcript's viewport shows now: `null` while
8138	* drawn outside it, absent where the surface does not say. Read-only.
8139	*
8140	* Reported once drawn and again when it changes: on a scroll, for the
8141	* messages at the viewport's edges only. A rewrite carries it on as
8142	* received; one that changes or drops it is refused.
8143	*/
8144	onScreen?: OnScreen \| null;
8145	};
8146	/**
8147	* One row of the live tool-progress region under a running tool call; today
8148	* the run-in-background pill. One instance per row.
8149	*
8150	* A union on `kind`: other progress kinds join as their props become plain
8151	* data, each with its own fields, so a hook matches `{ props: { kind:
8152	* "background_hint" } }` or branches on `e.props.kind` and stays right.
8153	*
8154	* Raised on the terminal surface only.
8155	*/
8156	ToolProgress: {
8157	/**
8158	* The tool call the row belongs to, as `tool.call` and the `ToolUse` row
8159	* carry it. Read-only: a rewrite carries it on as received.
8160	*
8161	* While several foreground calls share one pill, the first of them.
8162	*/
8163	tool_use_id: string;
8164	/**
8165	* Which progress row: the run-in-background pill. Read-only.
8166	*/
8167	kind: 'background_hint';
8168	/**
8169	* The pill's text as the engine draws it, dim, under the tool call:
8170	* `(ctrl+b to run in background)`, or with the person's own binding.
8171	*
8172	* A rewrite is drawn in its place, dim; `""` draws nothing. A hook that
8173	* returns a tree draws that instead.
8174	*/
8175	hint: string;
8176	};
8177	/**
8178	* The line that animates while a turn runs (`Sauteing... (12s, 300
8179	* tokens)`); a remote surface draws its own.
8180	*
8181	* The row reads `word` (or `message` while one overrides it), then
8182	* `suffix`, then the dim parenthetical the engine keeps (elapsed time,
8183	* tokens, effort); a hook rewrites the first three or draws its own tree.
8184	*
8185	* Raised on the terminal surface only.
8186	*/
8187	Spinner: {
8188	/**
8189	* Animated by the line (`Sauteing`), as sampled for this turn.
8190	*/
8191	word: string;
8192	/**
8193	* The text drawn instead of the word while a state overrides it, else null.
8194	*/
8195	message: string \| null;
8196	/**
8197	* What the engine draws right after the word or message to say the turn is
8198	* still going: one ellipsis character.
8199	*
8200	* Left off a text that already ends in an ellipsis, so a rewritten
8201	* `message` ending in one shows one. A rewrite is drawn as given (`""`
8202	* draws the text bare, `" ~"` draws `Sauteing ~`); left out, the engine's.
8203	*/
8204	suffix: string;
8205	/**
8206	* What the turn is doing.
8207	*/
8208	mode: 'requesting' \| 'responding' \| 'thinking' \| 'tool-input' \| 'tool-use';
8209	};
8210	/**
8211	* The line that closes a turn in the transcript (`Baked for 3s`); a
8212	* remote surface draws its own footer.
8213	*
8214	* Raised on the terminal surface only.
8215	*/
8216	TurnDuration: {
8217	/**
8218	* The past-tense word the line drew (`Baked`), as sampled for this line.
8219	*/
8220	word: string;
8221	/**
8222	* The turn's duration in milliseconds, as the line formats it (`3s`,
8223	* `1m 4s`).
8224	*/
8225	durationMs: number;
8226	/**
8227	* Which of its rows the transcript's viewport shows now: `null` while
8228	* drawn outside it, absent where the surface does not say. Read-only.
8229	*
8230	* Reported once drawn and again when it changes: on a scroll, for the
8231	* messages at the viewport's edges only. A rewrite carries it on as
8232	* received; one that changes or drops it is refused.
8233	*/
8234	onScreen?: OnScreen \| null;
8235	};
8236	/**
8237	* One dim status line under the logo (the model source, an experiment
8238	* enrollment, a settings hint), with a trailing `/command`.
8239	*
8240	* Raised on the terminal surface only.
8241	*/
8242	InfoNotice: {
8243	/**
8244	* The notice's text, flattened to one string.
8245	*/
8246	text: string;
8247	/**
8248	* The slash command appended after the text, or null when the notice has
8249	* none.
8250	*/
8251	command: string \| null;
8252	/**
8253	* Which of its rows the transcript's viewport shows now: `null` while
8254	* drawn outside it, absent where the surface does not say. Read-only.
8255	*
8256	* Reported once drawn and again when it changes: on a scroll, for the
8257	* messages at the viewport's edges only. A rewrite carries it on as
8258	* received; one that changes or drops it is refused.
8259	*/
8260	onScreen?: OnScreen \| null;
8261	};
8262	/**
8263	* The dim mode labels at the right of the prompt footer (`focus`, `memory
8264	* paused`), joined by ` & `. One instance.
8265	*
8266	* A hook adds a mode by rewriting `modes`, removes one by filtering, or
8267	* draws its own tree.
8268	*
8269	* Raised on the terminal and desktop surfaces only.
8270	*/
8271	SessionMode: {
8272	/**
8273	* The labels the footer shows, in order; empty when there are none.
8274	*/
8275	modes: readonly string[];
8276	};
8277	/**
8278	* The dim hint line under the prompt (`? for shortcuts`, `esc to
8279	* interrupt`, the pills beside them). One instance.
8280	*
8281	* A hook rewrites `hint` and the rewrite is drawn in the line's place, or
8282	* draws its own tree; `isDraft` and `isWorking` say what the line is for.
8283	*
8284	* Raised on the terminal surface only.
8285	*/
8286	PromptHint: {
8287	/**
8288	* True while the prompt holds typed text. Read-only.
8289	*/
8290	isDraft: boolean;
8291	/**
8292	* True while a model turn is running. Read-only.
8293	*/
8294	isWorking: boolean;
8295	/**
8296	* The line's text as the engine draws it; one string, so a rewrite
8297	* replaces the line.
8298	*
8299	* Read from the drawn line the way the screen reader reads it, one space
8300	* between parts.
8301	*/
8302	hint: string;
8303	};
8304	/**
8305	* The band directly above the prompt input, where the surveys draw; the
8306	* engine draws nothing of its own here.
8307	*
8308	* A hook draws a tree, or passes; one instance. The person collapses it
8309	* (ctrl+x ctrl+a, `[-]`) or focuses it (a click, ctrl+x tab): an Input
8310	* types, a Button arms the hotkeys, a tree taller than it scrolls.
8311	*
8312	* Raised on the terminal surface only.
8313	*/
8314	AbovePrompt: {
8315	/**
8316	* True while a survey holds the band; a hook yields to it. Read-only.
8317	*/
8318	hasSurvey: boolean;
8319	/**
8320	* True while a model turn is running. Read-only.
8321	*/
8322	isWorking: boolean;
8323	/**
8324	* Rows the band may take: in fullscreen, what the bottom slot has left
8325	* above the prompt; otherwise the terminal's height. Read-only.
8326	*
8327	* That slot is capped at half the terminal's rows, the prompt's included.
8328	* A tree of at most `maxRows` rows shows whole; a taller one scrolls in a
8329	* window of `scroll.bodyRows`, and a bare digit arms no Button's hotkey.
8330	*/
8331	maxRows: number;
8332	/**
8333	* Cells across the band: the terminal's width, or the transcript
8334	* column's while a `Pane` is docked beside it. Read-only.
8335	*
8336	* A tree wider than this wraps or truncates as its Text props say; size
8337	* a table or a rule to it rather than to `viewport.columns`.
8338	*/
8339	bodyColumns: number;
8340	/**
8341	* The band's window over a tree taller than `maxRows`: engine-owned,
8342	* moved by the wheel, and by the person's keys while the band is focused.
8343	*
8344	* `bodyRows` is `maxRows` less the `n more` row. Read-only.
8345	*/
8346	scroll: SiteScroll;
8347	/**
8348	* Which transcript is on screen above the band: the main conversation's
8349	* (no `agentId`) or one agent's, opened from the tasks list.
8350	*
8351	* The same band under either; a switch re-runs the hook with the new
8352	* view. Read-only: a rewrite carries it on as received; one that changes
8353	* or drops it is refused, the hook that passed it failing.
8354	*/
8355	view: SiteView;
8356	};
8357	/**
8358	* The framed region a plugin opened with `$.ui.open({ id })`: one instance
8359	* per id (`requestId`), its body the hook's tree, one shown, the rest tabs.
8360	*
8361	* Placed by the surface (docked in fullscreen, else above the prompt) and
8362	* keyed by the person (ctrl+x tab, Esc), who closes it from the engine's mark
8363	* or ctrl+x x: `ui.close` with origin `person`, which a hook may refuse.
8364	*
8365	* Raised on every surface.
8366	*/
8367	Pane: {
8368	/**
8369	* Its tab's label while more than one pane is open (with one, the engine
8370	* draws no title): the `title` it was opened with, or its id.
8371	*
8372	* A click on a tab, or Tab onto it and Enter, shows that pane. Read-only
8373	* here; another `$.ui.open` (or a hook on `ui.open`) retitles.
8374	*/
8375	title: string;
8376	/**
8377	* True while the person has given the pane the keyboard: Tab walks its
8378	* elements, a Button's `hotkey` presses it, the arrows scroll. Read-only.
8379	*/
8380	isFocused: boolean;
8381	/**
8382	* Cells across the body, inside the frame. Read-only.
8383	*/
8384	bodyColumns: number;
8385	/**
8386	* Where the surface seated the pane: `dock` beside the transcript (the
8387	* terminal in fullscreen from 110 columns), or `inline` above the prompt.
8388	*
8389	* Read-only: a rewrite carries it on as received; one that changes or
8390	* drops it is refused, the hook that passed it failing.
8391	*/
8392	placement: 'dock' \| 'inline';
8393	/**
8394	* The body's window over the tree: engine-owned, moved by the person's
8395	* keys while the pane is focused. Read-only.
8396	*/
8397	scroll: SiteScroll;
8398	/**
8399	* Which transcript is on screen beside the pane: the main conversation's
8400	* (no `agentId`) or one agent's, opened from the tasks list.
8401	*
8402	* The pane stays open across a switch, one instance re-rendered for the
8403	* view, so a hook draws for the agent in view. Read-only: a rewrite carries
8404	* it on as received; one that changes or drops it is refused.
8405	*/
8406	view: SiteView;
8407	};
8408	};
8409
8410	/**
8411	* What a `ui.render` hook returns and what `next(e)` resolves to: a
8412	* RenderElement tree, the same for every component.
8413	*/
8414	export type RenderResultOf = {
8415	[C in RenderComponent]: RenderElement;
8416	};
8417
8418	/**
8419	* Where a render event's component is drawn: `terminal` is Ink, which draws
8420	* the hook's whole tree; the rest are remote surfaces drawing it themselves.
8421	*
8422	* `desktop` is Claude Code Desktop, `mobile` the Claude mobile app, `vscode`
8423	* Claude Code for VS Code. A remote surface asks over the wire (ui_render),
8424	* draws with the props the hook handed core, and draws the tree where it has
8425	* a slot for it.
8426	*
8427	* Each surface's ask is its own evaluation, since a tree may hold an element
8428	* only some surfaces draw (Svg, Client).
8429	*/
8430	export type RenderSurface = 'terminal' \| 'desktop' \| 'mobile' \| 'vscode';
8431
8432	/**
8433	* The size of what a surface draws into, in character cells of the
8434	* surface's monospace metric, and whether its layout docks a pane.
8435	*
8436	* On the terminal, the conversation's columns and screen rows; on a remote
8437	* surface, the pane's width and height over the advance and line height of
8438	* its code font. Cell-based until the first element lays out in pixels.
8439	*/
8440	export type RenderViewport = {
8441	/**
8442	* Cells across. A tree wider than this wraps or truncates, as its Text
8443	* props say.
8444	*/
8445	columns: number;
8446	/**
8447	* Cells down the whole surface, not the room left for this component.
8448	*
8449	* Informational: a change of height alone re-draws nothing and keys no
8450	* new evaluation, so a hook reads it as of the last width or props change.
8451	*/
8452	rows: number;
8453	/**
8454	* Whether this surface docks a pane beside the transcript, so a pane a
8455	* plugin opens unasked is a sidebar, not a takeover; absent is unknown.
8456	*
8457	* What `command.run`'s `presentation.isFullscreen` says. The terminal always
8458	* says: `true` fullscreen, `false` on the main screen, fixed per session; a
8459	* remote surface once its client reports it with the size, absent before.
8460	*
8461	* @remarks The desktop and VS Code report it once they place panes; the
8462	* mobile app, which has no dock, `false`. A change re-draws the sites.
8463	* @example if (e.viewport?.isFullscreen === true) void $.ui.open({ id })
8464	*/
8465	isFullscreen?: boolean;
8466	};
8467
8468	/**
8469	* The input of `ui.resolve`: which surface's elements, for which component;
8470	* a union with one member per surface (ResolveInputOf).
8471	*
8472	* Resolved when the plugins load, ahead of any drawing, so it names the
8473	* surface and the component and not the props; a `ui.render` argument is
8474	* one (it carries both), which is what `$.ui.resolve(e)` takes.
8475	*/
8476	export type ResolveInput<C extends RenderComponent = RenderComponent, P extends RenderSurface = RenderSurface> = P extends RenderSurface ? ResolveInputOf<C, P> : never;
8477
8478	/**
8479	* One `ui.resolve` input, for a component on one surface.
8480	*/
8481	export type ResolveInputOf<C extends RenderComponent, P extends RenderSurface> = {
8482	/**
8483	* Where the table draws; one literal per member, so a hook that narrows
8484	* it narrows the table `next(e)` resolves to.
8485	*/
8486	surface: P;
8487	/**
8488	* Which drawing the table is resolved for; the key a matcher narrows on.
8489	*/
8490	component: C;
8491	};
8492
8493	/**
8494	* What each event's hook returns, and what its `next(e)` resolves to, by event
8495	* name.
8496	*/
8497	export type ResultOf = EngineResultOf & ClassicResultOf & {
8498	[N in OpEventName]: OpEventResult<N>;
8499	} & {
8500	[N in NounEventName]: NounEventResult<N>;
8501	};
8502
8503	type SDKAssistantMessageError = 'authentication_failed' \| 'oauth_org_not_allowed' \| 'account_on_hold' \| 'verification_required' \| 'billing_error' \| 'rate_limit' \| 'overloaded' \| 'invalid_request' \| 'model_not_found' \| 'server_error' \| 'unknown' \| 'max_output_tokens' \| 'cloud_credential_error';
8504
8505	/**
8506	* The members of `T` assignable to `S`; all of `T` when none is.
8507	*/
8508	type Select<T, S> = [Extract<T, S>] extends [never] ? T : Extract<T, S>;
8509
8510	/**
8511	* The events a pattern selects, as a union of names: the one named, every
8512	* one under a glob's namespace, or every one a negation does not exclude.
8513	*/
8514	export type Selected<P extends string> = P extends '' ? EventName : P extends `!${infer Negated}` ? Exclude<EventName, Selected<Negated>> : P extends `${infer Prefix}.` ? Extract<EventName, `${Prefix}.${string}`> : Extract<EventName, P>;
8515
8516	/**
8517	* The literal each tag key of `I` is held to by matcher `M`: one-of arrays
8518	* flattened, RegExps widened to `unknown`.
8519	*/
8520	type Selection<I, M> = {
8521	[K in keyof M & TagKeys<I>]: Literal<M[K] extends readonly (infer One)[] ? One : M[K]>;
8522	};
8523
8524	/**
8525	* One option of a `Select`: the value `onSelect` and `ui.select` carry, and
8526	* the text drawn for it (the value when absent).
8527	*/
8528	export type SelectOption = {
8529	value: string;
8530	label?: string;
8531	};
8532
8533	/**
8534	* The props of `Select`, every surface's one-of-several picker: an address,
8535	* a label, the options, the one selected, the closure a pick runs. A leaf.
8536	*
8537	* Focused through the same ring as `Button` (`abovePrompt:focus`); keys reach
8538	* it only while it has focus (arrows move, Enter picks) and Esc always
8539	* returns to the prompt; a pick raises `ui.select`, its bottom `onSelect`.
8540	*/
8541	export type SelectProps = {
8542	/**
8543	* The element's address: `e.element` at `ui.select`, what a matcher names.
8544	*/
8545	key: string;
8546	/**
8547	* Text drawn before the current value.
8548	*/
8549	label?: string;
8550	/**
8551	* What can be picked, in the order drawn; at least one, values unique.
8552	*/
8553	options: readonly SelectOption[];
8554	/**
8555	* Which option is selected when drawn; the person's pick replaces it
8556	* until the hook draws another.
8557	*/
8558	value?: string;
8559	/**
8560	* The site's focus ring starts here when the site takes the keyboard,
8561	* instead of on nothing, as the DOM's `autofocus`: Enter acts on it at once.
8562	*
8563	* A pane opened with `focus`, or the person's focus chord or click, is the
8564	* take. Of several in one site the first drawn wins; it raises `ui.focus`,
8565	* origin this plugin. A ring the person has moved stays where it was put.
8566	*/
8567	autoFocus?: true;
8568	/**
8569	* Runs on a pick with the option's value, in the plugin's own environment:
8570	* the bottom of a `ui.select` chain. No model turn unless it asks one.
8571	*/
8572	onSelect: (value: string, e: UiSelectArgument) => void;
8573	};
8574
8575	/**
8576	* The input of `session.attach`: a surface joined the session's roster of
8577	* attached clients (a phone opened the session; the desktop app connected).
8578	*
8579	* A remote client attaches by saying so (ui_attach) or by its first ask to
8580	* draw; the terminal's attachment is the REPL's binding and raises nothing.
8581	* Every field is the engine's: a hook observes, `next(e)` passes them on.
8582	*/
8583	export type SessionAttachInput = {
8584	/**
8585	* Where the client draws: what it declared, a rendering fact.
8586	*/
8587	surface: RenderSurface;
8588	/**
8589	* The client's own id, unique in the roster; two phones are two clients on
8590	* one surface. A client that never named itself is `<surface>:default`.
8591	*/
8592	clientId: string;
8593	/**
8594	* The size the client draws into, in character cells, and whether its
8595	* layout docks a pane, when it said.
8596	*/
8597	viewport?: RenderViewport;
8598	};
8599
8600	/**
8601	* What a `session.attach` hook returns and what `next(e)` resolves to:
8602	* `{ clientId }`, echoed by core; a hook's own value changes nothing.
8603	*/
8604	export type SessionAttachResult = {
8605	clientId: string;
8606	};
8607
8608	/**
8609	* What `$.session.authorize()` answers: an opaque handle for the session's
8610	* Anthropic credential and its kind, or null when there is none to hold.
8611	*
8612	* The secret itself stays with the engine; the handle is its plugin-side
8613	* face, spent through `$.http.fetch(url, { auth: handle })`.
8614	*/
8615	export type SessionAuthorization = {
8616	handle: string;
8617	kind: 'bearer' \| 'api-key';
8618	} \| null;
8619
8620	/**
8621	* One content block of an ApiMessage: `type` names its kind (`text`,
8622	* `tool_use`, `tool_result`, `image`, `document`, `thinking`, ...).
8623	*
8624	* The other fields are that kind's as the Messages API defines them (see its
8625	* reference); the engine hands the block over as it holds it, nothing renamed
8626	* or dropped.
8627	*/
8628	type ApiContentBlock = {
8629	/**
8630	* The block's kind; the rest of the block is that kind's fields.
8631	*/
8632	type: string;
8633	[field: string]: unknown;
8634	};
8635
8636	/**
8637	* `session.append`'s input as a plugin's `$.session.append(args)` takes it:
8638	* the row's kind and text, and the loop it joins.
8639	*
8640	* Its door (`note`), origin (the calling plugin) and id are the engine's to
8641	* set; a hook above, or the organization's policy plugin, may rewrite or
8642	* refuse it like any call on `$`.
8643	*/
8644	export type SessionAppendArgs = {
8645	/**
8646	* The row: `type: "user"` for a user-role row the person does not see as
8647	* typed (the model reads it), `"system"` for a notice the model never reads.
8648	*
8649	* Its `content` is text blocks alone (one, for a notice): the bottom
8650	* refuses any other block, and any other row type, with the reason.
8651	*/
8652	message: {
8653	type: 'user' \| 'system';
8654	content: ApiContentBlock[];
8655	};
8656	/**
8657	* The running subagent whose conversation the row joins; absent for main.
8658	* One that names no running loop is refused.
8659	*/
8660	agentId?: string;
8661	};
8662
8663	/**
8664	* Which door a row came in by, decided from the row alone; a closed set,
8665	* pinned on the event and the key a matcher narrows on.
8666	*/
8667	export type SessionAppendDoor = 'prompt' \| 'command' \| 'response' \| 'tool-result' \| 'tool-message' \| 'delivery' \| 'attachment' \| 'hook-context' \| 'note' \| 'compaction' \| 'notice';
8668
8669	/**
8670	* The input of `session.append`: one row being appended to a conversation of
8671	* this session, by the engine site that originates it or by a plugin's call.
8672	*
8673	* Not on `e`, so stored as made: a tool result's structured record, the row's
8674	* timestamps, parent links and provenance stamps, an attachment's payload
8675	* (the model reads its recorded rendering, which `content` rewrites).
8676	*/
8677	export type SessionAppendInput = {
8678	/**
8679	* The row as it will be kept (SessionAppendMessage). Its `content` is a
8680	* hook's to rewrite; the engine puts back what it pins.
8681	*/
8682	message: SessionAppendMessage;
8683	/**
8684	* Which door the row came in by (SessionAppendDoor); the key a matcher
8685	* narrows on. Pinned.
8686	*/
8687	door: SessionAppendDoor;
8688	/**
8689	* Who caused the row (SessionAppendOrigin): the person, the model, a tool,
8690	* the engine, a settings hook, a plugin. Pinned.
8691	*/
8692	origin: SessionAppendOrigin;
8693	/**
8694	* The row's id, the same in the transcript file and on every later read,
8695	* so a hook can keep a table by row before calling `next`. Pinned.
8696	*/
8697	uuid: string;
8698	/**
8699	* The loop whose conversation keeps the row: a subagent's id, as `turn.step`
8700	* and `tool.call` carry it; absent on main.
8701	*
8702	* Pinned: a different value is refused, one left out is kept.
8703	*/
8704	agentId?: string;
8705	};
8706
8707	/**
8708	* One row of a conversation as `session.append` hands it: how the transcript
8709	* files it, under which role a request carries it, and its blocks.
8710	*
8711	* `{ role, content }` of a row a request carries is an ApiMessage, so code
8712	* written for `$.session.messages({ as: "api" })` reads it unchanged.
8713	*/
8714	export type SessionAppendMessage = {
8715	/**
8716	* How the transcript files the row: `user`, `assistant`, `attachment` (what
8717	* the engine injects beside the conversation), `system` (a notice).
8718	*
8719	* Pinned, as `name`, `role` and `isMeta` are: left out it is kept, changed
8720	* it fails the hook.
8721	*/
8722	type: 'user' \| 'assistant' \| 'attachment' \| 'system';
8723	/**
8724	* An attachment's type (`queued_command`, `nested_memory`, ...) or a
8725	* notice's subtype (`compact_boundary`, `local_command`, ...). Pinned.
8726	*
8727	* Absent on user and assistant rows. Builds add and retire names.
8728	*/
8729	name?: string;
8730	/**
8731	* Under which role a request carries the row; absent when none does (a
8732	* notice, a record with no bytes on the wire, a virtual row). Pinned.
8733	*/
8734	role?: 'user' \| 'assistant';
8735	/**
8736	* True on a user-side row the person does not see as typed (a reminder, a
8737	* nudge, a delivery's text). Pinned.
8738	*/
8739	isMeta?: true;
8740	/**
8741	* The row's blocks in order (ApiContentBlock): an attachment's as the
8742	* engine recorded its rendering, a notice's as one text block.
8743	*
8744	* Rewritable: text blocks, a tool_result's `content` and `is_error`. Media
8745	* blocks may be dropped or moved, not changed or added. Thinking, tool_use,
8746	* unknown kinds and every tool_result's `tool_use_id` are put back.
8747	*/
8748	content: ApiContentBlock[];
8749	};
8750
8751	/**
8752	* Who caused a row, as the engine knows it from the row itself: a submission's
8753	* sender, an injected row's author, the model, or the tool that was called.
8754	*/
8755	export type SessionAppendOrigin = PromptOrigin \| PromptAttachmentOrigin \| {
8756	/**
8757	* A block of the model's response, or the engine's stand-in for one.
8758	*/
8759	kind: 'model';
8760	/**
8761	* Whose response it is: the id the response names.
8762	*/
8763	model: string;
8764	} \| {
8765	/**
8766	* A tool call's result, or a row a tool handed over beside it.
8767	*/
8768	kind: 'tool';
8769	/**
8770	* Which one was called, by name; `unknown` when no call of that id is
8771	* found.
8772	*/
8773	tool: string;
8774	};
8775
8776	/**
8777	* What a `session.append` hook returns and what `next(e)` resolves to: the
8778	* row as the session stored it, or `{ deny: reason }` for a plugin's own call.
8779	*
8780	* `next(e)` resolves once the row is kept. A hook relays it unchanged: one
8781	* that answers without `next`, or another row, is skipped. Only a plugin's own
8782	* append (door `note`) may be refused, in place of `next`: nothing is stored.
8783	*/
8784	export type SessionAppendResult = {
8785	/**
8786	* The row as stored: what arrived at the bottom, the pinned parts put
8787	* back.
8788	*/
8789	message: SessionAppendMessage;
8790	/**
8791	* The stored row's id: the same in the transcript file and on every
8792	* later read.
8793	*/
8794	uuid: string;
8795	deny?: undefined;
8796	} \| {
8797	/**
8798	* Refuses a plugin's own append, so nothing is stored: the call
8799	* resolves to this, the reason the refusing hook gave.
8800	*/
8801	deny: string;
8802	message?: undefined;
8803	uuid?: undefined;
8804	};
8805
8806	/**
8807	* `session.compact`'s input as a plugin's `$.session.compact(args)` takes
8808	* it: `trigger` (`plugin`), `messages` and `agentId` are the engine's.
8809	*/
8810	export type SessionCompactArgs = {
8811	/**
8812	* What the summary should keep or stress, as typed after `/compact`;
8813	* absent, the engine's own compaction prompt alone.
8814	*/
8815	instructions?: string;
8816	};
8817
8818	/**
8819	* A compaction that stands: the conversation as it reads afterwards, and
8820	* the token counts the engine recorded when it was the one compacting.
8821	*/
8822	export type SessionCompacted = {
8823	/**
8824	* The conversation after the compaction, oldest first: from core, its
8825	* summary and the messages it kept; from a hook, whatever it hands up.
8826	*
8827	* What the transcript becomes (kept, on `precompute`, for the compaction
8828	* that comes). A message with the engine's `handle` stands as the engine
8829	* has it; one without is built from its `role`, `text` and tool blocks.
8830	*/
8831	messages: readonly SessionMessage[];
8832	/**
8833	* The conversation's size before, in tokens; absent when core did not
8834	* record it.
8835	*/
8836	tokensBefore?: number;
8837	/**
8838	* Its size afterwards, in tokens; absent on `precompute` and when core
8839	* did not record it.
8840	*/
8841	tokensAfter?: number;
8842	skip?: undefined;
8843	};
8844
8845	/**
8846	* The input of `session.compact`: one compaction of the conversation, about
8847	* to run; `messages` is the transcript it runs over.
8848	*/
8849	export type SessionCompactInput = {
8850	/**
8851	* What is compacting (SessionCompactTrigger); the key a matcher narrows
8852	* on. Pinned: `next(e)` passes it on as received.
8853	*/
8854	trigger: SessionCompactTrigger;
8855	/**
8856	* The id of the loop compacting, for a subagent's or a fork's own
8857	* transcript; absent for the main conversation (tool.call's `agentId`).
8858	*
8859	* Pinned: left out of a rewrite it is put back, changed it fails the hook.
8860	* `$.session.messages()` is the main conversation whatever this names.
8861	*/
8862	agentId?: string;
8863	/**
8864	* What the summary should keep or stress: the text after `/compact`, a
8865	* plugin's, or absent.
8866	*
8867	* `next({ ...e, instructions })` changes what the summarizer is told.
8868	*/
8869	instructions?: string;
8870	/**
8871	* The transcript being compacted, in `$.session.messages()`'s shape, each
8872	* message carrying the engine's `handle`; a subagent's own under `agentId`.
8873	*
8874	* `next({ ...e, messages })` changes what is summarized: a message kept
8875	* with its handle is the engine's own, whole; one without is read as built.
8876	*/
8877	messages: readonly SessionMessage[];
8878	};
8879
8880	/**
8881	* What a `session.compact` hook returns and what `next(e)` resolves to: the
8882	* compaction (`{ messages, tokensBefore?, tokensAfter? }`) or `{ skip }`.
8883	*
8884	* There is no summary string: the summary is a message.
8885	*/
8886	export type SessionCompactResult = SessionCompacted \| SessionCompactSkipped;
8887
8888	/**
8889	* A compaction vetoed: on `precompute` nothing is computed or kept; on any
8890	* other trigger the conversation stays as it is and one line says why.
8891	*
8892	* Core answers it too, when a classic PreCompact hook blocks.
8893	*/
8894	export type SessionCompactSkipped = {
8895	/**
8896	* Why, as the notice reads.
8897	*/
8898	skip: string;
8899	messages?: undefined;
8900	};
8901
8902	/**
8903	* Who compacts: the person's `/compact` (`manual`), the engine at its
8904	* threshold or on a prompt too long (`auto`), a plugin, or a `precompute`.
8905	*
8906	* `precompute` is the one dispatch that installs nothing: its result is kept
8907	* for the compaction that comes, if the conversation it ran over still leads.
8908	*/
8909	export type SessionCompactTrigger = 'manual' \| 'auto' \| 'plugin' \| 'precompute';
8910
8911	/**
8912	* The context window broken down as /context breaks it down: the rows, the
8913	* grid and the lists beneath it, in the SDK's `get_context_usage` shape.
8914	*
8915	* Less that reply's internal-build sections. Token counts are the engine's
8916	* estimates as numbers, never formatted: a `full` breakdown counts with the
8917	* token-count API where it can, a `summary` one estimates throughout.
8918	*/
8919	export type SessionContextBreakdown = {
8920	/**
8921	* One row per category, the free space and the compaction buffer among
8922	* them; `kind` says which is which.
8923	*/
8924	categories: ContextCategory[];
8925	/**
8926	* Tokens in use, unclamped: past `rawMaxTokens` when over the window.
8927	*/
8928	totalTokens: number;
8929	/**
8930	* The window measured against, the same figure as `rawMaxTokens`.
8931	*/
8932	maxTokens: number;
8933	/**
8934	* The window measured against, in tokens: the model's limit, or a smaller
8935	* compaction window (`autocompactSource` says which).
8936	*/
8937	rawMaxTokens: number;
8938	/**
8939	* How that window was settled (ContextWindowSource); the SDK's reply
8940	* carries it under this name too, outside its typed schema.
8941	*/
8942	autocompactSource: ContextWindowSource;
8943	/**
8944	* `totalTokens` over `rawMaxTokens` as a whole percentage, 0 to 100 and
8945	* past it when over.
8946	*/
8947	percentage: number;
8948	/**
8949	* The grid, row by row: 10 by 10, 20 by 10 for a window of a million or
8950	* more, 5 wide when asked for under 80 `columns`.
8951	*/
8952	gridRows: ContextGridSquare[][];
8953	/**
8954	* Which model the breakdown was computed for, as `/model` shows it.
8955	*/
8956	model: string;
8957	/**
8958	* Each memory file in the context, with its path and tokens.
8959	*/
8960	memoryFiles: ContextMemoryFile[];
8961	/**
8962	* Each MCP tool's schema, with its server and tokens.
8963	*/
8964	mcpTools: ContextMcpTool[];
8965	/**
8966	* The custom agents the Agent tool describes, each with its tokens.
8967	*/
8968	agents: ContextAgent[];
8969	/**
8970	* The slash-command listing, counted; absent when the session lists none.
8971	*/
8972	slashCommands?: ContextSlashCommands;
8973	/**
8974	* The skill listing, counted, with one entry per skill; absent when the
8975	* session lists none.
8976	*/
8977	skills?: ContextSkills;
8978	/**
8979	* The token count at which auto-compaction runs; absent when it is off.
8980	*/
8981	autoCompactThreshold?: number;
8982	/**
8983	* Whether auto-compaction is on for the session.
8984	*/
8985	isAutoCompactEnabled: boolean;
8986	/**
8987	* The last response's own token counts, or null before one came back.
8988	*/
8989	apiUsage: ContextApiUsage \| null;
8990	};
8991
8992	/**
8993	* The live context window as the status line reads it, and by category as
8994	* /context breaks it down when the call asked (`{ breakdown }`).
8995	*
8996	* `tokens` and `percent` are the last API response's input side against the
8997	* model's window, absent until the first response of the live window: a
8998	* fresh session, or one just compacted, until its next response.
8999	*/
9000	export type SessionContextUsage = {
9001	/**
9002	* Input tokens the last response was answered over: uncached, cache-written
9003	* and cache-read together (the status line's `total_input_tokens`).
9004	*/
9005	tokens?: number;
9006	/**
9007	* The context window of the session's model, in tokens (the status line's
9008	* `context_window_size`).
9009	*/
9010	window: number;
9011	/**
9012	* `tokens` over `window` as a whole percentage, 0 to 100 (the status
9013	* line's `used_percentage`).
9014	*/
9015	percent?: number;
9016	/**
9017	* The window by category, as /context breaks it down: present only when
9018	* the call passed `breakdown`, and only with a session bound.
9019	*
9020	* It measures against the compaction window (`rawMaxTokens`), which may be
9021	* smaller than `window`, and estimates every category, so its
9022	* `totalTokens` need not equal `tokens`.
9023	*/
9024	breakdown?: SessionContextBreakdown;
9025	};
9026
9027	/**
9028	* What the session has cost, as `/cost` and the status line total it.
9029	*/
9030	export type SessionCost = {
9031	/**
9032	* US dollars, summed over every priced API response this session.
9033	*/
9034	usd: number;
9035	};
9036
9037	type SessionCronSummary = {
9038	id: string;
9039	/**
9040	* Cron expression, e.g. "0 9 * * 1-5".
9041	*/
9042	schedule: string;
9043	/**
9044	* False for one-shot wakeups whose cron field encodes a single fire time; true for tasks that re-fire on every match.
9045	*/
9046	recurring: boolean;
9047	/**
9048	* Prompt text submitted when the cron fires. Capped at 1000 chars; clipped values append an in-string "... [+N chars]" marker.
9049	*/
9050	prompt: string;
9051	};
9052
9053	/**
9054	* The input of `session.detach`: a client left the session's roster. Every
9055	* field is the engine's: a hook observes, and `next(e)` passes them on.
9056	*/
9057	export type SessionDetachInput = {
9058	/**
9059	* Where the client drew.
9060	*/
9061	surface: RenderSurface;
9062	/**
9063	* The id it attached under.
9064	*/
9065	clientId: string;
9066	/**
9067	* Why it left: it detached, or the session ended under it.
9068	*/
9069	reason: SessionDetachReason;
9070	};
9071
9072	/**
9073	* Why a client left the roster: `detach`, it said so (ui_detach); `end`, the
9074	* session ended with it still attached.
9075	*/
9076	export type SessionDetachReason = 'detach' \| 'end';
9077
9078	/**
9079	* What a `session.detach` hook returns and what `next(e)` resolves to:
9080	* `{ clientId }`, echoed by core; a hook's own value changes nothing.
9081	*/
9082	export type SessionDetachResult = {
9083	clientId: string;
9084	};
9085
9086	type SessionEndHookInput = BaseHookInput & {
9087	hook_event_name: 'SessionEnd';
9088	reason: ExitReason;
9089	};
9090
9091	/**
9092	* The input of `session.end`: the session is ending, why, and how to come back
9093	* to it.
9094	*
9095	* Every field is the engine's: a hook observes, and `next(e)` passes them on.
9096	*/
9097	export type SessionEndInput = {
9098	/**
9099	* Why it ends (SessionEndReason), the word the classic SessionEnd hook
9100	* receives as its `reason`.
9101	*/
9102	reason: SessionEndReason;
9103	/**
9104	* The ending session's id (`$.session.id()` until now); after a `/clear`
9105	* or a resume the process goes on under another.
9106	*/
9107	sessionId: string;
9108	/**
9109	* What `claude --resume` takes to return to it.
9110	*/
9111	resume: SessionResume;
9112	};
9113
9114	/**
9115	* Why the session ended: the classic SessionEnd hook's own `reason`, word for
9116	* word.
9117	*
9118	* `prompt_input_exit`, the person left (/exit, ctrl+c, ctrl+d); `clear`, a
9119	* /clear started a fresh one; `resume`, another took its place; `logout`;
9120	* `other`, a `-p` run finished or the process got SIGINT, SIGTERM or SIGHUP.
9121	*/
9122	export type SessionEndReason = ClassicHookInputs['SessionEnd']['reason'];
9123
9124	/**
9125	* What a `session.end` hook returns and what `next(e)` resolves to:
9126	* `{ sessionId }`, echoed by core; a hook's own value changes nothing.
9127	*/
9128	export type SessionEndResult = {
9129	sessionId: string;
9130	};
9131
9132	/**
9133	* The input of `session.measure`: what `$.session.usage()` answers at this
9134	* moment, and which of its units moved since the last measurement a hook saw.
9135	*
9136	* The same figures the op reads, without `context.breakdown`: call
9137	* `$.session.usage({ breakdown })` from the hook when the categories matter.
9138	* Every field is the engine's: a hook observes, and `next(e)` passes them on.
9139	*/
9140	export type SessionMeasureInput = {
9141	/**
9142	* The live context window (`$.session.usage()`'s `context`): the window,
9143	* and its fill once a response of the live window reported one.
9144	*
9145	* Never carries `breakdown` here.
9146	*/
9147	context: SessionContextUsage;
9148	/**
9149	* The rate-limit windows the last response reported, each with its
9150	* `percentUsed`; empty off a subscription or before the first reading.
9151	*/
9152	rateLimits: SessionRateLimit[];
9153	/**
9154	* What the session has cost so far; absent where the host keeps no ledger.
9155	*/
9156	cost?: SessionCost;
9157	/**
9158	* Which units differ from the last measurement raised (UsageUnit), never
9159	* empty; the first measurement names every unit it has a figure for.
9160	*
9161	* `context`: the fill moved; `rateLimits`: a window moved a whole point,
9162	* appeared or left, or the account's limit status changed; `cost`: the
9163	* total grew.
9164	*/
9165	changed: UsageUnit[];
9166	};
9167
9168	/**
9169	* What a `session.measure` hook returns and what `next(e)` resolves to:
9170	* `{ changed }`, echoed by core; a hook's own value changes nothing.
9171	*/
9172	export type SessionMeasureResult = {
9173	changed: UsageUnit[];
9174	};
9175
9176	/**
9177	* One message of the transcript as `$.session.messages()` returns it.
9178	*/
9179	export type SessionMessage = {
9180	/**
9181	* Who wrote it.
9182	*/
9183	role: 'user' \| 'assistant';
9184	/**
9185	* Its text blocks joined; '' when it has none.
9186	*/
9187	text: string;
9188	/**
9189	* The tool_use blocks of an assistant message, each with its outcome
9190	* (`result`, `text`, `isError`) once the transcript holds it.
9191	*/
9192	toolUses: ToolUseSummary[];
9193	/**
9194	* The tool_result blocks of a user message: `{ tool_use_id, text, isError,
9195	* result }`.
9196	*/
9197	toolResults?: ToolResultSummary[];
9198	/**
9199	* An opaque token the engine stamps on a message it hands a
9200	* `session.compact` hook, so a list handed back maps to its own messages.
9201	*
9202	* Absent on `$.session.messages()` and on a message a hook built.
9203	*/
9204	handle?: string;
9205	};
9206
9207	/**
9208	* One rate-limit window as the rate-limit notices read it.
9209	*/
9210	export type SessionRateLimit = {
9211	/**
9212	* Which window: `five_hour`, `seven_day`, or a Claude gateway's
9213	* `spend_limit`.
9214	*/
9215	kind: string;
9216	/**
9217	* How much of the window is used, 0 to 100 with at most one decimal:
9218	* 23.5, or 7, never 7.000000000000001; past 100 on an exceeded spend limit.
9219	*/
9220	percentUsed: number;
9221	/**
9222	* When the window resets, as an ISO 8601 timestamp.
9223	*/
9224	resetsAt?: string;
9225	};
9226
9227	/**
9228	* An external-event wake the delivery's text parsed as (a GitHub relay
9229	* event, a signal's notice): the envelope's attributes and its JSON body.
9230	*/
9231	export type SessionReceiveEvent = {
9232	/**
9233	* The producing service (`github`).
9234	*/
9235	source: string;
9236	/**
9237	* The event's discriminator (`pull_request.closed`, `check_suite`).
9238	*/
9239	kind: string;
9240	/**
9241	* The envelope's JSON body (`{ pr: "acme/app#12", outcome: "merged" }`).
9242	*/
9243	data: Record<string, unknown>;
9244	/**
9245	* The `data` keys whose values are free text a third party wrote (a
9246	* commenter's `author` and `comment`), as the producer marked them.
9247	*
9248	* Empty when none; the server asserts every other key's value, not these.
9249	*/
9250	untrustedKeys: readonly string[];
9251	};
9252
9253	/**
9254	* The input of `session.receive`: one inbound delivery (a relay's event, a
9255	* peer's message, a Remote Control prompt), sanitized, before it is queued.
9256	*/
9257	export type SessionReceiveInput = {
9258	/**
9259	* Where the delivery came from, as the bridge classified it; the key a
9260	* matcher narrows on. `next(e)` passes it on as received.
9261	*/
9262	origin: SessionReceiveOrigin;
9263	/**
9264	* The delivery's body as the model would read it (a content-block
9265	* delivery's text blocks, joined).
9266	*/
9267	text: string;
9268	/**
9269	* The external-event wake the text parsed as (`source` `github` for a
9270	* subscribed pull request's event); passed on as received.
9271	*
9272	* Present only for a delivery the server itself rendered as a wake (a
9273	* webhook relay, the session inbox), by its asserted origin; anyone else's
9274	* wake-shaped text stays `text`. Its `untrustedKeys` name third-party text.
9275	*/
9276	event?: SessionReceiveEvent;
9277	};
9278
9279	/**
9280	* Where an inbound delivery came from, as the bridge classified it from the
9281	* server's stamps: `prompt.submit`'s `e.origin`, less what never arrives.
9282	*/
9283	export type SessionReceiveOrigin = {
9284	/**
9285	* `bridge` the user's own from a Remote Control client; `peer` another
9286	* session; `unclassified` one the bridge could not place.
9287	*
9288	* `task-notification` a relay's event (a GitHub webhook) or a trigger;
9289	* `scheduled-trigger` a routine; `peer-send-message` another session's
9290	* SendMessage; `projects-relay` and `slack-ping` as at `prompt.submit`.
9291	*/
9292	kind: 'bridge' \| 'task-notification' \| 'scheduled-trigger' \| 'peer' \| 'peer-send-message' \| 'projects-relay' \| 'slack-ping' \| 'unclassified';
9293	};
9294
9295	/**
9296	* What a `session.receive` hook returns and what `next(e)` resolves to: the
9297	* delivery that was queued, `{ text }`, or `{ consumed: reason }`.
9298	*
9299	* `next(e)` resolves once the delivery is queued; a hook answering without
9300	* `next` queues nothing.
9301	*/
9302	export type SessionReceiveResult = {
9303	/**
9304	* The body the delivery was queued with; from core, `e.text` as it
9305	* arrived at the bottom.
9306	*
9307	* A rewrite passes it down, `next({ ...e, text })`.
9308	*/
9309	text: string;
9310	consumed?: undefined;
9311	} \| {
9312	/**
9313	* Takes the delivery, answered without `next`: it is not queued, not
9314	* written to the transcript and never reaches the model.
9315	*
9316	* The reason is logged, the plugin named.
9317	*/
9318	consumed: string;
9319	text?: undefined;
9320	};
9321
9322	/**
9323	* What `$.session.repo()` answers: the repository's root and its origin remote,
9324	* when the session is in one.
9325	*/
9326	export type SessionRepo = {
9327	/**
9328	* The repository's root, absolute: the main working tree's for a worktree.
9329	*/
9330	root: string;
9331	/**
9332	* The `origin` remote's URL as git has it (push URL preferred), or null when
9333	* the repository has none.
9334	*/
9335	remote: string \| null;
9336	/**
9337	* Whether the remote is one of the repositories this build treats as its
9338	* own; false in a build that has none or when the remote is unrecognized.
9339	*
9340	* The engine matches the build's own list of repositories with its
9341	* hardened remote parser. A plugin reads this to behave differently in a
9342	* public repository; which repositories are the build's is its to say.
9343	*/
9344	internal: boolean;
9345	/**
9346	* The repository the allowlist matched, as `owner/name`; null when
9347	* `internal` is false.
9348	*
9349	* A working copy without a remote that the engine still recognises is
9350	* named by its own checkout configuration; a remote's name is its path.
9351	*/
9352	name: string \| null;
9353	};
9354
9355	/**
9356	* How to come back to the session that ended: what `claude --resume` takes.
9357	*/
9358	export type SessionResume = {
9359	/**
9360	* What `claude --resume <id>` takes, the ending session's own.
9361	*
9362	* It resumes a session that wrote a transcript: one that never ran a
9363	* prompt, or ran with persistence off, left nothing under this id.
9364	*/
9365	id: string;
9366	};
9367
9368	type SessionStartHookInput = BaseHookInput & {
9369	hook_event_name: 'SessionStart';
9370	source: 'startup' \| 'resume' \| 'clear' \| 'compact' \| 'fork';
9371	agent_type?: string;
9372	model?: string;
9373	session_title?: string;
9374	/**
9375	* resume/fork: seconds since the resumed transcript's last assistant response
9376	*/
9377	seconds_since_last_response?: number;
9378	/**
9379	* resume/fork: the resumed transcript's last response input + cache_read + cache_creation + output tokens (for a server-side tool loop, its last iteration's window, not the summed totals)
9380	*/
9381	context_tokens?: number;
9382	/**
9383	* resume/fork: seconds_since_last_response exceeds the prompt-cache TTL, so the first request re-caches context_tokens
9384	*/
9385	prompt_cache_likely_expired?: boolean;
9386	/**
9387	* resume/fork: estimated cost of re-caching context_tokens on the session model - the managed modelPricing when set, otherwise list price; excludes the response
9388	*/
9389	estimated_cache_write_usd?: number;
9390	};
9391
9392	/**
9393	* The input of `session.start`: the session the process starts with, read the
9394	* way `$.session` reads it at that moment.
9395	*/
9396	export type SessionStartInput = {
9397	/**
9398	* The directory the session runs in, absolute (`$.session.cwd()`).
9399	*/
9400	cwd: string;
9401	/**
9402	* Where the session draws at start (`$.session.surfaces()[0]`): `terminal`
9403	* under the REPL; null for a `-p` run or the SDK, which draw nowhere yet.
9404	*/
9405	surface: RenderSurface \| null;
9406	/**
9407	* Whether a person is at the prompt: true under the REPL, false for a `-p`
9408	* run or the SDK.
9409	*/
9410	isInteractive: boolean;
9411	};
9412
9413	/**
9414	* What a `session.start` hook returns and what `next(e)` resolves to:
9415	* `{ cwd }`, echoed by core; a hook's own value does not change the session.
9416	*/
9417	export type SessionStartResult = {
9418	cwd: string;
9419	};
9420
9421	/**
9422	* What `$.session.usage()` answers: the context window's fill, the account's
9423	* rate-limit windows and the session's cost, as the status line has them.
9424	*
9425	* A figure the engine does not have is left out, never zeroed: `rateLimits`
9426	* is empty off a subscription, `cost` absent where the host keeps no ledger.
9427	*/
9428	export type SessionUsage = {
9429	/**
9430	* The live context window: the status line's `context_window` figures.
9431	*/
9432	context: SessionContextUsage;
9433	/**
9434	* The rate-limit windows the last API response reported (`five_hour`,
9435	* `seven_day`, a gateway's `spend_limit`); empty when none has a reading.
9436	*/
9437	rateLimits: SessionRateLimit[];
9438	/**
9439	* What the session has cost so far, as /cost totals it; absent only where
9440	* the host keeps no cost ledger (the CLI always has one).
9441	*/
9442	cost?: SessionCost;
9443	};
9444
9445	/**
9446	* What `$.session.usage(args)` takes: nothing for the status line's figures
9447	* alone; `breakdown` to have the window broken down as /context breaks it.
9448	*/
9449	export type SessionUsageArgs = {
9450	/**
9451	* Asks for `context.breakdown` and says how it is counted
9452	* (ContextBreakdownDetail); absent, none is computed and the call is free.
9453	*
9454	* `full` sends one token-count request per tool and memory file, as
9455	* /context does; `summary` estimates locally and sends none.
9456	*/
9457	breakdown?: ContextBreakdownDetail;
9458	/**
9459	* The width the breakdown's grid will be drawn in, in terminal columns;
9460	* absent, the full-width grid. Read only with `breakdown`.
9461	*
9462	* Under 80 the grid is the narrow one /context draws there, 5 wide. A thin
9463	* client's breakdown is the remote workspace's, whose grid ignores this.
9464	*/
9465	columns?: number;
9466	};
9467
9468	/**
9469	* What `$.session.version()` answers: the version of the engine the session
9470	* runs on, the release that version is built from, and when it was built.
9471	*
9472	* The three are what the engine's own analytics rows carry as `version`,
9473	* `version_base` and `build_time`, so a row a plugin sends and a row the
9474	* engine sends from the same binary agree.
9475	*/
9476	export type SessionVersion = {
9477	/**
9478	* The engine's full version, as `claude --version` prints it: a release's
9479	* (`2.1.280`) or a development build's, which adds the build's date, time
9480	* and commit (`2.1.280-dev.20260920.t101500.sha1a2b3c4`).
9481	*/
9482	version: string;
9483	/**
9484	* The release the version is built from, its semantic core and channel:
9485	* `2.1.280` for that release, `2.1.280-dev` for a development build of it.
9486	* Absent when the version is not spelled as a release.
9487	*/
9488	base?: string;
9489	/**
9490	* When the binary was built, an ISO 8601 timestamp
9491	* (`2026-09-20T10:15:00Z`). Absent in a run from source that stamps none.
9492	*/
9493	builtAt?: string;
9494	};
9495
9496	/**
9497	* What `$.settings.read` answers: an object keyed as a settings.json is
9498	* (`permissions`, `env`, `hooks`, `model`, `enabledPlugins`, ...).
9499	*
9500	* Each key is as https://code.claude.com/docs/en/settings documents it and
9501	* https://json.schemastore.org/claude-code-settings.json types it. A
9502	* snapshot in plain data: a write to it changes nothing the engine reads.
9503	*/
9504	export type Settings = Readonly<Record<string, unknown>>;
9505
9506	/**
9507	* What `$.settings.read(args)` takes.
9508	*/
9509	export type SettingsReadArgs = {
9510	/**
9511	* The one source read, as loaded; absent, the settings merged over every
9512	* source, as the engine runs under them.
9513	*/
9514	source?: SettingsSource;
9515	};
9516
9517	/**
9518	* One source of settings by the name a plugin gives it, lowest precedence
9519	* first; the engine's own name is the same word with `Settings` appended.
9520	*
9521	* `user` is ~/.claude/settings.json, `project` .claude/settings.json,
9522	* `local` .claude/settings.local.json, `flag` what `--settings` and the
9523	* SDK's inline settings carry, and `policy` the managed settings, every
9524	* managed tier merged.
9525	*/
9526	export type SettingsSource = 'user' \| 'project' \| 'local' \| 'flag' \| 'policy';
9527
9528	type SetupHookInput = BaseHookInput & {
9529	hook_event_name: 'Setup';
9530	trigger: 'init' \| 'maintenance';
9531	};
9532
9533	/**
9534	* Where a site's window sits over the tree a hook drew in it (a pane's body,
9535	* the band): the engine's to move (the person scrolls), the plugin's to read.
9536	*/
9537	export type SiteScroll = {
9538	/**
9539	* The first row of the tree the window shows; 0 at the top. Read-only.
9540	*/
9541	offset: number;
9542	/**
9543	* How many rows of the tree the window shows at once: the rows the
9544	* surface gave the body. Read-only.
9545	*/
9546	bodyRows: number;
9547	};
9548
9549	/**
9550	* Which transcript the person has on screen where a site draws: the main
9551	* conversation's, or one agent's, opened from the tasks list.
9552	*
9553	* The person's to switch, the plugin's to read: a switch re-runs the site's
9554	* hooks with the new view, the site itself staying where it is.
9555	*/
9556	export type SiteView = {
9557	/**
9558	* The agent whose transcript is in view: the `id` `$.agent.list()` gives
9559	* it, the `agentId` its `turn.step` and `tool.call` events carry.
9560	*
9561	* Absent while the main conversation is in view. Read-only.
9562	*/
9563	agentId?: string;
9564	};
9565
9566	/**
9567	* The input of `skill.prompt`: one skill's prompt, at the moment the engine
9568	* expanded it for the model.
9569	*
9570	* Typed as `/name`, called through the Skill tool, or preloaded into a
9571	* subagent: the same event at each.
9572	*/
9573	export type SkillPromptInput = {
9574	/**
9575	* Which skill (`commit`); the key a matcher narrows on.
9576	*/
9577	skill: string;
9578	/**
9579	* The prompt's text as the skill computed it (its text blocks, joined).
9580	*/
9581	text: string;
9582	};
9583
9584	/**
9585	* What a `skill.prompt` hook returns: the text the model reads for that
9586	* skill.
9587	*/
9588	export type SkillPromptResult = {
9589	text: string;
9590	};
9591
9592	/**
9593	* Options of `$.clock.sleep`.
9594	*/
9595	export type SleepOptions = {
9596	/**
9597	* Aborting it rejects the sleep at once.
9598	*/
9599	signal?: AbortSignal;
9600	};
9601
9602	/**
9603	* Options of `$.audio.speak`.
9604	*/
9605	export type SpeakOptions = {
9606	/**
9607	* The system voice's exact name as the platform lists it (`Samantha`, or the
9608	* name of a voice you installed). Absent: the synthesizer's default voice.
9609	*/
9610	voice?: string;
9611	};
9612
9613	/**
9614	* The argument of `$.audio.speak(text, options)` as the event carries it.
9615	*/
9616	type SpeakRequest = SpeakOptions & {
9617	/**
9618	* What to say, as plain text, of at most 4096 characters.
9619	*/
9620	text: string;
9621	};
9622
9623	/**
9624	* What `$.audio.speak` resolves with once the utterance has ended.
9625	*/
9626	export type SpeakResult = {
9627	/**
9628	* Which synthesizer spoke: `system`, the platform's own (`say` on macOS).
9629	*/
9630	via: 'system';
9631	};
9632
9633	/**
9634	* `next` in a `*` hook: the set of events is open at runtime, so `e` is
9635	* `unknown` until `next.is(pattern, e)` narrows it to events it knows.
9636	*
9637	* The callable is an overload per known event (OrderedOverloads), then
9638	* `(e: unknown) => Promise<unknown>` last: `next(e)` with `e` still unknown
9639	* resolves to `unknown`.
9640	*/
9641	export type StarNext = OrderedOverloads<EventName> & {
9642	(e: unknown): Promise<unknown>;
9643	/**
9644	* Continues this dispatch at a tier, as Next's `to` (a managed hook's):
9645	* `e` still unknown resolves to `unknown`.
9646	*/
9647	readonly to: (e: unknown, tier: TargetTier) => Promise<unknown>;
9648	readonly signal: AbortSignal;
9649	readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Frozen<Args<Selected<M>>>;
9650	readonly event: EventName;
9651	readonly origin: Origin;
9652	readonly trace: readonly TraceEntry<EventName, unknown, unknown>[];
9653	readonly budget: NextBudget;
9654	};
9655
9656	type StopFailureHookInput = BaseHookInput & {
9657	hook_event_name: 'StopFailure';
9658	error: SDKAssistantMessageError;
9659	error_details?: string;
9660	last_assistant_message?: string;
9661	};
9662
9663	type StopHookInput = BaseHookInput & {
9664	hook_event_name: 'Stop';
9665	stop_hook_active: boolean;
9666	/**
9667	* Text content of the last assistant message before stopping. Avoids the need to read and parse the transcript file.
9668	*/
9669	last_assistant_message?: string;
9670	/**
9671	* In-flight background work (running/pending + backgrounded) registered in this session. Lets hooks distinguish "session is done" from "session is paused waiting for background work to wake it". Empty array when nothing is in flight.
9672	*/
9673	background_tasks?: BackgroundTaskSummary[];
9674	/**
9675	* Session-scoped cron tasks (CronCreate, ScheduleWakeup, /loop) that will wake this session later. Empty array when none are scheduled.
9676	*/
9677	session_crons?: SessionCronSummary[];
9678	};
9679
9680	/**
9681	* The hook a streaming event takes: `async function* ($, e, next) {}`,
9682	* yielding the event's chunks and returning its result.
9683	*
9684	* `return yield* next(e)` passes; `for await (const c of next(e)) yield
9685	* f(c)` transforms; yielding without `next` answers alone. A chunk yielded
9686	* stays: a hook that fails mid-stream is left, the rest from beneath it.
9687	*
9688	* @example on('turn.step', async function* ($, e, next) {
9689	* const r = yield* next(e); return { ...r } })
9690	*/
9691	export type StreamHook<N extends StreamingEventName> = ($: EngineInterface, e: Frozen<Args<N>>, next: StreamNext<N>) => StreamHookBody<Chunk<N>, EventResult<N>>;
9692
9693	/**
9694	* What a hook on a streaming event evaluates to: the async generator an
9695	* `async function*` makes, yielding `C` and returning `R` or nothing.
9696	*
9697	* Returning nothing lets its last `next(e)`'s result stand. A plain
9698	* function is a type error here even when it returns `next(e)`: the hook
9699	* is the generator, not a function that hands one back.
9700	*/
9701	export type StreamHookBody<C, R> = AsyncGenerator<C, R \| void> & {
9702	/**
9703	* Absent on a generator; present on `next(e)`, which is not a hook body.
9704	*/
9705	readonly result?: never;
9706	};
9707
9708	/**
9709	* The events that stream: their hooks are async generators, `next(e)` is
9710	* the stream of everything beneath, and the result is what it returns.
9711	*
9712	* `turn.step` alone: the model's response arrives in pieces, and a hook
9713	* that saw it whole could not change what had already been shown.
9714	*/
9715	export type StreamingEventName = 'turn.step';
9716
9717	/**
9718	* The rest of the chain as a hook on a streaming event receives it: Next,
9719	* except that `next(e)` is the stream beneath (HookStream), not a promise.
9720	*
9721	* Each call opens a fresh stream; for `turn.step` each is a model request,
9722	* so a hook that calls it twice makes two. Not calling it yields the hook's
9723	* own chunks and returns its own result, and nothing beneath runs.
9724	*
9725	* @template S what `next.is(pattern, e)` narrows `e` to, as Next's
9726	* @see HookBudget `ms`: the hook's budget counts its own code, never a wait
9727	* at a `yield` or on this stream, however long the response beneath takes
9728	*/
9729	export type StreamNext<N extends StreamingEventName = StreamingEventName, E = Args<N>, O = NextResult<N>, S extends {
9730	[K in N]?: unknown;
9731	} = {
9732	[K in N]: Args<K>;
9733	}> = Pick<Next<N, E, O, S>, 'signal' \| 'is' \| 'event' \| 'origin' \| 'budget'> & {
9734	(e: E): HookStream<Chunk<N>, O>;
9735	/**
9736	* Continues this dispatch at a tier, as Next's `to`: the stream beneath
9737	* with the links between this hook's tier and that one skipped.
9738	*/
9739	readonly to: (e: E, tier: TargetTier) => HookStream<Chunk<N>, O>;
9740	/**
9741	* What settled beneath on the latest `next()` stream, as Next's; a
9742	* streaming link's entry counts the chunks it yielded up (`chunks`).
9743	*/
9744	readonly trace: readonly TraceEntry<N, E, O>[];
9745	};
9746
9747	/**
9748	* The shape a `Box` and a `Text` share in a render tree: allowlisted props,
9749	* an optional `hover`, the group stamp a `hover.scope` earns, and children.
9750	*
9751	* `Tag` is which of the two; `Hover` is that element's hover props. Every
9752	* surface draws both: Ink's Box and Text on the terminal, a flex div and a
9753	* styled span on the desktop.
9754	*/
9755	type StyledElement<Tag extends 'Box' \| 'Text', Hover> = {
9756	type: Tag;
9757	/**
9758	* A Box's layout, position, spacing and border props and the `key` that
9759	* makes it a hover scope; a Text's colors and styles. Others are refused.
9760	*/
9761	props?: Record<string, string \| number \| boolean>;
9762	/**
9763	* Style overrides the surface applies while the pointer is over the
9764	* nearest keyed Box, or over any member of the group `scope` names.
9765	*
9766	* Plain data, no hook. Nothing that moves a sibling: `borderStyle`
9767	* restyles a border the Box has, `display` only reveals a Box drawn
9768	* `"none"` (under a keyed Box or in a scope), an offset moves a placed Box.
9769	*/
9770	hover?: Hover;
9771	/**
9772	* Whose group `hover.scope` names; absent without a `scope`.
9773	*/
9774	group?: PluginStamp;
9775	/**
9776	* In order: a Box holds elements and strings (core wraps each string in
9777	* a Text); a Text holds strings and inline elements, never an engine node.
9778	*/
9779	children?: RenderNode[];
9780	};
9781
9782	type SubagentStartHookInput = BaseHookInput & {
9783	hook_event_name: 'SubagentStart';
9784	agent_id: string;
9785	agent_type: string;
9786	};
9787
9788	type SubagentStopHookInput = BaseHookInput & {
9789	hook_event_name: 'SubagentStop';
9790	stop_hook_active: boolean;
9791	agent_id: string;
9792	agent_transcript_path: string;
9793	agent_type: string;
9794	/**
9795	* Text content of the last assistant message before stopping. Avoids the need to read and parse the transcript file.
9796	*/
9797	last_assistant_message?: string;
9798	/**
9799	* In-flight background work (running/pending + backgrounded) registered in this session. Lets hooks distinguish "session is done" from "session is paused waiting for background work to wake it". Empty array when nothing is in flight.
9800	*/
9801	background_tasks?: BackgroundTaskSummary[];
9802	/**
9803	* Session-scoped cron tasks (CronCreate, ScheduleWakeup, /loop) that will wake this session later. Empty array when none are scheduled.
9804	*/
9805	session_crons?: SessionCronSummary[];
9806	};
9807
9808	/**
9809	* The props of `Svg`, the remote surfaces' vector leaf: the markup is the
9810	* element's data, as a string is a Text's, drawn isolated.
9811	*
9812	* A leaf: no children. The surface never lets the markup reach the page
9813	* (the engine bounds it; the desktop and the editor draw it as an image, or
9814	* in a sandboxed frame when `isInteractive`; the mobile app in a web view).
9815	*/
9816	export type SvgProps = {
9817	/**
9818	* The SVG document, `<svg ...>...</svg>`, at most 131072 characters.
9819	*/
9820	source: string;
9821	/**
9822	* What the drawing says, for a reader that cannot see it; required, since
9823	* a surface without the element draws nothing else of it.
9824	*/
9825	alt: string;
9826	/**
9827	* CSS pixels; absent, the box takes the markup's own width up to the slot.
9828	*/
9829	width?: number;
9830	/**
9831	* CSS pixels; absent, the markup's own height at the drawn width.
9832	*/
9833	height?: number;
9834	/**
9835	* `true` draws the SVG in a script-less sandboxed frame so hover, CSS
9836	* `:hover`, SMIL animation and `<title>` tooltips work; absent, an image.
9837	*
9838	* It never enables script or event-handler attributes (the frame has no
9839	* allow-scripts and the scrub strips them); presses that other plugins
9840	* should observe go on an enclosing element.
9841	*/
9842	isInteractive?: boolean;
9843	};
9844
9845	/**
9846	* The keys of `I` a matcher may select variants by: literal-valued in every
9847	* variant, and one literal per variant (IsDiscriminant).
9848	*/
9849	type TagKeys<I> = {
9850	[K in MatcherKeys<I>]: IsLiteralValued<MatcherValueOf<I, K>> extends true ? IsDiscriminant<I, K> extends true ? K : never : never;
9851	}[MatcherKeys<I>];
9852
9853	/**
9854	* A tier `next.to(e, tier)` may name: one a floor can reach past a tier of
9855	* less authority to, so never `prepend` or `user`, which nothing skips to.
9856	*/
9857	export type TargetTier = Exclude<Tier, 'prepend' \| 'user'>;
9858
9859	type TaskCompletedHookInput = BaseHookInput & {
9860	hook_event_name: 'TaskCompleted';
9861	task_id: string;
9862	task_subject: string;
9863	task_description?: string;
9864	teammate_name?: string;
9865	/**
9866	* @deprecated Sessions have a single implicit team; this carries the session-derived team name and will be removed in a future release.
9867	*/
9868	team_name?: string;
9869	};
9870
9871	type TaskCreatedHookInput = BaseHookInput & {
9872	hook_event_name: 'TaskCreated';
9873	task_id: string;
9874	task_subject: string;
9875	task_description?: string;
9876	teammate_name?: string;
9877	/**
9878	* @deprecated Sessions have a single implicit team; this carries the session-derived team name and will be removed in a future release.
9879	*/
9880	team_name?: string;
9881	};
9882
9883	type TeammateIdleHookInput = BaseHookInput & {
9884	hook_event_name: 'TeammateIdle';
9885	teammate_name: string;
9886	/**
9887	* @deprecated Sessions have a single implicit team; this carries the session-derived team name and will be removed in a future release.
9888	*/
9889	team_name: string;
9890	};
9891
9892	/**
9893	* The `Text` props a `hover` may override (its colors and styles, not its
9894	* wrapping) and `scope`, the hover group it joins; a `Button`'s label too.
9895	*/
9896	export type TextHoverProps = {
9897	/**
9898	* Names a hover group of this plugin's: every element it draws with the
9899	* same `scope`, in any site on the surface, lights while any is hovered.
9900	*
9901	* Another plugin's elements under the same string are a different group.
9902	* One to 64 characters, no control characters; no keyed Box needed. On the
9903	* terminal a Text nested in a Text follows its group but cannot heat it.
9904	*/
9905	scope?: string;
9906	color?: string;
9907	backgroundColor?: string;
9908	dimColor?: boolean;
9909	bold?: boolean;
9910	italic?: boolean;
9911	underline?: boolean;
9912	strikethrough?: boolean;
9913	inverse?: boolean;
9914	};
9915
9916	/**
9917	* The props of `Text`: the color and style props of Ink's Text a tree may
9918	* set. Colors are a theme key or a raw color.
9919	*/
9920	export type TextProps = {
9921	/**
9922	* Style overrides applied by the surface while the pointer is over the
9923	* nearest enclosing keyed `Box`, or, given a `scope`, over its group.
9924	*
9925	* No hook runs and nothing crosses to the plugin. Refused outside a keyed
9926	* Box unless it names a `scope`.
9927	*/
9928	hover?: TextHoverProps;
9929	color?: string;
9930	backgroundColor?: string;
9931	dimColor?: boolean;
9932	bold?: boolean;
9933	italic?: boolean;
9934	underline?: boolean;
9935	strikethrough?: boolean;
9936	inverse?: boolean;
9937	wrap?: 'wrap' \| 'end' \| 'middle' \| 'truncate' \| 'truncate-start' \| 'truncate-middle' \| 'truncate-end';
9938	};
9939
9940	/**
9941	* One of the chain's five tiers (TIERS), outermost first; on every
9942	* `next.trace` entry, and what `next.to(e, tier)` names.
9943	*
9944	* `prepend` and `append` are the managed plugins an administrator lists,
9945	* `user` everything a person installs, `builtin` the plugins bundled in the
9946	* binary, `core` the engine's innermost link.
9947	*/
9948	export type Tier = (typeof TIERS)[number];
9949
9950	/**
9951	* The chain's five tiers, outermost first: earlier is outer is more
9952	* authority, and same-event hooks nest in this order and no other way.
9953	*
9954	* The managed plugins an administrator prepends, everything a person
9955	* installs, the managed plugins appended, the plugins bundled in the binary,
9956	* the engine's innermost link; a built-in's `$` calls still raise everywhere.
9957	*/
9958	const TIERS: readonly ["prepend", "user", "append", "builtin", "core"];
9959
9960	/**
9961	* A pending timer from `$.clock.after` / `$.clock.every`.
9962	*/
9963	export type Timer = {
9964	/**
9965	* Stops it; a stopped timer never fires again.
9966	*/
9967	cancel: () => void;
9968	};
9969
9970	/**
9971	* A timer on `$.clock` (`after`, `every`): `fn` runs after `ms` milliseconds,
9972	* once or until `cancel()`.
9973	*/
9974	export type TimerCall = (ms: number, fn: () => void) => Timer;
9975
9976	/**
9977	* Options of `$.ui.toast`.
9978	*/
9979	export type ToastOptions = {
9980	/**
9981	* How long the line stays, in milliseconds; default 4000.
9982	*/
9983	timeoutMs?: number;
9984	};
9985
9986	/**
9987	* `tool.call`'s input as the call takes it: `tool_use_id` and `agentId` may
9988	* ride along (a hook passing its event's input on) and are dropped.
9989	*
9990	* The run gets its own id and runs in the session's loop.
9991	*/
9992	export type ToolCallArgs = ToolCallEnvelope extends infer I ? I extends ToolCallEnvelope ? Omit<I, 'tool_use_id'> & ToolCallReserved<I['tool']> : never : never;
9993
9994	/**
9995	* The envelope the two tool events share: the tool, the id of this call, and
9996	* the tool's arguments spread beside them (`e.command` for Bash).
9997	*
9998	* A union discriminated by `tool`: after `if (e.tool === "Bash")`, `e.command`
9999	* is a string and a rewrite is checked against Bash's schema. The `e` of
10000	* `classic.PreToolUse` exactly; `tool.call`'s adds the loop (ToolCallInput).
10001	*/
10002	export type ToolCallEnvelope = BuiltinToolCallInput \| McpToolCallInput;
10003
10004	/**
10005	* The input of `tool.call`: the tool, the id of this call, the tool's
10006	* arguments beside them (`e.command` for Bash), and `agentId` in a subagent.
10007	*
10008	* A union discriminated by `tool`: after `if (e.tool === "Bash")`, `e.command`
10009	* is a string and a rewrite is checked against Bash's schema. `tool`,
10010	* `tool_use_id` and `agentId` are reserved: a rewrite of any is refused.
10011	*/
10012	export type ToolCallInput = ToolCallEnvelope & AgentLoop;
10013
10014	/**
10015	* `$.tool.call(input)`: resolves with `result` typed for the tool `input`
10016	* names (ToolCallResult), or loosely for an input that names none literally.
10017	*/
10018	type ToolCallOverloads = {
10019	<T extends string>(input: ToolCallArgs & ToolNamed<T>): Promise<ToolCallResult<T>>;
10020	(input: ToolCallArgs): Promise<ToolCallResult>;
10021	};
10022
10023	/**
10024	* The keys `tool.call`'s input carries beside the tool's own arguments, none
10025	* of which the tool sees (the engine strips them before the tool runs).
10026	*
10027	* `consent` is the person's own words for the press that raised the call
10028	* (`The user pressed "1: Yes" on ...`): the run's context carries it as a human
10029	* turn, which the permission path reads as the user's request.
10030	*/
10031	export type ToolCallReserved<T> = {
10032	tool: T;
10033	tool_use_id?: string;
10034	consent?: string;
10035	};
10036
10037	/**
10038	* What a `tool.call` hook returns and what `next(e)` and `$.tool.call(input)`
10039	* resolve to: the tool's result (`{ result, context? }`) or `{ deny }`.
10040	*
10041	* From core the result is `{ ref, result, text }` or, when the tool reported
10042	* an error, `{ ref, result, text, isError }`; `ref` names core's messages.
10043	*
10044	* @template Name the tool the call went to, typing `result` per built-in
10045	* tool (BuiltinToolResults) once `e.tool` is narrowed; else `unknown`
10046	*/
10047	export type ToolCallResult<Name extends string = string> = {
10048	/**
10049	* Refuses the call: the model receives the text as an error result.
10050	* Absent when the call was answered.
10051	*/
10052	deny: string;
10053	result?: undefined;
10054	context?: undefined;
10055	ref?: undefined;
10056	text?: undefined;
10057	isError?: undefined;
10058	} \| {
10059	/**
10060	* The tool's output: from core the tool's record, typed per built-in
10061	* tool once `e.tool` and `isError` are narrowed; from a hook, its own.
10062	*
10063	* Core validates a hook's answer against the tool's output schema when
10064	* it has one, maps it for the model with the tool's own mapper, and
10065	* records it in the transcript as the tool's result. Absent on a deny.
10066	*/
10067	result: ToolResultOf<Name>;
10068	/**
10069	* What the model reads after the tool's result and the user never
10070	* sees. From core, none.
10071	*
10072	* One reminder, as a PostToolUse hook's is, after the managed tier's
10073	* review; none on a plugin's own `$.tool.call`. Kept whole from `next`,
10074	* none empty, any length: past 100,000 (200,000 together) head + path.
10075	*/
10076	context?: readonly string[];
10077	/**
10078	* Set by core on what `next(e)` resolves to: names the messages core
10079	* produced for the call (they stay on the host side).
10080	*
10081	* A hook that returns the object it got makes core use them verbatim.
10082	* Absent on a hook's own `{ result }` and on a deny.
10083	*/
10084	ref?: number;
10085	/**
10086	* Set by core: the result as the model reads it (text blocks joined),
10087	* present whatever the tool, where `result`'s shape varies per tool.
10088	*
10089	* Absent on a hook's own `{ result }`.
10090	*/
10091	text?: string;
10092	isError?: undefined;
10093	deny?: undefined;
10094	} \| {
10095	/**
10096	* Set by core, present only when the tool reported an error (it threw,
10097	* was interrupted, or answered an error): `text` is what the model read.
10098	*/
10099	isError: true;
10100	/**
10101	* What the transcript stored for the errored call: the error text, or
10102	* undefined when nothing was stored; never the tool's typed record.
10103	*/
10104	result: unknown;
10105	/**
10106	* The error as the model reads it.
10107	*/
10108	text?: string;
10109	/**
10110	* As on an answered result: names the messages core produced.
10111	*/
10112	ref?: number;
10113	/**
10114	* As on an answered result.
10115	*/
10116	context?: readonly string[];
10117	deny?: undefined;
10118	};
10119
10120	/**
10121	* `tool.check`'s input as `$.tool.check` takes it: the tool and its
10122	* arguments; `tool_use_id` is the engine's to set, never a query's.
10123	*/
10124	type ToolCheckArgs = Pick<ToolCheckInput, 'tool' \| 'input'>;
10125
10126	/**
10127	* Who an ask is put to, where that is not a dialog here: `host`, the program
10128	* that answers a hosted session's asks, or a served call's own session.
10129	*/
10130	type ToolCheckDecider = 'host';
10131
10132	/**
10133	* The verdict of `tool.check`: run the tool, put it to the mode's decider
10134	* (the dialog, the auto-mode classifier, a headless host), or refuse it.
10135	*/
10136	type ToolCheckDecision = 'allow' \| 'ask' \| 'deny';
10137
10138	/**
10139	* The input of `tool.check`: the tool, its arguments, and the call's id when
10140	* the engine is deciding a real call.
10141	*
10142	* All three are the question's identity and are pinned: a hook decides
10143	* about this call, it does not change it (`tool.call` rewrites a call).
10144	*/
10145	type ToolCheckInput = {
10146	/**
10147	* As the model names it (`Bash`, `mcp__server__tool`); the key a matcher
10148	* narrows on.
10149	*/
10150	tool: string;
10151	/**
10152	* The tool's arguments as the permission decision reads them
10153	* (`{ command }` for Bash, `{ file_path, ... }` for the file tools).
10154	*/
10155	input: unknown;
10156	/**
10157	* The call being decided, on a real call only; absent on a query.
10158	*
10159	* `next.origin` names who raised it: `{ plugin: 'engine', tier: 'core' }`
10160	* for the model's own call, the plugin for its `$.tool.call` or its query.
10161	*/
10162	tool_use_id?: string;
10163	};
10164
10165	/**
10166	* What a `tool.check` hook returns and what `next(e)` resolves to: the
10167	* verdict, why, what stands behind it, and who answers core's ask.
10168	*
10169	* From core, the engine's declarative decision for the session's mode and
10170	* rules. A hook may answer any verdict in either direction; the last word up
10171	* the chain is the decision.
10172	*/
10173	type ToolCheckResult = {
10174	/**
10175	* `allow` runs the tool; `ask` puts it to the mode's decider; `deny`
10176	* refuses it, the reason the model's error.
10177	*/
10178	decision: ToolCheckDecision;
10179	/**
10180	* Why, in a sentence: from core the rule or check that decided; from a
10181	* hook, what the model reads on a deny and the dialog shows on an ask.
10182	*/
10183	reason?: string;
10184	/**
10185	* The settings rule that decided, as written (`Bash(git push:*)`).
10186	*
10187	* Absent for a mode or a tool's own check.
10188	*/
10189	rule?: string;
10190	/**
10191	* The classic hook event that decided, or whose ask the verdict was reached
10192	* under (`PreToolUse`), whoever configured the hook.
10193	*
10194	* Absent on a `$.tool.check` query, which runs no classic hook.
10195	*/
10196	hook?: string;
10197	/**
10198	* The key of the option whose own check asked, whoever configured it
10199	* (`permissions.blockReadsOutsideWorkingDirectories`).
10200	*
10201	* From core, for the read block: its ask on a shell command that reads
10202	* outside the working directories or, the block on, leaves the sandbox.
10203	*/
10204	setting?: string;
10205	/**
10206	* Who an ask is put to, where that is not a dialog here: `host`, a hosted
10207	* session's permission callback or the cloud session a served call is for.
10208	*
10209	* From core, on its own ask, only where a host would be asked: an ask the
10210	* mode or the loop refuses with nobody asked (dontAsk, no prompt to show)
10211	* names none, and neither does a host whose card the person answers.
10212	*/
10213	decider?: ToolCheckDecider;
10214	/**
10215	* The most permissive verdict the organization lets a call of the tool
10216	* reach (`ask`), as its administrators set it on a connector's tool.
10217	*
10218	* The question's own (`e.ceiling`), set by the engine, from the tool, on
10219	* every verdict for it, core's and each hook's alike: a hook's own
10220	* `ceiling` is dropped. Absent where none is set.
10221	*/
10222	ceiling?: ToolCheckDecision;
10223	};
10224
10225	/**
10226	* Where a `tool.describe` answer places the tool: `true` behind ToolSearch
10227	* (its schema loads when the model asks for it), `false` in the prompt's list.
10228	*
10229	* Left out of an answer, the placement beneath stands.
10230	*/
10231	export type ToolDeferral = boolean;
10232
10233	/**
10234	* The input of `tool.describe`: one tool's description, at the moment the
10235	* engine first renders the tool's schema for the model.
10236	*/
10237	export type ToolDescribeInput = {
10238	/**
10239	* As the model sees the name (`Bash`, `mcp__server__tool`); the key a
10240	* matcher narrows on.
10241	*/
10242	tool: string;
10243	/**
10244	* The tool's description as it computed it.
10245	*/
10246	description: string;
10247	/**
10248	* Present, and true, when the engine lists the tool behind ToolSearch (its
10249	* schema loads when the model asks for it by name); absent for one listed.
10250	*
10251	* By the engine's rule an MCP server's tool, or one that asks to be,
10252	* unless a rule keeps it in front.
10253	*/
10254	isDeferred?: true;
10255	/**
10256	* Who provides this tool: the plugin and its tier; `{ plugin: "engine",
10257	* tier: "core" }` for a built-in. Pinned: a rewrite is refused.
10258	*
10259	* A configured MCP server's tool is `mcp:<server>`, in `prepend` when the
10260	* policy settings source configures the server, else `user`.
10261	*/
10262	provider: Origin;
10263	};
10264
10265	/**
10266	* What a `tool.describe` hook returns: the description the model sees for that
10267	* tool and, when the hook moves it, where the tool waits (ToolDeferral).
10268	*
10269	* `{ description }` alone, or `{ ...(await next(e)), description }`, changes
10270	* the text and keeps the engine's placement; `isDeferred: true` puts the tool
10271	* behind ToolSearch, `isDeferred: false` puts its schema in the prompt's list.
10272	*/
10273	export type ToolDescribeResult = {
10274	description: string;
10275	isDeferred?: ToolDeferral;
10276	};
10277
10278	/**
10279	* `{ tool, tool_use_id, ...args }` as one flat object type, generic over
10280	* the tool name and its parsed arguments.
10281	*/
10282	type ToolEnvelope<Name, Arguments> = {
10283	/**
10284	* The name of the tool being called (`Bash`, `mcp__<server>__<tool>`);
10285	* comparing it narrows `e`. Reserved: a rewrite of it is ignored by core.
10286	*/
10287	tool: Name;
10288	/**
10289	* The tool_use block's id: the same at every event of the call and in
10290	* `$.ui.notice`. Reserved: a rewrite of it is ignored by core.
10291	*/
10292	tool_use_id: string;
10293	} & Arguments;
10294
10295	/**
10296	* One tool call of a ToolGroup, as `ui.render` sees it under `calls`.
10297	*/
10298	export type ToolGroupCall = {
10299	/**
10300	* The id `tool.call` carried for this call (`e.tool_use_id` there), so a
10301	* hook that saw the call finds its row in the group. Read-only.
10302	*
10303	* Absent on a desktop host that predates it.
10304	*/
10305	tool_use_id?: string;
10306	/**
10307	* Which one the call ran (`Bash`, `Read`, `Grep`, ...).
10308	*/
10309	tool: string;
10310	/**
10311	* The call's input, as the model sent it.
10312	*/
10313	input: unknown;
10314	/**
10315	* True while the call is still running.
10316	*/
10317	isRunning: boolean;
10318	/**
10319	* True when the call ended in an error.
10320	*/
10321	isErrored: boolean;
10322	/**
10323	* True when an abort ended the call, as on `ToolUse`.
10324	*/
10325	isInterrupted: boolean;
10326	/**
10327	* As on `ToolUse`; undefined while the call runs.
10328	*/
10329	output?: unknown;
10330	};
10331
10332	/**
10333	* One tool as `$.tool.list()` returns it.
10334	*/
10335	export type ToolInfo = {
10336	/**
10337	* What the model calls it by.
10338	*/
10339	name: string;
10340	/**
10341	* What it does, in the tool's own words (its description; a first sentence at
10342	* most for MCP tools without one).
10343	*/
10344	description: string;
10345	/**
10346	* True for an MCP server's tool.
10347	*/
10348	mcp: boolean;
10349	};
10350
10351	/**
10352	* `{ tool, tool_use_id, ...args }` as one flat object type.
10353	*
10354	* The docs of `tool` and `tool_use_id` live on the `keyof` operand: a mapped
10355	* type takes its properties' docs from there.
10356	*/
10357	export type ToolInputOf<Name extends string, Arguments> = {
10358	[K in keyof ToolEnvelope<Name, Arguments>]: ToolEnvelope<Name, Arguments>[K];
10359	};
10360
10361	/**
10362	* An input that names its tool as the literal `T`: what `next` and
10363	* `$.tool.call` read to type the call's result per tool (NextResultFor).
10364	*/
10365	type ToolNamed<T extends string> = {
10366	/**
10367	* The name of the tool being called (`Bash`).
10368	*/
10369	readonly tool: T;
10370	};
10371
10372	/**
10373	* The structured result of the tool named `Name`: its BuiltinToolResults
10374	* entry for a built-in tool, else `unknown`.
10375	*
10376	* Agent's is its entry or an AgentCallRecord (what a plugin-raised call
10377	* answers). `unknown` covers an MCP tool, a name the results table lacks
10378	* (one merged into the inputs table alone too), and `Name` left at `string`.
10379	*/
10380	export type ToolResultOf<Name extends string> = string extends Name ? unknown : Name extends keyof BuiltinToolResults & string ? BuiltinToolResults[Name] \| (Name extends 'Agent' ? AgentCallRecord : never) : unknown;
10381
10382	/**
10383	* One tool_result block of a user message.
10384	*/
10385	export type ToolResultSummary = {
10386	/**
10387	* The id of the call this result answers (`tool.call`'s `e.tool_use_id`).
10388	*/
10389	tool_use_id: string;
10390	/**
10391	* The result as the model read it (text blocks joined).
10392	*/
10393	text: string;
10394	/**
10395	* True when the tool reported an error.
10396	*/
10397	isError: boolean;
10398	/**
10399	* What the transcript stored for the call: the tool's record on an answered
10400	* one (`tool.call`'s `result`), the error text when `isError`.
10401	*
10402	* Absent when nothing was stored. Headless (`-p`), a tool may store the
10403	* record less its bulk (Bash blanks `stdout`); `text` is what the model
10404	* read either way.
10405	*/
10406	result?: unknown;
10407	};
10408
10409	/**
10410	* What `$.tool.register` takes.
10411	*/
10412	export type ToolSpec = {
10413	/**
10414	* The tool's short name (letters, digits, `_`, `-`; up to 64); the model
10415	* calls it as `mcp__<plugin>__<name>`.
10416	*/
10417	name: string;
10418	/**
10419	* What the tool does, for the model (and the person where tools are
10420	* listed); an unpaired surrogate half in it is drawn as U+FFFD.
10421	*/
10422	description: string;
10423	/**
10424	* A JSON schema object for the input (`{ type: "object", properties,
10425	* required }`); default `{ type: "object" }`.
10426	*/
10427	inputSchema?: Record<string, unknown>;
10428	};
10429
10430	/**
10431	* One tool_use block of an assistant message, with its outcome once the
10432	* transcript holds the call's tool_result (paired by `tool_use_id`).
10433	*/
10434	export type ToolUseSummary = {
10435	/**
10436	* The call's id, as `tool.call` carried it (`e.tool_use_id` there).
10437	*/
10438	tool_use_id: string;
10439	/**
10440	* Which one was called (`Read`, `Bash`, `mcp__server__tool`), as
10441	* `tool.call` named it (`e.tool` there).
10442	*/
10443	tool: string;
10444	/**
10445	* The arguments the model gave it.
10446	*/
10447	input: Record<string, unknown>;
10448	/**
10449	* What the transcript stored for the call: the tool's record on an answered
10450	* one (`tool.call`'s `result`), the error text on a refused or errored one.
10451	*
10452	* Absent while the call is in flight or when nothing was stored. Headless
10453	* (`-p`), a tool may store the record less its bulk (Bash blanks `stdout`);
10454	* `text` holds either way.
10455	*/
10456	result?: unknown;
10457	/**
10458	* The result as the model read it; absent while the call is in flight.
10459	*/
10460	text?: string;
10461	/**
10462	* Present only when the tool reported an error, as on `tool.call`'s result.
10463	*/
10464	isError?: true;
10465	};
10466
10467	/**
10468	* One settled run of a link beneath the caller, as `next.trace` lists it:
10469	* data, not a handle.
10470	*
10471	* `received` and `returned` are the live references where the hook runs
10472	* beside the chain; in a hooks module its own copies, as `e` is.
10473	*/
10474	export type TraceEntry<N extends EventName = EventName, E = Args<N>, O = NextResult<N>> = {
10475	/**
10476	* The link's place in the chain, 0 the outermost.
10477	*/
10478	readonly index: number;
10479	/**
10480	* The hook's plugin; `"engine"` for the engine's own core or bottom.
10481	*/
10482	readonly plugin: string;
10483	/**
10484	* The link's tier (Tier); `"core"` for the engine's own core or bottom.
10485	*/
10486	readonly tier: Tier;
10487	readonly event: N;
10488	readonly outcome: TraceOutcome;
10489	/**
10490	* Why the link was skipped without running, when it was: `bypassed by
10491	* <plugin>`, whose `next.to` went beneath this tier. Absent when it ran.
10492	*/
10493	readonly reason?: string;
10494	/**
10495	* Its own wall time, its `next()` calls' time in flight taken out.
10496	*
10497	* The engine entry's is everything beneath the last hook: in a hooks
10498	* module, the host round trip.
10499	*/
10500	readonly ms: number;
10501	/**
10502	* How many chunks the link yielded up, on a streaming event; absent on
10503	* every other. A link left mid-stream counts what it yielded before.
10504	*/
10505	readonly chunks?: number;
10506	readonly received: E;
10507	/**
10508	* What the link settled on; undefined when it was skipped or rejected.
10509	*/
10510	readonly returned: O \| undefined;
10511	};
10512
10513	/**
10514	* What the chain decided for one link, as `next.trace` names it.
10515	*
10516	* `returned`: its result stood; `passed`: it returned, by reference, what its
10517	* last `next()` resolved to (a hooks module's hook answers with a copy of its
10518	* own, so it reads `returned`); `skipped`: it failed before `next`, or a
10519	* `next.to` above continued beneath its tier (`reason` says which), and
10520	* beneath ran in its place; `kept`: it failed after `next`, and that run's
10521	* result stands; `expired`: its budget ran out (what stands follows
10522	* skipped/kept); `caught`: it threw or its budget ran out, and its `.catch`
10523	* handler's result stands; `rejected`: the link rejected; the deepest such
10524	* entry is where the rejection came from, and the ones above it let it pass.
10525	*/
10526	export type TraceOutcome = 'caught' \| 'expired' \| 'kept' \| 'passed' \| 'rejected' \| 'returned' \| 'skipped';
10527
10528	/**
10529	* What every `turn.complete` carries whatever its reason: the answer, the
10530	* duration, the interrupt flag, the turn's id, its loop and what it cost.
10531	*/
10532	type TurnCompleteFields = {
10533	/**
10534	* The assistant's final visible text this turn ("" if none, e.g.
10535	* thinking-only).
10536	*/
10537	answer: string;
10538	/**
10539	* Wall-clock length of the turn in milliseconds.
10540	*/
10541	durationMs: number;
10542	/**
10543	* True when the turn ended by interruption (`reason === 'aborted'`).
10544	*/
10545	isAborted: boolean;
10546	/**
10547	* The turn's id, the same one its `turn.start` and every `turn.step`
10548	* carried; a subagent's run raises no `turn.start`, its steps carry it.
10549	*/
10550	turnId: string;
10551	/**
10552	* The loop the turn ran in: a subagent's id, as `$.agent.spawn` resolves
10553	* it, each run of its loop one turn; absent on the main loop.
10554	*
10555	* Pinned: a different value is refused, one left out is kept. Every hook
10556	* sees a subagent's turn, so a hook that spawns sees its children's turns
10557	* too and bounds itself.
10558	*/
10559	agentId?: string;
10560	/**
10561	* What the turn cost: its responses' token counts summed and the model of
10562	* the last, read off the API responses the engine already holds.
10563	*
10564	* Absent when the turn got no response (interrupted before one, an API
10565	* error).
10566	*/
10567	usage?: TurnUsage;
10568	};
10569
10570	/**
10571	* The input of `turn.complete`: the assistant's final message of a turn, at
10572	* the moment the turn ends (where the turn's duration is reported).
10573	*
10574	* `reason` says why it ended; `refusal` exists on a refusal alone.
10575	*/
10576	export type TurnCompleteInput = TurnCompleteFields & (TurnCompleteRefused \| TurnCompleteUnrefused);
10577
10578	/**
10579	* Why a turn ended: the model answered, the user interrupted it, the model
10580	* refused with no fallback model to retry on, or an API error ended it.
10581	*/
10582	export type TurnCompleteReason = 'answer' \| 'aborted' \| 'refusal' \| 'error';
10583
10584	/**
10585	* The end of a turn the model refused with no fallback model to retry on:
10586	* what the API said of the refusal rides along.
10587	*/
10588	type TurnCompleteRefused = {
10589	reason: 'refusal';
10590	refusal: TurnRefusal;
10591	};
10592
10593	/**
10594	* What a `turn.complete` hook returns and what `next(e)` resolves to:
10595	* `{ text }`; a text other than a main-loop answer's is shown beneath it.
10596	*
10597	* Core fills `usage` from `e.usage` when the turn had one; a hook above reads
10598	* it, and one that answers its own may leave it out.
10599	*/
10600	export type TurnCompleteResult = {
10601	text: string;
10602	usage?: TurnUsage;
10603	};
10604
10605	/**
10606	* The end of a turn that was not a refusal: answered, interrupted, or dead
10607	* on an API error (retries exhausted, the context limit), nothing more.
10608	*/
10609	type TurnCompleteUnrefused = {
10610	reason: Exclude<TurnCompleteReason, 'refusal'>;
10611	};
10612
10613	/**
10614	* What the API said about a refusal that ended a turn: the classifier's
10615	* category and its explanation, each null when the API sent none.
10616	*/
10617	export type TurnRefusal = {
10618	category: string \| null;
10619	explanation: string \| null;
10620	};
10621
10622	/**
10623	* The input of `turn.start`: the prompt a model turn begins with, after
10624	* `prompt.submit` settled the text and the UserPromptSubmit settings hooks ran.
10625	*/
10626	export type TurnStartInput = {
10627	/**
10628	* The user's text as the turn proceeds with it ("" for a turn started without
10629	* a typed prompt, e.g. a continuation).
10630	*/
10631	text: string;
10632	/**
10633	* The turn's id, minted here; the same one every `turn.step` and the
10634	* `turn.complete` of this turn carry.
10635	*/
10636	turnId: string;
10637	};
10638
10639	/**
10640	* What a `turn.start` hook returns and what `next(e)` resolves to:
10641	* `{ turnId }`, echoed by core; a hook's own value does not change the turn.
10642	*/
10643	export type TurnStartResult = {
10644	turnId: string;
10645	};
10646
10647	/**
10648	* One piece of a `turn.step` response as it streams through the chain:
10649	* what a hook's `next(e)` yields and what the hook yields up in turn.
10650	*
10651	* Text, thinking, a tool call's start and arguments, and the stop are
10652	* plain data a hook reads and rewrites; `engine` is the rest, passed on
10653	* unread. What leaves the outermost hook is what is shown and recorded.
10654	*/
10655	export type TurnStepChunk = TurnStepTextChunk \| TurnStepThinkingChunk \| TurnStepToolChunk \| TurnStepInputChunk \| TurnStepStopChunk \| TurnStepEngineChunk;
10656
10657	/**
10658	* An item of the engine's stream the other chunk kinds do not model (the
10659	* envelope, a block's start and end, a retry marker), opaque by `ref`.
10660	*
10661	* Pass it on where it came. A hook that yields its own response has none
10662	* to yield, and the engine supplies what the response needs around the
10663	* chunks it does yield.
10664	*/
10665	export type TurnStepEngineChunk = {
10666	kind: 'engine';
10667	/**
10668	* The engine's handle on the item; opaque, this step's only.
10669	*/
10670	ref: number;
10671	};
10672
10673	/**
10674	* The input of `turn.step`: one model request inside a turn, at the moment
10675	* the engine is about to send it; the bottom of the chain sends it.
10676	*
10677	* The transcript is not on it: `messageCount` says how many messages the
10678	* request carries, and `$.session.messages()` reads them. A hook rewrites
10679	* `model` or `effort` going down; the rest is pinned.
10680	*/
10681	export type TurnStepInput = {
10682	/**
10683	* The turn this step belongs to (`turn.start`'s id; inside a subagent's
10684	* loop, the id the run's `turn.complete` will carry). Pinned.
10685	*/
10686	turnId: string;
10687	/**
10688	* The step's position in the turn, from 0. Pinned.
10689	*/
10690	index: number;
10691	/**
10692	* Which model the request names, as the engine resolved it for this step
10693	* (the session's, a fallback's). `next({ ...e, model })` names another.
10694	*/
10695	model: string;
10696	/**
10697	* How hard the request asks the model to think: the session's setting or
10698	* the model's default, absent for a model without effort; rewritable.
10699	*/
10700	effort?: 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number;
10701	/**
10702	* How many messages the request carries (the conversation so far, the
10703	* turn's tool results included). Pinned: the messages are the engine's.
10704	*/
10705	messageCount: number;
10706	/**
10707	* The loop the request is made in: a subagent's id, the `id`
10708	* `$.agent.list()` gives it and its `tool.call`s carry; absent on main.
10709	*
10710	* Pinned: a different value is refused, one left out is kept. A subagent
10711	* a hook spawned through `$.agent.spawn` steps past that hook, as its tool
10712	* calls do; every other hook sees its steps.
10713	*/
10714	agentId?: string;
10715	};
10716
10717	/**
10718	* A piece of a tool call's arguments as they arrive: JSON text, partial,
10719	* for the `tool` chunk of the same `index`.
10720	*
10721	* The arguments the tool runs with are the pieces concatenated and parsed
10722	* once the block ends; pieces that do not parse leave the call without
10723	* arguments it can run on, as a model that wrote broken JSON would.
10724	*/
10725	export type TurnStepInputChunk = ChunkRef & {
10726	kind: 'input';
10727	index: number;
10728	/**
10729	* The next piece of the arguments' JSON text.
10730	*/
10731	json: string;
10732	};
10733
10734	/**
10735	* What a `turn.step` hook returns and what `next(e)` resolves to: the
10736	* model's response to the step's request, once its blocks are all in.
10737	*
10738	* From the bottom, the response the engine streamed; a hook's own value
10739	* changes what the hooks above it read, never what the engine streamed.
10740	*/
10741	export type TurnStepResult = {
10742	/**
10743	* The turn this step belongs to, as received.
10744	*/
10745	turnId: string;
10746	/**
10747	* The step's position in the turn, as received.
10748	*/
10749	index: number;
10750	/**
10751	* The visible text of the response ("" when it only called tools, only
10752	* thought, or no request was made).
10753	*/
10754	answer: string;
10755	/**
10756	* The tool calls the response made, in order; empty for a text-only step.
10757	*/
10758	toolUses: readonly TurnStepToolUse[];
10759	/**
10760	* Why the model stopped; null when no response arrived (the request
10761	* failed or was interrupted before a message, or no request was made).
10762	*/
10763	stopReason: TurnStopReason;
10764	/**
10765	* What the request cost as the API reported it, and the model that
10766	* answered; null when no response arrived or it carried no usage.
10767	*/
10768	usage: TurnUsage \| null;
10769	};
10770
10771	/**
10772	* The response is whole: why the model stopped and what the request cost,
10773	* as the step's result will carry them. The last chunk of one response.
10774	*/
10775	export type TurnStepStopChunk = ChunkRef & {
10776	kind: 'stop';
10777	stopReason: TurnStopReason;
10778	usage: TurnUsage \| null;
10779	};
10780
10781	/**
10782	* A piece of the response's visible text as it arrives, in block `index`.
10783	*
10784	* The text the person watches stream and the text the transcript records
10785	* are both the concatenation of these, in order, per block: a hook that
10786	* rewrites them rewrites both, one that drops them all drops the block.
10787	*/
10788	export type TurnStepTextChunk = ChunkRef & {
10789	kind: 'text';
10790	/**
10791	* The content block the piece belongs to, from 0 within one response.
10792	*/
10793	index: number;
10794	text: string;
10795	};
10796
10797	/**
10798	* A piece of the model's thinking as it arrives, in block `index`: what
10799	* the person sees of it live.
10800	*
10801	* The thinking block the transcript keeps is the one the model signed, as
10802	* the engine received it; thinking a hook streams without the engine's
10803	* block behind it is shown and not recorded.
10804	*/
10805	export type TurnStepThinkingChunk = ChunkRef & {
10806	kind: 'thinking';
10807	index: number;
10808	text: string;
10809	};
10810
10811	/**
10812	* The model begins a tool call in block `index`: the tool's name and the
10813	* call's id; its arguments follow as `input` chunks of the same index.
10814	*
10815	* A block whose `tool` chunk never comes out of the chain is no tool call:
10816	* the engine records none and runs none.
10817	*/
10818	export type TurnStepToolChunk = ChunkRef & {
10819	kind: 'tool';
10820	index: number;
10821	/**
10822	* The call's `tool_use_id`.
10823	*/
10824	id: string;
10825	/**
10826	* The tool's name (`Read`, `Bash`, `mcp__server__tool`).
10827	*/
10828	name: string;
10829	};
10830
10831	/**
10832	* One tool call the model asked for in a step: the tool's name and its
10833	* arguments.
10834	*/
10835	export type TurnStepToolUse = {
10836	/**
10837	* The tool's name (`Read`, `Bash`, `mcp__server__tool`).
10838	*/
10839	name: string;
10840	/**
10841	* The arguments the model gave it, as the tool schema shapes them.
10842	*/
10843	input: unknown;
10844	};
10845
10846	/**
10847	* Why the model stopped, as a `turn.step` result and its stop chunk carry
10848	* it: one of the API's stop reasons, or null when no response arrived.
10849	*/
10850	type TurnStopReason = 'end_turn' \| 'max_tokens' \| 'stop_sequence' \| 'tool_use' \| 'pause_turn' \| 'compaction' \| 'refusal' \| 'model_context_window_exceeded' \| null;
10851
10852	/**
10853	* What a model turn, or one response inside it, cost as the API reported it:
10854	* the four token counts (`$.model.fork`'s usage shape) and the model's id.
10855	*
10856	* A turn's counts are its responses' summed; its model is the last response's.
10857	*/
10858	export type TurnUsage = ModelForkUsage & {
10859	/**
10860	* Which model answered, by the id the API reports.
10861	*/
10862	model: string;
10863	};
10864
10865	/**
10866	* What a plugin's `$.ui.blit(args)` takes: a Raster's next `cells`
10867	* (RasterBlitArgs) or a keyed Image's next `source` (ImageBlitArgs).
10868	*
10869	* Either names an element this plugin's own `ui.render` hook drew, still
10870	* mounted; a hook above may rewrite the cells or the source, never the
10871	* address or which kind it is.
10872	*/
10873	export type UiBlitArgs = RasterBlitArgs \| ImageBlitArgs;
10874
10875	/**
10876	* What `$.ui.blit` resolves to and what a `ui.blit` hook's `{ value }`
10877	* holds: `{}` once the cells or source are the next frame's, or why not.
10878	*/
10879	export type UiBlitResult = {
10880	/**
10881	* Absent when the cells or source were taken; else why not.
10882	*
10883	* Nothing of this plugin's is mounted there (another plugin's reads so),
10884	* the size is not the mounted one, the cells or source are bad, or the
10885	* Image draws its `alt` there, the reason spelled out for a fallback.
10886	*/
10887	deny?: string;
10888	};
10889
10890	/**
10891	* What a plugin's `$.ui.focus(args)` takes: one of its own elements, by the
10892	* `key` it drew it under, in one of its sites that holds the keyboard now.
10893	*
10894	* The engine resolves it to that site's ring and raises `ui.focus` under
10895	* the plugin's origin; the keyboard is the person's to give, so a site that
10896	* does not hold it, or holds it on another plugin's element, is `{ deny }`.
10897	*/
10898	export type UiFocusArgs = {
10899	/**
10900	* The site, by the `requestId` this plugin draws it under: one of its
10901	* panes' ids, or the band's.
10902	*/
10903	requestId: string;
10904	/**
10905	* The element's `key`: a `Button`, `Input` or `Select` this plugin drew in
10906	* that site; of several under one key, the first in document order.
10907	*/
10908	key: string;
10909	};
10910
10911	/**
10912	* The render components whose site keeps a focus ring: a pane's body and
10913	* the band above the prompt, each a ring over the elements hooks drew there.
10914	*/
10915	export type UiFocusComponent = 'Pane' \| 'AbovePrompt';
10916
10917	/**
10918	* The input of `ui.focus`: a site's focus ring about to move onto one of the
10919	* elements a hook drew in it (a `Button`, `Input` or `Select`), or off them.
10920	*
10921	* Every key but `element` is the engine's word, pinned: `next(e)` passes
10922	* them on, a rewrite that leaves one out keeps it, one that changes it fails
10923	* the hook. `element` is the hook's to rewrite; the ring has not moved yet.
10924	*/
10925	export type UiFocusInput = {
10926	/**
10927	* Which site: a `Pane` body or the `AbovePrompt` band.
10928	*/
10929	component: UiFocusComponent;
10930	/**
10931	* The instance the `ui.render` hook drawing the site sees: the pane's id,
10932	* or the band's one id.
10933	*/
10934	requestId: string;
10935	/**
10936	* Whose `ui.render` hook drew the element taking the ring; absent with
10937	* `element`. Read-only.
10938	*/
10939	plugin?: string;
10940	/**
10941	* The `key` of the element taking the ring, as `ui.press` names it; absent
10942	* for one of the engine's own stops (a pane's close mark or another's tab).
10943	*
10944	* `next({ ...e, element })` lands it on another element `plugin` drew in
10945	* the site instead; one not drawn there is core's `{ deny }`.
10946	*/
10947	element?: string;
10948	/**
10949	* Who moves it (UiFocusOrigin), set by the engine where the move starts.
10950	*/
10951	origin: UiFocusOrigin;
10952	};
10953
10954	/**
10955	* Who moves the ring at `ui.focus`, as the engine stamps it where the move
10956	* starts; a closed set a matcher narrows on.
10957	*
10958	* `next(e)` passes it on as received; no hook sets one.
10959	*/
10960	export type UiFocusOrigin = {
10961	/**
10962	* The person, by Tab, the arrows or a click while the site holds the
10963	* keyboard.
10964	*/
10965	kind: 'person';
10966	} \| {
10967	/**
10968	* A plugin's `$.ui.focus`, or its `autoFocus` element taking the ring
10969	* as the site takes the keyboard.
10970	*/
10971	kind: 'plugin';
10972	/**
10973	* The focusing plugin's name.
10974	*/
10975	name: string;
10976	};
10977
10978	/**
10979	* What a `ui.focus` hook returns, what `next(e)` resolves to, and what
10980	* `$.ui.focus` hands back: `{}` once the ring moved, or why it did not.
10981	*
10982	* As `ui.scroll` spells it.
10983	*/
10984	export type UiFocusResult = {
10985	/**
10986	* Absent when the ring is where the chain left it; else why nothing
10987	* moved.
10988	*
10989	* A hook kept the ring (no `next`); the site is not this plugin's, does
10990	* not hold the keyboard, or another plugin's element holds it; no element
10991	* of `plugin` is drawn under `element`; another move landed first.
10992	*/
10993	deny?: string;
10994	};
10995
10996	/**
10997	* The argument of `ui.input`: a change of, or a submit from, an `Input` a
10998	* render hook drew. Flat and frozen like every event's.
10999	*
11000	* Another plugin addresses one field by matcher:
11001	* `on("ui.input", { plugin: "roster", element: "reply" }, ...)`.
11002	*/
11003	export type UiInputArgument = {
11004	/**
11005	* Whose `ui.render` hook drew the element.
11006	*/
11007	plugin: string;
11008	/**
11009	* The `key` the hook gave its `Input`: its address, what a matcher names.
11010	*/
11011	element: string;
11012	/**
11013	* The render component the element was drawn in (`AbovePrompt`,
11014	* `ToolUse`, ...).
11015	*/
11016	component: RenderComponent;
11017	/**
11018	* The instance the element was drawn in: the `requestId` the `ui.render`
11019	* hook that drew it saw (a tool row's tool_use_id, a pane's id).
11020	*/
11021	requestId: string;
11022	/**
11023	* Where the typing came from, one literal per member, so
11024	* `if (e.surface === "terminal")` narrows `e`.
11025	*/
11026	surface: RenderSurface;
11027	/**
11028	* `change` after every edit of the text; `submit` on Enter.
11029	*/
11030	kind: 'change' \| 'submit';
11031	/**
11032	* The field's whole text at that moment; a hook above may rewrite it for
11033	* the plugins beneath and the element's own handler.
11034	*/
11035	value: string;
11036	};
11037
11038	/**
11039	* What a `ui.input` hook returns and what `next(e)` resolves to.
11040	*
11041	* Beneath every hook, core runs the element's `onInput` (kind `change`) or
11042	* `onSubmit` (kind `submit`) closure in its plugin's environment with the
11043	* value as the chain left it, and answers `{ element, value }`.
11044	*/
11045	export type UiInputResult = {
11046	/**
11047	* Which handler the input reached, by its Input's `key`.
11048	*/
11049	element: string;
11050	/**
11051	* The text the handler received.
11052	*/
11053	value: string;
11054	};
11055
11056	/**
11057	* Options of `$.ui.log`.
11058	*/
11059	export type UiLogOptions = {
11060	/**
11061	* Where the line goes (UiLogSink); `transcript` when left out. A hook on
11062	* `ui.log` reads it as `e.to` and may send the line elsewhere.
11063	*/
11064	to?: UiLogSink;
11065	};
11066
11067	/**
11068	* Where a `$.ui.log` line goes: `transcript`, a dim row of its own (and the
11069	* debug log, as every line); `debug`, the debug log alone, nothing on screen.
11070	*
11071	* The debug log is `claude --debug` or the `--debug-file`; either way the
11072	* line is led by the plugin's name.
11073	*/
11074	export type UiLogSink = 'transcript' \| 'debug';
11075
11076	/**
11077	* The argument of `ui.message`: what a `Client` instance's surface module
11078	* posted (`surface.post(data)`), addressed by where the instance is drawn.
11079	*
11080	* The origin is `client`: code sent it, on nobody's behalf, so `data` is
11081	* input to validate, not a fact. Everything but `data` is the engine's word
11082	* and a hook may not rewrite it.
11083	*/
11084	export type UiMessageArgument = {
11085	/**
11086	* Where the instance is drawn: `terminal`, or `desktop` once it has them.
11087	*/
11088	surface: RenderSurface;
11089	/**
11090	* The render component the `Client` was drawn in (`AbovePrompt`, `Pane`,
11091	* ...).
11092	*/
11093	component: RenderComponent;
11094	/**
11095	* The engine's id for the drawing the `Client` sits in: the `requestId` the
11096	* `ui.render` hook that drew it saw.
11097	*/
11098	requestId: string;
11099	/**
11100	* The `Client`'s `key`: which instance posted.
11101	*/
11102	element: string;
11103	/**
11104	* The `Client`'s `module`: which surface module runs there, as its path
11105	* under the plugin's folder.
11106	*/
11107	module: string;
11108	/**
11109	* What the instance posted: plain data (JsonValue), bounded as a tree's
11110	* text is; typed `unknown` since it came from code. Rewritable.
11111	*/
11112	data: unknown;
11113	};
11114
11115	/**
11116	* What a `ui.message` hook returns and what `next(e)` resolves to.
11117	*
11118	* Core answers `{}`: the message was heard and nothing changes. A hook that
11119	* answers `{ props }` hands the posting instance its next props directly, its
11120	* local state kept, with no `ui.render` run; the plugin's next redraw hands
11121	* props again as usual.
11122	*/
11123	export type UiMessageResult = {
11124	/**
11125	* The instance's next props, plain data (JsonValue) bounded as a `Client`'s
11126	* props are; absent leaves the instance's props as they were.
11127	*/
11128	props?: unknown;
11129	};
11130
11131	/**
11132	* One of this plugin's open panes as `$.ui.panes()` lists it: the pane's
11133	* id and title, and where it stands with the person right now.
11134	*
11135	* Where a surface seated it (`dock` or `inline`) is that surface's to say, on
11136	* the `Pane` render props (`placement`); a session may draw on several.
11137	*/
11138	export type UiPane = {
11139	/**
11140	* What `$.ui.open({ id })` named it, which `$.ui.close` and its
11141	* `ui.render` `requestId` name too.
11142	*/
11143	id: string;
11144	/**
11145	* Its tab's label: the `title` of its latest open, or the id.
11146	*/
11147	title: string;
11148	/**
11149	* True for the one pane the surface shows; the rest are tabs behind it.
11150	*/
11151	isShown: boolean;
11152	/**
11153	* True while the person has given it the keyboard.
11154	*/
11155	isFocused: boolean;
11156	/**
11157	* False while it waits undrawn: opened unasked on a terminal too narrow
11158	* for an unrequested pane, until an open the width or the person admits.
11159	*/
11160	isPlaced: boolean;
11161	};
11162
11163	/**
11164	* The argument of `ui.press`: a press on a `Button` a render hook drew, or
11165	* on an answered `Markdown` link. Flat and frozen like every event's.
11166	*
11167	* Another plugin addresses one button by matcher:
11168	* `on("ui.press", { plugin: "explainer", element: "explain" }, ...)`.
11169	*/
11170	export type UiPressArgument = {
11171	/**
11172	* Whose `ui.render` hook drew the element.
11173	*/
11174	plugin: string;
11175	/**
11176	* The `key` the hook gave its `Button` or `Markdown`: its address, what a
11177	* matcher names.
11178	*/
11179	element: string;
11180	/**
11181	* The render component the element was drawn in (`ToolUse`,
11182	* `AssistantMessage`, ...).
11183	*/
11184	component: RenderComponent;
11185	/**
11186	* The instance the element was drawn in: the `requestId` the `ui.render`
11187	* hook that drew it saw (a tool row's tool_use_id, a pane's id).
11188	*/
11189	requestId: string;
11190	/**
11191	* Where the press came from, one literal per member, so
11192	* `if (e.surface === "terminal")` narrows `e`.
11193	*/
11194	surface: RenderSurface;
11195	/**
11196	* Where the press landed, when the element is a `Markdown` whose links
11197	* its plugin answers (`onLinkPress`); absent for a `Button`.
11198	*
11199	* A hook may rewrite its `href` for the hooks and the closure beneath; one
11200	* that adds or drops it fails, and the press goes on beneath it.
11201	*/
11202	link?: PressedLink;
11203	};
11204
11205	/**
11206	* What a `ui.press` hook returns and what `next(e)` resolves to.
11207	*
11208	* Beneath every hook, core runs the element's `onPress` closure in its
11209	* plugin's environment with `e` as the chain left it, and answers
11210	* `{ element }`.
11211	*/
11212	export type UiPressResult = {
11213	/**
11214	* Which handler the press reached, by its Button's `key`.
11215	*/
11216	element: string;
11217	};
11218
11219	/**
11220	* What a plugin's `$.ui.scroll(args)` takes: what to bring into view, in
11221	* which of its sites, and where in the window it lands.
11222	*
11223	* The engine resolves it to a window and an offset and raises `ui.scroll`
11224	* under the plugin's origin; a transcript row is the person's to move, so
11225	* it is revealed only while the plugin answers the person's own input.
11226	*/
11227	export type UiScrollArgs = {
11228	/**
11229	* What to reveal (UiScrollTarget): a render instance by `requestId`, one
11230	* of this plugin's elements by `key`, or the `start` or `end` of `in`.
11231	*/
11232	to: UiScrollTarget;
11233	/**
11234	* The site to scroll, by the `requestId` this plugin draws it under: one
11235	* of its panes' ids, or the band's.
11236	*
11237	* Required with `start` and `end`; with `{ key }` it picks the site when
11238	* the key is drawn in several.
11239	*/
11240	in?: string;
11241	/**
11242	* Where the target lands in the window (UiScrollBlock); `nearest` when
11243	* left out, so a row already showing does not move.
11244	*/
11245	block?: UiScrollBlock;
11246	};
11247
11248	/**
11249	* Where in its scrollable a revealed row lands, as the DOM's
11250	* `scrollIntoView({ block })` names it.
11251	*
11252	* `nearest` moves the least that shows the row whole, and not at all when
11253	* it already shows; `start`, `center` and `end` put its top, middle or
11254	* bottom at that edge of the window. A row taller than the window shows
11255	* its top.
11256	*/
11257	export type UiScrollBlock = 'start' \| 'center' \| 'end' \| 'nearest';
11258
11259	/**
11260	* The render components whose site the engine scrolls: a pane's body and
11261	* the band above the prompt, each a window over the tree a hook drew there.
11262	*/
11263	export type UiScrollComponent = 'Pane' \| 'AbovePrompt';
11264
11265	/**
11266	* The input of `ui.scroll`: a site's window asked to move over the tree a
11267	* hook drew in it (a pane's body, the band above the prompt).
11268	*
11269	* Every key but `offset` is the engine's word, pinned: `next(e)` passes
11270	* them on, a rewrite that leaves one out keeps it, one that changes or adds
11271	* one fails the hook. `offset` is the hook's to rewrite; nothing moved yet.
11272	*/
11273	export type UiScrollInput = {
11274	/**
11275	* Which site: a `Pane` body or the `AbovePrompt` band.
11276	*/
11277	component: UiScrollComponent;
11278	/**
11279	* The instance the `ui.render` hook drawing the site sees: the pane's id,
11280	* or the band's one id.
11281	*/
11282	requestId: string;
11283	/**
11284	* The first row the window is to show, 0 at the top: the row it shows
11285	* now plus `by`, clamped to the tree, or where `$.ui.scroll` resolved.
11286	*
11287	* `next({ ...e, offset })` moves it elsewhere (a clamp); one past the
11288	* tree's end lands at the end. Nothing has moved when a hook reads it.
11289	*/
11290	offset: number;
11291	/**
11292	* The rows the move asks for, signed, negative toward the top; what the
11293	* DOM's `scrollBy` takes. Read-only.
11294	*
11295	* The person's: a wheel tick `-1` or `1` at rest, more as ticks crowd or
11296	* summed in flight; an arrow a row while the engine has rows to scroll, a
11297	* page key `bodyRows`, Home and End `contentRows`. A plugin's: its distance.
11298	*/
11299	by: number;
11300	/**
11301	* How many rows of the tree the window shows at once, as drawn now.
11302	* Read-only.
11303	*/
11304	bodyRows: number;
11305	/**
11306	* How many rows the tree has, as drawn now: the window's last offset is
11307	* `contentRows - bodyRows`, none when the tree fits. Read-only.
11308	*/
11309	contentRows: number;
11310	/**
11311	* Who moves it (UiScrollOrigin), set by the engine where the move starts.
11312	*/
11313	origin: UiScrollOrigin;
11314	/**
11315	* The body cell the person's wheel or trackpad was over (UiScrollPointer);
11316	* absent for the scroll keys and for `$.ui.scroll`. Read-only.
11317	*
11318	* Moves summed while a dispatch was in flight carry the latest one's. A
11319	* hook pinning a list over rows it scrolls itself tells a tick over the
11320	* list (`row` among its list's rows) from one over the body.
11321	*/
11322	pointer?: UiScrollPointer;
11323	};
11324
11325	/**
11326	* Who moves the window at `ui.scroll`, as the engine stamps it where the
11327	* move starts; a closed set a matcher narrows on.
11328	*
11329	* `next(e)` passes it on as received; no hook sets one.
11330	*/
11331	export type UiScrollOrigin = {
11332	/**
11333	* The person, by the wheel over the site or its scroll keys while
11334	* they hold it.
11335	*/
11336	kind: 'person';
11337	} \| {
11338	/**
11339	* A plugin's `$.ui.scroll`.
11340	*/
11341	kind: 'plugin';
11342	/**
11343	* The scrolling plugin's name.
11344	*/
11345	name: string;
11346	};
11347
11348	/**
11349	* The cell the pointer was over when the person's wheel raised `ui.scroll`,
11350	* in the site's body: the box its `ui.render` hook draws into, as painted.
11351	*
11352	* The DOM's `clientY - body.top` in cells, the window's offset not added: a
11353	* hook drawing its own window reads `row` as its tree's row, one the engine
11354	* scrolls adds the `scroll.offset` it drew with. The frame lies outside.
11355	*/
11356	export type UiScrollPointer = {
11357	/**
11358	* 0 at the body's left edge, as `bodyColumns` counts them; negative, or
11359	* `bodyColumns` and past, over an inline pane's side borders.
11360	*/
11361	column: number;
11362	/**
11363	* 0 at the body's first showing row, as `bodyRows` counts them.
11364	*
11365	* The tree's row is `scroll.offset + row` under the engine's window, and
11366	* `row` itself under a hook's own (offset 0); negative over a pane's top
11367	* border or tab row, `bodyRows` or more over its bottom border.
11368	*/
11369	row: number;
11370	};
11371
11372	/**
11373	* What a `ui.scroll` hook returns, what `next(e)` resolves to, and what
11374	* `$.ui.scroll` hands back: `{}` once the window moved, or why it did not.
11375	*/
11376	export type UiScrollResult = {
11377	/**
11378	* Absent when the window is where the chain left it; else why nothing
11379	* moved, as `tool.call` and `config.set` spell a refusal.
11380	*
11381	* A hook kept the window (no `next`); the target is not this plugin's;
11382	* another move landed first (`the window moved meanwhile`); a transcript
11383	* row is not the person's ask (`not person-initiated`) or none scrolls.
11384	*/
11385	deny?: string;
11386	};
11387
11388	/**
11389	* What `$.ui.scroll` brings into view: never a row number, always a thing
11390	* drawn somewhere.
11391	*
11392	* `{ requestId }` names a render instance by the id its `ui.render` hook
11393	* saw (a transcript message's, a tool row's tool_use_id), scrolled into view
11394	* inside whatever scrolls it. `{ key }` names an element this plugin drew
11395	* with that `key`, inside the site it drew it in. `start` and `end` are the
11396	* top and bottom of the site `in` names; `end` keeps up with a tree that
11397	* grows (rows the plugin just added count) until anything next moves it.
11398	*/
11399	export type UiScrollTarget = {
11400	requestId: string;
11401	} \| {
11402	key: string;
11403	} \| 'start' \| 'end';
11404
11405	/**
11406	* The argument of `ui.select`: a pick from a `Select` a render hook drew.
11407	* Flat and frozen like every event's.
11408	*
11409	* Another plugin addresses one picker by matcher:
11410	* `on("ui.select", { plugin: "roster", element: "peer" }, ...)`.
11411	*/
11412	export type UiSelectArgument = {
11413	/**
11414	* Whose `ui.render` hook drew the element.
11415	*/
11416	plugin: string;
11417	/**
11418	* The `key` the hook gave its `Select`: its address, what a matcher names.
11419	*/
11420	element: string;
11421	/**
11422	* The render component the element was drawn in (`AbovePrompt`,
11423	* `ToolUse`, ...).
11424	*/
11425	component: RenderComponent;
11426	/**
11427	* The instance the element was drawn in: the `requestId` the `ui.render`
11428	* hook that drew it saw (a tool row's tool_use_id, a pane's id).
11429	*/
11430	requestId: string;
11431	/**
11432	* Where the pick came from, one literal per member, so
11433	* `if (e.surface === "terminal")` narrows `e`.
11434	*/
11435	surface: RenderSurface;
11436	/**
11437	* The picked option's value; a hook above may rewrite it for the plugins
11438	* beneath and the element's own handler.
11439	*/
11440	value: string;
11441	};
11442
11443	/**
11444	* What a `ui.select` hook returns and what `next(e)` resolves to.
11445	*
11446	* Beneath every hook, core runs the element's `onSelect` closure in its
11447	* plugin's environment with the value as the chain left it, and answers
11448	* `{ element, value }`.
11449	*/
11450	export type UiSelectResult = {
11451	/**
11452	* Which handler the pick reached, by its Select's `key`.
11453	*/
11454	element: string;
11455	/**
11456	* What the handler received: the option's value as the chain left it.
11457	*/
11458	value: string;
11459	};
11460
11461	/**
11462	* The intersection of a union's members (`A \| B` to `A & B`), by inferring
11463	* one parameter type from the contravariant positions.
11464	*/
11465	type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void ? I : never;
11466
11467	/**
11468	* One unit of what `$.session.usage()` answers, by its key there: the
11469	* context window's fill, the rate-limit windows, the session's cost.
11470	*/
11471	export type UsageUnit = 'context' \| 'rateLimits' \| 'cost';
11472
11473	/**
11474	* Who sent the message a `UserMessage` row carries, when someone other than
11475	* the person did: another agent, a teammate, another session, a channel.
11476	*
11477	* Read-only. The sender's words are not the person's: the model reads them
11478	* framed as that sender's whatever a hook draws for the row.
11479	*/
11480	type UserMessageFrom = {
11481	/**
11482	* The sender's name as the row shows it: a subagent's name, else its type;
11483	* a teammate's; another session's title; a channel's sender, else server.
11484	*
11485	* One printable line: control and format characters stripped, whitespace
11486	* collapsed, length bounded. Absent (no `from`) for a teammate block whose
11487	* frames name different senders or none.
11488	*/
11489	name: string;
11490	};
11491
11492	/**
11493	* The background task a `UserMessage` notification row reports on: a
11494	* subagent, a background shell, a workflow, a remote agent, a monitor.
11495	*
11496	* Every field is the notification's own, so the row names the same task on
11497	* every draw, a resumed session's included; the session's record of it
11498	* (name, type, description) is `$.agent.list()`'s, by `id`. Each string is
11499	* one printable line, bounded (a forged envelope's bytes capped). Read-only.
11500	*/
11501	type UserMessageTask = {
11502	/**
11503	* The task's id as the notification names it; for a subagent, the
11504	* `agentId` its `turn.complete` carried and `$.agent.list()` keys.
11505	*/
11506	id?: string;
11507	/**
11508	* How the task ended: `completed`, `failed` or `killed` (stopped, by the
11509	* person or by Claude), or another word its producer wrote.
11510	*/
11511	status?: string;
11512	/**
11513	* What kind of task, when the notification says (`remote_agent`, an
11514	* artifact watch's kind); a subagent's and a shell's leave it out.
11515	*/
11516	type?: string;
11517	/**
11518	* Which call started the task: its `tool_use_id`, when the notification
11519	* carries it.
11520	*/
11521	toolUseId?: string;
11522	/**
11523	* How long the task ran, in milliseconds, when the notification says; the
11524	* row draws it after the summary (`2m 2s`).
11525	*/
11526	durationMs?: number;
11527	};
11528
11529	type UserPromptExpansionHookInput = BaseHookInput & {
11530	hook_event_name: 'UserPromptExpansion';
11531	expansion_type: 'slash_command' \| 'mcp_prompt';
11532	command_name: string;
11533	command_args: string;
11534	command_source?: string;
11535	prompt: string;
11536	};
11537
11538	type UserPromptSubmitHookInput = BaseHookInput & {
11539	hook_event_name: 'UserPromptSubmit';
11540	prompt: string;
11541	/**
11542	* Who authored/injected the prompt: `user` = submitted from the interactive composer, `sdk` = non-interactive entrypoint (`-p` / Agent SDK), `loop_wakeup` = dynamic /loop wakeup, `schedule_wakeup` = scheduled-task fire (CronCreate/routine), `system` = other machine-injected turns (peer/channel messages, task notifications, auto-continuation), `poll_event` = the poll-event channel enqueue-time pass (the hook fires when the host submits an event, before its delivery ack exists - a blocking verdict rejects the event). Payloads may omit it while the field rolls out.
11543	*/
11544	source?: 'user' \| 'sdk' \| 'system' \| 'loop_wakeup' \| 'schedule_wakeup' \| 'poll_event';
11545	session_title?: string;
11546	};
11547
11548	/**
11549	* The result of a call on `$` as the hooks on its event see it: `{ value }`,
11550	* the call's answer, or `{ deny }`, the reason the caller's promise rejects.
11551	*/
11552	type ValueOrDeny<Value> = {
11553	value: Value;
11554	deny?: undefined;
11555	} \| {
11556	deny: string;
11557	value?: undefined;
11558	};
11559
11560	type WorktreeCreateHookInput = BaseHookInput & {
11561	hook_event_name: 'WorktreeCreate';
11562	name: string;
11563	};
11564
11565	type WorktreeRemoveHookInput = BaseHookInput & {
11566	hook_event_name: 'WorktreeRemove';
11567	worktree_path: string;
11568	};
11569
11570	/**
11571	* The globals of a hooks module's environment: these and no others (no DOM,
11572	* no Node). No code generation either: `eval` and `new Function` over a
11573	* string throw, and there is no `WebAssembly` (deliberately; a module that
11574	* needs compiled code runs it in a process of its own through `$.process.run`).
11575	* A surface module's environment (Client) has the same globals and a
11576	* `console`; neither has timers (a hooks module waits on `$.clock`, a
11577	* surface module on `surface.every`).
11578	*/
11579	global {
11580	/**
11581	* The JSX factory (classic runtime, `@jsx h`; the engine prepends the
11582	* pragma): a plain-data element from a string tag or a component.
11583	*
11584	* JSX compiles to bare `h(...)` calls resolved by name, so a module (hooks or
11585	* surface) never declares, imports or takes as a parameter anything named
11586	* `h` or `Fragment` where it writes JSX, and carries no `@jsx` pragma of its
11587	* own: either silently points its JSX away from this factory, and a
11588	* `<Client>` tag written under another factory is not found when the
11589	* module's surface modules are read off its source.
11590	*/
11591	const h: (
11592	tag: string \| ((props: never) => RenderNode \| null \| undefined),
11593	props: Record<string, unknown> \| null \| undefined,
11594	...children: unknown[]
11595	) => RenderNode \| null \| undefined
11596
11597	/**
11598	* `<>...</>`: a column Box around the children.
11599	*/
11600	const Fragment: (props: { children?: RenderNode[] }) => RenderElement
11601
11602	/**
11603	* JSX over the element table: every tag is a constructor from
11604	* `$.ui.resolve(e)` (`const { Box, Text } = $.ui.resolve(e)`), typed by
11605	* its props; there are no intrinsic (string) tags.
11606	*/
11607	namespace JSX {
11608	type Element = RenderElement
11609	type Children = RenderChildren
11610	type ElementType = (props: never) => RenderNode \| null \| undefined
11611	interface IntrinsicElements {}
11612	interface ElementChildrenAttribute {
11613	children: unknown
11614	}
11615	interface IntrinsicAttributes {
11616	key?: string
11617	}
11618	}
11619
11620	interface AbortSignal {
11621	readonly aborted: boolean
11622	readonly reason: unknown
11623	throwIfAborted(): void
11624	addEventListener(
11625	type: 'abort',
11626	listener: () => void,
11627	options?: { once?: boolean },
11628	): void
11629	removeEventListener(type: 'abort', listener: () => void): void
11630	}
11631	var AbortSignal: {
11632	prototype: AbortSignal
11633	abort(reason?: unknown): AbortSignal
11634	timeout(milliseconds: number): AbortSignal
11635	any(signals: AbortSignal[]): AbortSignal
11636	}
11637	interface AbortController {
11638	readonly signal: AbortSignal
11639	abort(reason?: unknown): void
11640	}
11641	var AbortController: {
11642	prototype: AbortController
11643	new (): AbortController
11644	}
11645	interface TextEncoder {
11646	readonly encoding: string
11647	encode(input?: string): Uint8Array
11648	}
11649	var TextEncoder: { prototype: TextEncoder; new (): TextEncoder }
11650	interface TextDecoder {
11651	readonly encoding: string
11652	decode(input?: ArrayBufferView \| ArrayBuffer): string
11653	}
11654	var TextDecoder: { prototype: TextDecoder; new (label?: string): TextDecoder }
11655	interface URLSearchParams {
11656	append(name: string, value: string): void
11657	delete(name: string): void
11658	get(name: string): string \| null
11659	getAll(name: string): string[]
11660	has(name: string): boolean
11661	set(name: string, value: string): void
11662	toString(): string
11663	forEach(callback: (value: string, key: string) => void): void
11664	}
11665	var URLSearchParams: {
11666	prototype: URLSearchParams
11667	new (init?: string \| Record<string, string> \| string[][]): URLSearchParams
11668	}
11669	interface URL {
11670	hash: string
11671	host: string
11672	hostname: string
11673	href: string
11674	readonly origin: string
11675	password: string
11676	pathname: string
11677	port: string
11678	protocol: string
11679	search: string
11680	readonly searchParams: URLSearchParams
11681	username: string
11682	toString(): string
11683	toJSON(): string
11684	}
11685	var URL: {
11686	prototype: URL
11687	new (url: string, base?: string \| URL): URL
11688	canParse(url: string, base?: string): boolean
11689	}
11690	function atob(data: string): string
11691	function btoa(data: string): string
11692	function structuredClone<T>(value: T): T
11693	var crypto: {
11694	readonly subtle: {
11695	digest(
11696	algorithm: string \| { name: string },
11697	data: ArrayBufferView \| ArrayBuffer,
11698	): Promise<ArrayBuffer>
11699	}
11700	randomUUID(): string
11701	getRandomValues<T extends ArrayBufferView>(array: T): T
11702	}
11703	var performance: { now(): number }
11704	}
11705	}
11706
11707	declare module 'claude-code/testing' {
11708	import type { Args } from 'claude-code';
11709	import type { Chunk } from 'claude-code';
11710	import type { ClientKeyEvent } from 'claude-code';
11711	import type { ClientPointerEvent } from 'claude-code';
11712	import type { Elements } from 'claude-code';
11713	import type { EventCalls } from 'claude-code';
11714	import type { EventName } from 'claude-code';
11715	import type { HookStream } from 'claude-code';
11716	import type { JsonValue } from 'claude-code';
11717	import type { On } from 'claude-code';
11718	import type { PressedLink } from 'claude-code';
11719	import type { Register } from 'claude-code';
11720	import type { RenderComponent } from 'claude-code';
11721	import type { RenderElement } from 'claude-code';
11722	import type { RenderPropsOf } from 'claude-code';
11723	import type { RenderSurface } from 'claude-code';
11724	import type { RenderViewport } from 'claude-code';
11725	import type { ResultOf } from 'claude-code';
11726	import type { StreamingEventName } from 'claude-code';
11727	import type { Tier } from 'claude-code';
11728	import type { UiInputArgument } from 'claude-code';
11729	import type { UiInputResult } from 'claude-code';
11730	import type { UiPressResult } from 'claude-code';
11731	import type { UiSelectResult } from 'claude-code';
11732
11733	/**
11734	* A value that matches by a rule inside `toEqual` and its kin
11735	* (`expect.any`, `expect.objectContaining`), known by its text in a failure.
11736	*/
11737	export type AsymmetricMatcher = {
11738	readonly text: string;
11739	};
11740
11741	/**
11742	* The same checks on what a promise received settles with, each resolving
11743	* once the promise has settled and the check passed.
11744	*/
11745	export type AsyncMatchers = {
11746	[K in keyof Matchers]: (...args: Parameters<Matchers[K]>) => Promise<void>;
11747	};
11748
11749	/**
11750	* Which `Client` of a mounted drawing an act or a read means, by the `key`
11751	* its element carries; optional while the drawing holds exactly one.
11752	*/
11753	export type ClientScope = {
11754	in?: string;
11755	};
11756
11757	/**
11758	* A class, as `toThrow`, `toBeInstanceOf` and `expect.any` take it.
11759	*/
11760	export type Constructor = abstract new (...args: never[]) => unknown;
11761
11762	/**
11763	* A group of tests: its name leads the title of each test declared inside,
11764	* and its body runs at once, while the file loads.
11765	*
11766	* @param name the group's name
11767	* @param body declares the group's tests
11768	*/
11769	export const describe: (name: string, body: () => void) => void;
11770
11771	/**
11772	* The element each surface-dependent act of a mounted drawing reaches: a
11773	* handle carries the act only where the surface's table has the element.
11774	*
11775	* `input` needs `Input` and `select` needs `Select` (every surface but
11776	* mobile today); `key`, `pointer`, `post`, `advance` and `resize` reach a
11777	* `Client` (terminal and desktop today). The rest need nothing but a tree.
11778	*/
11779	export type ElementOfAct = {
11780	input: 'Input';
11781	select: 'Select';
11782	key: 'Client';
11783	pointer: 'Client';
11784	post: 'Client';
11785	advance: 'Client';
11786	resize: 'Client';
11787	};
11788
11789	/**
11790	* What a mounted drawing's `find` and `findAll` match an element on, every
11791	* field given at once: its tag, its `key`, and the text it shows.
11792	*
11793	* `text` matches the element's whole shown text (string children, a Button
11794	* or Link's label, a Markdown's text, a Code's source, an Input's value):
11795	* a string by inclusion, a RegExp by test.
11796	*
11797	* @example
11798	* await ui.findAll({ type: 'Text', text: /overdue/, in: 'board' })
11799	*/
11800	export type ElementQuery = {
11801	type?: string;
11802	key?: string;
11803	text?: string \| RegExp;
11804	/**
11805	* Searches what this `Client`'s surface module drew (by the `Client`'s
11806	* key) instead of the plugin's own tree.
11807	*/
11808	in?: string;
11809	};
11810
11811	/**
11812	* What a test holds as `$`, the engine's own: every call on it is made as
11813	* the REPL, the query loop and the render sites make theirs, over every plugin.
11814	*
11815	* `next.origin` is the engine, and the whole chain runs over the plugins
11816	* loaded. A tool call's `tool_use_id` is minted when left out; `$.ui.mount`
11817	* is a surface the test names drawing an instance, `$.ui.press` a press on it.
11818	*/
11819	export type Engine = {
11820	[N in keyof EventCalls]: N extends 'ui' ? EngineNoun<N> & EnginePress & EngineMount : EngineNoun<N>;
11821	};
11822
11823	/**
11824	* One call on the engine's `$`: the event's input whole, as an engine call
11825	* site passes it, to its result, or for a streaming event to its stream.
11826	*/
11827	export type EngineCall<E extends EventName> = E extends StreamingEventName ? (e: Args<E>) => HookStream<Chunk<E>, ResultOf[E]> : (e: Args<E>) => Promise<ResultOf[E]>;
11828
11829	/**
11830	* A surface drawing a component instance through the plugins, then driven
11831	* by key through a handle typed by that surface (Mounted).
11832	*
11833	* `ui.render` raised there for those props, the tree validated by that
11834	* table, its `Client`s running; the reads and `press` on every surface,
11835	* `input` where the table has `Input`, the `Client` acts where `Client`.
11836	*
11837	* @example
11838	* for (const surface of SURFACES) run(await $.ui.mount({ ...HINT, surface }))
11839	*/
11840	export type EngineMount = {
11841	/**
11842	* Raises the plugins' drawing of the component on the surface and holds
11843	* it, as that surface showing the instance does.
11844	*
11845	* Resolves once the tree validated and every `Client` in it drew once.
11846	*
11847	* @param target whose elements, the surface, the component, its props,
11848	* the instance's requestId, and what the surface measured
11849	* @returns the mounted drawing; rejects when no `surface` (or an unknown
11850	* one) is named, when the surface cannot draw the tree the chain
11851	* returned (with the reason: an element its table lacks, a prop not
11852	* allowed), or when a `Client`'s module failed or drew nothing
11853	*/
11854	mount: <P extends RenderSurface, C extends RenderComponent>(target: MountTarget<P, C>) => Promise<Mounted<P, C>>;
11855	};
11856
11857	/**
11858	* One noun of the engine's `$`: each of its events as the engine calls it,
11859	* `tool.call` and `ui.render` typed per tool and component, `ui.resolve` out.
11860	*/
11861	export type EngineNoun<N extends keyof EventCalls> = {
11862	[V in EngineNounEvent<N>]: `${N}.${V}` extends 'tool.call' \| 'ui.render' ? EventCalls[N][V] : EngineCall<`${N}.${V}` & EventName>;
11863	};
11864
11865	/**
11866	* The events of one noun a test's `$` carries: every one but `ui.resolve`,
11867	* which a render hook calls on its own `$` and the engine never raises.
11868	*/
11869	export type EngineNounEvent<N extends keyof EventCalls> = Exclude<keyof EventCalls[N] & string, `${N}.resolve` extends 'ui.resolve' ? 'resolve' : never>;
11870
11871	/**
11872	* A surface pressing a Button a test rendered, or a Markdown's link: the
11873	* `ui.press` chain over every plugin hooked on it, its own closure last.
11874	*/
11875	export type EnginePress = {
11876	/**
11877	* Presses the Button, as a click or its hotkey does; with `link`, the
11878	* Markdown's link, as a click on it does.
11879	*
11880	* `e.surface` is the surface of the drawing that holds it.
11881	*
11882	* @param target whose element, its key, the instance and surface when
11883	* several hold it, and for a Markdown the link
11884	* @returns what the chain settled on; rejects when no such element is
11885	* drawn, or several are and neither instance nor surface tells them apart
11886	*/
11887	press: (target: PressTarget) => Promise<UiPressResult \| undefined>;
11888	};
11889
11890	/**
11891	* The checks on a value (`expect(received)`), and with them the matchers
11892	* that stand inside an expected value (`expect.any(Number)`).
11893	*/
11894	export type Expect = Expecting & Matching;
11895
11896	/**
11897	* Checks a value: `expect(received).toEqual(expected)` throws an
11898	* AssertionError naming both sides when it fails, a message given leading.
11899	*
11900	* `.not` negates; `.resolves` and `.rejects` check what a promise settles
11901	* with; `expect.any(Number)` and its kin stand inside an expected value.
11902	*/
11903	export const expect: Expect;
11904
11905	/**
11906	* What `expect(received)` answers: the checks, their negation, and the
11907	* checks on what a promise received resolves or rejects with.
11908	*/
11909	export type Expectation = Negatable<Matchers> & {
11910	/**
11911	* The checks on what the promise received resolves with; a rejection
11912	* fails them.
11913	*/
11914	resolves: Negatable<AsyncMatchers>;
11915	/**
11916	* The checks on what the promise received rejects with; a resolution
11917	* fails them.
11918	*/
11919	rejects: Negatable<AsyncMatchers>;
11920	};
11921
11922	/**
11923	* `expect(received, message?)`: the checks on a value, a message of the
11924	* test's own leading a failure's.
11925	*/
11926	export type Expecting = (received: unknown, message?: string) => Expectation;
11927
11928	/**
11929	* One element of a mounted drawing as `find` returns it: the description
11930	* the plugin's hook (or a `Client`'s module) built, read as plain data.
11931	*
11932	* What every surface is handed to draw, not what any surface painted: the
11933	* same on the terminal, the desktop, VS Code and mobile.
11934	*/
11935	export type FoundElement = {
11936	/**
11937	* The element's tag: `Box`, `Text`, `Button`, `Input`, `Client`, ...
11938	*/
11939	type: string;
11940	/**
11941	* What its props carry as `key`, when they do.
11942	*/
11943	key: string \| undefined;
11944	/**
11945	* Its props, plain data: a Button's `label`, a Text's `color`, ...;
11946	* handlers never cross (a Button's `onPress` is not here).
11947	*/
11948	props: Record<string, unknown>;
11949	/**
11950	* What it shows: its string children in document order and, for the
11951	* leaves that draw a prop as text, that prop (ElementQuery `text`).
11952	*/
11953	text: string;
11954	/**
11955	* Its children as drawn: strings and element descriptions.
11956	*/
11957	children: unknown[];
11958	};
11959
11960	/**
11961	* The checks `expect(received)` offers; each throws an AssertionError when
11962	* it fails, naming what was expected and what was received.
11963	*/
11964	export type Matchers = {
11965	/**
11966	* Passes when received is the value, by `Object.is`.
11967	*
11968	* @param expected the value
11969	*/
11970	toBe: (expected: unknown) => void;
11971	/**
11972	* Passes when received equals the value in structure, properties holding
11973	* undefined ignored; `expect.any` and its kin match inside it.
11974	*
11975	* @param expected the value
11976	*/
11977	toEqual: (expected: unknown) => void;
11978	/**
11979	* As `toEqual`, but undefined properties and prototypes count.
11980	*
11981	* @param expected the value
11982	*/
11983	toStrictEqual: (expected: unknown) => void;
11984	/**
11985	* Passes when received holds at least the object's properties, equal.
11986	*
11987	* @param expected the object
11988	*/
11989	toMatchObject: (expected: object) => void;
11990	/**
11991	* Passes when a string received includes the item, or an iterable
11992	* received has an element that is it.
11993	*
11994	* @param item the substring or element
11995	*/
11996	toContain: (item: unknown) => void;
11997	/**
11998	* Passes when an iterable received has an element equal to the item.
11999	*
12000	* @param item the element
12001	*/
12002	toContainEqual: (item: unknown) => void;
12003	/**
12004	* Passes when received's `length` is the number.
12005	*
12006	* @param length the number
12007	*/
12008	toHaveLength: (length: number) => void;
12009	/**
12010	* Passes when received holds a property at the path (`a.b`, or the keys
12011	* in order), equal to the value when one is given.
12012	*
12013	* @param path the property's path
12014	* @param value what it must equal, when given
12015	*/
12016	toHaveProperty: (path: string \| readonly string[], value?: unknown) => void;
12017	/**
12018	* Passes when received is undefined.
12019	*/
12020	toBeUndefined: () => void;
12021	/**
12022	* Passes when received is anything but undefined.
12023	*/
12024	toBeDefined: () => void;
12025	/**
12026	* Passes when received is null.
12027	*/
12028	toBeNull: () => void;
12029	/**
12030	* Passes when received is truthy.
12031	*/
12032	toBeTruthy: () => void;
12033	/**
12034	* Passes when received is falsy.
12035	*/
12036	toBeFalsy: () => void;
12037	/**
12038	* Passes when received is NaN.
12039	*/
12040	toBeNaN: () => void;
12041	/**
12042	* Passes when received is greater than the bound.
12043	*
12044	* @param bound the bound
12045	*/
12046	toBeGreaterThan: (bound: number \| bigint) => void;
12047	/**
12048	* Passes when received is the bound or greater.
12049	*
12050	* @param bound the bound
12051	*/
12052	toBeGreaterThanOrEqual: (bound: number \| bigint) => void;
12053	/**
12054	* Passes when received is less than the bound.
12055	*
12056	* @param bound the bound
12057	*/
12058	toBeLessThan: (bound: number \| bigint) => void;
12059	/**
12060	* Passes when received is the bound or less.
12061	*
12062	* @param bound the bound
12063	*/
12064	toBeLessThanOrEqual: (bound: number \| bigint) => void;
12065	/**
12066	* Passes when a string received includes the text, or the pattern matches
12067	* it.
12068	*
12069	* @param pattern the text or pattern
12070	*/
12071	toMatch: (pattern: string \| RegExp) => void;
12072	/**
12073	* Passes when a string received starts with the prefix.
12074	*
12075	* @param prefix the prefix
12076	*/
12077	toStartWith: (prefix: string) => void;
12078	/**
12079	* Passes when a string received ends with the suffix.
12080	*
12081	* @param suffix the suffix
12082	*/
12083	toEndWith: (suffix: string) => void;
12084	/**
12085	* Passes when received is an instance of the class.
12086	*
12087	* @param expected the class
12088	*/
12089	toBeInstanceOf: (expected: Constructor) => void;
12090	/**
12091	* Passes when calling received throws (or, under `rejects`, the rejection
12092	* is) an error as described: by substring, pattern, class or message.
12093	*
12094	* @param expected the description; any throw passes without one
12095	*/
12096	toThrow: (expected?: ThrowExpectation) => void;
12097	};
12098
12099	/**
12100	* The matchers that stand inside an expected value, each matching received
12101	* there by a rule instead of by equality.
12102	*/
12103	export type Matching = {
12104	/**
12105	* Matches any instance of the class, a primitive by its wrapper
12106	* (`expect.any(Number)`).
12107	*
12108	* @param expected the class
12109	* @returns the matcher
12110	*/
12111	any: (expected: Constructor) => AsymmetricMatcher;
12112	/**
12113	* Matches anything but null and undefined.
12114	*
12115	* @returns the matcher
12116	*/
12117	anything: () => AsymmetricMatcher;
12118	/**
12119	* Matches a string that includes the text.
12120	*
12121	* @param text the substring
12122	* @returns the matcher
12123	*/
12124	stringContaining: (text: string) => AsymmetricMatcher;
12125	/**
12126	* Matches a string the pattern matches.
12127	*
12128	* @param pattern the pattern, or the source of one
12129	* @returns the matcher
12130	*/
12131	stringMatching: (pattern: string \| RegExp) => AsymmetricMatcher;
12132	/**
12133	* Matches an object holding at least the shape's properties, equal.
12134	*
12135	* @param shape the properties
12136	* @returns the matcher
12137	*/
12138	objectContaining: (shape: object) => AsymmetricMatcher;
12139	/**
12140	* Matches an array holding an element equal to each of the items.
12141	*
12142	* @param items the elements
12143	* @returns the matcher
12144	*/
12145	arrayContaining: (items: readonly unknown[]) => AsymmetricMatcher;
12146	};
12147
12148	/**
12149	* The world beneath the plugins, mocked noun by noun: each member registers
12150	* hooks of the test's on `on`, visible where the test calls it.
12151	*/
12152	export type Mock = {
12153	/**
12154	* Answers `$.clock` from a clock in memory that moves only when the test
12155	* moves it: `clock.now` reads it, and each wait is held.
12156	*
12157	* A held wait resolves when an advance crosses the time it is due, and is
12158	* dropped when its dispatch aborts; one held past a hook's budget (ten
12159	* seconds of real time) is let go, as a hook that overran.
12160	*
12161	* @param on the test's `on`
12162	* @param options where the clock starts (`now`, 0 when not given)
12163	* @returns the clock: its time, and the calls that move it
12164	*/
12165	clock: (on: On, options?: MockClockOptions) => MockClock;
12166	/**
12167	* Answers `$.store` from a store in memory: `get`, `set`, `delete` and
12168	* `keys` over it, as the engine keeps a plugin's own.
12169	*
12170	* @param on the test's `on`
12171	* @param entries what the store holds at the start (nothing when not given)
12172	*/
12173	store: (on: On, entries?: Readonly<Record<string, unknown>>) => void;
12174	/**
12175	* Answers `$.env.get` from a set of variables; one not listed is unset.
12176	*
12177	* @param on the test's `on`
12178	* @param variables the environment the plugins read
12179	*/
12180	env: (on: On, variables: Readonly<Record<string, string>>) => void;
12181	};
12182
12183	/**
12184	* The world beneath the plugins, mocked noun by noun: `mock.clock`,
12185	* `mock.store` and `mock.env`.
12186	*
12187	* Each registers hooks of the test's on the `on` it is handed, visible where
12188	* the test calls it, and answers its noun from memory.
12189	*/
12190	export const mock: Mock;
12191
12192	/**
12193	* The clock `mock.clock` hands back: the time its hooks answer, and the only
12194	* ways it moves.
12195	*/
12196	export type MockClock = {
12197	/**
12198	* The time now, in milliseconds: what `$.clock.now()` resolves beneath the
12199	* plugins.
12200	*
12201	* @returns the time
12202	*/
12203	now: () => number;
12204	/**
12205	* Moves the clock on, resolving each wait due on the way (`$.clock.sleep`,
12206	* `after`, `every`, this clock's `sleep`) in the order it comes due.
12207	*
12208	* The clock reads each wait's time as it resolves, and what one started
12209	* runs before the next resolves.
12210	*
12211	* @param ms how far to move, in milliseconds
12212	* @returns resolves once the clock is there and the event loop settled
12213	*/
12214	advance: (ms: number) => Promise<void>;
12215	/**
12216	* Moves the clock to a time at or past now, as `advance` would.
12217	*
12218	* @param ms the time, in milliseconds
12219	* @returns resolves once the clock is there and the event loop settled
12220	*/
12221	set: (ms: number) => Promise<void>;
12222	/**
12223	* Lets what is already under way run as far as it can without the clock
12224	* moving: every wait due now resolves and the event loop settles.
12225	*
12226	* The same as `advance(0)`; the name for the step between starting a
12227	* dispatch unawaited and looking at what it did.
12228	*
12229	* @returns resolves once the event loop settled, the time where it was
12230	*/
12231	settle: () => Promise<void>;
12232	/**
12233	* Resolves once the clock has moved this far past now: how a hook of the
12234	* test's answers late.
12235	*
12236	* @param ms how far, in milliseconds
12237	* @returns resolves when an advance crosses that time
12238	*/
12239	sleep: (ms: number) => Promise<void>;
12240	};
12241
12242	/**
12243	* Where a mocked clock starts: `now`, in milliseconds (0 when not given).
12244	*/
12245	export type MockClockOptions = {
12246	now?: number;
12247	};
12248
12249	/**
12250	* A drawing of component `C` the test mounted on surface `P`: reads over its
12251	* description, acts on its elements by key, `Client` acts where `P` has one.
12252	*
12253	* Narrowed by the `surface` the test passed, as `e.surface` narrows
12254	* `$.ui.resolve(e)`: no `input` on `mobile`, no `key` on `vscode`, whose
12255	* tables (Elements) lack `Input` and `Client`; over a union, their meet.
12256	*/
12257	export type Mounted<P extends RenderSurface = RenderSurface, C extends RenderComponent = RenderComponent> = {
12258	[K in keyof MountedMembers<P, C> as K extends keyof ElementOfAct ? ElementOfAct[K] extends keyof Elements[P] ? K : never : K]: MountedMembers<P, C>[K];
12259	};
12260
12261	/**
12262	* Every member a mounted drawing of component `C` can have; `Mounted<P, C>`
12263	* keeps the ones surface `P` has the element for (ElementOfAct).
12264	*
12265	* Each act resolves once the loop settled and what a plugin invalidated
12266	* was drawn again. The kit exercises the mod (its hooks, its description
12267	* under the surface's rules, its `Client` modules), never a surface's paint.
12268	*/
12269	export type MountedMembers<P extends RenderSurface, C extends RenderComponent = RenderComponent> = {
12270	/**
12271	* Where this drawing is, as the test named it.
12272	*/
12273	readonly surface: P;
12274	/**
12275	* The tree as last drawn: what the plugins' `ui.render` chain returned
12276	* for this instance, validated by the surface's table, as plain data.
12277	*
12278	* With `in`, what that `Client`'s surface module last drew instead.
12279	*
12280	* @param scope `{ in }`: a `Client`'s key, to read its module's tree
12281	* @returns the tree; rejects with the refusal when the surface could not
12282	* draw what the chain returned, or with a `Client`'s fault line
12283	* @example
12284	* expect(await ui.drawn()).toMatchObject({ type: 'Box' })
12285	*/
12286	drawn: (scope?: ClientScope) => Promise<RenderElement>;
12287	/**
12288	* The first element matching the query, outermost first in document
12289	* order, or undefined.
12290	*
12291	* @param query tag, key and shown text to match; `in` to search a Client
12292	* @returns the element's description, or undefined when none matches
12293	* @example
12294	* expect((await ui.find({ key: 'count' }))?.text).toBe('3 notes')
12295	*/
12296	find: (query: ElementQuery) => Promise<FoundElement \| undefined>;
12297	/**
12298	* Every element matching the query, in document order.
12299	*
12300	* @param query tag, key and shown text to match; `in` to search a Client
12301	* @returns the matching elements' descriptions
12302	* @example
12303	* expect(await ui.findAll({ type: 'Button' })).toHaveLength(2)
12304	*/
12305	findAll: (query: ElementQuery) => Promise<FoundElement[]>;
12306	/**
12307	* Presses the Button keyed `key`, as the person activating it on this
12308	* surface does: the `ui.press` chain, the Button's own `onPress` last.
12309	*
12310	* `e.surface` is this drawing's. With `link`, presses that link of the
12311	* Markdown keyed `key` instead. A Button a `Client`'s module drew is
12312	* pressed the same way, by its key.
12313	*
12314	* @param target the key; another plugin's name to press its Button; a link
12315	* @returns what the chain settled on
12316	* @example
12317	* await ui.press({ key: 'save' })
12318	*/
12319	press: (target: MountPressTarget) => Promise<UiPressResult \| undefined>;
12320	/**
12321	* Types into the Input keyed `key`: the `ui.input` chain with the text as
12322	* `e.value`, the Input's own handler last.
12323	*
12324	* `kind` `submit` (the default) is Enter with that text, `change` an edit
12325	* that leaves it in the field.
12326	*
12327	* @param target the key and the text; `kind`; another plugin's name
12328	* @returns what the chain settled on
12329	* @example
12330	* await ui.input({ key: 'title', text: 'groceries' })
12331	*/
12332	input: (target: MountInputTarget) => Promise<UiInputResult \| undefined>;
12333	/**
12334	* Picks `value` in the Select keyed `key`: the `ui.select` chain, the
12335	* Select's own `onSelect` last.
12336	*
12337	* @param target the key and the option's value; another plugin's name
12338	* @returns what the chain settled on
12339	* @example
12340	* await ui.select({ key: 'sort', value: 'date' })
12341	*/
12342	select: (target: MountSelectTarget) => Promise<UiSelectResult \| undefined>;
12343	/**
12344	* Hands a `Client`'s `onKey` listener one key, as a key pressed while
12345	* its region has the focus does.
12346	*
12347	* `in` names the `Client` by key; optional when the drawing holds one.
12348	*
12349	* @param event the key (`{ key: 'right' }`, `{ key: 'a', ctrl: true }`)
12350	* @example
12351	* await ui.key({ key: 'return', in: 'board' })
12352	*/
12353	key: (event: MountKeyEvent) => Promise<void>;
12354	/**
12355	* Hands a `Client`'s `onPointer` listener one event, in the cells of its
12356	* region as every surface that draws a `Client` reports them.
12357	*
12358	* @param event the event (`{ type: 'down', x: 3, y: 0, button: 'left' }`)
12359	* @example
12360	* await ui.pointer({ type: 'down', x: 2, y: 0, button: 'left' })
12361	*/
12362	pointer: (event: MountPointerEvent) => Promise<void>;
12363	/**
12364	* Posts as a `Client`'s own `surface.post(data)` does: the plugin's
12365	* `ui.message` hooks run with `e.data`, `e.surface` this drawing's.
12366	*
12367	* A `{ props }` they answer reaches the instance, which redraws with
12368	* its state kept.
12369	*
12370	* @param data plain data (JsonValue)
12371	* @param scope `{ in }`: which `Client`, when the drawing holds several
12372	* @example
12373	* await ui.post({ pick: 2 })
12374	*/
12375	post: (data: JsonValue, scope?: ClientScope) => Promise<void>;
12376	/**
12377	* Moves the drawing's frame clock on: each `surface.every(ms, fn)` timer
12378	* of its `Client`s fires at every interval of its own the move crosses.
12379	*
12380	* @param ms how far, in milliseconds
12381	* @example
12382	* await ui.advance(250)
12383	*/
12384	advance: (ms: number) => Promise<void>;
12385	/**
12386	* Lays a `Client`'s region out at a size, as the surface measuring it
12387	* does: what its module reads as `surface.columns` and `surface.rows`.
12388	*
12389	* @param size cells across and down; `in`: which `Client`
12390	* @example
12391	* await ui.resize({ columns: 40, rows: 3 })
12392	*/
12393	resize: (size: MountResizeTarget) => Promise<void>;
12394	/**
12395	* Draws the instance again, as the engine does when its props change (a
12396	* tool row's output arrived): the `ui.render` chain with the next props.
12397	*
12398	* A plugin's own `$.ui.invalidate` needs no call: the drawing follows it
12399	* before the next read.
12400	*
12401	* @param props the component's next props; the current ones when absent
12402	* @example
12403	* await ui.redraw({ ...TOOL_ROW, isRunning: false, output: 'done' })
12404	*/
12405	redraw: (props?: RenderPropsOf[C]) => Promise<void>;
12406	/**
12407	* Lets the drawing go, as the surface dropping the instance does: its
12408	* `Client`s and their timers end. Later acts on the handle reject.
12409	*
12410	* @example
12411	* await ui.unmount()
12412	*/
12413	unmount: () => Promise<void>;
12414	};
12415
12416	/**
12417	* What a mounted drawing's `input` takes: the Input's key, the text, which
12418	* of the two inputs it is (`submit` when unsaid), another plugin's name.
12419	*/
12420	export type MountInputTarget = {
12421	key: string;
12422	text: string;
12423	kind?: UiInputArgument['kind'];
12424	plugin?: string;
12425	};
12426
12427	/**
12428	* What a mounted drawing's `key` takes: the key as a `Client`'s `onKey`
12429	* listener receives it (ClientKeyEvent), and which `Client` when several.
12430	*/
12431	export type MountKeyEvent = ClientKeyEvent & ClientScope;
12432
12433	/**
12434	* What a mounted drawing's `pointer` takes: the event as a `Client`'s
12435	* `onPointer` listener receives it, in its region's cells, and which one.
12436	*/
12437	export type MountPointerEvent = ClientPointerEvent & ClientScope;
12438
12439	/**
12440	* What a mounted drawing's `press` takes: the Button's key, another
12441	* plugin's name when the Button is not the mounted plugin's, a link.
12442	*/
12443	export type MountPressTarget = {
12444	key: string;
12445	plugin?: string;
12446	/**
12447	* Presses this link of the Markdown keyed `key` instead of a Button.
12448	*/
12449	link?: PressedLink;
12450	};
12451
12452	/**
12453	* What a mounted drawing's `resize` takes: a `Client` region's size in
12454	* cells, as the surface measuring it hands it, and which `Client`.
12455	*/
12456	export type MountResizeTarget = {
12457	columns: number;
12458	rows: number;
12459	in?: string;
12460	};
12461
12462	/**
12463	* What a mounted drawing's `select` takes: the Select's key, the picked
12464	* option's value, another plugin's name when the Select is not its own.
12465	*/
12466	export type MountSelectTarget = {
12467	key: string;
12468	value: string;
12469	plugin?: string;
12470	};
12471
12472	/**
12473	* What `$.ui.mount` takes: whose elements the test will act on, the surface
12474	* that draws, and the component instance the engine asks the plugins for.
12475	*
12476	* The envelope a `ui.render` hook sees as `e` (`surface`, `component`,
12477	* `requestId`, `viewport`, `props`) plus `plugin`. `surface` is never
12478	* defaulted: one body run over several surfaces is what shows independence.
12479	*
12480	* @example
12481	* $.ui.mount({ plugin: 'notes', surface, component: 'Pane', props: PANE })
12482	*/
12483	export type MountTarget<P extends RenderSurface = RenderSurface, C extends RenderComponent = RenderComponent> = {
12484	/**
12485	* Whose elements the handle's acts address by bare `key`: the plugin
12486	* under test, usually. An act names another plugin to reach its element.
12487	*/
12488	plugin: string;
12489	/**
12490	* What draws: its element table validates every tree the plugins
12491	* return, and every dispatch the handle raises carries it as `e.surface`.
12492	*
12493	* One of `terminal`, `desktop`, `vscode`, `mobile`.
12494	*/
12495	surface: P;
12496	/**
12497	* Which component the engine asks the plugins to draw (`Pane`,
12498	* `AbovePrompt`, `ToolUse`, ...): what a `ui.render` matcher narrows on.
12499	*/
12500	component: C;
12501	/**
12502	* The component's props, what the hook reads as `e.props`.
12503	*/
12504	props: RenderPropsOf[C];
12505	/**
12506	* The instance drawn (a pane's id, a tool row's tool_use_id); one is
12507	* minted when absent. Two mounts of one component are two instances.
12508	*/
12509	requestId?: string;
12510	/**
12511	* What the surface measured, as the hook reads it under `e.viewport`;
12512	* absent when the surface has not measured, as on `e`.
12513	*
12514	* Cells across and down in the surface's monospace metric and whether it
12515	* docks a pane. A `Client` in the drawing starts laid out at this size
12516	* (0 by 0 when absent) until the handle's `resize` lays its region out.
12517	*/
12518	viewport?: RenderViewport;
12519	};
12520
12521	/**
12522	* A set of checks and, under `not`, the same set passing where they fail.
12523	*/
12524	export type Negatable<M> = M & {
12525	/**
12526	* The checks negated.
12527	*/
12528	not: M;
12529	};
12530
12531	/**
12532	* Written inline in a test and loaded as a plugin folder is: its name, the
12533	* tier it loads in (`user` when not given), and its hooks module's `register`.
12534	*
12535	* `register` is written `register(on) { ... }` and is self-contained, as a
12536	* module's is: it closes over nothing of the test file.
12537	*/
12538	export type Plugin = {
12539	name: string;
12540	tier?: PluginTier;
12541	register: Register;
12542	};
12543
12544	/**
12545	* A tier a plugin loads in: every tier but the engine's own.
12546	*/
12547	export type PluginTier = Exclude<Tier, 'core'>;
12548
12549	/**
12550	* What `$.ui.press` takes: the plugin whose `ui.render` hook drew the element,
12551	* the `key` it gave it, the instance and surface when several, a `link`.
12552	*/
12553	export type PressTarget = {
12554	plugin: string;
12555	key: string;
12556	/**
12557	* Which instance holds it, when the plugin drew the key in several.
12558	*/
12559	requestId?: string;
12560	/**
12561	* Which surface's drawing, when the key is drawn on more than one; the
12562	* press carries the surface of the drawing it lands in either way.
12563	*/
12564	surface?: RenderSurface;
12565	/**
12566	* For a Markdown answering its links: which of them the press lands on.
12567	*/
12568	link?: PressedLink;
12569	};
12570
12571	/**
12572	* One test: it passes when its body returns or resolves, and fails when it
12573	* throws, rejects or outlasts its time (5000 ms, or `timeoutMs`).
12574	*
12575	* The body gets the engine's `$` and an `on` whose hooks sit beneath every
12576	* plugin; `plugins` load inline plugins beside the one under test. A failure
12577	* carries what the engine reported meanwhile: each hook it skipped, and why.
12578	*
12579	* @param name the test's name, led in its title by the describes around it
12580	* @param rest the body, `($, on) => ...`, or the options then the body
12581	*/
12582	export const test: (name: string, ...rest: TestRest) => void;
12583
12584	/**
12585	* A test: the engine's `$`, and `on`, a plugin's registrar, whose hooks sit
12586	* beneath every plugin; beneath them the bottom hook throws, naming its event.
12587	*
12588	* The plugins load at the test's first call on `$`, so a test registers its
12589	* hooks before it, as a module registers its own in `register()`.
12590	*/
12591	export type TestBody = ($: Engine, on: On) => unknown;
12592
12593	/**
12594	* What `test` takes beside its name: the inline plugins it loads beside the
12595	* one under test, and how long it may run (5000 ms when not given).
12596	*/
12597	export type TestOptions = {
12598	plugins?: readonly Plugin[];
12599	timeoutMs?: number;
12600	};
12601
12602	/**
12603	* What follows a test's name: its body, or its options then its body.
12604	*/
12605	export type TestRest = readonly [body: TestBody] \| readonly [options: TestOptions, body: TestBody];
12606
12607	/**
12608	* What `toThrow` compares the thrown error with: a substring or pattern of
12609	* its message, its class, a value carrying the whole message, or nothing.
12610	*/
12611	export type ThrowExpectation = string \| RegExp \| Constructor \| WithMessage;
12612
12613	/**
12614	* Says which tier the plugin under test loads in, once, at the top of the
12615	* file: `prepend`, `user` (when unsaid), `append` or `builtin`.
12616	*
12617	* @param tier the tier
12618	*/
12619	export const tier: (tier: PluginTier) => void;
12620
12621	/**
12622	* An error-like value `toThrow` compares by its whole message.
12623	*/
12624	export type WithMessage = {
12625	message: string;
12626	};
12627	}
12628
12629	// The inputs of the built-in tools this build has, from each tool's
12630	// input schema. Merges into ToolCallInput (BuiltinToolInputs) so
12631	// `e.tool === "Bash"` narrows to the tool's arguments.
12632	declare module 'claude-code' {
12633	interface BuiltinToolInputs {
12634	Agent: {
12635	/** A short (3-5 word) description of the task */
12636	description: string
12637	/** The task for the agent to perform */
12638	prompt: string
12639	/** The type of specialized agent to use for this task */
12640	subagent_type?: string
12641	/** Optional model override for this agent. Takes precedence over the agent definition's model frontmatter and the configured default subagent model. If omitted, uses the agent definition's model, else the default (inherits from the parent unless a default subagent model is configured). Ignored for subagent_type: "fork" — forks always inherit the parent model. */
12642	model?: "sonnet" \| "opus" \| "haiku" \| "fable"
12643	/** Agents run in the background by default; you will be notified when one completes. Set to false only when your very next action depends on this agent's result and nothing else could usefully happen while it runs — otherwise leave it in the background so the user can hand you other work. */
12644	run_in_background?: boolean
12645	/** Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running. */
12646	name?: string
12647	/** Deprecated; ignored. The session has a single implicit team. */
12648	team_name?: string
12649	/** Deprecated; ignored. Subagents inherit the parent session's permission mode; agent-definition frontmatter may override it. */
12650	mode?: "acceptEdits" \| "auto" \| "bypassPermissions" \| "default" \| "dontAsk" \| "plan"
12651	/** Isolation mode. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo. "remote" launches the agent in a remote cloud environment (always runs in background; availability is gated). */
12652	isolation?: "worktree" \| "remote"
12653	}
12654	Bash: {
12655	/** The command to execute */
12656	command: string
12657	/** Optional timeout in milliseconds (max 600000) */
12658	timeout?: number
12659	/** Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does. Say what the command does in plain words: do not echo the command's text, its flags, or file paths - the user reads this description, often without seeing the command. For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words): - ls → "List files in current directory" - git status → "Show working tree status" - npm install → "Install package dependencies" For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does: - find . -name ".tmp" -exec rm {} \; → "Find and delete all .tmp files recursively" - git reset --hard origin/main → "Discard all local changes and match remote main" - curl -s url \| jq '.data[]' → "Fetch JSON from URL and extract data array elements" /
12660	description?: string
12661	/** Set to true to run this command in the background. */
12662	run_in_background?: boolean
12663	/** Set this to true to dangerously override sandbox mode and run commands without sandboxing. */
12664	dangerouslyDisableSandbox?: boolean
12665	}
12666	CronCreate: {
12667	/** Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "* /5 * * * " = every 5 minutes, "30 14 28 2 " = Feb 28 at 2:30pm local once). */
12668	cron: string
12669	/** The prompt to enqueue at each fire time. */
12670	prompt: string
12671	/** true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month. */
12672	recurring?: boolean
12673	/** true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions. */
12674	durable?: boolean
12675	}
12676	CronDelete: {
12677	/** Job ID returned by CronCreate. */
12678	id: string
12679	}
12680	CronList: {}
12681	Edit: {
12682	/** The absolute path to the file to modify */
12683	file_path: string
12684	/** The text to replace */
12685	old_string: string
12686	/** The text to replace it with (must be different from old_string) */
12687	new_string: string
12688	/** Replace all occurrences of old_string (default false) */
12689	replace_all?: boolean
12690	}
12691	EnterWorktree: {
12692	/** Optional name for a new worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided. Mutually exclusive with `path`. */
12693	name?: string
12694	/** Path to an existing worktree to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo — or, on first entry from the launch directory, for a repo nested inside it (multi-repo workspace). Mutually exclusive with `name`. */
12695	path?: string
12696	}
12697	ExitWorktree: {
12698	/** "keep" leaves the worktree and branch on disk; "remove" deletes both. */
12699	action: "keep" \| "remove"
12700	/** Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise. */
12701	discard_changes?: boolean
12702	}
12703	ListAgents: {
12704	/** Not available in this build; leave unset. */
12705	channel?: string
12706	/** Not available in this build; leave unset. */
12707	q?: string
12708	}
12709	NotebookEdit: {
12710	/** The absolute path to the Jupyter notebook file to edit (must be absolute, not relative) */
12711	notebook_path: string
12712	/** The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified. */
12713	cell_id?: string
12714	/** The new source for the cell */
12715	new_source: string
12716	/** The type of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required. */
12717	cell_type?: "code" \| "markdown"
12718	/** The type of edit to make (replace, insert, delete). Defaults to replace. */
12719	edit_mode?: "replace" \| "insert" \| "delete"
12720	}
12721	PowerShell: {
12722	/** The PowerShell command to execute */
12723	command: string
12724	/** Optional timeout in milliseconds (max 600000) */
12725	timeout?: number
12726	/** Clear, concise description of what this command does in active voice. */
12727	description?: string
12728	/** Set to true to run this command in the background. */
12729	run_in_background?: boolean
12730	/** Set this to true to dangerously override sandbox mode and run commands without sandboxing. */
12731	dangerouslyDisableSandbox?: boolean
12732	}
12733	Read: {
12734	/** The absolute path to the file to read */
12735	file_path: string
12736	/** The line number to start reading from. Only provide if the file is too large to read at once */
12737	offset?: number
12738	/** The number of lines to read. Only provide if the file is too large to read at once. */
12739	limit?: number
12740	/** Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum 20 pages per request. */
12741	pages?: string
12742	}
12743	ReportFindings: {
12744	/** Effort level the review ran at */
12745	level?: "low" \| "medium" \| "high" \| "xhigh" \| "max"
12746	/** Verified findings, most-severe first; empty if none survived */
12747	findings: Array<{
12748	/** Repo-relative path of the file the finding is in */
12749	file: string
12750	/** 1-indexed line the finding anchors to */
12751	line?: number
12752	/** One-sentence statement of the defect */
12753	summary: string
12754	/** Compressed label for compact UI (≤60 chars): the claim alone, no rationale or consequence clause */
12755	short_summary?: string
12756	/** Concrete inputs/state → wrong output/crash */
12757	failure_scenario: string
12758	/** Short kebab-case slug of the finding type, e.g. "correctness", "simplification", "efficiency", "test-coverage" */
12759	category?: string
12760	/** Set when a verify pass ran; absent on inline-only reviews */
12761	verdict?: "CONFIRMED" \| "PLAUSIBLE"
12762	/** Set ONLY when re-reporting after applying fixes: what happened to this finding */
12763	outcome?: "fixed" \| "skipped" \| "no_change_needed"
12764	}>
12765	}
12766	ScheduleWakeup: {
12767	/** Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless `stop` is true. */
12768	delaySeconds?: number
12769	/** One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific. Required unless `stop` is true. */
12770	reason?: string
12771	/** The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing re-enters the skill and continues the loop. For autonomous /loop (no user prompt), pass the literal sentinel `<<autonomous-loop-dynamic>>` instead (the dynamic-pacing variant, not the CronCreate-mode `<<autonomous-loop>>`). Required unless `stop` is true. */
12772	prompt?: string
12773	/** Set to true to end the dynamic loop immediately instead of scheduling another wakeup. When true, all other fields are ignored and no further wakeups fire. */
12774	stop?: boolean
12775	/** true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless `stop` is true. */
12776	noop?: boolean
12777	}
12778	SendMessage: {
12779	/** Recipient: a name from ListAgents (append its " [ref]" only when a listing or an error shows one), a teammate name, "main", or a background agent's agentId */
12780	to: unknown & unknown
12781	/** A 5-10 word label for your own transcript row (not transmitted — the recipient previews the first line of `message`). Truncated to 200 characters rather than rejected. */
12782	summary?: string
12783	/** Plain text message content. The recipient's human sees only the FIRST LINE as a one-line preview until they expand it, so make the first line a clear, self-contained sentence saying what this is about — not a greeting, preamble, or bare @-mention. */
12784	message: string
12785	/** Ask a session ON THIS MACHINE to send you ONE notice when it next goes idle (finishes its turn with nothing queued) or exits — opt-in, one-shot, no polling. With a message: deliver it now AND subscribe. Without a message (omit it): a pure subscription that costs the other session nothing. */
12786	notify_when_idle?: boolean
12787	}
12788	Skill: {
12789	/** The name of a skill from the available-skills list. Do not guess names. */
12790	skill: string
12791	/** Optional arguments for the skill */
12792	args?: string
12793	}
12794	TaskOutput: {
12795	/** The task ID to get output from */
12796	task_id: string
12797	/** Whether to wait for completion */
12798	block: boolean
12799	/** Max wait time in ms */
12800	timeout: number
12801	}
12802	TaskStop: {
12803	/** The ID of the background task to stop. Agent-team teammates and named background agents are also accepted by agent ID or name. */
12804	task_id?: string
12805	/** Deprecated: use task_id instead */
12806	shell_id?: string
12807	}
12808	ToolSearch: {
12809	/** Query to find deferred tools. Use "select:<tool_name>" for direct selection, or keywords to search. */
12810	query: string
12811	/** Maximum number of results to return (default: 5) */
12812	max_results: number
12813	}
12814	WebFetch: {
12815	/** The URL to fetch content from */
12816	url: string
12817	/** The prompt to run on the fetched content */
12818	prompt: string
12819	}
12820	WebSearch: {
12821	/** The search query to use */
12822	query: string
12823	/** Only include search results from these domains */
12824	allowed_domains?: string[]
12825	/** Never include search results from these domains */
12826	blocked_domains?: string[]
12827	}
12828	Workflow: {
12829	/** Self-contained workflow script. Must begin with `export const meta = { name, description, phases }` (pure literal, no computed values) followed by the script body using agent()/parallel()/pipeline()/phase(). */
12830	script?: string
12831	/** Name of a predefined workflow (built-in or from .claude/workflows/). Resolves to a self-contained script. */
12832	name?: string
12833	/** Ignored — set the workflow description in the script's `meta` block. */
12834	description?: string
12835	/** Ignored — set the workflow title in the script's `meta` block. */
12836	title?: string
12837	/** Optional input value exposed to the script as the global `args`, verbatim. Pass arrays/objects as actual JSON values, NOT as a JSON-encoded string — a stringified list breaks `args.filter`/`args.map` in the script. Use for parameterized named workflows (e.g. a research question). */
12838	args?: unknown
12839	/** Path to a workflow script file on disk. Every Workflow invocation persists its script under the session directory and returns the path in the tool result. To iterate, edit that file with Write/Edit and re-invoke Workflow with the same `scriptPath` instead of re-sending the full script. Takes precedence over `script` and `name`. */
12840	scriptPath?: string
12841	/** Run ID of a prior Workflow invocation to resume from. Completed agent() calls with unchanged (prompt, opts) return their cached results instantly; only edited or new calls re-run. Same-session only. Stop the prior run first (TaskStop) before resuming. */
12842	resumeFromRunId?: string
12843	}
12844	Write: {
12845	/** The absolute path to the file to write (must be absolute, not relative) */
12846	file_path: string
12847	/** The content to write to the file */
12848	content: string
12849	}
12850	}
12851	}
12852
12853	// The structured results of the same tools, from each tool's output
12854	// schema. Merges into ToolCallResult (BuiltinToolResults) so after
12855	// `e.tool === "Bash"` the `result` of `next(e)` is the tool's record.
12856	declare module 'claude-code' {
12857	interface BuiltinToolResults {
12858	Agent: {
12859	agentId: string
12860	/** @internal Count of leading harness-authored content blocks (hand-back provenance bookkeeping; not a stable consumer field) */
12861	harnessNoteCount?: number
12862	/** @internal Count of trailing harness-authored content blocks (hand-back provenance bookkeeping; not a stable consumer field) */
12863	harnessTailCount?: number
12864	/** @internal Fingerprint binding the harness section counts to the exact content they were computed against; a hook rewrite invalidates the counts rather than misplacing rewritten bytes */
12865	harnessSectionHash?: string
12866	agentType?: string
12867	/** @internal How the report reached this result under the subagent hand-back contract: 'send' = the child's classified SubagentHandback delivery, 'flagged' = that delivery under a SECURITY WARNING, 'withheld' = nothing was delivered (not a stable consumer field) */
12868	handback?: "send" \| "flagged" \| "withheld"
12869	content: Array<{
12870	type: "text"
12871	text: string
12872	citations?: unknown[] \| null
12873	}>
12874	resolvedModel?: string
12875	modelsUsed?: string[]
12876	totalToolUseCount: number
12877	totalDurationMs: number
12878	totalTokens: number
12879	usage: {
12880	input_tokens: number
12881	output_tokens: number
12882	cache_creation_input_tokens: number \| null
12883	cache_read_input_tokens: number \| null
12884	server_tool_use: {
12885	web_search_requests: number
12886	web_fetch_requests: number
12887	} \| null
12888	service_tier: string \| null
12889	cache_creation: {
12890	ephemeral_1h_input_tokens: number
12891	ephemeral_5m_input_tokens: number
12892	} \| null
12893	inference_geo?: string \| null
12894	speed?: string \| null
12895	iterations?: unknown
12896	output_tokens_details?: {
12897	thinking_tokens?: number \| null
12898	} \| null
12899	}
12900	toolStats?: {
12901	readCount: number
12902	searchCount: number
12903	bashCount: number
12904	editFileCount: number
12905	linesAdded: number
12906	linesRemoved: number
12907	otherToolCount: number
12908	frameCount?: number
12909	}
12910	status: "completed"
12911	prompt: string
12912	worktreePath?: string
12913	worktreeBranch?: string
12914	} \| {
12915	status: "async_launched"
12916	isAsync?: true
12917	/** The ID of the async agent */
12918	agentId: string
12919	/** The description of the task */
12920	description: string
12921	/** Model in use at the backgrounding transition (a pre-background swap is reflected here) */
12922	resolvedModel?: string
12923	/** Ordered distinct models used before backgrounding (length > 1 means a mid-run swap) */
12924	modelsUsed?: string[]
12925	/** The prompt for the agent */
12926	prompt: string
12927	/** Path to the output file for checking agent progress */
12928	outputFile: string
12929	/** Whether the calling agent has Read/Bash tools to check progress */
12930	canReadOutputFile?: boolean
12931	} \| {
12932	status: "remote_launched"
12933	/** The ID of the remote agent task */
12934	taskId: string
12935	/** The URL of the cloud session */
12936	sessionUrl: string
12937	/** The description of the task */
12938	description: string
12939	/** The prompt for the agent */
12940	prompt: string
12941	/** Path to the output file for checking agent progress */
12942	outputFile: string
12943	}
12944	Bash: {
12945	/** The standard output of the command */
12946	stdout: string
12947	/** The standard error output of the command */
12948	stderr: string
12949	/** Path to raw output file for large MCP tool outputs */
12950	rawOutputPath?: string
12951	/** Whether the command was interrupted */
12952	interrupted: boolean
12953	/** Flag to indicate if stdout contains image data */
12954	isImage?: boolean
12955	/** ID of the background task if command is running in background */
12956	backgroundTaskId?: string
12957	/** True if the user manually backgrounded the command with Ctrl+B */
12958	backgroundedByUser?: boolean
12959	/** @internal True if a plugin's turn abort moved the running command to the background */
12960	backgroundedByTurnAbort?: boolean
12961	/** @internal True if the command was moved to the background so a message queued for the model could reach it */
12962	backgroundedToDeliverMessage?: boolean
12963	/** Set when the command hit its timeout and was auto-backgrounded; the timeout value in ms */
12964	timedOutAfterMs?: number
12965	/** Model-facing note that the session cwd was not changed by a backgrounded command containing a directory-change builtin (cd/pushd/popd/chdir) */
12966	backgroundCwdHint?: string
12967	/** True when this backgrounded command is owned by a synchronous subagent and is therefore terminated when that agent gives its final response; absent when the command survives (main loop, async subagents) */
12968	backgroundEndsWithFinalResponse?: true
12969	/** Flag to indicate if sandbox mode was overridden */
12970	dangerouslyDisableSandbox?: boolean
12971	/** Semantic interpretation for non-error exit codes with special meaning */
12972	returnCodeInterpretation?: string
12973	/** Whether the command is expected to produce no output on success */
12974	noOutputExpected?: boolean
12975	/** Structured content blocks */
12976	structuredContent?: unknown[]
12977	/** Path to the persisted full output in tool-results dir (set when output is too large for inline) */
12978	persistedOutputPath?: string
12979	/** Total size of the output in bytes (set when output is too large for inline) */
12980	persistedOutputSize?: number
12981	/** Model-facing note listing readFileState entries whose mtime bumped during this command (set when WRITE_COMMAND_MARKERS matches) */
12982	staleReadFileStateHint?: string
12983	/** Model-facing system-reminder appended when a gh command reports a GitHub API rate-limit error */
12984	ghRateLimitHint?: string
12985	/** Structured classification of git/gh operations detected in this command (commit/push/merge/rebase/PR). Client-facing — lets clients render git activity without re-parsing stdout; not surfaced to the model. */
12986	gitOperation?: {
12987	commit?: {
12988	sha: string
12989	kind: "committed" \| "amended" \| "cherry-picked"
12990	branch?: string
12991	}
12992	push?: {
12993	branch: string
12994	}
12995	branch?: {
12996	ref: string
12997	action: "merged" \| "rebased"
12998	}
12999	pr?: {
13000	number: number
13001	url?: string
13002	action: "created" \| "edited" \| "merged" \| "commented" \| "closed" \| "reopened" \| "ready" \| "draft" \| "auto-merge-enabled" \| "auto-merge-disabled"
13003	}
13004	}
13005	/** @internal Per-file diff of the working-tree changes this command made, for rendering and for PostToolUse Bash hooks (changedFiles: absolute paths of every changed file known, shown or not, at most 200; cut when shorter than files.length + moreFiles); not surfaced to the model. */
13006	bashEditDiff?: {
13007	files: {
13008	filePath: string
13009	hunks: {
13010	oldStart: number
13011	oldLines: number
13012	newStart: number
13013	newLines: number
13014	lines: string[]
13015	}[]
13016	created?: true
13017	deleted?: true
13018	}[]
13019	moreFiles: number
13020	changedFiles?: string[]
13021	unavailable?: true
13022	skipped?: true
13023	shared?: true
13024	}
13025	}
13026	CronCreate: {
13027	id: string
13028	humanSchedule: string
13029	recurring: boolean
13030	durable?: boolean
13031	}
13032	CronDelete: {
13033	id: string
13034	}
13035	CronList: {
13036	jobs: {
13037	id: string
13038	cron: string
13039	humanSchedule: string
13040	prompt: string
13041	recurring?: boolean
13042	durable?: boolean
13043	}[]
13044	}
13045	Edit: {
13046	/** The file path that was edited */
13047	filePath: string
13048	/** The original string that was replaced */
13049	oldString: string
13050	/** The new string that replaced it */
13051	newString: string
13052	/** The original file contents before editing */
13053	originalFile: string \| null
13054	/** Diff patch showing the changes */
13055	structuredPatch: {
13056	oldStart: number
13057	oldLines: number
13058	newStart: number
13059	newLines: number
13060	lines: string[]
13061	}[]
13062	/** Whether the user modified the proposed changes */
13063	userModified: boolean
13064	/** Whether all occurrences were replaced */
13065	replaceAll: boolean
13066	gitDiff?: {
13067	filename: string
13068	status: "modified" \| "added"
13069	additions: number
13070	deletions: number
13071	changes: number
13072	patch: string
13073	/** GitHub owner/repo when available */
13074	repository?: string \| null
13075	}
13076	/** True when the edit was held for the machine owner to review instead of written; the file is unchanged */
13077	staged?: boolean
13078	}
13079	EnterWorktree: {
13080	worktreePath: string
13081	worktreeBranch?: string
13082	message: string
13083	}
13084	ExitWorktree: {
13085	action: "keep" \| "remove"
13086	originalCwd: string
13087	worktreePath: string
13088	worktreeBranch?: string
13089	tmuxSessionName?: string
13090	discardedFiles?: number
13091	discardedCommits?: number
13092	message: string
13093	}
13094	ListAgents: {
13095	/** Formatted list of reachable agents */
13096	listing: string
13097	}
13098	NotebookEdit: {
13099	/** The new source code that was written to the cell */
13100	new_source: string
13101	/** The previous cell source (replace/delete only). Enables cell-relative diff rendering without re-reading the notebook. */
13102	old_source?: string
13103	/** The ID of the cell that was edited */
13104	cell_id?: string
13105	/** The type of the cell */
13106	cell_type: "code" \| "markdown"
13107	/** The programming language of the notebook */
13108	language: string
13109	/** The edit mode that was used */
13110	edit_mode: string
13111	/** Error message if the operation failed */
13112	error?: string
13113	/** The path to the notebook file */
13114	notebook_path: string
13115	/** The original notebook content before modification */
13116	original_file: string
13117	/** The updated notebook content after modification */
13118	updated_file: string
13119	}
13120	PowerShell: {
13121	/** The standard output of the command */
13122	stdout: string
13123	/** The standard error output of the command */
13124	stderr: string
13125	/** Whether the command was interrupted */
13126	interrupted: boolean
13127	/** Semantic interpretation for non-error exit codes with special meaning */
13128	returnCodeInterpretation?: string
13129	/** Flag to indicate if stdout contains image data */
13130	isImage?: boolean
13131	/** Path to persisted full output when too large for inline */
13132	persistedOutputPath?: string
13133	/** Total output size in bytes when persisted */
13134	persistedOutputSize?: number
13135	/** ID of the background task if command is running in background */
13136	backgroundTaskId?: string
13137	/** True if the user manually backgrounded the command with Ctrl+B */
13138	backgroundedByUser?: boolean
13139	/** @internal True if a plugin's turn abort moved the running command to the background */
13140	backgroundedByTurnAbort?: boolean
13141	/** @internal True if the command was moved to the background so a message queued for the model could reach it */
13142	backgroundedToDeliverMessage?: boolean
13143	/** Set when the command hit its timeout and was auto-backgrounded; the timeout value in ms */
13144	timedOutAfterMs?: number
13145	/** True when this backgrounded command is owned by a synchronous subagent and is therefore terminated when that agent gives its final response; absent when the command survives (main loop, async subagents) */
13146	backgroundEndsWithFinalResponse?: true
13147	/** Structured classification of git/gh operations detected in this command (commit/push/merge/rebase/PR). Client-facing — lets clients render git activity without re-parsing stdout; not surfaced to the model. */
13148	gitOperation?: {
13149	commit?: {
13150	sha: string
13151	kind: "committed" \| "amended" \| "cherry-picked"
13152	branch?: string
13153	}
13154	push?: {
13155	branch: string
13156	}
13157	branch?: {
13158	ref: string
13159	action: "merged" \| "rebased"
13160	}
13161	pr?: {
13162	number: number
13163	url?: string
13164	action: "created" \| "edited" \| "merged" \| "commented" \| "closed" \| "reopened" \| "ready" \| "draft" \| "auto-merge-enabled" \| "auto-merge-disabled"
13165	}
13166	}
13167	}
13168	Read: {
13169	type: "text"
13170	file: {
13171	/** The path to the file that was read */
13172	filePath: string
13173	/** The content of the file */
13174	content: string
13175	/** Number of lines in the returned content */
13176	numLines: number
13177	/** The starting line number */
13178	startLine: number
13179	/** Total number of lines in the file */
13180	totalLines: number
13181	/** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). A programmatic signal for internal consumers; survives output reconstruction (unlike the render-time banner). */
13182	truncatedByTokenCap?: boolean
13183	}
13184	/** Set when this Read completed a saved Artifact source file: the Artifact and the version of it that now counts as viewed. */
13185	artifactRead?: {
13186	slug: string
13187	ver: string
13188	}
13189	} \| {
13190	type: "image"
13191	file: {
13192	/** Base64-encoded image data */
13193	base64: string
13194	/** The MIME type of the image */
13195	type: "image/jpeg" \| "image/png" \| "image/gif" \| "image/webp"
13196	/** Original file size in bytes */
13197	originalSize: number
13198	/** Image dimension info for coordinate mapping */
13199	dimensions?: {
13200	/** Original image width in pixels */
13201	originalWidth?: number
13202	/** Original image height in pixels */
13203	originalHeight?: number
13204	/** Displayed image width in pixels (after resizing) */
13205	displayWidth?: number
13206	/** Displayed image height in pixels (after resizing) */
13207	displayHeight?: number
13208	}
13209	}
13210	} \| {
13211	type: "notebook"
13212	file: {
13213	/** The path to the notebook file */
13214	filePath: string
13215	/** Array of notebook cells */
13216	cells: unknown[]
13217	}
13218	} \| {
13219	type: "pdf"
13220	file: {
13221	/** The path to the PDF file */
13222	filePath: string
13223	/** Base64-encoded PDF data */
13224	base64: string
13225	/** Original file size in bytes */
13226	originalSize: number
13227	}
13228	} \| {
13229	type: "parts"
13230	file: {
13231	/** The path to the PDF file */
13232	filePath: string
13233	/** Original file size in bytes */
13234	originalSize: number
13235	/** Number of pages extracted */
13236	count: number
13237	/** Directory containing extracted page images */
13238	outputDir: string
13239	}
13240	/** Document page number of the first extracted page (1 when no range was requested); labels the page images in the model-facing tool_result */
13241	firstPage?: number
13242	/** Extracted page images, in page order. Present only transiently in-process: the page image bytes are delivered solely as image blocks in the model-facing tool_result content and are not retained on the tool_use_result, so this key is absent on the emitted/persisted result */
13243	pages?: Array<{
13244	/** Base64-encoded page image; empty when the page could not be processed */
13245	base64: string
13246	/** The MIME type of the image */
13247	mediaType: "image/jpeg" \| "image/png" \| "image/gif" \| "image/webp"
13248	/** Why the page could not be processed as an image; set only when base64 is empty */
13249	error?: string
13250	}>
13251	} \| {
13252	type: "file_unchanged"
13253	file: {
13254	/** The path to the file */
13255	filePath: string
13256	}
13257	/** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result */
13258	source?: "seeded"
13259	}
13260	ReportFindings: {
13261	/** Number of findings reported */
13262	count: number
13263	/** Effort level the review ran at */
13264	level?: "low" \| "medium" \| "high" \| "xhigh" \| "max"
13265	/** Echoed for the result body */
13266	findings: Array<{
13267	/** Repo-relative path of the file the finding is in */
13268	file: string
13269	/** 1-indexed line the finding anchors to */
13270	line?: number
13271	/** One-sentence statement of the defect */
13272	summary: string
13273	/** Compressed label for compact UI (≤60 chars): the claim alone, no rationale or consequence clause */
13274	short_summary?: string
13275	/** Concrete inputs/state → wrong output/crash */
13276	failure_scenario: string
13277	/** Short kebab-case slug of the finding type, e.g. "correctness", "simplification", "efficiency", "test-coverage" */
13278	category?: string
13279	/** Set when a verify pass ran; absent on inline-only reviews */
13280	verdict?: "CONFIRMED" \| "PLAUSIBLE"
13281	/** Set ONLY when re-reporting after applying fixes: what happened to this finding */
13282	outcome?: "fixed" \| "skipped" \| "no_change_needed"
13283	}>
13284	}
13285	ScheduleWakeup: {
13286	/** Epoch ms timestamp when the next wakeup will fire */
13287	scheduledFor: number
13288	/** Actual delay used after clamping to runtime bounds */
13289	clampedDelaySeconds: number
13290	/** True if the requested delaySeconds was outside [60, 3600] */
13291	wasClamped: boolean
13292	/** True when the model ended the loop via `stop: true` */
13293	stopped?: boolean
13294	/** How many pending dynamic-loop wakeups stop:true cancelled. 0 means nothing was pending — a recurring /loop cron is not cancelled by stop:true. */
13295	cancelledWakeups?: number
13296	}
13297	SendMessage: unknown
13298	Skill: {
13299	/** Whether the skill is valid */
13300	success: boolean
13301	/** The name of the skill */
13302	commandName: string
13303	/** Tools allowed by this skill */
13304	allowedTools?: string[]
13305	/** Resolved model the skill turn runs on when a frontmatter model override took effect; omitted otherwise */
13306	model?: string
13307	/** Execution status */
13308	status?: "inline"
13309	/** True when the skill instructions were loaded read-only (nothing was executed) */
13310	readOnly?: boolean
13311	} \| {
13312	/** Whether the skill completed successfully */
13313	success: boolean
13314	/** The name of the skill */
13315	commandName: string
13316	/** Execution status */
13317	status: "forked"
13318	/** The ID of the sub-agent that executed the skill */
13319	agentId: string
13320	/** The result from the forked skill execution */
13321	result: string
13322	/** True when the sub-agent was launched in the background: `result` describes the launch, and the skill outcome arrives later as a task notification. */
13323	background?: boolean
13324	}
13325	TaskOutput: unknown
13326	TaskStop: {
13327	/** Status message about the operation */
13328	message: string
13329	/** The ID of the task that was stopped */
13330	task_id: string
13331	/** The type of the task that was stopped */
13332	task_type: string
13333	/** The command or description of the stopped task */
13334	command?: string
13335	}
13336	ToolSearch: {
13337	matches: string[]
13338	query: string
13339	total_deferred_tools: number
13340	pending_mcp_servers?: string[]
13341	failed_mcp_servers?: {
13342	name: string
13343	errorCode?: string
13344	error?: string
13345	}[]
13346	}
13347	WebFetch: {
13348	/** Size of the fetched content in bytes */
13349	bytes: number
13350	/** HTTP response code */
13351	code: number
13352	/** HTTP response code text */
13353	codeText: string
13354	/** Processed result from applying the prompt to the content */
13355	result: string
13356	/** Time taken to fetch and process the content */
13357	durationMs: number
13358	/** The URL that was fetched */
13359	url: string
13360	artifactRead?: {
13361	slug: string
13362	ver?: string
13363	seeded?: false
13364	}
13365	}
13366	WebSearch: {
13367	/** The search query that was executed */
13368	query: string
13369	/** Search results and/or text commentary from the model */
13370	results: Array<{
13371	/** ID of the tool use */
13372	tool_use_id: string
13373	/** Array of search hits */
13374	content: Array<{
13375	/** The title of the search result */
13376	title: string
13377	/** The URL of the search result */
13378	url: string
13379	}>
13380	} \| string>
13381	/** Time taken to complete the search operation */
13382	durationSeconds: number
13383	/** Number of web searches performed */
13384	searchCount?: number
13385	}
13386	Workflow: {
13387	status: "async_launched" \| "remote_launched"
13388	taskId: string
13389	/** TaskType of the registered background task — 'local_workflow' for in-process runs, 'remote_agent' when remote:true dispatches to CCR. Set on all new writes; absent only on transcripts written before this field existed. */
13390	taskType?: "local_workflow" \| "remote_agent"
13391	/** meta.name from the workflow script — same value as task_started.workflow_name. Set on all new writes; absent only on transcripts written before this field existed. */
13392	workflowName?: string
13393	/** Local workflow run identifier for resumeFromRunId. Absent for remote_launched (the CCR session URL is the resume handle there) and on transcripts written before this field existed. */
13394	runId?: string
13395	summary?: string
13396	/** Directory where subagent transcripts are written during execution */
13397	transcriptDir?: string
13398	/** Path to the persisted workflow script for this invocation. Editable via Write/Edit; pass back as `scriptPath` to re-run without resending the script. */
13399	scriptPath?: string
13400	/** CCR session URL when status is remote_launched */
13401	sessionUrl?: string
13402	/** Non-blocking heads-up (e.g. local git state diverges from the pushed branch the cloud session will clone) */
13403	warning?: string
13404	/** Set if syntax check failed */
13405	error?: string
13406	}
13407	Write: {
13408	/** Whether a new file was created or an existing file was updated */
13409	type: "create" \| "update"
13410	/** The path to the file that was written */
13411	filePath: string
13412	/** The content that was written to the file */
13413	content: string
13414	/** Diff patch showing the changes (empty when nothing changed, the diff timed out, or — with originalFile null on an update — the previous content was too large to diff) */
13415	structuredPatch: {
13416	oldStart: number
13417	oldLines: number
13418	newStart: number
13419	newLines: number
13420	lines: string[]
13421	}[]
13422	/** The original file content before the write (null for new files, or when the previous content was too large to include) */
13423	originalFile: string \| null
13424	gitDiff?: {
13425	filename: string
13426	status: "modified" \| "added"
13427	additions: number
13428	deletions: number
13429	changes: number
13430	patch: string
13431	/** GitHub owner/repo when available */
13432	repository?: string \| null
13433	}
13434	/** True when the user edited the proposed content in the permission dialog before accepting */
13435	userModified?: boolean
13436	/** True when the write was held for the machine owner to review instead of written; the file is unchanged */
13437	staged?: boolean
13438	}
13439	}
13440	}