@namzu/sdk 56.2.0 → 57.0.0

package/src/compaction/wire.ts

@@ -1,6 +1,13 @@
 import type { CompactionConfig } from '../config/runtime.js'
 import { WorkingStateManager } from './manager.js'
-import type { FileSlot, PinSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.js'
+import type {
+	FileSlot,
+	PinSlot,
+	PlanSlot,
+	RestorableState,
+	ToolResultSlot,
+	WorkingState,
+} from './types.js'
 
 /**
  * The working state in a form that survives a process boundary.
@@ -42,6 +49,8 @@ export interface WorkingStateSnapshot {
 	 * completeness it does not have.
 	 */
 	readonly evicted: Readonly<Record<string, number>>
+	/** Absent in snapshots written before bodies were restored; restored as none. */
+	readonly restorable?: RestorableState
 }
 
 export function snapshotWorkingState(manager: WorkingStateManager): WorkingStateSnapshot {
@@ -59,6 +68,14 @@ export function snapshotWorkingState(manager: WorkingStateManager): WorkingState
 		userRequirements: [...state.userRequirements],
 		assistantNotes: [...state.assistantNotes],
 		evicted: { ...state.evicted },
+		...(state.restorable
+			? {
+					restorable: {
+						skills: state.restorable.skills.map((skill) => ({ ...skill })),
+						files: state.restorable.files.map((file) => ({ ...file })),
+					},
+				}
+			: {}),
 	}
 }
 
@@ -89,6 +106,14 @@ export function restoreWorkingState(
 		userRequirements: [...snapshot.userRequirements],
 		assistantNotes: [...snapshot.assistantNotes],
 		evicted: { ...snapshot.evicted },
+		...(snapshot.restorable
+			? {
+					restorable: {
+						skills: snapshot.restorable.skills.map((skill) => ({ ...skill })),
+						files: snapshot.restorable.files.map((file) => ({ ...file })),
+					},
+				}
+			: {}),
 	}
 	manager.replaceState(state)
 	return manager

package/src/index.ts

