@namzu/sdk 37.0.0 → 38.1.0

package/src/runtime/query/request-context.ts

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto'
+import type { Message, MessageRole } from '../../types/message/index.js'
+
+/** A content block present at the SDK's provider-input boundary, not a file freshness claim. */
+export interface RequestContextPart {
+	readonly messageIndex: number
+	readonly partIndex: number
+	readonly role: MessageRole
+	readonly kind: 'text' | 'image' | 'document' | 'stored' | 'tool-call'
+	readonly digest: string
+	readonly toolCallId?: string
+	readonly isError?: boolean
+}
+
+export interface RequestContextSnapshot {
+	readonly boundary: 'provider-input'
+	readonly parts: readonly RequestContextPart[]
+}
+
+export interface RequestContextChange {
+	/** Parts from the earlier snapshot no longer present, including replaced content. */
+	readonly removed: readonly RequestContextPart[]
+	/** Parts in the new snapshot not present before. */
+	readonly added: readonly RequestContextPart[]
+}
+
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_key, item: unknown) => {
+		if (!item || typeof item !== 'object' || Array.isArray(item)) return item
+		return Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+	})
+}
+
+/**
+ * Inspect supplied messages after compaction and request projection. No content
+ * is retained in the snapshot. A digest identifies exact blocks, not semantic
+ * knowledge, token counts, file versions or provider-private reasoning replay.
+ */
+export function snapshotRequestContext(messages: readonly Message[]): RequestContextSnapshot {
+	const parts: RequestContextPart[] = []
+	for (const [messageIndex, message] of messages.entries()) {
+		let partIndex = 0
+		const add = (kind: RequestContextPart['kind'], payload: unknown, toolCallId?: string) => {
+			parts.push(
+				Object.freeze({
+					messageIndex,
+					partIndex: partIndex++,
+					role: message.role,
+					kind,
+					digest: createHash('sha256').update(canonicalJson(payload)).digest('hex'),
+					...(toolCallId !== undefined ? { toolCallId } : {}),
+					...(message.role === 'tool' ? { isError: message.isError === true } : {}),
+				}),
+			)
+		}
+		const callId = message.role === 'tool' ? message.toolCallId : undefined
+		if (typeof message.content === 'string') add('text', message.content, callId)
+		else if (Array.isArray(message.content)) {
+			for (const block of message.content) {
+				if (block.type === 'text') add('text', block.text, callId)
+				else add(block.type, block, callId)
+			}
+		}
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				add(attachment.type ?? 'image', attachment)
+			}
+		}
+		if (message.role === 'assistant') {
+			for (const call of message.toolCalls ?? []) {
+				add('tool-call', [call.function.name, call.function.arguments], call.id)
+			}
+		}
+	}
+	return Object.freeze({ boundary: 'provider-input', parts: Object.freeze(parts) })
+}
+
+const key = (part: RequestContextPart): string =>
+	JSON.stringify([part.role, part.kind, part.toolCallId, part.isError, part.digest])
+
+/** Compare occurrences, not sets: removing one of two identical blocks is a removal. */
+export function diffRequestContext(
+	previous: RequestContextSnapshot,
+	next: RequestContextSnapshot,
+): RequestContextChange {
+	const unmatched = new Map<string, RequestContextPart[]>()
+	for (const part of previous.parts) {
+		const identity = key(part)
+		const occurrences = unmatched.get(identity) ?? []
+		occurrences.push(part)
+		unmatched.set(identity, occurrences)
+	}
+	const added: RequestContextPart[] = []
+	for (const part of next.parts) {
+		const occurrences = unmatched.get(key(part))
+		if (occurrences?.length) occurrences.pop()
+		else added.push(part)
+	}
+	const removed = [...unmatched.values()]
+		.flat()
+		.sort((a, b) => a.messageIndex - b.messageIndex || a.partIndex - b.partIndex)
+	return Object.freeze({ removed: Object.freeze(removed), added: Object.freeze(added) })
+}

package/src/runtime/query/request-rich-content.ts

