@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/tools/dispatch-runner.ts

@@ -90,7 +90,9 @@ import type {
 import type { ToolInvokeOptions, ToolResult, ToolResultDetails } from "./registry.js";
 import { truncateUtf8 } from "./truncate-utf8.js";
 import {
+	compactHelperResultLines,
 	receiptEvidenceLabels,
+	receiptHelperResult,
 	SPOT_CHECK_GUIDANCE,
 	workerTextLabel,
 	workerTextNonEvidenceNotices,
@@ -474,6 +476,7 @@ function formatDispatchOutput(
 		.map((run) => integrityFailureBanner(run))
 		.filter((banner): banner is string => banner !== null);
 	const needsSpotCheck = runs.some((run) => {
+		if (receiptHelperResult(run.receipt, run.integrity) !== null) return false;
 		const state = adaptRunReceiptTrustStatus(run.receipt, { integrity: run.integrity }).validationGrounding.state;
 		return state === "absent" || state === "unknown" || state === "ungrounded";
 	});
@@ -485,6 +488,8 @@ function formatDispatchOutput(
 		"",
 		...runs.flatMap((run, index) => {
 			const { receipt, receiptPath } = run;
+			const helperLines = compactHelperResultLines(receipt, run.integrity, perRunOutputBytes);
+			if (helperLines !== null) return helperLines;
 			const note = successNote(receipt);
 			const noteSuffix = note !== null ? ` note=${note}` : "";
 			// A non-success outcome is load-bearing evidence (a timeout has no
@@ -579,7 +584,9 @@ function dispatchDetails(
 			// field so a run entry without them keeps its exact shape.
 			const provenance = extractRunProvenance(receipt);
 			const trustStatus = adaptRunReceiptTrustStatus(receipt, { integrity });
+			const helperResult = receiptHelperResult(receipt, integrity);
 			return {
+				...(helperResult !== null ? { helperResult } : {}),
 				runId: receipt.runId,
 				agentId: receipt.agentId,
 				exitCode: receipt.exitCode,
@@ -2113,6 +2120,16 @@ export async function runDispatchTool(
 		runEvents: inputDeps.runEvents ?? createDispatchRunEventRegistry(),
 	};
 	const snapshot = admissionState.trustedExecutionSnapshots.get(args);
+	if (
+		options?.turnConstraints?.allowedTools !== undefined &&
+		(snapshot?.kind === "apply-winner" || (snapshot?.kind === "dispatch" && snapshot.mode === "compete"))
+	) {
+		return {
+			kind: "error",
+			message:
+				"dispatch: compete/worktree application cannot run under a capability allowlist; use a native single-worker assignment",
+		};
+	}
 	if (snapshot?.kind === "list") {
 		const catalog = deps.getAgentCatalog?.().trim() ?? "";
 		if (catalog.length === 0) {
@@ -2179,6 +2196,7 @@ export async function runDispatchTool(
 	// admission bounds. Keep these off the serializable approved request.
 	const dispatch = deps.dispatch;
 	const preparation = {
+		...(options?.turnConstraints === undefined ? {} : { turnConstraints: structuredClone(options.turnConstraints) }),
 		...(options?.hostRun === undefined ? {} : { hostRun: structuredClone(options.hostRun) }),
 		...(options?.signal === undefined ? {} : { signal: options.signal }),
 		...(timeoutMs === undefined ? {} : { deadlineAt: Date.now() + timeoutMs }),

package/src/tools/dispatch-schema.ts

@@ -1,4 +1,4 @@
-import { type Static, Type } from "typebox";
+import { Type } from "typebox";
 import type { FleetSettings } from "../core/defaults.js";
 import { RESULT_SUMMARY_MAX_BYTES_CEILING } from "../domains/agents/result-contract.js";
 import { WORKER_CONTEXT_SPLICE_TOKENS } from "../domains/context/worker/contract.js";
@@ -73,8 +73,7 @@ const DispatchBudgetSchema = Type.Object(
 	},
 	{
 		additionalProperties: false,
-		description:
-			"Advisory tool-call estimate; choose appropriate counts even above recipe recommendations. retryRevision sets a retry/revision estimate. Crossing estimates does not stop work.",
+		description: "Advisory call counts, never a hard stop. retryRevision estimates a retry.",
 	},
 );
 
@@ -89,11 +88,9 @@ const DispatchVerificationSchema = Type.Array(
 	{ maxItems: 8 },
 );
 
-// The intent and budget schemas are wanted at the top level and on every
-// task. Each is serialized once, under `$defs`, and referenced by JSON
-// pointer from both places; the per-task copies alone cost 371 tokens of
-// every first turn on the ornith tokenizer. TypeBox's validator and pi's
-// argument validator both resolve the pointer.
+// Keep nested schemas self-contained. Pi's non-strict Anthropic adapter carries
+// root properties/required but drops root $defs, leaving references unresolved.
+// Inline objects cost more prompt tokens but preserve the actual provider contract.
 const DispatchIntentSchema = Type.Object(
 	{
 		read_roots: Type.Optional(Type.Array(Type.String(), { maxItems: 32 })),
@@ -101,7 +98,7 @@ const DispatchIntentSchema = Type.Object(
 			Type.Array(Type.String(), {
 				maxItems: 32,
 				description:
-					"Paths the worker may write; every expected output sits under one. Declaring any confines the worker and removes bash and verify from it, so put checks in verification instead of the task text.",
+					"Allowed write paths containing every expected output. Confines the worker and disables bash/verify; declare checks in verification.",
 			}),
 		),
 		relevant_paths: Type.Optional(Type.Array(Type.String(), { maxItems: 32 })),
@@ -113,13 +110,10 @@ const DispatchIntentSchema = Type.Object(
 	{
 		additionalProperties: false,
 		description:
-			"Repository-relative paths and outputs. Declare it on every dispatch: it selects the project rules that apply and pins worker context, where omitting it falls back to path tokens scraped from the task text. verification entries are declared check ids from package scripts or .clio-coder/verifiers.yaml. Per-task intent fields override inherited top-level fields within its scope. For disjoint parallel writes, set each task's write_roots to only its assigned outputs; expected_outputs alone does not narrow write access.",
+			"Required paths and check IDs. Per-task values override defaults. Parallel write_roots must be disjoint; expected_outputs does not confine access.",
 	},
 );
 
-const IntentRef = Type.Unsafe<Static<typeof DispatchIntentSchema>>({ $ref: "#/$defs/intent" });
-const BudgetRef = Type.Unsafe<Static<typeof DispatchBudgetSchema>>({ $ref: "#/$defs/budget" });
-
 const MODE_DESCRIPTION: Record<"full" | "noCouncil" | "noCompete" | "neither", string> = {
 	full:
 		"parallel (default); sequential; pipeline, where each task receives the previous output; compete, where candidates build the same task in scratch worktrees and a judge picks; council, where roster members answer the same question.",
@@ -154,16 +148,9 @@ const WorkerContextSchema = Type.Union(
 		),
 	],
 	{
-		description: `Parent conversation: isolated (default), fork (native history; never silently truncated), or splice (selected text evidence, default ${WORKER_CONTEXT_SPLICE_TOKENS} tokens). refs: tool:<call-id> or message:<index> in the current snapshot. Batch defaults may be overridden per task.`,
+		description: `Parent history: isolated (default), fork (full native transcript), splice (selected text, default ${WORKER_CONTEXT_SPLICE_TOKENS} tokens). refs: tool:<id> or message:<index>. Per-task overrides allowed.`,
 	},
 );
-const ContextRef = Type.Unsafe<Static<typeof WorkerContextSchema>>({ $ref: "#/$defs/workerContext" });
-const DISPATCH_DEFS = {
-	intent: DispatchIntentSchema,
-	budget: DispatchBudgetSchema,
-	workerContext: WorkerContextSchema,
-};
-
 export function buildDispatchParameters(composition: DispatchSchemaComposition = FULL_DISPATCH_SCHEMA_COMPOSITION) {
 	const modes = [
 		"parallel",
@@ -180,196 +167,190 @@ export function buildDispatchParameters(composition: DispatchSchemaComposition =
 				: composition.council
 					? MODE_DESCRIPTION.noCompete
 					: MODE_DESCRIPTION.neither;
-	return Type.Object(
-		{
-			list: Type.Optional(Type.Boolean({ description: "List the agent roster instead of dispatching." })),
-			from_scout: Type.Optional(
-				Type.Object(
-					{
-						run_id: Type.String({ description: "Terminal Scout run id." }),
-						receipt_digest: Type.String({ description: "Its sha256 receipt digest." }),
-					},
-					{
-						additionalProperties: false,
-						description: "Compile a Scout split result into one approval-gated dependency plan; use with no other argument.",
-					},
-				),
-			),
-			task: Type.Optional(Type.String({ description: "One worker assignment. Use tasks for a batch." })),
-			tasks: Type.Optional(
-				Type.Array(
-					Type.Union([
-						Type.String(),
-						// A task carries only what varies per task. persona, tool_profile,
-						// cwd, and apply come from the batch defaults (admission still reads
-						// them when a caller sends them; the schema no longer spends the
-						// tokens advertising them twice).
-						Type.Object({
-							task: Type.String({ description: "The assignment, with expected output and constraints." }),
-							context: Type.Optional(ContextRef),
-							briefing: Type.Optional(
-								Type.String({ description: `Per-task parent context, max ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes.` }),
-							),
-							agent: Type.Optional(
-								Type.String({
-									description:
-										"Recipe id for this task: set scout/documenter explicitly in a mixed pipeline; names in task text do not select recipes, and omission inherits the batch/default recipe.",
-								}),
-							),
-							budget: Type.Optional(BudgetRef),
-							target: Type.Optional(Type.String()),
-							model: Type.Optional(Type.String()),
-							node: Type.Optional(Type.String({ description: "Fleet node pin: local or a fleet.nodes id." })),
-							worktree: Type.Optional(Type.Literal(true, { description: "Run this writer in an isolated git worktree." })),
-							intent: Type.Optional(IntentRef),
-							gate: Type.Optional(Type.String({ description: "One declared check id, shorthand for intent.verification." })),
-							result_summary_max_bytes: Type.Optional(
-								Type.Integer({
-									minimum: 1,
-									maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
-									description: "This task's inline summary allowance; mutation-report workers (coder, documenter) only.",
-								}),
-							),
-						}),
-					]),
-					{ description: "Batch of assignments; one string or object is wrapped." },
-				),
+	return Type.Object({
+		list: Type.Optional(Type.Boolean({ description: "List the agent roster instead of dispatching." })),
+		from_scout: Type.Optional(
+			Type.Object(
+				{
+					run_id: Type.String({ description: "Terminal Scout run id." }),
+					receipt_digest: Type.String({ description: "Its sha256 receipt digest." }),
+				},
+				{
+					additionalProperties: false,
+					description: "Compile a Scout split result into one approval-gated dependency plan; use with no other argument.",
+				},
 			),
-			mode: Type.Optional(StringEnum(modes, { description: modeDescription })),
-			...(composition.council
-				? {
-						roster: Type.Optional(Type.String({ description: "Configured workers.rosters name (council)." })),
-						members: Type.Optional(
-							Type.Array(CouncilMemberSchema, { minItems: 2, maxItems: 5, description: "Explicit council members, 2 to 5." }),
+		),
+		task: Type.Optional(Type.String({ description: "One worker assignment. Use tasks for a batch." })),
+		tasks: Type.Optional(
+			Type.Array(
+				Type.Union([
+					Type.String(),
+					// A task carries only what varies per task. persona, tool_profile,
+					// cwd, and apply come from the batch defaults (admission still reads
+					// them when a caller sends them; the schema no longer spends the
+					// tokens advertising them twice).
+					Type.Object({
+						task: Type.String({ description: "The assignment, with expected output and constraints." }),
+						context: Type.Optional(WorkerContextSchema),
+						briefing: Type.Optional(
+							Type.String({ description: `Per-task parent context, max ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes.` }),
 						),
-						synthesis: Type.Optional(StringEnum(["none", "judge", "vote"] as const, { description: "Council synthesis." })),
-						rounds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3, description: "Council rounds." })),
-					}
-				: {}),
-			writers: Type.Optional(
-				Type.Literal(1, { description: "Serialize writer admission in task order while readers run concurrently." }),
-			),
-			worktree: Type.Optional(
-				Type.Literal(true, { description: "Run a singular writer task in an isolated git worktree." }),
-			),
-			apply: Type.Optional(
-				StringEnum(["merge", "preserve"], { description: "merge (default) or preserve the worktree branch." }),
-			),
-			detach: Type.Optional(
-				Type.Boolean({
-					description: "Return run ids immediately and collect with monitor before final synthesis. Parallel mode only.",
-				}),
-			),
-			review: Type.Optional(
-				Type.Union(
-					[
-						Type.Boolean(),
-						Type.Object({
-							reviewer: Type.Optional(
-								Type.String({ description: "Reviewer recipe id (default: the builder's agent, read-only)." }),
-							),
-							max_cycles: Type.Optional(
-								Type.Number({ description: "Review/revise cycles before an operator decision (default 2, max 4)." }),
-							),
-							node: Type.Optional(Type.String({ description: "Fleet node pin for the reviewer." })),
-							model: Type.Optional(Type.String({ description: "Model for the reviewer." })),
-							target: Type.Optional(Type.String({ description: "Target for the reviewer." })),
-						}),
-					],
-					{
-						description:
-							"Reviewer gate for one task: a read-only reviewer verdicts pass, revise, or fail, and revise re-runs the builder with the findings.",
-					},
-				),
-			),
-			...(composition.compete
-				? {
-						candidates: Type.Optional(Type.Number({ description: "Compete candidates, 2 to 4 (default 2)." })),
-						judge: Type.Optional(
-							Type.Object(
-								{
-									agent: Type.Optional(Type.String({ description: "Judge recipe id (default: the builder's agent)." })),
-									model: Type.Optional(Type.String()),
-									target: Type.Optional(Type.String()),
-									node: Type.Optional(Type.String({ description: "Fleet node pin for the judge." })),
-								},
-								{ description: "Read-only judge that ranks compete candidates." },
-							),
+						agent: Type.Optional(
+							Type.String({
+								description:
+									"Recipe id for this task: set scout/documenter explicitly in a mixed pipeline; names in task text do not select recipes, and omission inherits the batch/default recipe.",
+							}),
 						),
-						apply_winner: Type.Optional(
-							Type.Object(
-								{
-									branch: Type.String({ description: "Preserved winner branch: clio-coder/compete/<group>/<n>." }),
-									cwd: Type.Optional(Type.String({ description: "Repository root (default: current directory)." })),
-								},
-								{
-									description:
-										"Merge a preserved compete winner and clean up its group; supervised autonomy parks this for operator confirmation.",
-								},
-							),
+						budget: Type.Optional(DispatchBudgetSchema),
+						target: Type.Optional(Type.String()),
+						model: Type.Optional(Type.String()),
+						node: Type.Optional(Type.String({ description: "Fleet node pin: local or a fleet.nodes id." })),
+						worktree: Type.Optional(Type.Literal(true, { description: "Run this writer in an isolated git worktree." })),
+						intent: Type.Optional(DispatchIntentSchema),
+						gate: Type.Optional(Type.String({ description: "One declared check id, shorthand for intent.verification." })),
+						result_summary_max_bytes: Type.Optional(
+							Type.Integer({
+								minimum: 1,
+								maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
+								description: "This task's inline summary allowance; mutation-report workers (coder, documenter) only.",
+							}),
 						),
-					}
-				: {}),
-			agent: Type.Optional(
-				Type.String({
-					description: composition.council
-						? "Default recipe id for tasks without their own agent, or auto (default coder; researcher for council)."
-						: "Default recipe id for tasks without their own agent, or auto (default coder).",
-				}),
+					}),
+				]),
+				{ description: "Batch of assignments; one string or object is wrapped." },
 			),
-			context: Type.Optional(ContextRef),
-			briefing: Type.Optional(
-				Type.String({
-					description: `Parent context for task, or the shared default for tasks; never instructions. Max ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes.`,
-				}),
-			),
-			intent: Type.Optional(IntentRef),
-			gate: Type.Optional(Type.String({ description: "One declared check id, shorthand for intent.verification." })),
-			persona: Type.Optional(Type.String({ description: "Default persona for the batch, max 8000 chars." })),
-			tool_profile: Type.Optional(StringEnum(TOOL_PROFILE_NAMES, { description: "Default worker tool profile." })),
-			budget: Type.Optional(BudgetRef),
-			target: Type.Optional(Type.String({ description: "Default target id (omit for the fleet default)." })),
-			model: Type.Optional(Type.String({ description: "Default model override." })),
-			node: Type.Optional(Type.String({ description: "Default fleet node pin (omit for automatic placement)." })),
-			routing: Type.Optional(
-				Type.Object(
-					{
-						...(composition.adaptiveRouting
-							? { posture: Type.Optional(StringEnum(["manual", "quality", "balanced", "latency", "economy"] as const)) }
-							: {}),
-						maxCostUsd: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
-						deadlineMs: Type.Optional(Type.Integer({ exclusiveMinimum: 0 })),
-						...(composition.adaptiveRouting
-							? { minimumQuality: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })) }
-							: {}),
-						requiredCapabilities: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-						...(composition.adaptiveRouting
-							? {
-									locality: Type.Optional(StringEnum(["local-only", "prefer-local", "any"] as const)),
-									failover: Type.Optional(StringEnum(["none", "approved"] as const)),
-								}
-							: {}),
-					},
-					{
-						additionalProperties: false,
-						description: composition.adaptiveRouting
-							? "Advisory posture and hard routing bounds; exact target, model, and node pins stay manual."
-							: "Hard routing bounds: cost ceiling, deadline, and required model capabilities.",
-					},
-				),
+		),
+		mode: Type.Optional(StringEnum(modes, { description: modeDescription })),
+		...(composition.council
+			? {
+					roster: Type.Optional(Type.String({ description: "Configured workers.rosters name (council)." })),
+					members: Type.Optional(
+						Type.Array(CouncilMemberSchema, { minItems: 2, maxItems: 5, description: "Explicit council members, 2 to 5." }),
+					),
+					synthesis: Type.Optional(StringEnum(["none", "judge", "vote"] as const, { description: "Council synthesis." })),
+					rounds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3, description: "Council rounds." })),
+				}
+			: {}),
+		writers: Type.Optional(
+			Type.Literal(1, { description: "Serialize writer admission in task order while readers run concurrently." }),
+		),
+		worktree: Type.Optional(
+			Type.Literal(true, { description: "Run a singular writer task in an isolated git worktree." }),
+		),
+		apply: Type.Optional(
+			StringEnum(["merge", "preserve"], { description: "merge (default) or preserve the worktree branch." }),
+		),
+		detach: Type.Optional(
+			Type.Boolean({
+				description: "Return run ids immediately and collect with monitor before final synthesis. Parallel mode only.",
+			}),
+		),
+		review: Type.Optional(
+			Type.Union(
+				[
+					Type.Boolean(),
+					Type.Object({
+						reviewer: Type.Optional(
+							Type.String({ description: "Reviewer recipe id (default: the builder's agent, read-only)." }),
+						),
+						max_cycles: Type.Optional(
+							Type.Number({ description: "Review/revise cycles before an operator decision (default 2, max 4)." }),
+						),
+						node: Type.Optional(Type.String({ description: "Fleet node pin for the reviewer." })),
+						model: Type.Optional(Type.String({ description: "Model for the reviewer." })),
+						target: Type.Optional(Type.String({ description: "Target for the reviewer." })),
+					}),
+				],
+				{
+					description: "Read-only review of one task: pass, fail, or revise (re-run builder with findings).",
+				},
 			),
-			thinking_level: Type.Optional(StringEnum(THINKING_LEVELS)),
-			cwd: Type.Optional(Type.String({ description: "Default worker working directory." })),
-			timeout_ms: Type.Optional(Type.Number({ description: "Abort the dispatch after this many ms." })),
-			max_output_bytes: Type.Optional(Type.Number({ description: "Max summary bytes returned." })),
-			result_summary_max_bytes: Type.Optional(
-				Type.Integer({
-					minimum: 1,
-					maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
-					description: `UTF-8 byte allowance for a mutation-report worker's inline summary (coder, documenter), default 16384. A batch default applies to mutation-report steps only; other steps ignore it. Storage bound, not the returned preview (max_output_bytes).`,
-				}),
+		),
+		...(composition.compete
+			? {
+					candidates: Type.Optional(Type.Number({ description: "Compete candidates, 2 to 4 (default 2)." })),
+					judge: Type.Optional(
+						Type.Object(
+							{
+								agent: Type.Optional(Type.String({ description: "Judge recipe id (default: the builder's agent)." })),
+								model: Type.Optional(Type.String()),
+								target: Type.Optional(Type.String()),
+								node: Type.Optional(Type.String({ description: "Fleet node pin for the judge." })),
+							},
+							{ description: "Read-only judge that ranks compete candidates." },
+						),
+					),
+					apply_winner: Type.Optional(
+						Type.Object(
+							{
+								branch: Type.String({ description: "Preserved winner branch: clio-coder/compete/<group>/<n>." }),
+								cwd: Type.Optional(Type.String({ description: "Repository root (default: current directory)." })),
+							},
+							{
+								description:
+									"Merge a preserved compete winner and clean up its group; supervised autonomy parks this for operator confirmation.",
+							},
+						),
+					),
+				}
+			: {}),
+		agent: Type.Optional(
+			Type.String({
+				description: composition.council
+					? "Recipe id, not model: coder, verifier, scout, or auto. Default coder; researcher for council."
+					: "Recipe id, not model: coder, verifier, scout, or auto. Default coder.",
+			}),
+		),
+		context: Type.Optional(WorkerContextSchema),
+		briefing: Type.Optional(
+			Type.String({
+				description: `Parent context for task, or the shared default for tasks; never instructions. Max ${DISPATCH_BRIEFING_MAX_BYTES} UTF-8 bytes.`,
+			}),
+		),
+		intent: Type.Optional(DispatchIntentSchema),
+		gate: Type.Optional(Type.String({ description: "One declared check id, shorthand for intent.verification." })),
+		persona: Type.Optional(Type.String({ description: "Default persona for the batch, max 8000 chars." })),
+		tool_profile: Type.Optional(StringEnum(TOOL_PROFILE_NAMES, { description: "Default worker tool profile." })),
+		budget: Type.Optional(DispatchBudgetSchema),
+		target: Type.Optional(Type.String({ description: "Default target id (omit for the fleet default)." })),
+		model: Type.Optional(Type.String({ description: "Default model override." })),
+		node: Type.Optional(Type.String({ description: "Default fleet node pin (omit for automatic placement)." })),
+		routing: Type.Optional(
+			Type.Object(
+				{
+					...(composition.adaptiveRouting
+						? { posture: Type.Optional(StringEnum(["manual", "quality", "balanced", "latency", "economy"] as const)) }
+						: {}),
+					maxCostUsd: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+					deadlineMs: Type.Optional(Type.Integer({ exclusiveMinimum: 0 })),
+					...(composition.adaptiveRouting ? { minimumQuality: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })) } : {}),
+					requiredCapabilities: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+					...(composition.adaptiveRouting
+						? {
+								locality: Type.Optional(StringEnum(["local-only", "prefer-local", "any"] as const)),
+								failover: Type.Optional(StringEnum(["none", "approved"] as const)),
+							}
+						: {}),
+				},
+				{
+					additionalProperties: false,
+					description: composition.adaptiveRouting
+						? "Advisory posture and hard routing bounds; exact target, model, and node pins stay manual."
+						: "Hard routing bounds: cost ceiling, deadline, and required model capabilities.",
+				},
 			),
-		},
-		{ $defs: DISPATCH_DEFS },
-	);
+		),
+		thinking_level: Type.Optional(StringEnum(THINKING_LEVELS)),
+		cwd: Type.Optional(Type.String({ description: "Default worker working directory." })),
+		timeout_ms: Type.Optional(Type.Number({ description: "Abort the dispatch after this many ms." })),
+		max_output_bytes: Type.Optional(Type.Number({ description: "Max summary bytes returned." })),
+		result_summary_max_bytes: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				maximum: RESULT_SUMMARY_MAX_BYTES_CEILING,
+				description: `Stored inline summary limit in UTF-8 bytes for mutation-report workers (coder, documenter); default 16384. Other steps ignore it. max_output_bytes separately limits the returned preview.`,
+			}),
+		),
+	});
 }

package/src/tools/edit.ts

@@ -11,7 +11,7 @@ import {
 	stripBom,
 } from "./edit-diff.js";
 import { publishFileAtomically, withFileMutationQueue } from "./file-mutation-queue.js";
-import { resolveToCwd } from "./path-utils.js";
+import { resolveMutationTarget } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 
 const DIFF_LIMIT = 1024 * 1024;
@@ -166,50 +166,54 @@ export const editTool: ToolSpec = {
 		if (!edits || edits.length === 0) {
 			return { kind: "error", message: 'edit: provide edits as [{"oldText":"...","newText":"..."}, ...]' };
 		}
-		const filePath = resolveToCwd(pathArg);
+		const { path: filePath, physical } = resolveMutationTarget(pathArg);
 
 		try {
-			return await withFileMutationQueue(filePath, async () => {
-				const info = await stat(filePath);
-				if (!info.isFile()) throw new Error("Refusing directory or non-file target");
-				const bytes = await readFile(filePath);
-				const originalEnding = await classifyEndings(bytes);
-				let rawContent: string;
-				try {
-					rawContent = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
-				} catch {
-					throw new Error(`Invalid UTF-8 at byte offset ${await invalidUtf8Offset(bytes)}`);
-				}
-				const { bom, text: content } = stripBom(rawContent);
-				let finalContent: string;
-				let diff: ReturnType<typeof generateDiffString> | undefined;
-				if (bytes.length > DIFF_LIMIT) {
-					finalContent = bom + applyLargeExactEdits(content, edits, originalEnding);
-				} else {
-					const applied = applyEditsToNormalizedContent(normalizeToLF(content), edits, pathArg);
-					finalContent = bom + restoreLineEndings(applied.newContent, originalEnding);
-					if (Buffer.byteLength(finalContent, "utf8") <= DIFF_LIMIT) {
-						diff = generateDiffString(applied.baseContent, applied.newContent);
+			return await withFileMutationQueue(
+				filePath,
+				async () => {
+					const info = await stat(filePath);
+					if (!info.isFile()) throw new Error("Refusing directory or non-file target");
+					const bytes = await readFile(filePath);
+					const originalEnding = await classifyEndings(bytes);
+					let rawContent: string;
+					try {
+						rawContent = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+					} catch {
+						throw new Error(`Invalid UTF-8 at byte offset ${await invalidUtf8Offset(bytes)}`);
 					}
-				}
-				const file = await publishFileAtomically(filePath, finalContent);
-				// The validation nudge is point-of-failure conditioning: measured on
-				// a live 35B coder worker, the model edited correctly and then spent
-				// its remaining calls "validating" with navigation tools (code_nav
-				// deps) until the loop guard aborted the run. Naming the real
-				// validation path on the mutation result is the deterministic channel
-				// every agent sees at exactly the moment it matters.
-				return {
-					kind: "ok",
-					output: `edited ${pathArg}: ${edits.length} replacement(s). Validate now: rerun the failing test or verify; navigation tools do not validate edits.${!diff ? "\nnote: diff skipped because the previous or new file exceeds 1 MiB" : ""}${file.durabilityWarning ? `\n${file.durabilityWarning}` : ""}`,
-					details: {
-						file: { before: file.before, after: file.after },
-						diff: diff?.diff,
-						firstChangedLine: diff?.firstChangedLine,
-						paths: [filePath],
-					},
-				};
-			});
+					const { bom, text: content } = stripBom(rawContent);
+					let finalContent: string;
+					let diff: ReturnType<typeof generateDiffString> | undefined;
+					if (bytes.length > DIFF_LIMIT) {
+						finalContent = bom + applyLargeExactEdits(content, edits, originalEnding);
+					} else {
+						const applied = applyEditsToNormalizedContent(normalizeToLF(content), edits, pathArg);
+						finalContent = bom + restoreLineEndings(applied.newContent, originalEnding);
+						if (Buffer.byteLength(finalContent, "utf8") <= DIFF_LIMIT) {
+							diff = generateDiffString(applied.baseContent, applied.newContent);
+						}
+					}
+					const file = await publishFileAtomically(filePath, finalContent);
+					// The validation nudge is point-of-failure conditioning: measured on
+					// a live 35B coder worker, the model edited correctly and then spent
+					// its remaining calls "validating" with navigation tools (code_nav
+					// deps) until the loop guard aborted the run. Naming the real
+					// validation path on the mutation result is the deterministic channel
+					// every agent sees at exactly the moment it matters.
+					return {
+						kind: "ok",
+						output: `edited ${pathArg}: ${edits.length} replacement(s). Validate now: rerun the failing test or verify; navigation tools do not validate edits.${!diff ? "\nnote: diff skipped because the previous or new file exceeds 1 MiB" : ""}${file.durabilityWarning ? `\n${file.durabilityWarning}` : ""}`,
+						details: {
+							file: { before: file.before, after: file.after },
+							diff: diff?.diff,
+							firstChangedLine: diff?.firstChangedLine,
+							paths: [filePath],
+						},
+					};
+				},
+				physical,
+			);
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			const code = (err as NodeJS.ErrnoException | undefined)?.code;