@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/interactive/view/view-overlay.ts

@@ -1,6 +1,6 @@
+import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
 import {
 	type Component,
-	fuzzyFilter,
 	Input,
 	Markdown,
 	matchesKey,
@@ -168,10 +168,6 @@ function isNonEmptySearchValue(value: string | undefined): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
 
-function broadFilterText(artifact: ViewArtifact): string {
-	return `${artifact.id} ${artifact.category} ${artifact.title}`;
-}
-
 function artifactSearchValues(artifact: ViewArtifact): string[] {
 	return [
 		artifact.id,
@@ -188,8 +184,12 @@ function artifactSearchValues(artifact: ViewArtifact): string[] {
 	].filter(isNonEmptySearchValue);
 }
 
-function categoryFilterText(artifact: ViewArtifact): string {
-	return artifactSearchValues(artifact).join(" ");
+function matchesFilterText(artifact: ViewArtifact, query: string): boolean {
+	const values = artifactSearchValues(artifact).map((value) => value.toLocaleLowerCase());
+	return query
+		.toLocaleLowerCase()
+		.split(/\s+/u)
+		.every((token) => values.some((value) => value.includes(token)));
 }
 
 function matchesExactArtifactValue(artifact: ViewArtifact, value: string): boolean {
@@ -225,10 +225,10 @@ function filterViewArtifacts(artifacts: ReadonlyArray<ViewArtifact>, query: stri
 	if (parsed.kind === "category") {
 		const categoryArtifacts = artifacts.filter((artifact) => artifact.category === parsed.category);
 		if (parsed.value.length === 0) return categoryArtifacts;
-		return fuzzyFilter(categoryArtifacts, parsed.value, categoryFilterText);
+		return categoryArtifacts.filter((artifact) => matchesFilterText(artifact, parsed.value));
 	}
 	if (parsed.text.length === 0) return [...artifacts];
-	return fuzzyFilter([...artifacts], parsed.text, broadFilterText);
+	return artifacts.filter((artifact) => matchesFilterText(artifact, parsed.text));
 }
 
 function artifactsInCategoryOrder(artifacts: ReadonlyArray<ViewArtifact>): ViewArtifact[] {
@@ -418,6 +418,7 @@ function viewFooterHint(focus: ViewPaneFocus, canVerify: boolean, innerWidth?: n
 			{ key: "PgUp/PgDn", verb: "page" },
 			{ key: "g/G", verb: "top/bottom" },
 			...(canVerify ? [{ key: "v", verb: "verify" }] : []),
+			{ key: "i", verb: "info" },
 			{ key: "o", verb: "path" },
 		],
 		"back",
@@ -446,31 +447,44 @@ export class ViewOverlayView implements Component {
 	private artifactError: string | null = null;
 	private content: LoadedContent | null = null;
 	private loadToken = 0;
+	private refreshToken = 0;
+	private showProvenance = false;
 	private lastContentWidth = 80;
 	private lastContentBodyHeight = 1;
 	private readonly verifications = new Map<string, ViewVerificationState>();
 
 	constructor(private readonly options: ViewOverlayOptions) {
 		this.filterText = options.initialFilter ?? "";
-		this.filterInput.setValue(this.filterText);
+		this.filterInput.handleInput(`\x1b[200~${this.filterText}\x1b[201~`);
 	}
 
 	refresh(): void {
+		const refreshToken = ++this.refreshToken;
+		const selected = this.selectedArtifact();
+		this.loadToken += 1;
 		this.loadingArtifacts = true;
 		this.artifactError = null;
 		this.options.requestRender?.();
 		void (async () => {
 			try {
-				this.artifacts = await listViewArtifacts(this.options.providers);
-				this.selectedIndex = initialViewSelection(this.artifacts, this.filterText);
+				const artifacts = await listViewArtifacts(this.options.providers);
+				if (refreshToken !== this.refreshToken) return;
+				this.artifacts = artifacts;
+				const retainedIndex = selected
+					? this.filteredArtifacts().findIndex((artifact) => artifactKey(artifact) === artifactKey(selected))
+					: -1;
+				this.selectedIndex = retainedIndex >= 0 ? retainedIndex : initialViewSelection(this.artifacts, this.filterText);
 				this.contentScrollOffset = 0;
 				this.content = null;
 			} catch (err) {
+				if (refreshToken !== this.refreshToken) return;
 				this.artifactError = err instanceof Error ? err.message : String(err);
 				this.artifacts = [];
 			} finally {
-				this.loadingArtifacts = false;
-				this.options.requestRender?.();
+				if (refreshToken === this.refreshToken) {
+					this.loadingArtifacts = false;
+					this.options.requestRender?.();
+				}
 			}
 		})();
 	}
@@ -490,6 +504,8 @@ export class ViewOverlayView implements Component {
 	}
 
 	private selectIndex(next: number): void {
+		this.loadToken += 1;
+		this.showProvenance = false;
 		const filtered = this.filteredArtifacts();
 		if (filtered.length === 0) {
 			this.selectedIndex = 0;
@@ -513,14 +529,17 @@ export class ViewOverlayView implements Component {
 	}
 
 	private ensureContentLoaded(artifact: ViewArtifact | undefined): void {
-		if (!artifact) return;
+		if (!artifact) {
+			this.content = null;
+			return;
+		}
 		const key = artifactKey(artifact);
 		if (this.content?.key === key) return;
 		const token = ++this.loadToken;
 		this.content = { key, status: "loading", lines: [clioTheme().fg("dim", "loading artifact…")], format: "text" };
 		void (async () => {
 			try {
-				const loaded = await artifact.load();
+				const loaded = await Promise.resolve().then(() => artifact.load());
 				if (token !== this.loadToken) return;
 				this.content = { key, status: "loaded", lines: loaded.lines, format: loaded.format };
 			} catch (err) {
@@ -540,6 +559,20 @@ export class ViewOverlayView implements Component {
 	}
 
 	private renderedContentLines(width: number): string[] {
+		if (this.showProvenance) {
+			const artifact = this.selectedArtifact();
+			if (!artifact) return [];
+			return [
+				`Title: ${artifact.title}`,
+				`Category: ${artifact.category}`,
+				`ID: ${artifact.id}`,
+				`Path: ${artifact.path ?? "No backing path"}`,
+				...(artifact.sessionId ? [`Session: ${artifact.sessionId}`] : []),
+				...(artifact.runId ? [`Run: ${artifact.runId}`] : []),
+				...(artifact.correlationId ? [`Correlation: ${artifact.correlationId}`] : []),
+				...(artifact.description ? [`Details: ${artifact.description}`] : []),
+			].flatMap((line) => wrapTextWithAnsi(sanitizeCallTargetText(line), Math.max(1, width)));
+		}
 		const content = this.content;
 		if (!content) return [];
 		if (content.status === "error") return content.lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
@@ -572,10 +605,30 @@ export class ViewOverlayView implements Component {
 		}
 
 		const filtered = this.filteredArtifacts();
-		if (filtered.length === 0) return this.fixedLines([...lines, theme.fg("dim", "No matching details.")], width, height);
+		lines.push(
+			padAnsi(
+				theme.fg(
+					this.focus === "list" ? "accent" : "dim",
+					`List · ${filtered.length}/${this.artifacts.length} · ←→ category`,
+				),
+				width,
+				ELLIPSIS,
+			),
+		);
+		if (filtered.length === 0)
+			return this.fixedLines(
+				[
+					...lines,
+					theme.fg("dim", "No matching details."),
+					theme.fg("muted", "Ctrl+U clears the filter."),
+					theme.fg("dim", "Try workspace: or receipt:"),
+				],
+				width,
+				height,
+			);
 		const rows = groupedViewRows(filtered);
 		const selectedRow = rows.findIndex((row) => row.type === "item" && row.itemIndex === this.selectedIndex);
-		const rowHeight = Math.max(1, height - 1);
+		const rowHeight = Math.max(1, height - lines.length);
 		if (selectedRow >= 0) {
 			if (selectedRow < this.listScrollOffset) this.listScrollOffset = selectedRow;
 			if (selectedRow >= this.listScrollOffset + rowHeight) this.listScrollOffset = selectedRow - rowHeight + 1;
@@ -614,7 +667,21 @@ export class ViewOverlayView implements Component {
 		this.ensureContentLoaded(artifact);
 		this.lastContentWidth = width;
 		const verification = artifact ? this.verifications.get(artifactKey(artifact)) : undefined;
-		const header = buildArtifactHeaderLines(artifact, verification, width);
+		const header = [
+			padAnsi(
+				clioTheme().fg(
+					this.focus === "content" ? "accent" : "dim",
+					this.showProvenance
+						? "Provenance · i preview · Esc list"
+						: this.focus === "content"
+							? "Preview · i info · Esc list"
+							: "Preview · Enter/Tab focus",
+				),
+				width,
+				ELLIPSIS,
+			),
+			...buildArtifactHeaderLines(artifact, verification, width),
+		];
 		const bodyHeight = Math.max(0, height - header.length);
 		this.lastContentBodyHeight = Math.max(1, bodyHeight);
 		const body = this.renderedContentLines(width);
@@ -657,6 +724,7 @@ export class ViewOverlayView implements Component {
 			matchesKey(data, "shift+tab") ||
 			(this.focus === "list" && matchesKey(data, "enter"))
 		) {
+			if (this.focus === "list" && !this.selectedArtifact()) return;
 			this.focus = this.focus === "list" ? "content" : "list";
 			this.options.requestRender?.();
 			return;
@@ -669,6 +737,12 @@ export class ViewOverlayView implements Component {
 			this.selectCategory(1);
 			return;
 		}
+		if (this.focus === "content" && data === "i") {
+			this.showProvenance = !this.showProvenance;
+			this.contentScrollOffset = 0;
+			this.options.requestRender?.();
+			return;
+		}
 		if (this.focus === "content" && data === "v") {
 			this.verifySelected();
 			return;
@@ -704,7 +778,9 @@ export class ViewOverlayView implements Component {
 			return true;
 		}
 		const previous = this.filterText;
-		this.filterInput.handleInput(data);
+		if (matchesKey(data, "ctrl+u")) {
+			this.filterInput.applyEdit("clear");
+		} else this.filterInput.handleInput(data);
 		this.filterText = this.filterInput.getValue();
 		if (previous !== this.filterText) {
 			this.selectInitialFilterMatch();

package/src/tools/agent-tools.ts

@@ -30,6 +30,7 @@ import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "../eng
 import { applyToolProfile, type ToolProfileName } from "./profiles.js";
 import type { ToolInvokeOptions, ToolRegistry, ToolResult, ToolSpec } from "./registry.js";
 import { isDispositionedToolResultError, toolResultContextText } from "./result-disposition.js";
+import { toolSpecPlacement, withGatewayForCapabilities } from "./surface.js";
 
 /**
  * Lightweight per-call observability hook. Default no-op so unused
@@ -308,9 +309,10 @@ function errorMessage(err: unknown): string {
  * (`Value.Check` answers identically with and without), so the copy handed
  * to the agent loop drops every `~`-prefixed key. Symbol keys are copied
  * through untouched because pi-ai picks its coercion path by the TypeBox
- * kind symbol on the root schema.
+ * kind symbol on the root schema. Exported for the gateway's describe, which
+ * hands a capability's schema to the model through a result the same way.
  */
-function wireParameterSchema<T>(schema: T): T {
+export function wireParameterSchema<T>(schema: T): T {
 	if (Array.isArray(schema)) return schema.map((entry) => wireParameterSchema(entry)) as T;
 	if (typeof schema !== "object" || schema === null) return schema;
 	const source = schema as Record<PropertyKey, unknown>;
@@ -374,30 +376,41 @@ function toAgentTool(
  *   1. tools registered on the supplied registry
  *   2. tools whose id appears in `allowedTools`
  *
- * When `allowedTools` is undefined, step 3 is skipped.
+ * projected onto the direct surface: a gateway-placed capability on the
+ * effective list is reachable through the attached `gateway` tool, never as
+ * a schema of its own. When `allowedTools` is undefined, step 2 is skipped.
  */
 export function resolveAgentTools(input: ResolveAgentToolsInput): AgentTool[] {
 	const specs: ToolSpec[] = [];
 	for (const name of effectiveToolNames(input)) {
 		const spec = input.registry.get(name);
-		if (spec) specs.push(spec);
+		if (spec && toolSpecPlacement(spec) === "direct") specs.push(spec);
 	}
 	specs.sort((a, b) => a.name.localeCompare(b.name));
 	return specs.map((spec) => toAgentTool(spec, input.registry, input.telemetry, input.invokeOptions));
 }
 
 /**
- * The effective tool surface for one worker run, as names. This is the single
+ * The effective capability surface for one run, as names. This is the single
  * narrowing used both to build the executable tool set and to compute the
  * signature the worker attests, so an attested identity can never describe a
  * different surface than the one the agent actually gets.
+ *
+ * The list names capabilities, whatever their placement: a recipe that admits
+ * `git` keeps `git` here, and because `git` sits behind the gateway the list
+ * gains `gateway` as well (the same rule dispatch admission applies to the
+ * list it approves, so the two signatures agree). `resolveAgentTools` then
+ * attaches only the direct-placed names, and the gateway enforces this list
+ * on every call it makes on the run's behalf.
  */
 export function effectiveToolNames(input: Omit<ResolveAgentToolsInput, "telemetry" | "invokeOptions">): ToolName[] {
 	const profileContext = {
 		...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
 		...(input.task !== undefined ? { task: input.task } : {}),
 	};
-	const toolIds = applyToolProfile(input.registry.listRegistered(), input.toolProfile, profileContext);
+	const gatewayNames = input.registry.listGateway().map((spec) => spec.name);
+	const registered = [...input.registry.listRegistered(), ...gatewayNames];
+	const toolIds = applyToolProfile(registered, input.toolProfile, profileContext);
 	const allowed = input.allowedTools ? new Set<string>(input.allowedTools) : null;
 	const includeInteractiveTools = input.includeInteractiveTools !== false;
 	const names: ToolName[] = [];
@@ -408,7 +421,8 @@ export function effectiveToolNames(input: Omit<ResolveAgentToolsInput, "telemetr
 		if (allowed && !allowed.has(name)) continue;
 		names.push(name);
 	}
-	return names;
+	if (input.registry.get(ToolNames.Gateway) === undefined) return names;
+	return withGatewayForCapabilities(names);
 }
 
 /**

package/src/tools/artifact.ts

@@ -1,10 +1,9 @@
-import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Type } from "typebox";
 import { artifactDefaultPath, CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
 import { ToolNames } from "../core/tool-names.js";
 import { StringEnum } from "../engine/ai.js";
-import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { type AtomicPublishResult, publishFileAtomically, withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 
@@ -14,6 +13,12 @@ import type { ToolResult, ToolSpec } from "./registry.js";
  * answer, so pi-agent-core skips the follow-up LLM call that would only
  * summarize it.
  *
+ * Placement: gateway. The terminal contract survives the indirection because
+ * the gateway propagates `terminate`, `details.kind`, and `details.paths`
+ * from this result unchanged, so the turn still ends and `/view` still lists
+ * the document. The write is an atomic publish (temp file, fsync, rename) so
+ * a failed write never leaves a half-written artifact behind.
+ *
  * A pathless call lands under `.clio-coder/artifacts/`, not in the repo working
  * tree. A turn nobody asked for a file from used to drop REPORT.md into the
  * project root, which the operator then had to notice and delete; the working
@@ -58,11 +63,9 @@ async function writeTerminalArtifact(
 	}
 	const title = typeof args.title === "string" ? args.title.trim() : "";
 	const body = title.length > 0 && !content.trimStart().startsWith("#") ? `# ${title}\n\n${content}` : content;
+	let published: AtomicPublishResult;
 	try {
-		await withFileMutationQueue(target, async () => {
-			mkdirSync(path.dirname(target), { recursive: true });
-			writeFileSync(target, body, "utf8");
-		});
+		published = await withFileMutationQueue(target, () => publishFileAtomically(target, body));
 	} catch (err) {
 		return { kind: "error", message: `artifact: ${err instanceof Error ? err.message : String(err)}` };
 	}
@@ -70,10 +73,15 @@ async function writeTerminalArtifact(
 	const bytes = Buffer.byteLength(body, "utf8");
 	return {
 		kind: "ok",
-		output: `wrote ${kind} artifact (${bytes}B) to ${rel}`,
+		output: `wrote ${kind} artifact (${bytes}B) to ${rel}${published.durabilityWarning ? `\n${published.durabilityWarning}` : ""}`,
 		// shownBytes is the artifact's real size; the ledger otherwise measures
 		// this confirmation sentence (a 4753B plan rendered as "60B", #76).
-		details: { kind, paths: [target], observation: { shownBytes: bytes } },
+		details: {
+			kind,
+			paths: [target],
+			observation: { shownBytes: bytes },
+			file: { before: published.before, after: published.after },
+		},
 		// Writing the artifact is the whole turn; terminate skips the follow-up
 		// LLM call that would only restate what was just written.
 		terminate: true,

package/src/tools/bash.ts

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { BASH_HARD_CAP_BYTES, combineBashOutput, runBashCommand } from "../core/bash-exec.js";
+import { BASH_HARD_CAP_BYTES, type BashCommandResult, combineBashOutput, runBashCommand } from "../core/bash-exec.js";
 import { resolveSafeCwd } from "../core/safe-exec.js";
 import { ToolNames } from "../core/tool-names.js";
 import { expandPath } from "./path-utils.js";
@@ -11,8 +11,9 @@ import {
 	type ToolResultContextDisposition,
 	type ToolResultDisposition,
 } from "./result-disposition.js";
+import { writeToolOffload } from "./result-shaping.js";
 import { DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
-import { byteLength } from "./truncate-utf8.js";
+import { byteLength, truncateUtf8 } from "./truncate-utf8.js";
 
 // The registry's bounded model projection and operator presentation share this
 // cap. Both are tail-biased for Bash because diagnostics usually land last.
@@ -120,6 +121,91 @@ function bashResultDetails(
 		retainedBytes: byteLength(rawOutput),
 		stdoutBytes: byteLength(result.stdout),
 		stderrBytes: byteLength(result.stderr),
+		observedStdoutBytes: result.observedStdoutBytes,
+		observedStderrBytes: result.observedStderrBytes,
+		retainedStdoutBytes: result.retainedStdoutBytes,
+		retainedStderrBytes: result.retainedStderrBytes,
+	};
+}
+
+/** Finalize cap retention before projection so every policy carries the actual outcome. */
+export function bashOutputCapResult(
+	result: BashCommandResult,
+	policy: BashOutputPolicy,
+	context?: { sessionId?: string; toolResultMaxBytes?: number },
+): ToolResult {
+	const raw = combineBashOutput(result);
+	const bytes = byteLength(raw);
+	const cap = Math.min(BASH_DISPLAY_MAX_BYTES, context?.toolResultMaxBytes ?? BASH_DISPLAY_MAX_BYTES);
+	const bodyBudget = Math.max(0, cap - 2048);
+	const showBody = policy === "full" || policy === "bounded";
+	const inline = showBody && bytes <= bodyBudget;
+	const preview = inline
+		? raw
+		: showBody
+			? truncateTail(raw, { maxBytes: Math.max(1, bodyBudget), maxLines: DEFAULT_MAX_LINES }).content
+			: "";
+	let offloadPath: string | null = null;
+	let savedBytes = 0;
+	let discardedBytes = 0;
+	let retention: string;
+	if (inline) {
+		retention = `Partial output shown inline (${bytes} decoded output bytes).`;
+	} else {
+		const saved = truncateUtf8(raw, BASH_HARD_CAP_BYTES, "");
+		offloadPath = writeToolOffload(saved, context, BASH_HARD_CAP_BYTES);
+		if (offloadPath !== null) {
+			savedBytes = byteLength(saved);
+			discardedBytes = bytes - savedBytes;
+			retention = `Partial output offloaded to ${offloadPath} (${savedBytes} decoded output bytes saved).`;
+			if (discardedBytes > 0)
+				retention += ` Retention truncated by the ${BASH_HARD_CAP_BYTES}-byte (16 MiB) offload ceiling; ${discardedBytes} decoded output bytes discarded from the offload.`;
+		} else {
+			discardedBytes = bytes - byteLength(preview);
+			retention = `Partial-output retention failed; no offload was written. ${byteLength(preview)} decoded output bytes shown inline; ${discardedBytes} decoded output bytes discarded.`;
+		}
+	}
+	const status = `bash: command output exceeded the ${BASH_HARD_CAP_BYTES}-byte (16 MiB) hard cap and was stopped. Observed stdout: ${result.observedStdoutBytes ?? "unavailable"} bytes, stderr: ${result.observedStderrBytes ?? "unavailable"} bytes; retained stream stdout: ${result.retainedStdoutBytes ?? "unavailable"} bytes, stderr: ${result.retainedStderrBytes ?? "unavailable"} bytes. ${retention} Use run_script to stream unbounded output to .clio-coder/runs/<runId>/ instead.`;
+	const message = preview.length > 0 ? `${preview}\n\n${status}` : status;
+	const disposition = normalizedBashDisposition(policy);
+	return {
+		kind: "error",
+		message,
+		modelContext: message,
+		details: {
+			...bashResultDetails(result, raw, "output-cap"),
+			retention: {
+				status: inline ? "inline" : offloadPath === null ? "failed" : discardedBytes > 0 ? "truncated" : "offloaded",
+				savedBytes,
+				discardedBytes,
+				...(offloadPath === null ? {} : { offloadPath }),
+			},
+			resultSize: {
+				bytes,
+				shownBytes: byteLength(message),
+				maxBytes: cap,
+				truncated: !inline,
+				policy,
+				...(offloadPath === null ? {} : { offloadPath }),
+			},
+			resultDisposition: {
+				version: 1,
+				applications: 1,
+				presentation: { ...disposition.presentation, content: message },
+				context: {
+					requestedMode: policy === "metadata-only" ? "metadata-only" : disposition.context.mode,
+					appliedMode: disposition.context.mode,
+					maxBytes: cap,
+				},
+				capturedBytes: bytes,
+				displayedBytes: byteLength(message),
+				contextBytes: byteLength(message),
+				presentationTruncated: !inline,
+				contextTruncated: !inline,
+				retrieval: retention,
+				...(offloadPath === null ? {} : { offloadPath }),
+			},
+		},
 	};
 }
 
@@ -157,7 +243,7 @@ function observeToolsNudge(command: string, sessionId: string | undefined): stri
 export const bashTool: ToolSpec = {
 	name: ToolNames.Bash,
 	description:
-		"Execute a bash command in a fresh child at the workspace root (or explicit cwd); shell state does not persist across calls. The default timeout is 300s; use panes for long-lived processes or an explicit timeout_ms, and use output_policy for bounded diagnostic tail (default), summary, metadata-only, or budget-limited full output. Network reachability follows the host environment and OS isolation; disabling web_fetch does not isolate bash networking.",
+		"Execute a bash command in a fresh child at the workspace root (or explicit cwd); shell state does not persist across calls. Combined stdout and stderr have a 16 MiB hard cap that stops the child; use run_script to stream unbounded output to .clio-coder/runs/<runId>/. The default timeout is 300s; use panes for long-lived processes or an explicit timeout_ms, and use output_policy for bounded diagnostic tail (default), summary, metadata-only, or budget-limited full output. Network reachability follows the host environment and OS isolation; disabling web_fetch does not isolate bash networking.",
 	parameters: Type.Object({
 		command: Type.String({ description: "Bash command to execute." }),
 		cwd: Type.Optional(
@@ -238,14 +324,7 @@ export const bashTool: ToolSpec = {
 					details: bashResultDetails(result, rawOutput, "timeout"),
 				};
 			}
-			if (outputCapped) {
-				const status = `bash: command output exceeded ${BASH_HARD_CAP_BYTES} bytes and was stopped`;
-				return {
-					kind: "error",
-					message: output.length > 0 ? `${output}\n\n${status}` : status,
-					details: bashResultDetails(result, rawOutput, "output-cap"),
-				};
-			}
+			if (outputCapped) return bashOutputCapResult(result, outputPolicy, options);
 			if (error) {
 				const code = typeof error.code === "number" ? error.code : (error as { code?: string }).code;
 				const status = `bash: command failed (exit ${code ?? "?"})`;

package/src/tools/bootstrap.ts

@@ -1,10 +1,12 @@
 import { BusChannels } from "../core/bus-events.js";
 import type { WorkerRosters } from "../core/defaults.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import type { getTerminationCoordinator } from "../core/termination.js";
 import type { AgentSpec } from "../domains/agents/spec.js";
 import type { WorkerContextSnapshot } from "../domains/context/worker/contract.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
+import { DEFAULT_KILL_GRACE_MS, DEFAULT_TEARDOWN_BOUND_MS } from "../domains/gateway/mcp/index.js";
 import type { PanesOperations } from "../domains/mux/operations.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import type { DecisionLedgerEntry } from "../domains/session/entries.js";
@@ -14,6 +16,7 @@ import { assertRegisteredBuiltinTools, type CoreToolBootstrapDeps, registerCoreT
 import { createDispatchRunEventRegistry, createDispatchTool } from "./dispatch.js";
 import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
 import type { DispatchSchemaComposition } from "./dispatch-schema.js";
+import { createMcpCapabilitySource, type McpCapabilitySource } from "./gateway/index.js";
 import { registerHarnessExtensionTools } from "./harness-extensions.js";
 import { lazyTool } from "./lazy-tool.js";
 import { monitorToolSurface } from "./monitor-surface.js";
@@ -23,10 +26,11 @@ import { steerToolSurface } from "./steer-surface.js";
 
 export { toolPromptHintsForNames };
 
-export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
+export interface ToolBootstrapDeps extends Omit<CoreToolBootstrapDeps, "mcpCapabilities"> {
 	captureWorkerContext?: () => WorkerContextSnapshot | null;
 	dispatch?: DispatchContract;
 	bus?: SafeEventBus;
+	termination?: Pick<ReturnType<typeof getTerminationCoordinator>, "onTerminate">;
 	getAgentCatalog?: () => string;
 	getAgentSpecs?: () => ReadonlyArray<AgentSpec>;
 	getAgentRoleFacts?: AgentRoleFactsResolver;
@@ -45,6 +49,19 @@ export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
 	 * is what keeps the `panes` tool out of the prompt on a machine with none.
 	 */
 	panes?: PanesOperations;
+	/**
+	 * Local MCP servers for the gateway. Absent means one is built for the
+	 * session cwd; `false` registers none (a registry that must never launch a
+	 * child process, such as a test's).
+	 */
+	mcpCapabilities?: McpCapabilitySource | false;
+}
+
+export interface ToolBootstrapHandle {
+	/** The MCP capability source the gateway launches servers through, when one was registered. */
+	mcpCapabilities: McpCapabilitySource | null;
+	/** Close every launched MCP client. Idempotent; also bound to session end and shutdown on the bus. */
+	close(): Promise<void>;
 }
 
 /**
@@ -52,8 +69,14 @@ export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
  * controls in their canonical order. Worker registries call registerCoreTools
  * directly so their boot graph never evaluates dispatch implementations.
  */
-export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps = {}): void {
-	const registration = registerCoreTools(registry, deps);
+export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps = {}): ToolBootstrapHandle {
+	const cwd = deps.session?.current()?.cwd ?? process.cwd();
+	const { mcpCapabilities: requestedMcp, ...coreDeps } = deps;
+	const mcpCapabilities = requestedMcp === false ? null : (requestedMcp ?? createMcpCapabilitySource({ cwd, registry }));
+	const registration = registerCoreTools(registry, {
+		...coreDeps,
+		...(mcpCapabilities ? { mcpCapabilities } : {}),
+	});
 	if (deps.dispatch) {
 		const dispatch = deps.dispatch;
 		// Display tail only. In a composed process the dispatch domain writes the
@@ -114,7 +137,22 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 		});
 	}
 	assertRegisteredBuiltinTools(registry, registration, Boolean(deps.dispatch), Boolean(deps.panes));
-	for (const diagnostic of registerHarnessExtensionTools(registry, deps.session?.current()?.cwd ?? process.cwd())) {
+	for (const diagnostic of registerHarnessExtensionTools(registry, cwd)) {
 		deps.bus?.emit(BusChannels.ExtensionsLoadIssue, { message: diagnostic.message });
 	}
+	// Every MCP client the gateway launched closes with the session: a
+	// detached server must not outlive the process that trusted it.
+	let closePromise: Promise<void> | undefined;
+	const close = (): Promise<void> => {
+		closePromise ??= Promise.resolve(mcpCapabilities?.close()).then(() => undefined);
+		return closePromise;
+	};
+	if (mcpCapabilities) {
+		deps.termination?.onTerminate(close, { timeoutMs: DEFAULT_KILL_GRACE_MS + DEFAULT_TEARDOWN_BOUND_MS + 1_000 });
+	}
+	if (mcpCapabilities && deps.bus) {
+		deps.bus.on(BusChannels.SessionEnd, () => void close());
+		deps.bus.on(BusChannels.ShutdownRequested, () => void close());
+	}
+	return { mcpCapabilities, close };
 }