@namzu/sdk 56.2.0 → 57.0.0

package/src/runtime/query/executor.ts

@@ -6,6 +6,7 @@ import { unknownProgramInLine } from '../../authorization/program.js'
 import { type SkillGrantSet, compileSkillGrant } from '../../authorization/skill-grant.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
+import { recordRestorable } from '../../compaction/restore.js'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
 import type { PluginLifecycleManager } from '../../plugin/lifecycle.js'
 import { buildProbeContext } from '../../probe/context.js'
@@ -13,6 +14,7 @@ import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
@@ -700,6 +702,7 @@ export class ToolExecutor {
 	private emitEvent: EmitEvent
 	private log: Logger
 	private workingStateManager?: WorkingStateManager
+	private historyView?: () => readonly Message[]
 	private probes: ProbeEnforcement
 	private parentSpan?: Span
 	private readonly toolCallBudget?: ToolCallBudget
@@ -749,6 +752,30 @@ export class ToolExecutor {
 		this.workingStateManager = manager
 	}
 
+	/**
+	 * Read the conversation the model is shown, as it is now. Lets a tool ask
+	 * whether an earlier receipt is still there (see `ToolContext.receiptVisible`)
+	 * without being handed the history.
+	 */
+	setHistoryView(view: () => readonly Message[]): void {
+		this.historyView = view
+	}
+
+	private receiptVisible = (callId: string, renderedFingerprint: string): boolean => {
+		const history = this.historyView?.()
+		if (!history) return false
+		for (let index = history.length - 1; index >= 0; index -= 1) {
+			const message = history[index]
+			if (message?.role !== 'tool' || message.toolCallId !== callId) continue
+			return (
+				typeof message.content === 'string' &&
+				message.isError !== true &&
+				fingerprintContent(message.content) === renderedFingerprint
+			)
+		}
+		return false
+	}
+
 	setSandbox(sandbox: Sandbox): void {
 		this.config = { ...this.config, sandbox }
 		this.sandboxGate = undefined
@@ -2185,6 +2212,7 @@ export class ToolExecutor {
 				this.dispatchNested(name, input, context, recordObservation, undefined, options),
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
+			receiptVisible: this.receiptVisible,
 			...(this.config.codeAnalysis ? { codeAnalysis: this.config.codeAnalysis } : {}),
 			// Bound to this turn, once. Binding here rather than passing the
 			// owner from the tool is what makes the scoping structural: there
@@ -2584,6 +2612,15 @@ export class ToolExecutor {
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
+			// What the model was shown, kept whole so a compaction can put it back.
+			recordRestorable(this.workingStateManager, {
+				toolName,
+				input,
+				output: typeof modelContent === 'string' ? modelContent : output,
+				success: !effectiveIsError,
+				unchanged: result.facts?.kind === 'read' && result.facts.unchanged === true,
+				workingDirectory: this.config.workingDirectory,
+			})
 			for (const pin of this.config.abortSignal.aborted ? [] : (result.workingState ?? [])) {
 				this.workingStateManager.pin(pin.key, pin.text, toolName)
 			}

package/src/runtime/query/file-evidence-context.ts

@@ -149,7 +149,7 @@ export function recordFileEvidence(
 	const lead =
 		recorded.length === 0
 			? `${FILE_EVIDENCE_HEADING}: ${FILE_EVIDENCE_GUIDANCE}`
-			: `${FILE_EVIDENCE_HEADING}, changed since the last entry. An entry for a path replaces the earlier entries for that path.`
+			: `${FILE_EVIDENCE_HEADING}, changed since the last entry; \`bodyInCall\` and \`observedFingerprint\` read as before. An entry for a path replaces the earlier entries for that path.`
 	return [
 		lead,
 		...(gone.length > 0 ? [`${NO_LONGER_HOLDS}${JSON.stringify(gone)}`] : []),

package/src/runtime/query/index.ts

@@ -814,6 +814,13 @@ export interface QueryParams {
 	 */
 	projectInstructionContext?: ProjectInstructionContext
 
+	/**
+	 * Text the host wants carried across a compaction, such as where its plan
+	 * file is. Asked once per pass, after the summary is written; the answer is
+	 * appended to the restored context. Returning nothing adds nothing.
+	 */
+	postCompactionContext?: () => string | undefined | Promise<string | undefined>
+
 	/**
 	 * Where this conversation's durable state lives.
 	 *
@@ -1656,6 +1663,8 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		const compactionConfig = params.compactionConfig
 			? CompactionConfigSchema.parse(params.compactionConfig)
 			: undefined
+		// The live history, so a tool can ask whether an earlier receipt is still in it.
+		toolExecutor.setHistoryView(() => ctx.recorder.messages)
 		if (compactionConfig && compactionConfig.strategy !== 'disabled') {
 			workingStateManager = new WorkingStateManager(compactionConfig)
 			toolExecutor.setWorkingStateManager(workingStateManager)
@@ -1829,6 +1838,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			...(params.projectInstructionContext
 				? { projectInstructionContext: params.projectInstructionContext }
 				: {}),
+			...(params.postCompactionContext
+				? { postCompactionContext: params.postCompactionContext }
+				: {}),
 			...(providerContextWindow !== undefined ? { providerContextWindow } : {}),
 			resolveModelContextWindow: async (model) => {
 				if (!modelContextWindows.has(model)) {

package/src/runtime/query/iteration/phases/compaction.ts

@@ -11,6 +11,7 @@ import {
 } from '../../../../compaction/plan.js'
 import type { ContextReducer, ContextReduction } from '../../../../compaction/reducer.js'
 import { createSlidingWindowReducer } from '../../../../compaction/reducer.js'
+import { renderRestoredContext } from '../../../../compaction/restore.js'
 import { findRetainedIndices } from '../../../../compaction/retention.js'
 import { serializeState } from '../../../../compaction/serializer.js'
 import {
@@ -1003,6 +1004,24 @@ async function runCompactionCheckInner(
 		compactedContent = serializeState(manager.getState())
 	}
 
+	// Skills the model loaded and files it read go back verbatim after the
+	// summary, with whatever the host wants carried across (its plan file).
+	let hostNote: string | undefined
+	try {
+		hostNote = await ctx.postCompactionContext?.()
+	} catch (error) {
+		// A host note is an addition; the pass does not depend on it.
+		ctx.log.warn('The host note for a compaction could not be read — leaving it out', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			'exception.message': error instanceof Error ? error.message : String(error),
+		})
+	}
+	const restored = renderRestoredContext(manager.getState(), {
+		contextWindowTokens: budget,
+		...(hostNote ? { hostNote } : {}),
+	})
+	if (restored) compactedContent = `${compactedContent}\n\n${restored}`
+
 	// The pointer is only worth a line when both tools it names are mounted.
 	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
 	const compactionMessage = buildCompactionMessage(

package/src/runtime/query/iteration/phases/context.ts

@@ -256,6 +256,9 @@ export interface IterationContext {
 	/** Live project policy; separate from human inbound continuation. */
 	readonly projectInstructionContext?: ProjectInstructionContext
 
+	/** Host text appended to the restored context after a compaction. */
+	readonly postCompactionContext?: () => string | undefined | Promise<string | undefined>
+
 	readonly workingStateManager?: WorkingStateManager
 
 	/**

package/src/runtime/query/iteration/stream-turn.ts

@@ -30,7 +30,7 @@ import type {
 	ReasoningBlock,
 	ToolInputError,
 } from '../../../types/message/index.js'
-import { ProviderError } from '../../../types/provider/errors.js'
+import { ProviderError, classifyProviderError } from '../../../types/provider/errors.js'
 import type {
 	ChatCompletionResponse,
 	LLMProvider,
@@ -298,7 +298,7 @@ export async function* streamProviderTurn(
 	let streamedLength = 0
 	const toolBuckets = new Map<number, ToolCallBucket>()
 	// Places a fragment that came without an index; see `ToolCallIndexer`.
-	const toolIndexer = new ToolCallIndexer()
+	let toolIndexer = new ToolCallIndexer()
 	// The call the model's latest output went to, or `undefined` once text,
 	// reasoning or a hosted tool followed it. An output limit, a content
 	// filter or a dropped stream stops the response wherever it is, so this
@@ -397,6 +397,36 @@ export async function* streamProviderTurn(
 			})
 		: undefined
 
+	/**
+	 * Drop everything the failed attempt wrote, so the request starts over under
+	 * the same message: after a restarting retry, or a swap that says the same.
+	 * The failed attempt's text, reasoning and tool calls are void. A call is
+	 * restarted only while still being written and nothing runs before the
+	 * response settles, so a half-written call never reaches the model.
+	 */
+	const discardAttempt = () => {
+		toolBuckets.clear()
+		toolIndexer = new ToolCallIndexer()
+		framingViolated = false
+		text = new StreamTextAccumulator()
+		reasoningBuckets.clear()
+		citations.length = 0
+		replayState = undefined
+		id = ''
+		finishReason = 'stop'
+		reportedFinishReason = undefined
+		finishDetail = undefined
+		streamedLength = 0
+		lastOutputCall = undefined
+		usage = {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		}
+	}
+
 	try {
 		for (;;) {
 			const next = it.next()
@@ -426,28 +456,7 @@ export async function* streamProviderTurn(
 					...(chunk.retry.restart ? { restart: true } : {}),
 				})
 				yield* drainPending()
-				if (chunk.retry.restart) {
-					// The failed attempt's text and reasoning are void: the request
-					// starts over under the same message. The decorator never
-					// restarts once a tool call began, so no bucket is left behind.
-					text = new StreamTextAccumulator()
-					reasoningBuckets.clear()
-					citations.length = 0
-					replayState = undefined
-					id = ''
-					finishReason = 'stop'
-					reportedFinishReason = undefined
-					finishDetail = undefined
-					streamedLength = 0
-					lastOutputCall = undefined
-					usage = {
-						promptTokens: 0,
-						completionTokens: 0,
-						totalTokens: 0,
-						cachedTokens: 0,
-						cacheWriteTokens: 0,
-					}
-				}
+				if (chunk.retry.restart) discardAttempt()
 				continue
 			}
 
@@ -472,8 +481,10 @@ export async function* streamProviderTurn(
 					code: chunk.fallback.code,
 					...(chunk.fallback.status !== undefined ? { status: chunk.fallback.status } : {}),
 					reason: chunk.fallback.reason,
+					...(chunk.fallback.restart ? { restart: true } : {}),
 				})
 				yield* drainPending()
+				if (chunk.fallback.restart) discardAttempt()
 				continue
 			}
 
@@ -947,10 +958,21 @@ export async function* streamProviderTurn(
 
 	// Not after a framing violation: the calls it would recover are the ones
 	// the stream was just refused for garbling.
+	//
+	// Nor when the stream was cut by a connection that may come back and no
+	// call came through whole: the retries are spent, the half-written call is
+	// not the model's mistake, and telling the model about it would spend a
+	// turn on a fault it cannot fix. The failure goes up and the turn pauses.
+	const cutByConnection =
+		streamError !== undefined &&
+		streamCause !== undefined &&
+		classifyProviderError(streamCause).retryable
 	const recoveredToolInputFromStreamError =
 		streamError !== undefined &&
 		!framingViolated &&
-		toolCalls.some((tc) => tc.id && tc.function.name)
+		toolCalls.some(
+			(tc) => tc.id && tc.function.name && (!cutByConnection || !tc.metadata?.inputError),
+		)
 	const effectiveFinishReason: ChatCompletionResponse['finishReason'] =
 		recoveredToolInputFromStreamError ? 'tool_calls' : finishReason
 

package/src/runtime/query/prepare-turn.ts

@@ -43,6 +43,7 @@ import { generateCheckpointId, generateTurnId } from '../../utils/id.js'
 import { errorAttributes } from '../../utils/log/exception.js'
 import type { Logger } from '../../utils/logger.js'
 import { AUTO_APPROVE_POLICY_NAME, createSessionApprovalPolicy } from './approval-policy.js'
+import { readCallsThatNeverStarted } from './calls-that-never-started.js'
 import { type TurnContext, TurnContextFactory } from './context.js'
 import { EventTranslator } from './events.js'
 import type { QueryParams } from './index.js'
@@ -681,9 +682,17 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 						pinCompaction: true,
 					})),
 		])
-		const initialRepair = params.resumeFromCheckpoint
+		let initialRepair = params.resumeFromCheckpoint
 			? { messages: projectedInitialMessages, report: undefined }
 			: repairToolMessageHistory(projectedInitialMessages)
+		if (initialRepair.report && initialRepair.report.syntheticToolResultsInserted > 0) {
+			// A call that was waiting for approval when the session ended never ran;
+			// the model is told so rather than that its outcome is unknown.
+			const neverRan = await readCallsThatNeverStarted(storage.log)
+			if (neverRan.size > 0) {
+				initialRepair = repairToolMessageHistory(projectedInitialMessages, { neverRan })
+			}
+		}
 		const initialMessages = initialRepair.messages
 		if (initialRepair.report && toolHistoryRepairChanged(initialRepair.report)) {
 			pendingHistoryRepairs.push({

package/src/scheduler/completion-inbox.ts

@@ -46,7 +46,7 @@ const OWNED_WORK_DISPLAY_LIMIT = 16
 
 /** What the model is told about owned work, wherever it is shown. */
 const OWNED_WORK_GUIDANCE =
-	'Each task gives its id (taskId), its state, how its turn ended (turnStatus), why it stopped (stopReason), and whether its result has reached this conversation (resultDelivery: delivered-to-history, or not-delivered). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.'
+	'Each task gives its id (taskId), its state, how its turn ended (turnStatus), why it stopped (stopReason), and whether its result has reached this conversation (resultDelivery: delivered-to-history, or not-delivered). Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Results reach you and not the user, so before you end a reply check that the result of every finished task has been reported to the user, once. Do not repeat a synthesis already given.'
 
 /**
  * The ids of the tasks that earlier recorded entries name, read from the
@@ -809,8 +809,8 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 
 	const preamble =
 		handles.length === 1
-			? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result.'
-			: `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results.`
+			? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result. The user has not seen it; tell them what it found in your next message.'
+			: `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results. The user has not seen them; tell them what each found in your next message.`
 
 	return `${preamble}\n\n${blocks.join('\n\n')}`
 }

package/src/tools/admit-facts.ts

@@ -118,6 +118,7 @@ export function admitToolFacts(value: unknown): ToolFacts | undefined {
 						? { bytes: count(value.binary.bytes) }
 						: undefined,
 				background: flag(value.background),
+				continued: flag(value.continued),
 			})
 		case 'read': {
 			const path = text(value.path)

package/src/tools/builtins/bash.ts

@@ -4,6 +4,7 @@ import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { killTree } from '../../process/kill-tree.js'
 import { genericLabel } from '../../registry/tool/presentation.js'
+import { cancelCauseOf } from '../../types/session/cancel-cause.js'
 import type { ToolFacts } from '../../types/tool/presentation.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
@@ -93,6 +94,28 @@ export function movedToBackgroundMessage(jobId: string, timeoutMs: number): stri
 	return `Command did not complete within its ${seconds}s timeout and was moved to the background as job ${jobId}; it was not stopped. You will be told when it ends. Its output so far is above.`
 }
 
+/**
+ * How long a foreground command runs before it is offered for hand-over to
+ * the background. A command that ends sooner is never interrupted by a stray
+ * key press, and a host that shows a hint shows it from this moment.
+ */
+export const FOREGROUND_HANDOFF_AFTER_MS = 2_000
+
+/**
+ * What the model is told when the person moved a running foreground command to
+ * the background instead of stopping it. Exported so the test states the same
+ * words.
+ */
+export function handedOffMessage(jobId: string, reason: 'user' | 'message' | 'interrupt'): string {
+	const why =
+		reason === 'user'
+			? "at the person's request"
+			: reason === 'message'
+				? 'so a message from the person could reach you'
+				: 'because the person interrupted the turn'
+	return `Command was moved to the background as job ${jobId} ${why}; it was not stopped. You will be told when it ends. Its output so far is above.`
+}
+
 const inputSchema = z.object({
 	command: z
 		.string()
@@ -240,10 +263,34 @@ export function execHostShell(
 			child: ReturnType<typeof spawnHostShell>
 			initialOutput: readonly { stream: 'stdout' | 'stderr'; text: string }[]
 		}) => string | undefined
+		/**
+		 * Takes the live process over for a hand-over the person asked for
+		 * (a key press, a message that must reach the model, an interrupt),
+		 * with the same contract as `onTimeout`. Absent, those hand-overs are
+		 * not offered and an interrupt kills the command as it always did.
+		 */
+		adopt?: (running: {
+			child: ReturnType<typeof spawnHostShell>
+			initialOutput: readonly { stream: 'stdout' | 'stderr'; text: string }[]
+		}) => string | undefined
+		/**
+		 * An interrupt the person caused (Esc, Ctrl+C) hands the command to
+		 * `adopt` instead of killing it. Any other abort, a parent stopping a
+		 * child or a budget stop, still kills it.
+		 */
+		adoptOnInterrupt?: boolean
+		/**
+		 * Called once, right after the process is spawned, with the means to
+		 * hand it over later. `background` returns whether the process was
+		 * taken over; it settles the call with `backgroundedJobId` set.
+		 */
+		onRunning?: (control: { background(reason: 'user' | 'message'): boolean }) => void
 	},
 ): Promise<{
-	/** Set when `onTimeout` took the process over; the command was not stopped. */
+	/** Set when the process was taken over; the command was not stopped. */
 	backgroundedJobId?: string
+	/** Why it was taken over. */
+	backgroundedBy?: 'timeout' | 'user' | 'message' | 'interrupt'
 	stdout: string
 	stderr: string
 	/** Bytes captured on each stream, before decoding; absent from a runner that does not count them. */
@@ -401,44 +448,64 @@ export function execHostShell(
 			)
 		}
 		child.once('close', onClose)
-		const deadline = setTimeout(() => {
-			if (options.onTimeout && !closed && cause === undefined) {
-				let jobId: string | undefined
-				try {
-					jobId = options.onTimeout({
-						child,
-						initialOutput: (['stdout', 'stderr'] as const)
-							.map((stream) => ({ stream, text: decodeCapture(stream) }))
-							.filter((part) => part.text !== ''),
-					})
-				} catch {
-					// A host that cannot take the process over leaves the kill in place.
-				}
-				if (jobId !== undefined) {
-					// The registry owns the process from here: stop listening to it,
-					// so a later Stop or its exit is not this call's business.
-					closed = true
-					disposeAbort?.()
-					child.stdout?.off('data', onStdout)
-					child.stderr?.off('data', onStderr)
-					child.off('close', onClose)
-					child.off('error', onError)
-					child.off('spawn', onSpawn)
-					resolve({
-						backgroundedJobId: jobId,
-						stdout: decodeCapture('stdout'),
-						stderr: decodeCapture('stderr'),
-					})
-					return
-				}
+		// Hands the live process to the host's job registry, once. `onTimeout`
+		// answers for the deadline; every other reason goes to `adopt`.
+		const takeOver = (reason: 'timeout' | 'user' | 'message' | 'interrupt'): boolean => {
+			const adopter =
+				reason === 'timeout' ? options.onTimeout : (options.adopt ?? options.onTimeout)
+			if (!adopter || closed || cause !== undefined) return false
+			let jobId: string | undefined
+			try {
+				jobId = adopter({
+					child,
+					initialOutput: (['stdout', 'stderr'] as const)
+						.map((stream) => ({ stream, text: decodeCapture(stream) }))
+						.filter((part) => part.text !== ''),
+				})
+			} catch {
+				// A host that cannot take the process over leaves the process where it is.
 			}
+			if (jobId === undefined) return false
+			// The registry owns the process from here: stop listening to it,
+			// so a later Stop or its exit is not this call's business.
+			closed = true
+			disposeAbort?.()
+			clearTimeout(deadline)
+			child.stdout?.off('data', onStdout)
+			child.stderr?.off('data', onStderr)
+			child.off('close', onClose)
+			child.off('error', onError)
+			child.off('spawn', onSpawn)
+			resolve({
+				backgroundedJobId: jobId,
+				backgroundedBy: reason,
+				stdout: decodeCapture('stdout'),
+				stderr: decodeCapture('stderr'),
+			})
+			return true
+		}
+		const deadline = setTimeout(() => {
+			if (takeOver('timeout')) return
 			cancel('timeout')
 		}, options.timeout)
 		deadline.unref?.()
 		if (options.signal) {
-			disposeAbort = subscribeToAbort(options.signal, () => cancel('caller'))
-			if (options.signal.aborted) cancel('caller')
+			const signal = options.signal
+			const onAbort = () => {
+				// Esc or Ctrl+C keeps what the command was doing; any other stop
+				// (a parent cancelling a child, a budget) still ends it.
+				if (
+					options.adoptOnInterrupt === true &&
+					cancelCauseOf(signal.reason) === 'user' &&
+					takeOver('interrupt')
+				)
+					return
+				cancel('caller')
+			}
+			disposeAbort = subscribeToAbort(signal, onAbort)
+			if (signal.aborted) onAbort()
 		}
+		options.onRunning?.({ background: (reason) => takeOver(reason) })
 	})
 }
 
@@ -714,51 +781,76 @@ const BashToolBase = defineTool({
 		// registry, a sandboxed turn, a one-off sandbox escape, a plain wait)
 		// is there anything to hand the process to, so those keep the kill.
 		const adopt = context.backgroundJobs?.adopt?.bind(context.backgroundJobs)
-		const canMoveToBackground =
-			adopt !== undefined &&
-			context.sandbox === undefined &&
-			!backgroundTasksDisabled() &&
-			!startsWithSleep(input.command)
+		const canHandOff =
+			adopt !== undefined && context.sandbox === undefined && !backgroundTasksDisabled()
+		const canMoveOnTimeout = canHandOff && !startsWithSleep(input.command)
+		const adoptRunning = (running: {
+			child: Parameters<NonNullable<typeof adopt>>[0]['child']
+			initialOutput: Parameters<NonNullable<typeof adopt>>[0]['initialOutput']
+		}) =>
+			adopt?.({
+				command: input.command,
+				child: running.child,
+				workingDirectory: context.workingDirectory,
+				initialOutput: running.initialOutput,
+			}).id
+		// Offered for hand-over once it has run long enough to be worth moving.
+		let offerTimer: ReturnType<typeof setTimeout> | undefined
+		let withdrawOffer: (() => void) | undefined
+		const offer = context.backgroundJobs?.registerForeground?.bind(context.backgroundJobs)
 
 		try {
-			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId } = await execHostShell(
-				input.command,
-				{
+			const { stdout, stderr, stdoutBytes, stderrBytes, backgroundedJobId, backgroundedBy } =
+				await execHostShell(input.command, {
 					cwd: context.workingDirectory,
 					timeout: input.timeout,
 					env: { ...inherited.env, ...context.env },
 					maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 					signal: context.abortSignal,
 					onOutput,
-					...(canMoveToBackground
+					...(canMoveOnTimeout ? { onTimeout: adoptRunning } : {}),
+					...(canHandOff
 						? {
-								onTimeout: ({ child, initialOutput }) =>
-									adopt({
-										command: input.command,
-										child,
-										workingDirectory: context.workingDirectory,
-										initialOutput,
-									}).id,
+								adopt: adoptRunning,
+								adoptOnInterrupt: true,
+								...(offer
+									? {
+											onRunning: (control: {
+												background(reason: 'user' | 'message'): boolean
+											}) => {
+												offerTimer = setTimeout(() => {
+													withdrawOffer = offer({
+														command: input.command,
+														background: (reason) => control.background(reason),
+													})
+												}, FOREGROUND_HANDOFF_AFTER_MS)
+												offerTimer.unref?.()
+											},
+										}
+									: {}),
 							}
 						: {}),
-				},
-			)
+				})
 			if (backgroundedJobId !== undefined) {
+				const timedOut = backgroundedBy === 'timeout'
 				return {
 					success: true,
 					output: [
 						formatShellOutput(stdout, stderr),
-						movedToBackgroundMessage(backgroundedJobId, input.timeout),
+						timedOut || backgroundedBy === undefined
+							? movedToBackgroundMessage(backgroundedJobId, input.timeout)
+							: handedOffMessage(backgroundedJobId, backgroundedBy),
 					]
 						.filter(Boolean)
 						.join('\n\n'),
 					data: {
 						jobId: backgroundedJobId,
 						background: true,
-						timedOut: true,
+						...(timedOut || backgroundedBy === undefined ? { timedOut: true } : {}),
 						movedToBackground: true,
+						...(backgroundedBy ? { backgroundedBy } : {}),
 					},
-					facts: { kind: 'command', command: input.command, background: true },
+					facts: { kind: 'command', command: input.command, background: true, continued: true },
 				}
 			}
 			return {
@@ -856,6 +948,9 @@ const BashToolBase = defineTool({
 					...(failure.stderrBytes !== undefined ? { stderrBytes: failure.stderrBytes } : {}),
 				}),
 			}
+		} finally {
+			if (offerTimer !== undefined) clearTimeout(offerTimer)
+			withdrawOffer?.()
 		}
 	},
 })