@namzu/sdk 51.1.0 → 52.1.0

package/src/types/hitl/index.ts

@@ -55,6 +55,14 @@ export type HITLResumeDecision =
 			 * listed here for an unmarked call is ignored rather than trusted.
 			 */
 			skillGranted?: readonly string[]
+			/**
+			 * Ids of calls approved on the strength of a `pre_tool_use` hook's
+			 * `allow` ({@link ToolCallSummary.hookGrant}), with nobody asked.
+			 *
+			 * Audited like `skillGranted`, and ignored for any id whose call did
+			 * not carry the mark.
+			 */
+			hookGranted?: readonly string[]
 	  }
 	| {
 			action: 'modify_tools'
@@ -77,6 +85,15 @@ export type HITLResumeDecision =
 			action: 'answer_question'
 			selectedOptionIds: string[]
 			freeText?: string
+			/**
+			 * One answer per question of a batch (`UserQuestionData.questions`).
+			 * When present it is the answer; `selectedOptionIds`/`freeText`
+			 * then carry nothing the tool reads (send `[]`). Absent on a
+			 * single-question park, and on a batch from a host that only
+			 * knows one question — then `selectedOptionIds`/`freeText`
+			 * answer the first question and the rest are unanswered.
+			 */
+			answers?: readonly UserQuestionAnswer[]
 			/**
 			 * Echo of `UserQuestionData.questionId` — the misdirection
 			 * guard. The park/resolve registry on hosts is typically
@@ -176,6 +193,28 @@ export interface ToolCallSummary {
 	 * and `strict`. A host's own handler may ignore it.
 	 */
 	skillGrant?: { readonly skill: string }
+	/**
+	 * What a `pre_tool_use` hook answered about approving this call, as the
+	 * hooks reported it. `ask` is acted on by the kernel (it makes the call an
+	 * explicit review); `allow` is acted on only through {@link hookGrant}.
+	 */
+	hookPermission?: {
+		readonly decision: 'allow' | 'ask'
+		readonly reason?: string
+	}
+	/**
+	 * Present when a `pre_tool_use` hook said `allow` and nothing stronger
+	 * stands in the way.
+	 *
+	 * Marked on the same terms as {@link skillGrant}: only a call the
+	 * operator's policy left to review (no `deny`, no explicit `ask` rule, no
+	 * hook `ask`), that is not destructive, carries no {@link escalation} and
+	 * is not one the tool always asks about. A sandbox escape, a path outside
+	 * the roots, a tool's own `requiresApproval`, a rule's review and the
+	 * dangerous-pattern floor therefore all still reach a person, or refuse.
+	 * `plan` and `strict` refuse a marked call exactly as they refuse any other.
+	 */
+	hookGrant?: { readonly reason?: string }
 }
 
 /** See {@link ToolCallSummary.escalation}. */