@@ -47,6 +47,8 @@ export {
 } from './runtime/jobs/job-id.js'
 export type {
 	BackgroundJob,
+	ForegroundCommand,
+	ForegroundHandoffReason,
 	BackgroundJobOutput,
 	BackgroundJobRegistryConfig,
 	BackgroundJobStatus,

package/src/plugin/shell-hook.ts

@@ -14,7 +14,13 @@
  * The command runs with `sh -c` in `cwd`. It receives one JSON object on
  * stdin — `event`, `cwd`, `session_id`, `turn_id` inside a turn, and for
  * tool events `tool_name`, `tool_input` and (after the call) `tool_result`;
- * `subagent_stop` adds `parent_session_id` and `parent_turn_id` — and the
+ * `subagent_stop` adds `parent_session_id` and `parent_turn_id`. Each fact a
+ * script written for another host would look for under a different name is
+ * also sent under that name: `hook_event_name` (the PascalCase spelling,
+ * `PreToolUse`, `Stop`, ...), `tool_response` (the same object as
+ * `tool_result`), and, when the host knows them, `transcript_path` and
+ * `permission_mode`. The Namzu names stay, so no existing script changes.
+ * The same facts go out as
  * same facts as `NAMZU_HOOK_EVENT`, `NAMZU_SESSION_ID`, `NAMZU_TURN_ID`,
  * `NAMZU_TOOL_NAME` and, when the input names a file, `NAMZU_TOOL_PATH`.
  *
@@ -305,6 +311,10 @@ export interface ShellHookInput {
 	readonly notification?: PluginNotificationInfo
 	/** On `turn_end` and `subagent_stop`: an earlier answer already kept this turn going. */
 	readonly stopHookActive?: boolean
+	/** The session's transcript file, when the host has one. Sent as `transcript_path`. */
+	readonly transcriptPath?: string
+	/** How tool calls are being decided right now. Sent as `permission_mode`. */
+	readonly permissionMode?: string
 }
 
 /** Run one hook command to completion, bounded by its deadline and capture. */
@@ -319,8 +329,11 @@ export function runShellHook(
 	)
 	const payload = JSON.stringify({
 		event: input.event,
+		hook_event_name: PASCAL_EVENT_NAMES[input.event] ?? input.event,
 		cwd: input.cwd,
 		session_id: input.sessionId,
+		...(input.transcriptPath !== undefined ? { transcript_path: input.transcriptPath } : {}),
+		...(input.permissionMode !== undefined ? { permission_mode: input.permissionMode } : {}),
 		...(input.turnId !== undefined ? { turn_id: input.turnId } : {}),
 		...(input.parentSessionId !== undefined ? { parent_session_id: input.parentSessionId } : {}),
 		...(input.parentTurnId !== undefined ? { parent_turn_id: input.parentTurnId } : {}),
@@ -328,7 +341,9 @@ export function runShellHook(
 		...(input.compaction !== undefined ? { compaction: input.compaction } : {}),
 		...(input.toolName !== undefined ? { tool_name: input.toolName } : {}),
 		...(input.toolInput !== undefined ? { tool_input: input.toolInput } : {}),
-		...(input.toolResult !== undefined ? { tool_result: input.toolResult } : {}),
+		...(input.toolResult !== undefined
+			? { tool_result: input.toolResult, tool_response: input.toolResult }
+			: {}),
 		...(input.event === 'post_tool_use_failure' && input.toolResult?.error !== undefined
 			? { error: input.toolResult.error }
 			: {}),
@@ -589,11 +604,12 @@ function readShellHookJson(event: ShellHookEvent, stdout: string): ShellHookRead
 				reading.permission = { decision, ...(why ? { reason: why } : {}) }
 			} else if (decision !== 'defer') {
 				return {
-					invalid: '`permissionDecision` must be "allow", "deny" or "ask"',
+					invalid: '`permissionDecision` must be "allow", "deny", "ask" or "defer"',
 				}
 			}
-			// "defer" hands the decision to a separate permission service the kernel
-			// does not have: nothing is decided, and the ordinary rules apply.
+			// "defer" is accepted and decides nothing: a script that hands a call
+			// back to a separate permission service gets the ordinary rules, the
+			// same as a hook that said nothing.
 		}
 		if (specific.updatedInput !== undefined) {
 			if (!isRecord(specific.updatedInput)) return { invalid: '`updatedInput` must be an object' }
@@ -802,6 +818,14 @@ export interface ShellHookOptions {
 	/** Where the command runs and what `cwd` says on stdin. */
 	readonly cwd: string
 	readonly log?: Logger
+	/**
+	 * The transcript file of a session, sent as `transcript_path`. Called at
+	 * each run, because a host's session can change under one manager. Absent
+	 * or returning `undefined`, the field is left out.
+	 */
+	readonly transcriptPath?: (sessionId: string) => string | undefined
+	/** The permission mode in force now, sent as `permission_mode`. Called at each run. */
+	readonly permissionMode?: () => string | undefined
 }
 
 /** One entry as a hook definition the lifecycle manager accepts. */
@@ -828,6 +852,8 @@ export function createShellHook(
 				return { action: 'continue' }
 			}
 			if (entry.once === true) spent = true
+			const transcriptPath = options.transcriptPath?.(String(context.sessionId))
+			const permissionMode = options.permissionMode?.()
 			const outcome = await runShellHook(
 				entry,
 				{
@@ -858,6 +884,8 @@ export function createShellHook(
 						: {}),
 					...(context.notification !== undefined ? { notification: context.notification } : {}),
 					...(context.stopHookActive === true ? { stopHookActive: true } : {}),
+					...(transcriptPath !== undefined ? { transcriptPath } : {}),
+					...(permissionMode !== undefined ? { permissionMode } : {}),
 				},
 				context.signal,
 			)

package/src/prompt/coding-agent-doctrine.ts

@@ -70,7 +70,7 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 - Never change git configuration or other persistent settings without asking: not \`user.name\` or \`user.email\`, hooks, remotes, credential helpers, or any \`git config\` (local or global), nor a shell profile or a tool's own config file. If a commit fails because no identity is set, stop and tell the user the command to set one; do not invent one.
 
 ### Keeping the user informed
-- Before a batch of tool calls, say in one short line what you are about to do and why. When you have been working for a while without saying anything, say in a few words where you are, then continue. One line, not a paragraph; the tool rows on screen already show the details.
+- Before your first tool call, say in one short line what you are about to do and why. While you work, add a one-line update when you find something, change direction or hit a blocker, and after a long stretch without one, say in a few words where you are, then continue. Brief is good and silence is not; the tool rows on screen already show the details.
 - Keep the final reply short and specific: what changed, what was verified, what is left.`
 
 /**
@@ -78,8 +78,9 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
  * delegated sub-agent does not have. See the module comment for the split.
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
-- For work that is multi-step — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Skip it for a single inspect-edit-test cycle: the list is for the user to follow, and a list of one item tells them nothing.
+- For work of three or more steps — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Skip it for a single inspect-edit-test cycle or a two-step job: the list is for the user to follow, and a list of one or two items tells them nothing.
 - When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. It starts with none of your context and returns what you ask for.
+- When delegated agents finish, tell the user what each one found in your next message. Their results reach you and not the user, so a result you do not pass on stays unseen.
 - Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.`
 
 /**

package/src/provider/errors.ts

@@ -31,6 +31,11 @@
 
 import { LOG_SECRET_PATTERNS } from '../constants/secret-patterns.js'
 import type { ProviderErrorKind, ProviderRequestErrorInit } from '../types/provider/error.js'
+import {
+	type TransportCause,
+	readCertificateFailure,
+	readTransportCause,
+} from '../types/provider/errors.js'
 export type {
 	ProviderErrorInfo,
 	ProviderErrorKind,
@@ -78,6 +83,8 @@ export class ProviderRequestError extends Error {
 	public readonly detail?: string
 	/** The provider's `x-should-retry` verdict, when it sent one; see {@link ProviderRequestErrorInit.shouldRetry}. */
 	public readonly shouldRetry?: boolean
+	/** The part of the network path the request tripped on, when known; see {@link ProviderRequestErrorInit.transport}. */
+	public readonly transport?: TransportCause
 
 	constructor(init: ProviderRequestErrorInit) {
 		super(buildProviderErrorMessage(init))
@@ -90,6 +97,7 @@ export class ProviderRequestError extends Error {
 		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
 		if (init.detail !== undefined) this.detail = init.detail
 		if (init.shouldRetry !== undefined) this.shouldRetry = init.shouldRetry
+		if (init.transport !== undefined) this.transport = init.transport
 	}
 }
 
@@ -520,8 +528,14 @@ export function providerVendorError(input: {
 	const name = error instanceof Error ? error.name : ''
 	const message = error instanceof Error ? error.message : ''
 
+	// A proxy that refuses the tunnel or a certificate nobody trusts has no status
+	// to read, and the same request meets the same obstacle again.
+	const transport = readTransportCause(error)
+
 	let kind: ProviderErrorKind
-	if (/ThrottlingException|TooManyRequests|ServiceQuotaExceeded/i.test(name)) {
+	if (transport !== undefined) {
+		kind = 'network'
+	} else if (/ThrottlingException|TooManyRequests|ServiceQuotaExceeded/i.test(name)) {
 		kind = 'throttle'
 	} else if (/AccessDenied|Unauthorized|Forbidden|Authentication/i.test(name)) {
 		kind = 'auth'
@@ -550,7 +564,12 @@ export function providerVendorError(input: {
 		input.retryAfter ?? vendorRetryAfter(error),
 		input.now ?? Date.now(),
 	)
-	const shouldRetry = parseShouldRetry(vendorHeader(error, ['x-should-retry']))
+	// A certificate that fails verification is refused the same way every time.
+	const certificate = status === undefined ? readCertificateFailure(error) : undefined
+	const shouldRetry =
+		transport !== undefined || certificate !== undefined
+			? false
+			: parseShouldRetry(vendorHeader(error, ['x-should-retry']))
 	const fields = error as { type?: unknown; param?: unknown; requestID?: unknown } | null
 	// A message that already carries its body (Anthropic's) has the fields; one that is only the
 	// parsed sentence (OpenAI's) gets them from the SDK error's own properties.
@@ -566,11 +585,16 @@ export function providerVendorError(input: {
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
-		...(exactProviderCode !== undefined ? { providerCode: exactProviderCode } : {}),
+		...(certificate !== undefined
+			? { providerCode: certificate }
+			: exactProviderCode !== undefined
+				? { providerCode: exactProviderCode }
+				: {}),
 		...(status !== undefined ? { status } : {}),
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),
 		...(shouldRetry !== undefined ? { shouldRetry } : {}),
+		...(transport !== undefined ? { transport } : {}),
 	})
 }
 

package/src/provider/fallback.ts

@@ -225,6 +225,24 @@ function isOutputChunk(chunk: StreamChunk): boolean {
 	)
 }
 
+/**
+ * Output the consumer can take back: reasoning, or the pieces of a tool call
+ * that is still being written (nothing runs before the response settles).
+ * A finished call, text, a citation, a hosted tool or a finish reason is real.
+ */
+function isVoidable(chunk: StreamChunk): boolean {
+	const { content, toolCallEnd, citation, hostedTool, textPart } = chunk.delta
+	return !(
+		content ||
+		toolCallEnd ||
+		citation !== undefined ||
+		hostedTool !== undefined ||
+		textPart !== undefined ||
+		chunk.textParts !== undefined ||
+		chunk.finishReason !== undefined
+	)
+}
+
 /** Read one member's canonical menu, adapting the one-release legacy member. */
 function memberReasoningEffortLevels(
 	member: ProviderChainMember,
@@ -405,9 +423,20 @@ export function withProviderFallback(
 			assertNativeStructuredOutputSupported(member.provider, request)
 			assertHostedWebSearchSupported(member.provider, request)
 			let produced = false
+			let fragments = false
 			try {
 				for await (const chunk of member.provider.chatStream(request)) {
-					if (isOutputChunk(chunk)) produced = true
+					// The retry notice that restarts a request voids what the failed
+					// attempt wrote, and the consumer drops it: nothing real was produced.
+					if (chunk.retry?.restart) {
+						produced = false
+						fragments = false
+					} else if (isOutputChunk(chunk)) {
+						// Pieces the consumer can drop on a notice (a call still being
+						// written, reasoning) are not output a swap would duplicate.
+						if (isVoidable(chunk)) fragments = true
+						else produced = true
+					}
 					yield chunk
 				}
 				return
@@ -457,13 +486,16 @@ export function withProviderFallback(
 					fallback: {
 						fromIndex: cursor - 1,
 						fromProviderId: member.provider.id,
-						...(member.model !== undefined ? { fromModel: member.model } : {}),
+						// The model this member was asked for, which for the head of the chain
+						// (declared without one) is the request's own.
+						...(targetModel ? { fromModel: targetModel } : {}),
 						toIndex: cursor,
 						toProviderId: to.provider.id,
 						...(to.model !== undefined ? { toModel: to.model } : {}),
 						code: classified.code,
 						...(classified.status !== undefined ? { status: classified.status } : {}),
 						reason: classified.message,
+						...(fragments ? { restart: true } : {}),
 					},
 				}
 			}

package/src/provider/retry.ts

@@ -60,8 +60,13 @@ export interface ProviderRetryConfig extends BackoffPolicy {
 	 * Off by default, because the decorator cannot un-emit: the consumer has
 	 * already seen those deltas. When on, the retry notice carries
 	 * `restart: true` and the consumer must discard what the failed attempt
-	 * produced; the runtime does this itself. A stream that has begun a tool
-	 * call is never restarted, because the call may already be underway.
+	 * produced; the runtime does this itself.
+	 *
+	 * A stream that has so far produced only tool-call fragments (no text) is
+	 * restarted whatever this says: nothing runs before the response settles,
+	 * and the half-written call is discarded on the same notice. A stream in
+	 * which a call finished, or the provider ran a hosted tool, is never
+	 * restarted, because that work is real.
 	 */
 	readonly retryMidStream?: boolean
 }
@@ -113,9 +118,11 @@ function isReasoningOnly(chunk: StreamChunk): boolean {
  * blocks by index, and clears them on a restart). Once a text or tool-call delta has been
  * yielded the consumer has already emitted `text_delta` events and
  * appended to its buffer, so restarting the request would duplicate
- * output. A mid-stream failure is therefore surfaced, not retried — the
- * existing stream-error path in `streamProviderTurn` handles it (and can
- * still salvage a truncated tool call). This is the whole reason the
+ * output. A mid-stream failure after text is therefore surfaced, not retried,
+ * unless `retryMidStream` — the existing stream-error path in
+ * `streamProviderTurn` handles it (and can still salvage a finished call).
+ * A stream that has only begun tool calls has shown no text, so it is retried
+ * too, the half-written call dropped. This is the whole reason the
  * retry lives in a decorator rather than inside the loop: the loop cannot
  * un-emit.
  *
@@ -158,8 +165,13 @@ export function withProviderRetry(
 			// this is retryable without `retryMidStream`; the notice says
 			// `restart` so a host that showed the thinking drops it.
 			let reasoned = false
-			// A tool call or hosted tool began: past this point a restart could
-			// repeat work that is already underway, so it is never offered.
+			// Text, a citation or a part reached the consumer: a pipe cannot take
+			// that back, so a restart needs `retryMidStream`.
+			let printed = false
+			// A call finished (its arguments are whole) or the provider ran a hosted
+			// tool: that work is real, so a restart is never offered. A call still
+			// being written is not work: nothing runs before the response settles,
+			// and the consumer drops the half-written call on `restart`.
 			let acted = false
 			try {
 				for await (const chunk of provider.chatStream(params)) {
@@ -173,9 +185,16 @@ export function withProviderRetry(
 						if (isReasoningOnly(chunk)) reasoned = true
 						else produced = true
 					}
-					if (chunk.delta.toolCalls?.length || chunk.delta.toolCallEnd || chunk.delta.hostedTool) {
-						acted = true
+					if (
+						chunk.delta.content ||
+						chunk.delta.textPart !== undefined ||
+						chunk.textParts !== undefined ||
+						chunk.delta.citation !== undefined
+					) {
+						printed = true
 					}
+					// A reported finish means the response was whole.
+					if (chunk.delta.toolCallEnd || chunk.delta.hostedTool || chunk.finishReason) acted = true
 
 					if (isErrorOnly && !produced && attempt < config.maxRetries) {
 						throw new Error(chunk.error)
@@ -203,7 +222,8 @@ export function withProviderRetry(
 				const exhausted = attempt >= config.maxRetries
 
 				const restartable =
-					(produced && config.retryMidStream === true && !acted) || (!produced && reasoned)
+					(produced && !acted && (config.retryMidStream === true || !printed)) ||
+					(!produced && reasoned)
 				if ((produced && !restartable) || !classified.retryable || exhausted) {
 					log?.warn('Provider call failed', {
 						[GENAI.SYSTEM]: provider.id,

package/src/public-runtime.ts

@@ -543,6 +543,9 @@ export {
 	EXPLORE_AGENT_ID,
 	EXPLORE_AGENT_PROMPT,
 	MAX_AGENT_FILE_CHARS,
+	PLAN_AGENT_DESCRIPTION,
+	PLAN_AGENT_ID,
+	PLAN_AGENT_PROMPT,
 	parseAgentFile,
 	parseAgentMarkdown,
 } from './agents/index.js'
@@ -782,6 +785,10 @@ export type {
 	WithProviderFallbackOptions,
 	WithProviderRetryOptions,
 } from './provider/index.js'
+// Which part of the network path a failed request tripped on (a proxy that
+// wants a sign-in, an untrusted certificate), read off the failure's causes.
+export { readTransportCause } from './types/provider/errors.js'
+export type { TransportCause } from './types/provider/errors.js'
 // The curve `ProviderRetryConfig` extends and `query({ toolRetryBackoff })`
 // takes a partial of. Both public surfaces name it, so a consumer has to be
 // able to name it too — a type reachable only through an inline `import(...)`
@@ -1340,6 +1347,7 @@ export {
 	WorkingStateManager,
 } from './compaction/index.js'
 export type {
+	ToolHistoryRepairOptions,
 	ToolHistoryRepairReport,
 	ToolHistoryRepairResult,
 } from './compaction/index.js'

package/src/public-types.ts

@@ -353,6 +353,9 @@ export type {
 	ToolResultSlot,
 	WorkingState,
 	PinSlot,
+	RestorableFile,
+	RestorableSkill,
+	RestorableState,
 	WorkingStatePin,
 } from './compaction/index.js'
 export type * from './eval/index.js'

package/src/runtime/jobs/registry.ts

@@ -358,12 +358,111 @@ function groupAlive(pid: number | undefined): boolean {
 
 const GROUP_POLL_MS = 250
 
+/**
+ * Why a command that was running in the foreground moved to the background:
+ * the person asked (`user`), or the person sent a message that has to reach
+ * the model while the command is still running (`message`).
+ */
+export type ForegroundHandoffReason = 'user' | 'message'
+
+/** A foreground command that can be moved to the background right now. */
+export interface ForegroundCommand {
+	readonly id: string
+	readonly owner: string
+	readonly command: string
+	readonly startedAt: number
+}
+
+interface ForegroundEntry extends ForegroundCommand {
+	readonly background: (reason: ForegroundHandoffReason) => boolean
+}
+
 export class BackgroundJobRegistry {
 	private readonly jobs = new Map<string, JobEntry>()
 	private readonly exitListeners = new Set<(job: BackgroundJob) => void>()
 	private readonly monitorListeners = new Set<(event: MonitorEvent) => void>()
 	private outputWaiters = 0
 	private readonly outputWaitersByOwner = new Map<string, number>()
+	private readonly foreground = new Map<string, ForegroundEntry>()
+	private readonly foregroundListeners = new Set<(owner: string) => void>()
+	private foregroundSeq = 0
+
+	/**
+	 * A foreground command a tool is waiting on, offered for hand-over: while it
+	 * is registered, {@link backgroundForeground} can move it to a job. The tool
+	 * registers once the command has run long enough that moving it is worth
+	 * offering, and unregisters (the returned function) when the call settles.
+	 * `background` returns whether the command was taken over.
+	 */
+	registerForeground(
+		owner: string,
+		entry: {
+			readonly command: string
+			readonly background: (reason: ForegroundHandoffReason) => boolean
+		},
+	): () => void {
+		const id = `fg-${++this.foregroundSeq}`
+		this.foreground.set(id, {
+			id,
+			owner,
+			command: entry.command,
+			startedAt: Date.now(),
+			background: entry.background,
+		})
+		this.announceForeground(owner)
+		return () => {
+			if (this.foreground.delete(id)) this.announceForeground(owner)
+		}
+	}
+
+	/** Foreground commands of one owner that can be moved to the background, oldest first. */
+	foregroundCommands(owner: string): readonly ForegroundCommand[] {
+		return [...this.foreground.values()]
+			.filter((entry) => entry.owner === owner)
+			.map(({ id, command, startedAt }) => ({ id, owner, command, startedAt }))
+	}
+
+	/**
+	 * Move every foreground command of `owner` to the background. Returns how
+	 * many were taken over; a command that ended or could not be taken over
+	 * keeps its own outcome and is not counted.
+	 */
+	backgroundForeground(owner: string, reason: ForegroundHandoffReason): number {
+		let moved = 0
+		for (const entry of [...this.foreground.values()]) {
+			if (entry.owner !== owner) continue
+			let taken = false
+			try {
+				taken = entry.background(reason)
+			} catch {
+				// A command that cannot be handed over keeps running where it is.
+			}
+			if (taken) {
+				moved += 1
+				this.foreground.delete(entry.id)
+			}
+		}
+		if (moved > 0) this.announceForeground(owner)
+		return moved
+	}
+
+	/** Be told when the set of hand-over-able foreground commands of any owner changes. */
+	onForegroundChange(listener: (owner: string) => void): () => void {
+		this.foregroundListeners.add(listener)
+		return () => {
+			this.foregroundListeners.delete(listener)
+		}
+	}
+
+	private announceForeground(owner: string): void {
+		for (const listener of this.foregroundListeners) {
+			try {
+				listener(owner)
+			} catch {
+				// A listener that throws is its owner's problem.
+			}
+		}
+	}
 
 	/**
 	 * Be told when a job ends, whoever owns it. A job outlives the call that
@@ -1257,6 +1356,12 @@ export function bindOwner(
 				hostOutput: true,
 				...(params.initialOutput ? { initialOutput: params.initialOutput } : {}),
 			}),
+		// The owner is bound here, so a tool can offer its own waiting command and
+		// no other turn's.
+		registerForeground: (entry: {
+			command: string
+			background: (reason: ForegroundHandoffReason) => boolean
+		}) => registry.registerForeground(owner, entry),
 		get: (id: string) => mine(id),
 		awaitStarted: (id: string) => {
 			mine(id)

package/src/runtime/query/calls-that-never-started.ts

@@ -0,0 +1,37 @@
+import type { SessionLog } from '../../store/session-log/index.js'
+import type { SessionRecord } from '../../types/session/records.js'
+
+/**
+ * Ids of the tool calls the log proves never started.
+ *
+ * A call that started has a `tool_executing` record, so one with no result is
+ * of unknown outcome. A call of a turn that journals its calls (it has a
+ * `tool_executing` or a `tool_review_requested` record) and has none of its
+ * own ran nothing: it was queued or waiting for approval when the process
+ * ended. A turn with no such record proves nothing, so its calls are left out.
+ */
+export async function readCallsThatNeverStarted(log: SessionLog): Promise<ReadonlySet<string>> {
+	const started = new Set<string>()
+	const journaled = new Set<string>()
+	const callsOfTurn = new Map<string, string[]>()
+	for await (const entry of log.read()) {
+		const record = entry.record as SessionRecord
+		if (record.type === 'tool_review_requested') {
+			journaled.add(record.turnId)
+		} else if (record.type === 'tool_executing') {
+			journaled.add(record.turnId)
+			started.add(record.toolUseId)
+		} else if (record.type === 'message') {
+			const content = record.content as { role?: string; toolCalls?: readonly { id: string }[] }
+			if (content?.role !== 'assistant' || !content.toolCalls) continue
+			const ids = callsOfTurn.get(record.turnId) ?? []
+			for (const call of content.toolCalls) ids.push(call.id)
+			callsOfTurn.set(record.turnId, ids)
+		}
+	}
+	const never = new Set<string>()
+	for (const turnId of journaled) {
+		for (const id of callsOfTurn.get(turnId) ?? []) if (!started.has(id)) never.add(id)
+	}
+	return never
+}

package/src/runtime/query/executor/tool-call-admission.ts

@@ -717,8 +717,8 @@ function ceilingBelow(length: number): number | undefined {
 
 /**
  * How much one call should carry, in the model's words, or `undefined` when
- * there is no number to give: a stream that ended, to a tool that declares no
- * large arguments.
+ * there is no number to give: after an output limit that left no figure worth
+ * stating, to a tool that declares no large arguments.
  *
  * A tool that declares large arguments is given a budget for each of them.
  * After an output limit, any tool is told to keep its arguments under half of
@@ -741,9 +741,7 @@ function sizeAdvice(
 	// would tell a call cut after three characters to keep `content` under
 	// 12000 of them: more than a budget, an invitation back into the same
 	// cutoff, and a broken invariant (a call is always told less than what
-	// arrived). Only a stream that ended for a reason other than the output
-	// limit — where no ceiling applies at all — still gets the plain
-	// declared budgets below.
+	// arrived).
 	if (lengthCutoff && ceiling === undefined) return undefined
 	const declared = Object.entries(largeStringArguments ?? {}).filter(
 		([, budget]) => Number.isFinite(budget) && budget > 0,
@@ -831,8 +829,8 @@ function unseenOutput(error: ToolInputError): string | undefined {
  *   call is to carry less, {@link sizeAdvice} and the tool's
  *   `truncatedInputHint`, with nothing about reasoning or what came before
  *   it: the window is the conversation's length, not this response's.
- * - Cut off by the stream ending: the declared budgets, if any, or just to
- *   send the call again, and the tool's `truncatedInputHint`.
+ * - Cut off by the connection dropping: no size and no hint. The call did not
+ *   come near any limit, so it is to be sent again unchanged.
  * - Stopped by a content filter: no advice. Sending less does not get past a
  *   filter.
  *
@@ -874,7 +872,7 @@ export function unreadableToolInputMessage(
 				? 'the response reached its output token limit'
 				: error.finishReason === 'content_filter'
 					? "the provider's content filter stopped the response"
-					: 'the response stream ended'
+					: 'the connection dropped'
 		parts.push(
 			`Error: The call to "${toolName}" was cut off: ${cause} after ${error.length} characters of its arguments, before they were complete. The tool was NOT executed.`,
 		)
@@ -897,9 +895,14 @@ export function unreadableToolInputMessage(
 			parts.push(
 				`${error.precedingLength} of the ${error.precedingLength + error.length} characters the response streamed came before this call, so send the call again with less before it in the same response.`,
 			)
-		} else if (error.finishReason !== 'content_filter') {
+		} else if (error.finishReason === 'length') {
 			parts.push(sizeAdvice(tool?.largeStringArguments, error) ?? 'Send the call again.')
 			hint(tool?.truncatedInputHint)
+		} else if (error.finishReason !== 'content_filter') {
+			// The transport ended the response, not a limit: the call may have been
+			// well inside any budget, so no size is named and the call is not to
+			// change. Sending the same call again is the whole remedy.
+			parts.push('Nothing was wrong with the call. Send the same call again, unchanged.')
 		}
 	}
 	return parts.join(' ')