@@ -45,20 +45,25 @@ export interface RequestImageIdentity {
 const userMarker = (kind: RichKind): string =>
 	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; attach it again in a new message if it is still needed.]`
 
+// Losing an observation does not undo the action that produced it. This
+// projection knows the result bytes, not whether repeating its tool is safe.
+const toolRecovery =
+	'The original result is retained in conversation history, but this content is not available in the current model request. Recover it from an available saved artifact or a read-only observation if needed. Do not repeat a state-changing action merely to recover its output.'
+
 const toolMarker = (kind: RichKind): string =>
-	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; call the producing tool again if it is still needed.]`
+	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit. ${toolRecovery}]`
 
 const rejectedUserImageMarker = (): string =>
 	'[image omitted from this model request because the provider rejected this image; attach a corrected image in a new message if it is still needed.]'
 
 const rejectedToolImageMarker = (): string =>
-	'[image omitted from this model request because the provider rejected this image; call the producing tool again after correcting its image source if it is still needed.]'
+	`[image omitted from this model request because the provider rejected this image. ${toolRecovery} Correct the image source before presenting it again.]`
 
 const invalidUserImageMarker = (): string =>
 	'[image omitted from this model request because its encoded bytes are not a complete supported raster matching the declared media type; attach a corrected image in a new message if it is still needed.]'
 
 const invalidToolImageMarker = (): string =>
-	'[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type; call the tool again after correcting its image source if it is still needed.]'
+	`[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type. ${toolRecovery} Correct the image source before presenting it again.]`
 
 function assertInlineAttachment(
 	attachment: MessageAttachment,

package/src/runtime/query/review-policy.ts

@@ -25,6 +25,7 @@ import type { ToolRegistry } from '../../registry/tool/execute.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../types/hitl/index.js'
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
+import type { RunId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
 
 export type ReviewMode =
@@ -141,6 +142,8 @@ export function batchNeedsReview(
 
 /** The batch a person is asked about. */
 export interface ToolReviewRequest {
+	/** Originating run, preserved by createReviewHandler for host attribution. */
+	readonly runId?: RunId
 	readonly toolCalls: readonly ToolCallSummary[]
 }
 
@@ -204,7 +207,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		if (mode === 'auto' || !prompt || remembered.all) {
 			return { action: 'approve_tools' }
 		}
-		const answer = await prompt({ toolCalls: request.toolCalls })
+		const answer = await prompt({
+			runId: request.runId,
+			toolCalls: request.toolCalls,
+		})
 		switch (answer.kind) {
 			case 'approve':
 				return { action: 'approve_tools' }

package/src/runtime/query/tooling.ts

@@ -20,6 +20,7 @@ import { ToolExecutor } from './executor.js'
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
 export interface ToolingBootstrapConfig {
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -67,6 +68,7 @@ export class ToolingBootstrap {
 		return new ToolExecutor(
 			{
 				tools: config.tools,
+				...(config.fileReadTracker ? { fileReadTracker: config.fileReadTracker } : {}),
 				runId: config.runId,
 				workingDirectory: config.workingDirectory,
 				...(config.additionalDirectories?.length

package/src/sandbox/file-walk-program.ts

@@ -51,6 +51,14 @@ async function run() {
     try { canonicalRoot = await fs.realpath(plan.root); }
     catch (error) { if (missing(error)) return; throw error; }
     if (canonicalRoot !== path.resolve(plan.root)) throw new Error('File walk root follows a symbolic link; use its authorized real directory');
+    const rootInfo = await fs.lstat(plan.root);
+    if (rootInfo.isFile()) {
+      visit(++visited);
+      if (matchers.some(matcher => matcher.test(path.basename(plan.root)))) {
+        await write({type:'entry', path:plan.root, size:rootInfo.size});
+      }
+      return;
+    }
     let start = plan.root;
     for (const part of plan.prefix) {
       start = path.join(start, part);

package/src/sandbox/file-walk.ts

@@ -227,6 +227,15 @@ async function* executeWalk(
 		}
 		if (canonicalRoot !== path.resolve(plan.root))
 			throw new Error('File walk root follows a symbolic link; use its authorized real directory')
+		// A named regular file is a one-entry search, not an empty directory.
+		const rootInfo = await wait(fs.lstat(plan.root))
+		check()
+		if (rootInfo.isFile()) {
+			noteVisit()
+			if (matchers.some((matcher) => matcher.test(path.basename(plan.root))))
+				yield { path: plan.root, size: rootInfo.size }
+			return
+		}
 		let start = plan.root
 		// Never follow a static-prefix symlink to speed up a pattern: traversal
 		// and its optimized starting point must have the same link policy.

package/src/scheduler/completion-inbox.ts

@@ -464,6 +464,9 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 			`task_id: ${handle.taskId}`,
 			`agent: ${handle.agentId}`,
 			`state: ${handle.state}`,
+			...(handle.state === 'completed' && run?.stopReason && run.stopReason !== 'end_turn'
+				? ['outcome: incomplete — execution stopped; this does not establish task completion.']
+				: []),
 			...(handle.result?.stopReason ? [`stop_reason: ${handle.result.stopReason}`] : []),
 			...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
 			'',

package/src/scheduler/local.ts

@@ -112,6 +112,8 @@ export class LocalTaskScheduler implements TaskScheduler {
 			{
 				agentId: options.agentId,
 				beforeStart: options.beforeStart,
+				...(options.planId ? { planId: options.planId } : {}),
+				...(options.planStepId ? { planStepId: options.planStepId } : {}),
 				input: {
 					messages: [createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,

package/src/store/run/token-budget-disk.ts

@@ -227,6 +227,9 @@ function assertSameRoot(before: TokenBudgetSnapshot, after: TokenBudgetSnapshot)
 			!current ||
 			current.accountId !== previous.accountId ||
 			current.runId !== previous.runId ||
+			(previous.unresolved === true &&
+				current.unresolved !== true &&
+				(active.has(previous.id) || current.usage === undefined)) ||
 			(reconciled && current.usage === undefined) ||
 			!usageAtLeast(current.usage, previous.usage)
 		) {

package/src/testing.ts

@@ -38,3 +38,5 @@ export {
 	defineProviderDriverConformance,
 } from './provider/conformance.js'
 export type { ProviderDriverConformanceOptions } from './provider/conformance.js'
+
+export { fixtureId } from './test-support/ids.js'

package/src/tools/builtins/edit.ts

@@ -362,12 +362,18 @@ export const EditTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const buffer = await context.sandbox.readFile(parsed.data.path)
-				const result = applyEdit(buffer.toString('utf-8'), normalized.operations)
+				const content = buffer.toString('utf-8')
+				const seen = context.fileReadTracker?.fingerprint?.(parsed.data.path)
+				if (seen !== undefined && seen !== fingerprintContent(content)) {
+					return { success: false as const, output: '', error: staleFileError(parsed.data.path) }
+				}
+				const result = applyEdit(content, normalized.operations)
 				if (!result.success) {
 					return { success: false as const, output: '', error: result.error }
 				}
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
+				context.fileReadTracker?.recordRead(parsed.data.path, result.content)
 				return {
 					success: true as const,
 					output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
@@ -378,33 +384,12 @@ export const EditTool = defineTool({
 			const hostPath = filePath as string
 			const content = await readFile(hostPath, 'utf-8')
 
-			const result = applyEdit(content, normalized.operations)
-			if (!result.success) {
-				// The anchor did not match what is on disk. Two very different
-				// situations produce that, and the difference is the whole
-				// value of the fingerprint:
-				//
-				// The file is as the agent left it, and the anchor is simply
-				// wrong — "not found, match the whitespace exactly" is the
-				// right thing to say.
-				//
-				// Or the file moved after the read — a person in an editor,
-				// another process, a second agent — and the same message is a
-				// lie that sends the agent to re-check text that was never the
-				// problem, so it retries the identical edit against the same
-				// moved file.
-				//
-				// Deliberately NOT a gate on the successful path. An anchor
-				// that still matches uniquely is well defined however much
-				// changed elsewhere in the file, and refusing there would
-				// reject safe edits every time anyone touched an unrelated
-				// line.
-				const seen = context.fileReadTracker?.fingerprint?.(hostPath)
-				if (seen !== undefined && seen !== fingerprintContent(content)) {
-					return { success: false as const, output: '', error: staleFileError(hostPath) }
-				}
-				return { success: false as const, output: '', error: result.error }
+			const seen = context.fileReadTracker?.fingerprint?.(hostPath)
+			if (seen !== undefined && seen !== fingerprintContent(content)) {
+				return { success: false as const, output: '', error: staleFileError(hostPath) }
 			}
+			const result = applyEdit(content, normalized.operations)
+			if (!result.success) return { success: false as const, output: '', error: result.error }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/file-write-result.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto'
+import type { ToolResult } from '../../types/tool/index.js'
+
+/** A final newline terminates a line; it does not add an empty line. */
+function lines(text: string): string[] {
+	if (text === '') return []
+	const result = text.split('\n')
+	if (result.at(-1) === '') result.pop()
+	return result
+}
+
+/** null means the backend could not establish the previous state. */
+export function fileWriteResult(
+	path: string,
+	before: string | undefined | null,
+	after: string,
+	sandboxed = false,
+): ToolResult {
+	const operation =
+		before === null
+			? 'write'
+			: before === undefined
+				? 'create'
+				: before === after
+					? 'unchanged'
+					: 'replace'
+	const oldLines = lines(before ?? '')
+	const newLines = lines(after)
+	let start = 0
+	let end = 0
+	if (typeof before === 'string') {
+		while (
+			start < oldLines.length &&
+			start < newLines.length &&
+			oldLines[start] === newLines[start]
+		)
+			start++
+		while (
+			end < oldLines.length - start &&
+			end < newLines.length - start &&
+			oldLines[oldLines.length - end - 1] === newLines[newLines.length - end - 1]
+		)
+			end++
+	}
+	const removed = oldLines.slice(start, oldLines.length - end)
+	const added = newLines.slice(start, newLines.length - end)
+	const bytes = Buffer.byteLength(after, 'utf8')
+	const label =
+		operation === 'create'
+			? 'Created'
+			: operation === 'replace'
+				? 'Updated'
+				: operation === 'unchanged'
+					? 'Unchanged'
+					: 'Wrote'
+	const newlineChanged =
+		typeof before === 'string' && before.endsWith('\n') !== after.endsWith('\n')
+	const summary = `${label} ${path}${before === null ? '' : ` (+${added.length} -${removed.length})`}${newlineChanged ? ' · final newline changed' : ''}`
+	return {
+		success: true,
+		output: `${summary} · ${bytes} bytes`,
+		data: {
+			path,
+			size: after.length,
+			...(sandboxed ? { sandboxed: true } : {}),
+			fileChange: {
+				operation,
+				...(before === null
+					? {}
+					: {
+							preview: {
+								before: removed.length ? `${removed.join('\n')}\n` : '',
+								after: added.length ? `${added.join('\n')}\n` : '',
+							},
+						}),
+				bytes,
+				sha256: createHash('sha256').update(after, 'utf8').digest('hex'),
+				...(before === null
+					? {}
+					: { added: added.length, removed: removed.length, newlineChanged }),
+			},
+		},
+	}
+}

package/src/tools/builtins/glob.ts

@@ -68,7 +68,13 @@ export const GlobTool = defineTool({
 	timeoutMs: 15_000,
 
 	presentCall(input) {
-		return { kind: 'generic', label: `${input.pattern} in ${input.path ?? '.'}` }
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Find ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
 	},
 
 	async execute(input, context) {

package/src/tools/builtins/grep.ts

@@ -98,6 +98,16 @@ export const GrepTool = defineTool({
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
+
+	presentCall(input) {
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Search ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
 	timeoutMs: 15_000,
 
 	async execute(input, context) {

package/src/tools/builtins/job.ts

@@ -54,6 +54,14 @@ export const JobTool = defineTool({
 	destructive: (input: JobInput) => input.action === 'kill',
 	concurrencySafe: true,
 
+	presentCall(input) {
+		const label =
+			input.action === 'list'
+				? 'List background jobs'
+				: `${input.action === 'kill' ? 'Stop background job' : 'Read background output'} · ${input.id ?? '(missing id)'}`
+		return { kind: 'generic', presentation: 'activity', label }
+	},
+
 	async execute(input, context) {
 		if (!context.backgroundJobs) {
 			return {

package/src/tools/builtins/read-file.ts

@@ -32,6 +32,16 @@ export const ReadFileTool = defineTool({
 	destructive: false,
 	concurrencySafe: true,
 
+	presentCall(input) {
+		if (typeof input.path !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Read ${input.path}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
+
 	async execute(input, context) {
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {

package/src/tools/builtins/write-file.ts

@@ -7,6 +7,7 @@ import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
+import { fileWriteResult } from './file-write-result.js'
 
 const inputSchema = z
 	.object({
@@ -81,40 +82,35 @@ export const WriteFileTool = defineTool({
 	destructive: true,
 	concurrencySafe: false,
 
-	/**
-	 * The whole file body, described by the tool.
-	 *
-	 * A `diff` with an EMPTY `before`, which is what a write actually is:
-	 * whatever was there is gone and this is what replaces it. `edit`
-	 * declines to do that for an insert — there, an empty `before` would
-	 * claim the whole file was added and it was not. Here it is true.
-	 *
-	 * A host with nothing to contrast against renders the `after` plainly
-	 * rather than as `+` lines, which is the row a reader wants: they are
-	 * approving a file, not reviewing a patch.
-	 */
+	// Input alone cannot establish whether this replaces an existing file.
 	presentCall(input: WriteInput) {
-		const content = input.content ?? input.newStr
-		if (typeof content !== 'string') return undefined
-		return {
-			kind: 'diff' as const,
-			...(input.path ? { path: input.path } : {}),
-			before: '',
-			after: content,
-		}
+		return { kind: 'generic' as const, label: input.path }
 	},
 
-	/**
-	 * A label, deliberately — which is what suppresses the detail block.
-	 *
-	 * The content was already shown under the CALL, where the user could
-	 * act on it. Repeating it under the result doubles the longest rows in
-	 * the transcript to say nothing new. A host used to decide this by
-	 * matching `name === 'write' || name === 'edit'`; it is the tool's to
-	 * say, and now it says it.
-	 */
+	/** The receipt names the observed operation; failures retain their error output. */
 	presentResult(_input: WriteInput, result: ToolResult) {
-		return { kind: 'generic' as const, label: result.output?.split('\n')[0] ?? '' }
+		const data = result.data as
+			| { fileChange?: { preview?: { before?: unknown; after?: unknown } } }
+			| undefined
+		const preview = data?.fileChange?.preview
+		if (
+			result.success &&
+			typeof preview?.before === 'string' &&
+			typeof preview.after === 'string'
+		) {
+			return {
+				kind: 'diff' as const,
+				path: _input.path,
+				label: result.output?.split('\n')[0],
+				before: preview.before,
+				after: preview.after,
+			}
+		}
+		return {
+			kind: 'generic' as const,
+			label: result.output?.split('\n')[0] ?? '',
+			...(result.success ? { presentation: 'activity' as const } : {}),
+		}
 	},
 
 	async execute(input: WriteInput, context) {
@@ -146,7 +142,7 @@ export const WriteFileTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const current = await readSandboxFileIfPresent(context, valid.path)
-				if (current !== undefined) {
+				if (current !== undefined && current !== null) {
 					const guard = enforceFreshOverwrite(context, valid.path, current.toString('utf-8'))
 					if (guard) return guard
 				}
@@ -155,11 +151,12 @@ export const WriteFileTool = defineTool({
 				// the boolean would leave an older content fingerprint in place and
 				// make the next same-run write refuse its own predecessor as drift.
 				context.fileReadTracker?.recordRead(valid.path, content)
-				return {
-					success: true as const,
-					output: `File written successfully: ${valid.path} (${content.length} chars) [sandboxed]`,
-					data: { path: valid.path, size: content.length, sandboxed: true },
-				}
+				return fileWriteResult(
+					valid.path,
+					current === null ? null : current?.toString('utf-8'),
+					content,
+					true,
+				)
 			}
 
 			const hostPath = filePath as string
@@ -176,11 +173,7 @@ export const WriteFileTool = defineTool({
 			await atomicWriteFile(hostPath, content)
 			context.fileReadTracker?.recordRead(hostPath, content)
 
-			return {
-				success: true as const,
-				output: `File written successfully: ${hostPath} (${content.length} chars)`,
-				data: { path: hostPath, size: content.length },
-			}
+			return fileWriteResult(hostPath, current, content)
 		})
 	},
 })
@@ -237,14 +230,16 @@ function isMissingFileError(error: unknown): boolean {
 async function readSandboxFileIfPresent(
 	context: ToolContext,
 	path: string,
-): Promise<Buffer | undefined> {
+): Promise<Buffer | undefined | null> {
 	if (!context.sandbox) return undefined
 	try {
 		return await context.sandbox.readFile(path)
-	} catch {
+	} catch (error) {
+		if (isMissingFileError(error)) return undefined
 		// `Sandbox` currently has no typed missing-file result. Preserve the
 		// existing create behavior for all backends; when a read succeeds, the
 		// exact body above is still a real admission-time freshness check.
-		return undefined
+		// An untyped read failure does not prove that the target was absent.
+		return null
 	}
 }

package/src/tools/coordinator/index.ts

@@ -566,6 +566,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// could report `failed` or stay `executing` forever but never
 			// `completed`.
 			const planStepId = plan_step_id
+			const planId = planStepId ? getPlanManager?.()?.active?.id : undefined
 			const reportStep = (status: 'running' | 'completed' | 'failed', error?: string): void => {
 				if (!planStepId) return
 				getPlanManager?.()?.updateStepStatus(planStepId, status, error)
@@ -595,6 +596,8 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				prompt,
 				workingDirectory: cwd,
 				runtimeContext: opts.runtimeContext,
+				...(planStepId ? { planStepId } : {}),
+				...(planId ? { planId } : {}),
 				// Hang the child run off THIS tool's span, so the delegation
 				// shows up inside the turn that asked for it.
 				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),

package/src/tools/file-read-tracker.ts

@@ -0,0 +1,16 @@
+import type { FileReadTracker } from '../types/tool/index.js'
+import { fingerprintContent } from './builtins/content-fingerprint.js'
+
+/** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
+export function createFileReadTracker(): FileReadTracker {
+	const paths = new Set<string>()
+	const fingerprints = new Map<string, string>()
+	return {
+		recordRead(key, content) {
+			paths.add(key)
+			if (content !== undefined) fingerprints.set(key, fingerprintContent(content))
+		},
+		hasRead: (key) => paths.has(key),
+		fingerprint: (key) => fingerprints.get(key),
+	}
+}

package/src/tools/task/list.ts

@@ -8,7 +8,7 @@ export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefin
 	return defineTool({
 		name: 'task_list',
 		description:
-			'List all tasks for the current run. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
+			'List planning items for the current run, not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
 		inputSchema: z.object({}),
 		category: 'custom',
 		permissions: [],
@@ -46,7 +46,7 @@ export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefin
 				success: true,
 				output:
 					tasks.length === 0
-						? 'No tasks yet.'
+						? 'No planning tasks yet. This list does not report delegated agent status; use agent_task_list when available.'
 						: `${stats.total} tasks: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
 				data: { tasks: summary, stats },
 			}

package/src/types/agent/reactive.ts

@@ -19,6 +19,8 @@ import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface ReactiveAgentConfig extends BaseAgentConfig {
 	systemPrompt?: string
+	/** Provider-hosted search for this run; the selected driver must support it. */
+	webSearch?: { mode: 'live' | 'cached' }
 
 	persona?: AgentPersona