@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/claude-code-cli/models.ts

@@ -48,6 +48,15 @@ export const CLAUDE_CODE_MODELS = [
 		contextWindow: 1_000_000,
 		maxTokens: 128_000,
 	},
+	{
+		id: "claude-sonnet-5",
+		name: "Claude Sonnet 5 (via Claude Code)",
+		reasoning: true,
+		input: ["text", "image"] as ("text" | "image")[],
+		cost: ZERO_COST,
+		contextWindow: 1_000_000,
+		maxTokens: 128_000,
+	},
 	{
 		id: "claude-sonnet-4-6",
 		name: "Claude Sonnet 4.6 (via Claude Code)",

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -50,6 +50,7 @@ import { markToolStart, markToolEnd } from "../gsd/auto.js";
 import {
 	markInteractiveElicitationStart,
 	markInteractiveElicitationEnd,
+	isInteractiveElicitationInFlight,
 } from "../gsd/auto-tool-tracking.js";
 import {
 	discoverBrowserMcpServerName,
@@ -74,6 +75,7 @@ import {
 	endWorkflowMcpSdkSession,
 } from "../gsd/workflow-mcp-readiness-cache.js";
 import { getGuidedUnitContext } from "../gsd/guided-unit-context.js";
+import { getActiveAutoUnitType, isAutoActive } from "../gsd/auto-runtime-state.js";
 import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
 import type {
@@ -100,6 +102,7 @@ export type {
 interface PromptToolContextOptions {
 	workflowMcpServerName?: string | null;
 	browserMcpServerName?: string | null;
+	questionToolAvailable?: boolean;
 }
 
 /** `SimpleStreamOptions` extended with an optional extension UI context for elicitation dialogs. */
@@ -225,6 +228,36 @@ interface SDKInputUserMessage {
 const OTHER_OPTION_LABEL = "None of the above";
 /** Regex pattern that identifies field names and descriptions that should be treated as sensitive/secure inputs. */
 const SENSITIVE_FIELD_PATTERN = /(password|passphrase|secret|token|api[_\s-]*key|private[_\s-]*key|credential)/i;
+/** Mirrors @opengsd/mcp-server's ask_user_questions host elicitation timeout. */
+const WORKFLOW_ELICIT_TIMEOUT_MS = 10 * 60 * 1000;
+/** Close the local form just before the server drops the MCP elicitation request. */
+const WORKFLOW_ELICIT_TIMEOUT_SKEW_MS = 1_000;
+export const CLAUDE_CODE_INTERVIEW_FORM_TIMEOUT_MS = Math.max(
+	1,
+	WORKFLOW_ELICIT_TIMEOUT_MS - WORKFLOW_ELICIT_TIMEOUT_SKEW_MS,
+);
+const ELICITATION_EXPIRED_NOTICE =
+	"Question expired before you answered - the form was closed and no answers were sent.";
+const activeAskUserQuestionElicitationTimeoutAborters = new Set<() => void>();
+
+function isAskUserQuestionsToolName(toolName: string | undefined): boolean {
+	const name = String(toolName ?? "");
+	return name === "ask_user_questions" || name.endsWith("__ask_user_questions");
+}
+
+function isAskUserQuestionsTimedOutResult(
+	toolCall: Pick<ToolCall, "name">,
+	result: ExternalToolResultPayload,
+): boolean {
+	return isAskUserQuestionsToolName(toolCall.name) && result.details?.timed_out === true;
+}
+
+function abortActiveAskUserQuestionElicitationsForTimeout(): void {
+	if (!isInteractiveElicitationInFlight()) return;
+	for (const abort of [...activeAskUserQuestionElicitationTimeoutAborters]) {
+		abort();
+	}
+}
 
 // ---------------------------------------------------------------------------
 // Stream factory
@@ -365,31 +398,46 @@ function extractMessageText(msg: { role: string; content: unknown }): string {
 	return "";
 }
 
+// Patterns are anchored to the `UNIT: <Phase>` dispatch header ONLY. The old
+// patterns also matched bare slugs (`run-uat`, `plan-slice`, `gsd_plan_slice`,
+// …) anywhere in the text, so any incidental occurrence — a branch name like
+// `milestone/M039`, an untracked file `m039-s05-…spec.ts`, a forensic report,
+// or the user literally typing "slice"/"UAT" while describing a problem — would
+// misclassify the turn as a dispatched unit. Only the dispatch header is an
+// authoritative phase signal, so match nothing else.
 const GSD_PHASE_PATTERNS: Array<[string, RegExp]> = [
-	["run-uat", /\b(?:UNIT:\s*Run UAT|run-uat)\b/i],
-	["complete-milestone", /\b(?:UNIT:\s*Complete Milestone|complete-milestone)\b/i],
-	["validate-milestone", /\b(?:UNIT:\s*Validate Milestone|validate-milestone)\b/i],
-	["reassess-roadmap", /\b(?:UNIT:\s*Reassess Roadmap|reassess-roadmap)\b/i],
-	["complete-slice", /\b(?:UNIT:\s*Complete Slice|complete-slice)\b/i],
-	["replan-slice", /\b(?:UNIT:\s*Replan Slice|replan-slice)\b/i],
-	["refine-slice", /\b(?:UNIT:\s*Refine Slice|refine-slice)\b/i],
-	["plan-slice", /\b(?:UNIT:\s*Plan Slice|plan-slice|gsd_plan_slice)\b/i],
-	["plan-milestone", /\b(?:UNIT:\s*Plan Milestone|plan-milestone|gsd_plan_milestone)\b/i],
-	["execute-task", /\b(?:UNIT:\s*Execute Task|execute-task|execute-task-simple|reactive-execute)\b/i],
-	["gate-evaluate", /\b(?:UNIT:\s*Gate Evaluate|gate-evaluate|gsd_save_gate_result)\b/i],
-	["research-milestone", /\b(?:UNIT:\s*Research Milestone|research-milestone)\b/i],
-	["research-slice", /\b(?:UNIT:\s*Research Slice|research-slice)\b/i],
-	["research-decision", /\b(?:research decision|research-decision)\b/i],
-	["discuss-milestone", /\b(?:Discuss milestone|discuss-milestone)\b/i],
-	["discuss-slice", /\b(?:Discuss slice|discuss-slice)\b/i],
-	["discuss-project", /\b(?:discuss-project|Discuss project)\b/i],
-	["discuss-requirements", /\b(?:discuss-requirements|Discuss requirements)\b/i],
+	["run-uat", /\bUNIT:\s*Run UAT\b/i],
+	["complete-milestone", /\bUNIT:\s*Complete Milestone\b/i],
+	["validate-milestone", /\bUNIT:\s*Validate Milestone\b/i],
+	["reassess-roadmap", /\bUNIT:\s*Reassess Roadmap\b/i],
+	["complete-slice", /\bUNIT:\s*Complete Slice\b/i],
+	["replan-slice", /\bUNIT:\s*Replan Slice\b/i],
+	["refine-slice", /\bUNIT:\s*Refine Slice\b/i],
+	["plan-slice", /\bUNIT:\s*Plan Slice\b/i],
+	["plan-milestone", /\bUNIT:\s*Plan Milestone\b/i],
+	["execute-task", /\bUNIT:\s*Execute Task\b/i],
+	["gate-evaluate", /\bUNIT:\s*Gate Evaluate\b/i],
+	["research-milestone", /\bUNIT:\s*Research Milestone\b/i],
+	["research-slice", /\bUNIT:\s*Research Slice\b/i],
+	["research-decision", /\bUNIT:\s*Research Decision\b/i],
+	["discuss-milestone", /\bUNIT:\s*Discuss Milestone\b/i],
+	["discuss-slice", /\bUNIT:\s*Discuss Slice\b/i],
+	["discuss-project", /\bUNIT:\s*Discuss Project\b/i],
+	["discuss-requirements", /\bUNIT:\s*Discuss Requirements\b/i],
 ];
 
+/** The set of GSD phases this adapter recognises, derived from the patterns above. */
+const KNOWN_GSD_PHASES = new Set(GSD_PHASE_PATTERNS.map(([phase]) => phase));
+
 export function inferGsdPhaseFromContext(context: Context): string | undefined {
+	// Scan only the system prompt and the most recent user directive. Scanning
+	// the entire scrollback let a phase header that merely appeared in history
+	// (e.g. a SUMMARY the agent read, or a pasted prior dispatch) re-classify
+	// every subsequent turn.
+	const lastUser = [...context.messages].reverse().find((m) => m.role === "user");
 	const text = [
 		context.systemPrompt ?? "",
-		...context.messages.map((message) => extractMessageText(message)),
+		lastUser ? extractMessageText(lastUser) : "",
 	].join("\n");
 	for (const [phase, pattern] of GSD_PHASE_PATTERNS) {
 		if (pattern.test(text)) return phase;
@@ -414,6 +462,27 @@ export function resolveGsdPhaseForSdk(context: Context, projectRoot: string): st
 			return guided.unitType;
 		}
 	}
+	// Auto-mode records the dispatched unit type before each turn — that is the
+	// authoritative phase, so prefer it over any inference. (Guided interactive
+	// dispatch is handled above via getGuidedUnitContext.) Ignore `hook/*`
+	// pseudo-units and anything not a recognised GSD phase.
+	const autoUnit = getActiveAutoUnitType();
+	if (autoUnit && KNOWN_GSD_PHASES.has(autoUnit)) {
+		return autoUnit;
+	}
+
+	// No authoritative guided/auto signal → ad-hoc turn. Do NOT regex-infer a
+	// phase from prose: that would fire the workflow MCP preflight and, for
+	// run-uat, strip Bash/Write/Edit/gsd_exec for the rest of the session the
+	// moment the conversation (or the GSD system prompt itself) happened to
+	// mention a phase token. An ad-hoc turn keeps the full tool surface.
+	//
+	// The header-anchored inference remains only as a last resort while auto is
+	// running but the current unit wasn't recorded for some reason; even then it
+	// matches the `UNIT:` dispatch header only, never bare slugs in scrollback.
+	if (!isAutoActive()) {
+		return undefined;
+	}
 	return inferGsdPhaseFromContext(context);
 }
 
@@ -443,8 +512,10 @@ export function buildPromptFromContext(context: Context, toolContext: PromptTool
 		? "- GSD workflow tools (gsd_exec, gsd_slice_complete, gsd_task_complete, gsd_plan_slice, gsd_save_gate_result, etc.) " +
 			`are MCP tools — call them as mcp__${toolContext.workflowMcpServerName}__<tool_name> ` +
 			`(e.g. mcp__${toolContext.workflowMcpServerName}__gsd_exec, mcp__${toolContext.workflowMcpServerName}__gsd_save_gate_result)\n` +
-			`- Structured user input: call mcp__${toolContext.workflowMcpServerName}__ask_user_questions. ` +
-			"Do not call bare ask_user_questions. Do not call native AskUserQuestion.\n"
+			(toolContext.questionToolAvailable !== false
+				? `- Structured user input: call mcp__${toolContext.workflowMcpServerName}__ask_user_questions. ` +
+					"Do not call bare ask_user_questions. Do not call native AskUserQuestion.\n"
+				: "")
 		: "- GSD workflow MCP tools are unavailable in this Claude Code run.\n";
 	const toolSearchLine = toolContext.workflowMcpServerName
 		? "- ToolSearch is available only for Claude Code deferred workflow MCP hydration. " +
@@ -1526,12 +1597,32 @@ export function createClaudeCodeElicitationHandler(
 			// it does not tear down the very elicitation that IS the human boundary
 			// (#cc-elicitation-self-cancel). It clears in the finally on every exit.
 			const elicId = "cc-elicit-" + ((request as { id?: string | number }).id ?? `${Date.now()}-${nextElicitationSeq()}`);
+			const formAbortController = new AbortController();
+			let expiryNoticeShown = false;
+			const abortExpiredForm = (): void => {
+				if (formAbortController.signal.aborted) return;
+				formAbortController.abort();
+				if (!expiryNoticeShown) {
+					expiryNoticeShown = true;
+					ui.notify(ELICITATION_EXPIRED_NOTICE, "warning");
+				}
+			};
+			const forwardSdkAbort = (): void => {
+				if (!formAbortController.signal.aborted) formAbortController.abort();
+			};
+			if (signal.aborted) {
+				forwardSdkAbort();
+			} else {
+				signal.addEventListener("abort", forwardSdkAbort, { once: true });
+			}
+			const expiryTimer = setTimeout(abortExpiredForm, CLAUDE_CODE_INTERVIEW_FORM_TIMEOUT_MS);
 			markInteractiveElicitationStart();
 			markToolStart(elicId, "ask_user_questions");
+			activeAskUserQuestionElicitationTimeoutAborters.add(abortExpiredForm);
 			try {
 				const interviewResult = await showInterviewRound(
 					questions,
-					{ signal, overlay: true },
+					{ signal: formAbortController.signal, overlay: true },
 					{ ui } as any,
 				).catch(() => undefined);
 				if (interviewResult === undefined) {
@@ -1540,7 +1631,7 @@ export function createClaudeCodeElicitationHandler(
 					// `finally` runs the moment the promise is created and the fallback
 					// wait runs with zero in-flight tools — reintroducing the
 					// self-cancel on this path (Bugbot #1c00624d).
-					return await promptElicitationWithDialogs(request, questions, ui, signal);
+					return await promptElicitationWithDialogs(request, questions, ui, formAbortController.signal);
 				}
 				if (Object.keys(interviewResult.answers).length === 0) {
 					// A system/host teardown (compaction, session_switch, true
@@ -1556,6 +1647,9 @@ export function createClaudeCodeElicitationHandler(
 					content: roundResultToElicitationContent(questions, interviewResult),
 				};
 			} finally {
+				clearTimeout(expiryTimer);
+				signal.removeEventListener("abort", forwardSdkAbort);
+				activeAskUserQuestionElicitationTimeoutAborters.delete(abortExpiredForm);
 				markToolEnd(elicId);
 				markInteractiveElicitationEnd();
 			}
@@ -1716,6 +1810,16 @@ function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string |
 	return undefined;
 }
 
+function workflowQuestionToolAvailableFromAllowedTools(
+	allowedTools: unknown,
+	workflowMcpServerName: string | undefined,
+	gsdPhase: string | undefined,
+): boolean | undefined {
+	if (!workflowMcpServerName || !gsdPhase) return undefined;
+	return Array.isArray(allowedTools)
+		&& allowedTools.includes(`mcp__${workflowMcpServerName}__ask_user_questions`);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -1724,6 +1828,15 @@ function isStringRecord(value: unknown): value is Record<string, string> {
 	return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
 
+export function resolveWorkflowMcpPreflightServerConfig(
+	mcpServers: unknown,
+	workflowServerName: string | undefined,
+): Record<string, unknown> | undefined {
+	if (!workflowServerName || !isRecord(mcpServers)) return undefined;
+	const workflowServerConfig = mcpServers[workflowServerName];
+	return isRecord(workflowServerConfig) ? workflowServerConfig : undefined;
+}
+
 function cloneSdkMcpServerConfig(config: unknown): Record<string, unknown> | undefined {
 	if (!isRecord(config)) return undefined;
 	const cloned: Record<string, unknown> = {};
@@ -2103,6 +2216,19 @@ export function buildSdkOptions(
 // streamSimple implementation
 // ---------------------------------------------------------------------------
 
+let capturedClaudeCodeUIContext: ExtensionUIContext | undefined;
+
+/**
+ * Capture the active extension UI context from `before_provider_request`. Core
+ * invokes `streamSimple` with a plain `SimpleStreamOptions` (no
+ * `extensionUIContext`), so without this the elicitation handler is never wired
+ * and `ask_user_questions` immediately returns cancelled. See index.ts, which
+ * registers the hook that calls this.
+ */
+export function setClaudeCodeUIContext(ui: ExtensionUIContext | undefined): void {
+	capturedClaudeCodeUIContext = ui;
+}
+
 /**
  * GSD streamSimple function that delegates to the Claude Agent SDK.
  *
@@ -2127,6 +2253,8 @@ interface SdkAttemptMessageState {
 	builder: PartialMessageBuilder | null;
 	intermediateToolBlocks: AssistantMessage["content"];
 	toolResultsById: Map<string, ExternalToolResultPayload>;
+	toolCompletionTargetsById: Map<string, { partial: AssistantMessage; contentIndex: number }>;
+	emittedExternalToolResultIds: Set<string>;
 }
 
 function createSdkAttemptMessageState(): SdkAttemptMessageState {
@@ -2134,6 +2262,8 @@ function createSdkAttemptMessageState(): SdkAttemptMessageState {
 		builder: null,
 		intermediateToolBlocks: [],
 		toolResultsById: new Map<string, ExternalToolResultPayload>(),
+		toolCompletionTargetsById: new Map<string, { partial: AssistantMessage; contentIndex: number }>(),
+		emittedExternalToolResultIds: new Set<string>(),
 	};
 }
 
@@ -2152,7 +2282,7 @@ async function pumpSdkMessages(
 	try {
 		const permissionMode = await resolveClaudePermissionMode();
 		const claudeOptions = options as ClaudeCodeStreamOptions | undefined;
-		const uiContext = claudeOptions?.extensionUIContext;
+		const uiContext = claudeOptions?.extensionUIContext ?? capturedClaudeCodeUIContext;
 		const onExternalToolCall = claudeOptions?.onExternalToolCall;
 		const onExternalToolResult = claudeOptions?.onExternalToolResult;
 		const sdkQueryForTest = claudeOptions?._sdkQueryForTest;
@@ -2198,6 +2328,11 @@ async function pumpSdkMessages(
 		const prompt = buildPromptFromContext(context, {
 			workflowMcpServerName,
 			browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+			questionToolAvailable: workflowQuestionToolAvailableFromAllowedTools(
+				sdkOpts.allowedTools,
+				workflowMcpServerName,
+				gsdPhase,
+			),
 		});
 		const queryPrompt = buildSdkQueryPrompt(context, prompt);
 
@@ -2239,6 +2374,10 @@ async function pumpSdkMessages(
 						unitType: gsdPhase,
 						workflowServerName: workflowMcpServerName,
 						projectRoot,
+						workflowServerConfig: resolveWorkflowMcpPreflightServerConfig(
+							sdkOpts.mcpServers,
+							workflowMcpServerName,
+						),
 						signal: options?.signal,
 					});
 					if (preflightError) {
@@ -2260,7 +2399,13 @@ async function pumpSdkMessages(
 
 			sdkAttemptLoop:
 			for (let readinessAttempt = 0; ; readinessAttempt++) {
-				let { builder, intermediateToolBlocks, toolResultsById } = createSdkAttemptMessageState();
+				let {
+					builder,
+					intermediateToolBlocks,
+					toolResultsById,
+					toolCompletionTargetsById,
+					emittedExternalToolResultIds,
+				} = createSdkAttemptMessageState();
 				const controller = new AbortController();
 				const forwardAbort = (): void => controller.abort();
 				if (options?.signal) {
@@ -2394,7 +2539,7 @@ async function pumpSdkMessages(
 						case "user": {
 							// Capture content from the completed turn before resetting
 							if (builder) {
-								for (const block of builder.message.content) {
+								for (const [contentIndex, block] of builder.message.content.entries()) {
 									if (block.type === "text" && block.text) {
 										lastTextContent = block.text;
 									} else if (block.type === "thinking" && block.thinking) {
@@ -2402,6 +2547,10 @@ async function pumpSdkMessages(
 									} else if (block.type === "toolCall" || block.type === "serverToolUse") {
 										// Collect tool blocks for externalToolExecution rendering
 										intermediateToolBlocks.push(block);
+										toolCompletionTargetsById.set(block.id, {
+											partial: builder.message,
+											contentIndex,
+										});
 									}
 								}
 							}
@@ -2416,59 +2565,70 @@ async function pumpSdkMessages(
 							// Push a synthetic toolcall_end for each tool call from this turn
 							// so the TUI can render tool results in real-time during the SDK
 							// session instead of waiting until the entire session completes.
-							if (builder) {
-								for (const block of builder.message.content) {
-									const extResult = (block as ToolCallWithExternalResult).externalResult;
-									if (!extResult) continue;
-									const contentIndex = builder.message.content.indexOf(block);
-									if (contentIndex < 0) continue;
-									const suppressDuplicateUnavailable = shouldSuppressDuplicateToolUnavailableBlock(
-										block,
-										builder.message.content,
-									);
-									// Push synthetic completion events with result attached so the
-									// chat-controller can update pending ToolExecutionComponents.
-									if (block.type === "toolCall") {
-										if (suppressDuplicateUnavailable) {
-											delete (block as ToolCallWithExternalResult).externalResult;
-											stream.push({
-												type: "toolcall_end",
-												contentIndex,
-												toolCall: block,
-												partial: builder.message,
-											});
-											(block as ToolCallWithExternalResult).externalResult = extResult;
-											continue;
-										}
-										try {
-											await onExternalToolResult?.({
-												toolCall: block,
-												result: extResult,
-											});
-										} catch (error) {
-											console.warn("[claude-code] onExternalToolResult callback failed:", error);
-										}
+							for (const block of intermediateToolBlocks) {
+								if (block.type !== "toolCall" && block.type !== "serverToolUse") continue;
+								if (emittedExternalToolResultIds.has(block.id)) continue;
+								const target = toolCompletionTargetsById.get(block.id);
+								if (!target) continue;
+
+								const extResult = (block as ToolCallWithExternalResult).externalResult;
+								if (!extResult) continue;
+								const suppressDuplicateUnavailable = shouldSuppressDuplicateToolUnavailableBlock(
+									block,
+									target.partial.content,
+								);
+								// Push synthetic completion events with result attached so the
+								// chat-controller can update pending ToolExecutionComponents.
+								if (block.type === "toolCall") {
+									if (isAskUserQuestionsTimedOutResult(block, extResult)) {
+										abortActiveAskUserQuestionElicitationsForTimeout();
+									}
+									if (suppressDuplicateUnavailable) {
+										delete (block as ToolCallWithExternalResult).externalResult;
 										stream.push({
 											type: "toolcall_end",
-											contentIndex,
+											contentIndex: target.contentIndex,
 											toolCall: block,
-											partial: builder.message,
+											partial: target.partial,
 										});
-									} else if (block.type === "serverToolUse") {
-										try {
-											await onExternalToolResult?.({
-												toolCall: serverToolUseToToolCallLike(block),
-												result: extResult,
-											});
-										} catch (error) {
-											console.warn("[claude-code] onExternalToolResult callback failed:", error);
-										}
-										stream.push({
-											type: "server_tool_use",
-											contentIndex,
-											partial: builder.message,
+										(block as ToolCallWithExternalResult).externalResult = extResult;
+										emittedExternalToolResultIds.add(block.id);
+										continue;
+									}
+									try {
+										await onExternalToolResult?.({
+											toolCall: block,
+											result: extResult,
+										});
+									} catch (error) {
+										console.warn("[claude-code] onExternalToolResult callback failed:", error);
+									}
+									stream.push({
+										type: "toolcall_end",
+										contentIndex: target.contentIndex,
+										toolCall: block,
+										partial: target.partial,
+									});
+									emittedExternalToolResultIds.add(block.id);
+								} else if (block.type === "serverToolUse") {
+									const toolCall = serverToolUseToToolCallLike(block);
+									if (isAskUserQuestionsTimedOutResult(toolCall, extResult)) {
+										abortActiveAskUserQuestionElicitationsForTimeout();
+									}
+									try {
+										await onExternalToolResult?.({
+											toolCall,
+											result: extResult,
 										});
+									} catch (error) {
+										console.warn("[claude-code] onExternalToolResult callback failed:", error);
 									}
+									stream.push({
+										type: "server_tool_use",
+										contentIndex: target.contentIndex,
+										partial: target.partial,
+									});
+									emittedExternalToolResultIds.add(block.id);
 								}
 							}
 

package/src/resources/extensions/claude-code-cli/tests/index.test.ts

@@ -0,0 +1,61 @@
+// gsd-pi - Claude Code CLI extension wiring tests
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import claudeCodeCli from "../index.ts";
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+function makeMockPi() {
+	const handlers = new Map<string, Handler[]>();
+	const providers: Array<{ name: string; config: Record<string, unknown> }> = [];
+	const pi = {
+		on(event: string, handler: Handler) {
+			const list = handlers.get(event) ?? [];
+			list.push(handler);
+			handlers.set(event, list);
+		},
+		registerProvider(name: string, config: Record<string, unknown>) {
+			providers.push({ name, config });
+		},
+	};
+	return { pi, handlers, providers };
+}
+
+test("registers the claude-code provider with a streamSimple delegate", () => {
+	const { pi, providers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	assert.equal(providers.length, 1);
+	assert.equal(providers[0].name, "claude-code");
+	assert.equal(typeof providers[0].config.streamSimple, "function");
+});
+
+test("registers Claude Sonnet 5 as a Claude Code CLI model", () => {
+	const { pi, providers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	const models = providers[0].config.models as Array<Record<string, unknown>>;
+	const sonnet5 = models.find((model) => model.id === "claude-sonnet-5");
+
+	assert.ok(sonnet5, "claude-sonnet-5 must be selectable via the claude-code provider");
+	assert.equal(sonnet5.name, "Claude Sonnet 5 (via Claude Code)");
+	assert.equal(sonnet5.reasoning, true);
+	assert.equal(sonnet5.contextWindow, 1_000_000);
+	assert.equal(sonnet5.maxTokens, 128_000);
+});
+
+test("registers a before_provider_request hook to capture the UI context", () => {
+	const { pi, handlers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	const registered = handlers.get("before_provider_request");
+	assert.ok(registered && registered.length === 1, "before_provider_request handler must be registered");
+
+	// Without this hook, core calls streamSimple with no UI context and
+	// ask_user_questions self-cancels. The handler must accept both UI states
+	// without throwing and must not mutate the provider payload.
+	const handler = registered[0];
+	const sentinelUi = { kind: "ui" };
+	assert.equal(handler({ type: "before_provider_request" }, { hasUI: true, ui: sentinelUi }), undefined);
+	assert.equal(handler({ type: "before_provider_request" }, { hasUI: false, ui: sentinelUi }), undefined);
+});