@zvada/agent-server 0.2.1 → 0.3.0

package/src/core/agents/base.ts

@@ -14,7 +14,15 @@ import type {
  * `allow`/`deny`, codex `accept`/`decline`/`cancel`).
  */
 export type PermissionDecision =
-	| { decision: "allow" }
+	| {
+			decision: "allow";
+			/**
+			 * Allow-with-modified-input (`permission.resolved.outcome.updatedInput`):
+			 * the harness MUST execute this input, not the original — what was
+			 * approved is what runs. Absent = the original input was approved as-is.
+			 */
+			updatedInput?: Record<string, unknown>;
+	  }
 	| { decision: "deny"; reason?: string }
 	/** The turn is being cancelled — abort rather than merely skip the tool. */
 	| { decision: "cancel" };
@@ -69,6 +77,21 @@ export interface AgentExecuteOptions {
 /** Raw, harness-specific event. Adapters interpret it; the engine never does. */
 export type RawAgentEvent = unknown;
 
+/**
+ * What `cancel` reports back. `confirmed: true` = the cancelled state holds —
+ * either nothing was running (`hadTurn: false`, a clean no-op ack) or the
+ * harness acknowledged the interrupt and the turn will end promptly.
+ * `confirmed: false` = a turn existed and the cancel was dispatched
+ * best-effort but NOT acknowledged (the backend's interrupt timed out) — the
+ * underlying agent may still be running, and the turn's `turn.ended` event
+ * remains the source of truth.
+ */
+export interface CancelResult {
+	confirmed: boolean;
+	/** Whether an in-flight turn existed when the cancel arrived. */
+	hadTurn: boolean;
+}
+
 /**
  * A harness: a thin wrapper over one agent backend (Claude Code, Codex SDK,
  * Codex app-server). `execute` yields raw backend events; normalization is the
@@ -78,8 +101,8 @@ export interface Agent {
 	readonly harness: AgentHarness;
 	readonly capabilities: AgentCapabilities;
 	execute(input: AgentInput, options: AgentExecuteOptions): AsyncIterableIterator<RawAgentEvent>;
-	/** Cancel the in-flight turn for a logical session. */
-	cancel(sessionId: string): Promise<void>;
+	/** Cancel the in-flight turn for a logical session (see `CancelResult`). */
+	cancel(sessionId: string): Promise<CancelResult>;
 	/** Release all harness-owned state for one idle logical session. */
 	release?(sessionId: string): Promise<void>;
 	/** Tear down every live session (process shutdown). */
@@ -103,8 +126,15 @@ export abstract class BaseAgent implements Agent {
 		options: AgentExecuteOptions,
 	): AsyncIterableIterator<RawAgentEvent>;
 
-	async cancel(sessionId: string): Promise<void> {
-		for (const controller of this.inflight.get(sessionId) ?? []) controller.abort();
+	async cancel(sessionId: string): Promise<CancelResult> {
+		const controllers = this.inflight.get(sessionId);
+		const hadTurn = (controllers?.size ?? 0) > 0;
+		for (const controller of controllers ?? []) controller.abort();
+		// Idle sessions are a clean no-op ack, and the abort signal
+		// deterministically ends the engine's execute loop for tracked turns —
+		// both confirmed. Harnesses whose backend needs its own interrupt
+		// round-trip (claude) refine `confirmed` in their override.
+		return { confirmed: true, hadTurn };
 	}
 
 	async release(sessionId: string): Promise<void> {

package/src/core/agents/claude-code/adapter.ts

@@ -3,9 +3,11 @@ import {
 	type ReasoningPart,
 	type StopReason,
 	type StreamContext,
+	type SubagentMetadata,
 	type TextPart,
 	type TokenUsage,
 	type ToolPart,
+	type ToolResultContent,
 	appendToolInput,
 	completeToolPart,
 	createPendingToolPart,
@@ -41,6 +43,8 @@ interface StreamEvent {
 		type?: string;
 		text?: string;
 		thinking?: string;
+		/** Withheld-thinking placeholder: running size of a thought whose text never streams. */
+		estimated_tokens?: number;
 		partial_json?: string;
 		stop_reason?: string;
 	};
@@ -150,6 +154,61 @@ function stringifyToolResult(content: unknown): string {
 	return JSON.stringify(content);
 }
 
+/**
+ * The display-grade view of a tool_result's content blocks (spec §3.4): the
+ * flattened string stays the model-facing record, this preserves what
+ * flattening drops — images especially, which contribute "" to the string.
+ * Block shapes we can't express are skipped, never guessed.
+ */
+function toolResultContent(content: unknown): ToolResultContent[] | undefined {
+	if (!Array.isArray(content)) return undefined;
+	const out: ToolResultContent[] = [];
+	for (const raw of content) {
+		if (!raw || typeof raw !== "object") continue;
+		const block = raw as {
+			type?: unknown;
+			text?: unknown;
+			source?: { data?: unknown; media_type?: unknown } | null;
+		};
+		if (block.type === "text" && typeof block.text === "string") {
+			out.push({ type: "text", text: block.text });
+			continue;
+		}
+		if (block.type === "image") {
+			const { data, media_type } = block.source ?? {};
+			// Only the base64 source form is expressible — ToolResultContent has no url variant.
+			if (typeof data === "string" && typeof media_type === "string") {
+				out.push({ type: "image", data, mimeType: media_type });
+			}
+		}
+	}
+	return out.length ? out : undefined;
+}
+
+/**
+ * SubagentMetadata from a spawning tool's input, shared by the streamed and
+ * non-streaming paths. `subagent_type` in the input identifies a spawn on any
+ * tool name; `Task` is Claude's own spawn tool and counts even before its
+ * input parses into anything useful (presence of `subagent` is what promotes
+ * the part to `kind: "task"` — see protocol §3.5).
+ */
+function subagentFromInput(
+	toolName: string,
+	input: Record<string, unknown>,
+): SubagentMetadata | undefined {
+	const str = (key: string): string | undefined =>
+		typeof input[key] === "string" ? (input[key] as string) : undefined;
+	const type = str("subagent_type");
+	if (type === undefined && toolName !== "Task") return undefined;
+	const description = str("description");
+	const model = str("model");
+	return {
+		...(type !== undefined && { type }),
+		...(description !== undefined && { description }),
+		...(model !== undefined && { model }),
+	};
+}
+
 export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	private readonly ctx: StreamContext;
 	/** Anthropic content blocks of the in-flight message, by stream index. */
@@ -237,7 +296,10 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	}
 
 	private ctxFor(): StreamContext {
-		return { ...this.ctx, ...(this.currentParent ? { parentToolUseId: this.currentParent } : {}) };
+		// `parentToolCallId` is the protocol spelling; Claude's own wire field is
+		// `parent_tool_use_id`. Spelling this the provider's way silently dropped
+		// every subagent linkage (a conditional spread dodges excess-property checks).
+		return { ...this.ctx, ...(this.currentParent ? { parentToolCallId: this.currentParent } : {}) };
 	}
 
 	/**
@@ -264,24 +326,25 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		for (const block of content) {
 			if (block.type === "text" && block.text) {
 				events.push({ kind: "part-open", part: createTextPart(this.ctxFor(), block.text, false) });
-			} else if (
-				(block.type === "thinking" || block.type === "redacted_thinking") &&
-				block.thinking
-			) {
-				events.push({
-					kind: "part-open",
-					part: createReasoningPart(this.ctxFor(), block.thinking, false),
-				});
+			} else if (block.type === "thinking" || block.type === "redacted_thinking") {
+				const redacted = block.type === "redacted_thinking";
+				// A redacted block carries no plaintext (its `data` is an encrypted
+				// blob), so emit it on the flag alone — the redaction is the signal.
+				if (!block.thinking && !redacted) continue;
+				// A complete block opens and closes at once: one stamp for both ends.
+				const now = Date.now();
+				const part = createReasoningPart(this.ctxFor(), block.thinking ?? "", false);
+				part.time = { start: now, end: now };
+				if (redacted) part.providerMetadata = { redacted: true };
+				events.push({ kind: "part-open", part });
 			} else if (block.type === "tool_use" && block.id) {
 				const name = block.name ?? "tool";
 				const input = block.input ?? {};
-				const part = createToolPart(
-					this.ctxFor(),
-					block.id,
-					name,
-					input,
-					claudeToolMeta(name, input),
-				);
+				const subagent = subagentFromInput(name, input);
+				const part = createToolPart(this.ctxFor(), block.id, name, input, {
+					...claudeToolMeta(name, input),
+					...(subagent && { subagent }),
+				});
 				this.toolPartsById.set(block.id, part);
 				events.push({ kind: "part-open", part });
 			}
@@ -290,17 +353,17 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		return [...gauge, ...events];
 	}
 
-	private handleStream(event: StreamEvent, parentToolUseId?: string): AdapterEvent[] {
+	private handleStream(event: StreamEvent, parentToolCallId?: string): AdapterEvent[] {
 		// Sticky for the whole turn: any stream event means the trailing complete
 		// `assistant` snapshot is a duplicate of what we streamed.
 		this.hasStreamed = true;
 		switch (event.type) {
 			case "message_start":
 				this.blocks.clear();
-				this.currentParent = parentToolUseId;
+				this.currentParent = parentToolCallId;
 				// Each top-level model message becomes a wire message. Sub-agent
-				// messages don't open one — their parts nest via parentToolUseId.
-				return parentToolUseId ? [] : [{ kind: "message-start", role: "assistant" }];
+				// messages don't open one — their parts nest via parentToolCallId.
+				return parentToolCallId ? [] : [{ kind: "message-start", role: "assistant" }];
 			case "content_block_start":
 				return this.openBlock(event);
 			case "content_block_delta":
@@ -313,7 +376,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 				if (event.usage?.output_tokens) this.usage.output = event.usage.output_tokens;
 				return [];
 			case "message_stop":
-				return parentToolUseId || this.currentParent ? [] : [{ kind: "message-end" }];
+				return parentToolCallId || this.currentParent ? [] : [{ kind: "message-end" }];
 			default:
 				return [];
 		}
@@ -330,6 +393,11 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		}
 		if (cb.type === "thinking" || cb.type === "redacted_thinking") {
 			const part = createReasoningPart(this.ctxFor(), "", true);
+			// Thought duration starts here; content_block_stop closes it.
+			part.time = { start: Date.now() };
+			// The plaintext never arrives for a redacted block — keep the flag so a
+			// consumer can render "[redacted]" instead of an empty thought.
+			if (cb.type === "redacted_thinking") part.providerMetadata = { redacted: true };
 			this.blocks.set(index, { partId: part.id, kind: "reasoning", part });
 			return [{ kind: "part-open", part }];
 		}
@@ -351,8 +419,18 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 			(entry.part as TextPart).text += d.text;
 			return [{ kind: "text-delta", partId: entry.partId, text: d.text }];
 		}
-		if (d.type === "thinking_delta" && entry.kind === "reasoning" && d.thinking) {
-			(entry.part as ReasoningPart).text += d.thinking;
+		if (d.type === "thinking_delta" && entry.kind === "reasoning") {
+			const reasoning = entry.part as ReasoningPart;
+			// Withheld thinking streams placeholder deltas: a token estimate, no
+			// text. Keep the estimate so a text-less thought still has a size.
+			if (typeof d.estimated_tokens === "number") {
+				reasoning.providerMetadata = {
+					...reasoning.providerMetadata,
+					estimatedThinkingTokens: d.estimated_tokens,
+				};
+			}
+			if (!d.thinking) return [];
+			reasoning.text += d.thinking;
 			return [{ kind: "reasoning-delta", partId: entry.partId, text: d.thinking }];
 		}
 		if (d.type === "input_json_delta" && entry.kind === "tool" && d.partial_json) {
@@ -375,15 +453,25 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 		const entry = this.blocks.get(event.index ?? 0);
 		if (!entry) return [];
 		if (entry.kind === "text" || entry.kind === "reasoning") {
-			(entry.part as TextPart | ReasoningPart).state = "done";
-			return [{ kind: "part-update", part: entry.part }];
+			const part = entry.part as TextPart | ReasoningPart;
+			part.state = "done";
+			if (entry.kind === "reasoning") {
+				const reasoning = part as ReasoningPart;
+				reasoning.time = { start: reasoning.time?.start ?? Date.now(), end: Date.now() };
+			}
+			return [{ kind: "part-update", part }];
 		}
 		const tool = entry.part as ToolPart;
 		const partial = tool.state.status === "pending" ? tool.state.partialInput : "";
 		const input = safeParseJson(partial);
 		startToolPart(tool, input);
+		// The streamed open carried no input, so subagent metadata can only be
+		// read now that the partial JSON has parsed.
 		const locations = toolLocationsFromInput(input);
-		if (locations) setToolMeta(tool, { locations });
+		const subagent = subagentFromInput(tool.toolName, input);
+		if (locations || subagent) {
+			setToolMeta(tool, { ...(locations && { locations }), ...(subagent && { subagent }) });
+		}
 		return [{ kind: "part-update", part: tool }];
 	}
 
@@ -394,9 +482,11 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 			if (block.type !== "tool_result" || !block.tool_use_id) continue;
 			const tool = this.toolPartsById.get(block.tool_use_id);
 			if (!tool) continue;
+			const content = toolResultContent(block.content);
 			completeToolPart(tool, {
 				output: stringifyToolResult(block.content),
 				isError: block.is_error === true,
+				...(content && { content }),
 			});
 			events.push({ kind: "part-update", part: tool });
 		}

package/src/core/agents/claude-code/claude-agent.ts

@@ -1,10 +1,12 @@
 import type { SDKMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentCapabilities, AgentInput, McpServerConfig } from "../../../protocol/index.ts";
-import type { AgentExecuteOptions, RawAgentEvent } from "../base.ts";
+import { type DiagnosticHandler, emitDiagnostic } from "../../diagnostics.ts";
+import type { AgentExecuteOptions, CancelResult, RawAgentEvent } from "../base.ts";
 import { BaseAgent } from "../base.ts";
 import type {
 	ClaudeHooksFactory,
+	ClaudeSessionEndReason,
 	ClaudeSessionExtras,
 	ClaudeToolPolicy,
 } from "./generator-session.ts";
@@ -30,13 +32,13 @@ function toClaudeContent(input: AgentInput): ClaudeContent {
 		if (part.type === "text") return { type: "text", text: part.text };
 		const source = part.url
 			? { type: "url", url: part.url }
-			: { type: "base64", media_type: part.mediaType, data: part.data ?? "" };
+			: { type: "base64", media_type: part.mimeType, data: part.data ?? "" };
 		// `file` inputs (PDFs etc.) are document blocks, not images.
 		return { type: part.type === "file" ? "document" : "image", source };
 	});
 	// Kept cast: the SDK's block sources require literal media_type unions
 	// ("image/jpeg" | ... and "application/pdf") while our PartInput carries an
-	// open string mediaType, so these blocks cannot satisfy the union as typed.
+	// open string mimeType, so these blocks cannot satisfy the union as typed.
 	return blocks as unknown as ClaudeContent;
 }
 
@@ -96,6 +98,18 @@ export interface ClaudeCodeAgentOptions {
 	toolPolicy?: ClaudeToolPolicy;
 	/** SDK lifecycle hooks factory (decision-capable). Operator embed-tier only. */
 	hooks?: ClaudeHooksFactory;
+	/**
+	 * Called exactly once when a live session's subprocess ends, with why:
+	 * `idle` (idle-timeout eviction), `replaced` (config change forced a
+	 * restart), `released` (explicit release/close), `shutdown`
+	 * (terminateAll). The seam for host-managed per-session resources — BYOK
+	 * proxy keys, recorders — instead of re-deriving termination from side
+	 * effects. NOTE: `replaced` sessions usually respawn immediately with
+	 * context preserved; drop only resources bound to the dead subprocess.
+	 */
+	onSessionEnd?: (sessionId: string, reason: ClaudeSessionEndReason) => void;
+	/** Operational diagnostics (interrupt timeouts, resume fallbacks). */
+	onDiagnostic?: DiagnosticHandler;
 	/**
 	 * Raw SDK option overrides merged over the engine's options at session
 	 * spawn (embedder escape hatch for SDK surface the engine does not model:
@@ -113,10 +127,11 @@ export interface ClaudeCodeAgentOptions {
 export class ClaudeCodeAgent extends BaseAgent {
 	readonly harness = "claude-code" as const;
 	readonly capabilities = CAPABILITIES;
-	private readonly manager = new ClaudeSessionManager();
+	private readonly manager: ClaudeSessionManager;
 
 	constructor(private readonly agentOptions: ClaudeCodeAgentOptions = {}) {
 		super();
+		this.manager = new ClaudeSessionManager(agentOptions.onSessionEnd);
 	}
 
 	private sessionExtras(): ClaudeSessionExtras {
@@ -193,6 +208,12 @@ export class ClaudeCodeAgent extends BaseAgent {
 				}
 
 				if (!resumeFailed) break;
+				emitDiagnostic(this.agentOptions.onDiagnostic, {
+					type: "resumeFallback",
+					sessionId: options.sessionId,
+					message: `resume of ${options.resumeSessionId} failed; re-running on a fresh session`,
+					detail: { resumeSessionId: options.resumeSessionId },
+				});
 				await this.manager.terminate(options.sessionId);
 			}
 
@@ -218,9 +239,25 @@ export class ClaudeCodeAgent extends BaseAgent {
 		return this.manager.setMcpServers(sessionId, servers);
 	}
 
-	override async cancel(sessionId: string): Promise<void> {
-		await this.manager.get(sessionId)?.interruptTurn();
-		await super.cancel(sessionId);
+	override async cancel(sessionId: string): Promise<CancelResult> {
+		// Abort FIRST: the controller ends the engine's execute loop, so this
+		// turn classifies as cancelled even when the generator drains to a
+		// natural end before the SDK interrupt lands (the abort-order race that
+		// could surface a clean user cancel as `error`/`end_turn`). The SDK
+		// interrupt then stops the underlying turn; its round-trip is what
+		// confirms the cancel.
+		const session = this.manager.get(sessionId);
+		const base = await super.cancel(sessionId);
+		if (!session || !base.hadTurn) return base;
+		const interrupted = await session.interruptTurn();
+		if (!interrupted) {
+			emitDiagnostic(this.agentOptions.onDiagnostic, {
+				type: "interruptTimeout",
+				sessionId,
+				message: "cancel dispatched but the SDK interrupt was not acknowledged in time",
+			});
+		}
+		return { confirmed: interrupted, hadTurn: true };
 	}
 
 	override async release(sessionId: string): Promise<void> {

package/src/core/agents/claude-code/generator-session.ts

@@ -4,6 +4,7 @@ import type {
 	CanUseTool,
 	McpSetServersResult,
 	PermissionResult,
+	PermissionUpdate,
 } from "@anthropic-ai/claude-agent-sdk";
 import { AsyncQueue } from "../../../protocol/index.ts";
 import type { McpServerConfig } from "../../../protocol/index.ts";
@@ -26,7 +27,19 @@ import {
 export type ClaudeToolPolicy = (
 	toolName: string,
 	input: Record<string, unknown>,
-	ctx: { sessionId: string; toolUseId: string; agentId?: string },
+	ctx: {
+		sessionId: string;
+		toolUseId: string;
+		agentId?: string;
+		/** Aborts when the turn is cancelled — a policy that waits on a remote approval must race this. */
+		signal: AbortSignal;
+		/** SDK permission-update suggestions; return them as `updatedPermissions` to honor an "always allow". */
+		suggestions?: PermissionUpdate[];
+		/** File path that triggered the request (e.g. access outside allowed directories). */
+		blockedPath?: string;
+		/** The SDK's explanation for why this permission request fired, when it gives one. */
+		decisionReason?: string;
+	},
 ) => PermissionResult | undefined | Promise<PermissionResult | undefined>;
 
 /** SDK lifecycle hooks factory (decision-capable); runs once at session spawn. */
@@ -36,6 +49,9 @@ export type ClaudeHooksFactory = (ctx: {
 }) => CCOptions["hooks"];
 
 /** Embed-tier extras threaded from ClaudeCodeAgentOptions into each session. */
+/** Why a live claude session's subprocess ended (see `onSessionEnd`). */
+export type ClaudeSessionEndReason = "idle" | "replaced" | "released" | "shutdown";
+
 export interface ClaudeSessionExtras {
 	/** Factory for in-process MCP servers; invoked ONCE at session spawn. */
 	sdkMcpServers?: (ctx: {
@@ -102,7 +118,7 @@ export class ClaudeGeneratorSession {
 	constructor(
 		readonly id: string,
 		config: ClaudeSessionConfig,
-		private readonly onTerminated?: () => void,
+		private readonly onTerminated?: (reason: ClaudeSessionEndReason) => void,
 		private readonly extras?: ClaudeSessionExtras,
 	) {
 		this.config = { ...config };
@@ -212,22 +228,32 @@ export class ClaudeGeneratorSession {
 		};
 	}
 
-	/** Stop the in-flight turn without killing the session. */
-	async interruptTurn(): Promise<void> {
-		if ((this.state !== "busy" && this.state !== "starting") || !this.query) return;
+	/**
+	 * Stop the in-flight turn without killing the session. Returns whether the
+	 * interrupt was CONFIRMED: true when there was nothing to interrupt or the
+	 * SDK acknowledged it; false when the round-trip timed out or failed — the
+	 * subprocess may still be running its turn and the caller must report that
+	 * honestly instead of assuming a clean cancel.
+	 */
+	async interruptTurn(timeoutMs = 2000): Promise<boolean> {
+		if ((this.state !== "busy" && this.state !== "starting") || !this.query) return true;
+		let timer: ReturnType<typeof setTimeout> | undefined;
 		try {
 			await Promise.race([
 				this.query.interrupt(),
-				new Promise<never>((_, reject) =>
-					setTimeout(() => reject(new Error("interrupt timeout")), 2000),
-				),
+				new Promise<never>((_, reject) => {
+					timer = setTimeout(() => reject(new Error("interrupt timeout")), timeoutMs);
+				}),
 			]);
+			return true;
 		} catch {
-			// best-effort
+			return false; // best-effort dispatched, unconfirmed
+		} finally {
+			clearTimeout(timer); // the losing racer must not keep the loop alive
 		}
 	}
 
-	async terminate(): Promise<void> {
+	async terminate(reason: ClaudeSessionEndReason = "released"): Promise<void> {
 		if (this.state === "terminated") return;
 		this.clearIdleTimer();
 		this.state = "terminated";
@@ -242,7 +268,12 @@ export class ClaudeGeneratorSession {
 			// The SDK documents close() as the forceful subprocess/MCP cleanup path.
 			query?.close();
 		} finally {
-			this.onTerminated?.();
+			try {
+				this.onTerminated?.(reason);
+			} catch {
+				// Observer failures (incl. the host's onSessionEnd) must never make
+				// terminate() reject — the idle timer calls it unawaited.
+			}
 		}
 	}
 
@@ -291,7 +322,7 @@ export class ClaudeGeneratorSession {
 	private resetIdleTimer(): void {
 		this.clearIdleTimer();
 		if (this.idleTimeoutMs > 0) {
-			this.idleTimer = setTimeout(() => void this.terminate(), this.idleTimeoutMs);
+			this.idleTimer = setTimeout(() => void this.terminate("idle"), this.idleTimeoutMs);
 			this.idleTimer.unref?.();
 		}
 	}
@@ -315,11 +346,16 @@ export function createCanUseTool(deps: {
 	policy?: ClaudeToolPolicy;
 	getBroker: () => PermissionRequestHandler | undefined;
 }): CanUseTool {
-	return async (toolName, input, { signal, toolUseID, agentID }) => {
+	return async (toolName, input, options) => {
+		const { signal, toolUseID, agentID, suggestions, blockedPath, decisionReason } = options;
 		const verdict = await deps.policy?.(toolName, input, {
 			sessionId: deps.sessionId,
 			toolUseId: toolUseID,
 			agentId: agentID,
+			signal,
+			suggestions,
+			blockedPath,
+			decisionReason,
 		});
 		if (verdict) return verdict;
 		const handler = deps.getBroker();
@@ -334,7 +370,10 @@ export function createCanUseTool(deps: {
 			{ signal },
 		);
 		return decision.decision === "allow"
-			? { behavior: "allow", updatedInput: input }
+			? // What was approved is what runs: an edited input from the broker
+				// replaces the original (C1 — silent divergence between the approved
+				// and executed input is the worst failure mode in an approval path).
+				{ behavior: "allow", updatedInput: decision.updatedInput ?? input }
 			: {
 					behavior: "deny",
 					message: (decision.decision === "deny" && decision.reason) || "Denied by user",

package/src/core/agents/claude-code/options.ts

@@ -68,13 +68,13 @@ export interface ClaudeSessionConfig {
  */
 function toSdkPermissionMode(mode: PermissionMode | undefined): CCOptions["permissionMode"] {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "bypassPermissions";
 		case "plan":
 			return "plan";
-		case "acceptEdits":
+		case "accept_edits":
 			return "acceptEdits";
-		case "dontAsk":
+		case "dont_ask":
 			// Native SDK mode: never prompt, deny unapproved. Unlike
 			// bypassPermissions it needs no dangerous flag (and the CLI keeps
 			// extended thinking enabled, which bypass turns off).
@@ -157,5 +157,15 @@ export function buildClaudeOptions(
 	// ClaudeSdkOptionOverrides type excludes them anyway).
 	if (overrides) Object.assign(options, overrides);
 
+	// Fable-class models withhold thinking plaintext by default: blocks stream
+	// structure + token estimates only, so every reasoning part arrives with
+	// empty text. The hidden `--thinking-display summarized` flag opts into
+	// summary text (ignored by CLIs that don't honor it). Applied after operator
+	// overrides so an unrelated operator extraArgs can't drop it, while an
+	// explicit operator `thinking-display` key still wins.
+	if (config.thinkingLevel !== "off") {
+		options.extraArgs = { "thinking-display": "summarized", ...options.extraArgs };
+	}
+
 	return options;
 }

package/src/core/agents/claude-code/session-manager.ts

@@ -2,7 +2,7 @@ import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
 import type { McpServerConfig } from "../../../protocol/index.ts";
 import { configFingerprint } from "../config-fingerprint.ts";
 import { ClaudeGeneratorSession } from "./generator-session.ts";
-import type { ClaudeSessionExtras } from "./generator-session.ts";
+import type { ClaudeSessionEndReason, ClaudeSessionExtras } from "./generator-session.ts";
 import type { ClaudeSessionConfig } from "./options.ts";
 
 /** Directory-set identity: order and duplicates don't change the sandbox surface. */
@@ -66,6 +66,10 @@ export function claudeRestartConfig(
 export class ClaudeSessionManager {
 	private readonly sessions = new Map<string, ClaudeGeneratorSession>();
 
+	constructor(
+		private readonly onSessionEnd?: (sessionId: string, reason: ClaudeSessionEndReason) => void,
+	) {}
+
 	async getOrCreate(
 		sessionId: string,
 		config: ClaudeSessionConfig,
@@ -80,7 +84,7 @@ export class ClaudeSessionManager {
 					config,
 					existing.currentSessionId,
 				);
-				await existing.terminate();
+				await existing.terminate("replaced");
 				this.sessions.delete(sessionId);
 			} else {
 				await this.hotSwapIfNeeded(existing, config);
@@ -91,8 +95,9 @@ export class ClaudeSessionManager {
 		const session = new ClaudeGeneratorSession(
 			sessionId,
 			startConfig,
-			() => {
+			(reason) => {
 				if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
+				this.onSessionEnd?.(sessionId, reason);
 			},
 			extras,
 		);
@@ -119,7 +124,7 @@ export class ClaudeSessionManager {
 	}
 
 	async terminateAll(): Promise<void> {
-		await Promise.all([...this.sessions.values()].map((s) => s.terminate()));
+		await Promise.all([...this.sessions.values()].map((s) => s.terminate("shutdown")));
 		this.sessions.clear();
 	}