@@ -218,6 +257,27 @@ export interface ToolCallEscalation {
 	 * where a program name is actually decided.
 	 */
 	unknownProgram?: string
+	/**
+	 * Absolute paths this call writes that are protected in every mode: git
+	 * hooks and config, shell rc files, editor and tool configuration, the
+	 * project's own `.namzu` directory (see `authorization/protected-paths.ts`
+	 * for the list). A write there plants something that runs later, outside
+	 * the turn, so it is asked about every time and refused when nobody can be
+	 * asked; no rule, mode or remembered approval covers it. Set for the file
+	 * tools' declared path and for the visible write targets of a shell line:
+	 * output redirections, and the operands of `cp`, `mv`, `tee`, `touch`,
+	 * `mkdir`, `rm`, `rmdir` and `sed -i`.
+	 */
+	protectedPaths?: readonly string[]
+	/**
+	 * Why a shell line removes something it must not: the file system root, a
+	 * top-level directory, the home directory, the working directory or one of
+	 * its parents, a glob that crosses directories, or a target a variable or
+	 * substitution may empty. The flags do not matter, only the targets. Asked
+	 * about every time and refused when nobody can be asked. Present only for a
+	 * tool that declares `commandArgument`.
+	 */
+	dangerousRemoval?: string
 }
 
 export interface ToolModification {
@@ -250,6 +310,12 @@ export interface UserQuestionOption {
 	 * Absent, not `false`, on every other option.
 	 */
 	recommended?: boolean
+	/**
+	 * Plain text or markdown a host may show beside the option list while this
+	 * option is focused (a snippet, a mock-up, a side-by-side). Optional and
+	 * never required to answer; a host that has nowhere to show it ignores it.
+	 */
+	preview?: string
 }
 
 /**
@@ -267,6 +333,44 @@ export interface UserQuestionData {
 	options: UserQuestionOption[]
 	multiSelect: boolean
 	allowFreeText: boolean
+	/**
+	 * Present when one `ask_user_question` call carries several related
+	 * questions (two to four; a single question leaves this out). The
+	 * top-level `question`, `header`, `options`, `multiSelect` and
+	 * `allowFreeText` then mirror the FIRST entry, so a host that does not
+	 * know this field still shows a coherent question and answers it; the
+	 * rest read as unanswered.
+	 *
+	 * A host shows all of them together, collects every answer, and returns
+	 * one {@link UserQuestionAnswer} per question it has an answer for through
+	 * `answer_question.answers`.
+	 */
+	questions?: readonly UserQuestionItem[]
+}
+
+/**
+ * One question of a batch. `id` is stable: the asking `tool_use_id`, `#`, and
+ * the question's zero-based position, so an answer names the question it
+ * belongs to even when a host shows them in another order.
+ */
+export interface UserQuestionItem {
+	id: string
+	question: string
+	header?: string
+	options: UserQuestionOption[]
+	multiSelect: boolean
+	allowFreeText: boolean
+}
+
+/**
+ * The answer to one question of a batch. A question with no entry was not
+ * answered; an entry with no selection and no text counts the same.
+ */
+export interface UserQuestionAnswer {
+	/** {@link UserQuestionItem.id}. */
+	questionId: string
+	selectedOptionIds: string[]
+	freeText?: string
 }
 
 export interface PlanApprovalData {

package/src/types/message/index.ts

@@ -352,11 +352,13 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'answer-review',
 	'auto-continuation',
 	'channel-message',
+	'hook-feedback',
 	'host-observation',
 	'job-exit',
 	'limit-finalization',
 	'peer-message',
 	'peer-notice',
+	'reminder',
 	'repeat-call',
 	'steering',
 	'step-context',

package/src/types/plugin/index.ts

@@ -107,6 +107,24 @@ export type PluginHookEvent =
 	| 'turn_interrupt'
 	| 'pre_tool_use'
 	| 'post_tool_use'
+	/**
+	 * A tool call ended in failure. Fired after `post_tool_use` for the same
+	 * call, only when the result is a failure. Carries `toolName`, `toolInput`
+	 * and `toolResult`.
+	 */
+	| 'post_tool_use_failure'
+	/**
+	 * A person is about to be asked whether a tool call may run. Carries
+	 * `toolName` and `toolInput`. A hook may answer before the question is
+	 * shown: `continue` with `permission: { decision: 'allow' }` approves the
+	 * call (never one that is always asked about), `skip` refuses it.
+	 */
+	| 'permission_request'
+	/**
+	 * The host wants the operator's attention: a review is waiting, or a turn
+	 * settled. Carries `notification` (`type` and `message`). Observational.
+	 */
+	| 'notification'
 	| 'pre_llm_call'
 	| 'post_llm_call'
 	| 'iteration_start'
@@ -139,6 +157,9 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
 		case 'turn_interrupt':
 		case 'pre_tool_use':
 		case 'post_tool_use':
+		case 'post_tool_use_failure':
+		case 'permission_request':
+		case 'notification':
 		case 'pre_llm_call':
 		case 'post_llm_call':
 		case 'iteration_start':
@@ -196,6 +217,16 @@ export interface PluginCompactionInfo {
 	readonly contextWindowTokens: number
 }
 
+/** What a `notification` hook is shown. */
+export interface PluginNotificationInfo {
+	/**
+	 * `approval_required` (a review is waiting), `turn_settled` (a turn ended) or
+	 * `idle_prompt` (the host has waited for the operator for a while).
+	 */
+	readonly type: 'approval_required' | 'turn_settled' | 'idle_prompt'
+	readonly message: string
+}
+
 export interface PluginHookContext {
 	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
 	readonly turnId?: TurnId
@@ -214,6 +245,15 @@ export interface PluginHookContext {
 	readonly toolName?: string
 	readonly toolInput?: unknown
 	readonly toolResult?: ToolResult
+	/** What the host is telling the operator, on `notification`. */
+	readonly notification?: PluginNotificationInfo
+	/**
+	 * On `turn_end` and `subagent_stop` when an earlier answer to the same
+	 * event kept the turn going: the hook is being asked again about a turn it
+	 * already refused to let end. A hook that always refuses would otherwise
+	 * keep the model working until the turn's own limits stop it.
+	 */
+	readonly stopHookActive?: boolean
 	readonly iteration?: number
 	/**
 	 * Why the turn was stopped, on `turn_interrupt`.
@@ -267,8 +307,41 @@ export interface PluginHookContext {
 	readonly signal?: AbortSignal
 }
 
+/**
+ * What a hook may say about a tool call beyond letting it run or not. Only
+ * `allow` and `ask` exist here: a refusal is `skip`, which always wins.
+ *
+ * `allow` stands in for the person's yes ONLY on a call that would have been
+ * asked about for no reason beyond "it changes something". It never covers a
+ * sandbox escape, a path outside the roots, a call the tool declares it always
+ * needs approval for, a call a rule sent to review explicitly, or one the tool
+ * declares destructive; and it never reopens what a rule denied.
+ * `ask` makes the call go to a person even where a rule or the tool's own
+ * read-only declaration would have let it through.
+ */
+export interface PluginHookPermission {
+	readonly decision: 'allow' | 'ask'
+	readonly reason?: string
+}
+
+/** Extra facts a hook may attach to the verdicts that let the work go on. */
+export interface PluginHookNotes {
+	/**
+	 * Text for the model. On a tool event it is appended to what the model
+	 * reads of that call; on `user_prompt_submit` it joins the turn's context.
+	 */
+	readonly context?: string
+	/** Stop the turn once the current step is done. `reason` is shown to the operator. */
+	readonly halt?: { readonly reason: string }
+	/** A warning for the operator, reported through the logger. */
+	readonly notice?: string
+}
+
 export type PluginHookResult =
-	| { action: 'continue' }
+	| ({
+			action: 'continue'
+			permission?: PluginHookPermission
+	  } & PluginHookNotes)
 	/**
 	 * Add to what the model is told, without changing anything else.
 	 *
@@ -278,8 +351,12 @@ export type PluginHookResult =
 	 * it is rejected, because a tool result is not a place for context.
 	 */
 	| { action: 'annotate'; text: string }
-	| { action: 'skip'; reason: string }
-	| { action: 'modify'; input: unknown }
+	| ({ action: 'skip'; reason: string } & PluginHookNotes)
+	| ({
+			action: 'modify'
+			input: unknown
+			permission?: PluginHookPermission
+	  } & PluginHookNotes)
 	| { action: 'error'; message: string }
 	| { action: 'retry' }
 	/**
@@ -333,9 +410,15 @@ export type PluginHookResultFor<E extends PluginHookEvent> = E extends 'user_pro
 		? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'modify' | 'error' }>
 		: E extends 'post_tool_use'
 			? Extract<PluginHookResult, { action: 'continue' | 'replace' | 'retry' | 'error' }>
-			: E extends 'turn_interrupt' | 'session_start' | 'session_end'
-				? Extract<PluginHookResult, { action: 'continue' }>
-				: Extract<PluginHookResult, { action: 'continue' | 'error' }>
+			: E extends 'post_tool_use_failure'
+				? Extract<PluginHookResult, { action: 'continue' | 'error' }>
+				: E extends 'permission_request'
+					? Extract<PluginHookResult, { action: 'continue' | 'skip' }>
+					: E extends 'turn_end' | 'subagent_stop' | 'pre_compact'
+						? Extract<PluginHookResult, { action: 'continue' | 'skip' | 'error' }>
+						: E extends 'turn_interrupt' | 'session_start' | 'session_end' | 'notification'
+							? Extract<PluginHookResult, { action: 'continue' }>
+							: Extract<PluginHookResult, { action: 'continue' | 'error' }>
 
 /** The event and its handler verdict stay correlated, including in hook arrays. */
 export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
@@ -344,21 +427,21 @@ export type PluginHookDefinition<E extends PluginHookEvent = PluginHookEvent> =
 				readonly event: E
 				readonly handler: (context: PluginHookContext) => Promise<PluginHookResultFor<E>>
 				/**
-				 * Lower runs first. Default 100.
+				 * Lower comes first in the answers. Default 100.
 				 *
-				 * Order was install order, which is neither declared nor stable — it
-				 * depends on when each plugin happened to be installed. That is fine
-				 * for hooks that only observe, and wrong for the ones that decide:
-				 * `executeHooks` SHORT-CIRCUITS on `skip` and `error`, so a hook that
-				 * denies a dangerous command only gets to deny it if it runs before
-				 * whatever else stops the chain. A guard that fires depending on
-				 * installation history is not a guard.
-				 *
-				 * Ties keep registration order, so plugins that never set a priority
-				 * behave exactly as before. Convention: guards below 100, observers
-				 * above.
+				 * The hooks of one event start together and none waits for another, so
+				 * priority no longer says who runs first; it says whose answer is read
+				 * first. The first refusal in that order is the one the model is told,
+				 * and of several rewrites the last in that order wins. Ties keep
+				 * registration order. Convention: guards below 100, observers above.
 				 */
 				readonly priority?: number
+				/**
+				 * Text for the operator's status line while this hook runs. Carried on
+				 * the `plugin_hook_executing` event; a host that draws no status line
+				 * ignores it.
+				 */
+				readonly statusMessage?: string
 			}
 		: never
 

package/src/types/provider/errors.ts

@@ -237,6 +237,47 @@ function chainMessages(err: unknown): string[] {
 	return out
 }
 
+/**
+ * What a provider said when prompt plus requested output together passed the
+ * window: the prompt size, the output cap that was asked for, and the window.
+ */
+export interface OutputOverflowFigures {
+	readonly inputTokens: number
+	readonly maxTokens: number
+	readonly contextLimit: number
+}
+
+/**
+ * Read the "input length and `max_tokens` exceed context limit: A + B > C"
+ * wording from a failure, anywhere on its cause chain.
+ *
+ * Different from a prompt that is too long on its own: here the prompt fits
+ * and only the requested output does not, so the remedy is a smaller
+ * `max_tokens`, not a smaller history. `undefined` means the failure does not
+ * carry those figures.
+ */
+export function readOutputOverflow(err: unknown): OutputOverflowFigures | undefined {
+	const pattern = /input length and `?max_tokens`? exceed context limit: (\d+) \+ (\d+) > (\d+)/i
+	for (const message of chainMessages(err)) {
+		const match = pattern.exec(message)
+		if (!match) continue
+		const inputTokens = Number.parseInt(match[1] ?? '', 10)
+		const maxTokens = Number.parseInt(match[2] ?? '', 10)
+		const contextLimit = Number.parseInt(match[3] ?? '', 10)
+		if (![inputTokens, maxTokens, contextLimit].every(Number.isFinite)) continue
+		return { inputTokens, maxTokens, contextLimit }
+	}
+	return undefined
+}
+
+/** Undici's `TypeError: terminated` anywhere on the chain: the body stream was cut. */
+function isUndiciTermination(err: unknown): boolean {
+	for (const link of causeChain(err)) {
+		if ((link as unknown) instanceof TypeError && link.message === 'terminated') return true
+	}
+	return false
+}
+
 /** Node/undici transport failures that mean "never reached the model". */
 const NETWORK_ERRNOS: ReadonlySet<string> = new Set([
 	'ECONNRESET',
@@ -271,12 +312,19 @@ function codeFromStatus(status: number): ProviderErrorCode {
 	return 'unknown'
 }
 
+function overflowWordingAllowed(status: number | undefined): boolean {
+	return status === undefined || status === 400 || status === 413
+}
+
+const CONTEXT_WINDOW_OVERFLOW =
+	/(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)\b[^.]{0,60}context window|context window[^.]{0,60}\b(?:exceed\w*|too (?:long|large|big)|larger than|longer than|over the|beyond|maximum|overflow\w*)/i
+
 /**
  * Message sniffing is the LAST resort, used only when there is no status
  * and no errno. Vendors that tunnel a 400 through a 200 body (several
  * gateways do) are only reachable this way.
  */
-function codeFromMessage(message: string): ProviderErrorCode | undefined {
+function codeFromMessage(message: string, status?: number): ProviderErrorCode | undefined {
 	const m = message.toLowerCase()
 	if (
 		m.includes('context length') ||
@@ -289,6 +337,13 @@ function codeFromMessage(message: string): ProviderErrorCode | undefined {
 		// overflow rescue tests for by exact equality. The turn died holding
 		// the remedy.
 		m.includes('too long for') ||
+		// The reference terminal's own wordings (its `context window` and
+		// `input length and max_tokens exceed context limit` matchers).
+		// Only where the status cannot say otherwise: a 429, 5xx or 401 that
+		// mentions the window is still a rate limit, a server fault or an auth
+		// failure, and must keep its retry and fallback behaviour.
+		(overflowWordingAllowed(status) &&
+			(CONTEXT_WINDOW_OVERFLOW.test(message) || m.includes('exceed context limit'))) ||
 		m.includes('maximum length') ||
 		m.includes('exceeds the maximum') ||
 		m.includes('input is too large') ||
@@ -465,7 +520,9 @@ export function classifyProviderError(
 	// usually generic ("request failed") — so matching only the outer text
 	// looks at the one string least likely to say anything.
 	const messages = chainMessages(err)
-	const fromMessage = messages.map(codeFromMessage).find((code) => code !== undefined)
+	const fromMessage = messages
+		.map((m) => codeFromMessage(m, status))
+		.find((code) => code !== undefined)
 	// A first-hand statement from whoever produced the failure, if there
 	// is one. It outranks the code's inference, not the code itself: the
 	// classification still says WHAT went wrong.
@@ -489,7 +546,7 @@ export function classifyProviderError(
 
 	// A 400 that is really a window overflow must not be filed as a plain
 	// invalid_request: the caller can recover from one and not the other.
-	if (messages.some((m) => codeFromMessage(m) === 'context_length_exceeded')) {
+	if (messages.some((m) => codeFromMessage(m, status) === 'context_length_exceeded')) {
 		return new ProviderError({
 			code: 'context_length_exceeded',
 			message,
@@ -533,8 +590,12 @@ export function classifyProviderError(
 		}
 	}
 
-	// `fetch` rejects with a bare TypeError on transport failure.
-	if (err instanceof TypeError && /fetch|network/i.test(message)) {
+	// `fetch` rejects with a bare TypeError on transport failure, and undici
+	// ends a response body the peer cut mid-stream with `TypeError:
+	// terminated`. Its socket error normally rides along as the cause and the
+	// errno walk above catches it, but a vendor SDK that re-wraps the stream
+	// error can drop that cause and leave only the bare word.
+	if ((err instanceof TypeError && /fetch|network/i.test(message)) || isUndiciTermination(err)) {
 		return new ProviderError({
 			code: 'network',
 			message,

package/src/types/provider/interface.ts

@@ -22,6 +22,19 @@ export interface LLMProvider {
 	/** Refine hosted search support for a model and mode. Absent uses the driver-wide declaration. */
 	supportsHostedWebSearchFor?(model: string, mode: 'live' | 'cached'): boolean
 
+	/**
+	 * Whether `model` reads images. `capabilities.supportsVision` is a statement
+	 * about the DRIVER (does it map image parts onto the wire); this is about the
+	 * MODEL behind it, which only the driver's catalogue can know: one driver
+	 * serves vision and text-only models side by side, and a text-only model
+	 * refuses the whole request when it finds an image in it.
+	 *
+	 * Answer `false` only when the model is known to be text-only. Absent, or
+	 * `true`, means "send images": the runtime also recovers from a refusal, so a
+	 * driver with no catalogue loses nothing by omitting this.
+	 */
+	supportsImageInputFor?(model: string): boolean
+
 	/**
 	 * Retry behaviour this DRIVER wants, when the generic default is wrong
 	 * for the vendor behind it.

package/src/types/provider/stream.ts

@@ -174,7 +174,7 @@ export interface ProviderRetryNotice {
 	/** The delay came from the server's own `Retry-After`, not backoff. */
 	readonly serverDirected: boolean
 	/**
-	 * The failed attempt had already streamed text or reasoning, and the request
+	 * The failed attempt had already streamed text or reasoning (reasoning alone is retried without any option), and the request
 	 * is being sent again from the start. Whatever that attempt produced is void
 	 * and the consumer must drop it before the next chunk.
 	 */

package/src/types/session/config.ts

@@ -88,6 +88,20 @@ export interface TurnConfig {
 		 * behaviour every sandboxed turn had before this existed.
 		 */
 		workspace?: 'ephemeral' | 'working-directory'
+		/**
+		 * When the turn acquires its sandbox. Absent means `'eager'`: acquired,
+		 * and waited for, before the input guardrails and the first model
+		 * request.
+		 *
+		 * `'concurrent'` starts at the same point but lets the first model
+		 * request go out while the provider allocates; the first tool call
+		 * waits for the handle. `'on-first-use'` does not start until the first
+		 * tool call. Either way `sandbox_created` is emitted when the handle
+		 * arrives, and a failure or timeout ends the turn with the stop reason
+		 * an eager acquisition would have produced, at the first tool call or
+		 * at turn end, whichever comes first.
+		 */
+		acquire?: 'eager' | 'concurrent' | 'on-first-use'
 	}
 
 	/**

package/src/types/session/events.ts

@@ -279,11 +279,20 @@ type CoreSessionEvent =
 			 *   `tool_result`, so it was refused wholesale rather than sent to
 			 *   a provider that rejects the pairing. A reducer bug, and one
 			 *   `findSafeTrimIndex` exists to prevent.
+			 * - `breaker_open` — only with `compactionConfig.circuitBreaker`:
+			 *   three passes in a row failed, so proactive compaction is off for
+			 *   the rest of the turn; a context overflow the provider reports
+			 *   still runs the reactive relief. Sent once, without `error`: it is
+			 *   for a host's records, not a line for the person. `messages` is
+			 *   the live count.
+			 * - `refilling` — only with `compactionConfig.circuitBreaker`: the
+			 *   context filled back up within three iterations of a compaction,
+			 *   three times in a row, and the turn is stopping. Sent once.
 			 */
-			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair'
+			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair' | 'breaker_open' | 'refilling'
 			/** Unchanged, and stated so a reader need not infer it. */
 			messages: number
-			/** Present only for `reducer_threw`. */
+			/** For `reducer_threw`, the reducer's message; for `refilling`, the one line to show. */
 			error?: string
 	  }
 	| {
@@ -708,9 +717,26 @@ type CoreSessionEvent =
 			sessionId: SessionId
 			turnId?: TurnId
 			capability: 'tools' | 'vision' | 'documents'
-			/** Present when the mismatch was produced after a tool executed. */
-			contentSource?: 'tool-result'
+			/**
+			 * Present when the mismatch was not about the user's own message:
+			 * `'tool-result'` after a tool executed; `'history'` when the model
+			 * itself turned out not to read images (see `model`) and the images
+			 * already in the conversation were left out of the request;
+			 * `'media-removed'` when the provider rejected an image or document
+			 * and it was left out of the request that then went through;
+			 * `'media-removed-current'` when that included a file attached to the
+			 * latest user message; `'media-limit'` when the oldest files were left
+			 * out only to fit a count the provider accepts.
+			 */
+			contentSource?:
+				| 'tool-result'
+				| 'history'
+				| 'media-removed'
+				| 'media-removed-current'
+				| 'media-limit'
 			providerId: string
+			/** The model that cannot read images, when the warning is about one model rather than the driver. */
+			model?: string
 			message: string
 	  }
 	/**
@@ -992,6 +1018,8 @@ type CoreSessionEvent =
 			turnId?: TurnId
 			pluginId: PluginId
 			hookEvent: PluginHookEvent
+			/** The hook's own text for a status line while it runs, when it declared one. */
+			statusMessage?: string
 	  }
 	| {
 			type: 'plugin_hook_completed'

package/src/types/session/records.ts

@@ -235,6 +235,7 @@ const stopReason = z.enum([
 	'stop_condition',
 	'step_refused',
 	'structured_output_failed',
+	'output_limit',
 	'answer_rejected',
 	'input_guardrail',
 	'output_guardrail',

package/src/types/session/stop-reason.ts

@@ -38,6 +38,11 @@ export type StopReason =
 	| 'step_refused'
 	/** The model never produced a valid structured output within its retries. */
 	| 'structured_output_failed'
+	/**
+	 * The model's reply was cut off at its output limit more times in a row
+	 * than `maxOutputContinuations` allows. Only with that option set.
+	 */
+	| 'output_limit'
 	/**
 	 * A host reviewer kept rejecting the answer and the turn ran out of
 	 * attempts.

package/src/types/tool/index.ts

@@ -1,3 +1,4 @@
+import type { ChildProcess } from 'node:child_process'
 import type { z } from 'zod'
 import type { CodeNavigationProvider } from '../code-navigation/index.js'
 // Type-only, and circular by design: a tool-result guardrail is described in
@@ -118,7 +119,24 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 	}
-	get(id: string): { id: string; status: string; exitCode?: number; error?: string }
+	get(id: string): {
+		id: string
+		status: string
+		exitCode?: number
+		error?: string
+	}
+	/**
+	 * Take over a process the caller already started and is waiting on, so a
+	 * foreground command that outran its timeout can keep running as a job
+	 * instead of being killed. Optional: a host without it (or a sandboxed
+	 * turn) keeps the kill. Throws when the owner is at its job cap.
+	 */
+	adopt?(params: {
+		command: string
+		child: ChildProcess
+		workingDirectory?: string
+		initialOutput?: readonly { readonly stream: 'stdout' | 'stderr'; readonly text: string }[]
+	}): { id: string; status: string }
 	/**
 	 * Resolves once the process exists or failed to start (`error` says why).
 	 * Optional: a host that cannot tell may omit it, and `bash` then replies
@@ -483,15 +501,39 @@ export interface ToolContext {
 	 */
 	web?: {
 		readonly fetch?: {
-			fetch(request: { url: string; signal?: AbortSignal }): Promise<{
+			fetch(request: {
+				url: string
+				signal?: AbortSignal
+				/** `same-host` asks for a redirect to another site to be handed back, not followed. */
+				redirects?: 'follow' | 'same-host'
+				headers?: Readonly<Record<string, string>>
+			}): Promise<{
 				url: string
 				status: number
 				contentType?: string
 				body: string
 				truncated: boolean
 				redirects: readonly string[]
+				/** A redirect that was not followed; `body` is then empty. */
+				redirect?: { url: string; status: number }
 			}>
 		}
+		/**
+		 * Answers a prompt from a page with a small model. Optional: without
+		 * it `web_fetch` returns the page as markdown instead of an answer.
+		 */
+		readonly extract?: {
+			extract(request: {
+				url: string
+				prompt: string
+				content: string
+				instruction: string
+				body: string
+				signal?: AbortSignal
+				sessionId: string
+				turnId: string
+			}): Promise<string | undefined>
+		}
 		readonly search?: {
 			search(request: {
 				query: string
@@ -1103,6 +1145,15 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * their external effects have stopped, and does not imply success.
 	 */
 	executionBarrier?: boolean
+	/**
+	 * The tool bounds its own output (a paged read, say), so the turn's default
+	 * per-result cap does not apply to it and its result is never replaced to
+	 * fit the per-message budget.
+	 *
+	 * Only the DEFAULT is lifted. A host that sets `maxToolOutputChars`
+	 * explicitly still bounds this tool's result by it.
+	 */
+	selfLimitingOutput?: boolean
 }
 
 /**