gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

package/dist/onboarding.js

@@ -118,6 +118,25 @@ function openBrowser(url) {
         execFile(cmd, [url], () => { });
     }
 }
+/**
+ * Persist the selected default provider to settings.json.
+ *
+ * This ensures first startup after onboarding prefers the provider the user
+ * just configured, instead of falling back to the first "available" provider
+ * (which can be influenced by unrelated env auth like AWS_PROFILE).
+ */
+function persistDefaultProvider(providerId) {
+    const settingsPath = join(agentDir, 'settings.json');
+    try {
+        const raw = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, 'utf-8')) : {};
+        raw.defaultProvider = providerId;
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(raw, null, 2), 'utf-8');
+    }
+    catch {
+        // Non-fatal: startup fallback logic will still run.
+    }
+}
 /** Sentinel returned by runStep when the user cancels — tells the caller
  *  to abort the entire wizard. */
 const STEP_CANCELLED = Symbol('step-cancelled');
@@ -283,16 +302,8 @@ async function runLlmStep(p, pc, authStorage) {
         p.log.info('Your Claude subscription will be used for inference. No API key needed.');
         // Store sentinel so hasAuth('claude-code') returns true on future boots
         authStorage.set('claude-code', { type: 'api_key', key: 'cli' });
-        // Persist claude-code as the default provider so the startup migration in
-        // cli.ts does not need to fire and the user is not left on "anthropic".
-        const settingsPath = join(agentDir, 'settings.json');
-        try {
-            const raw = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, 'utf-8')) : {};
-            raw.defaultProvider = 'claude-code';
-            mkdirSync(dirname(settingsPath), { recursive: true });
-            writeFileSync(settingsPath, JSON.stringify(raw, null, 2), 'utf-8');
-        }
-        catch { /* non-fatal — startup migration will catch it */ }
+        // Persist claude-code so startup does not keep users on anthropic direct API.
+        persistDefaultProvider('claude-code');
         return true;
     }
     // ── Step 2: Which provider? ──────────────────────────────────────────────
@@ -345,7 +356,7 @@ async function runOAuthFlow(p, pc, authStorage, providerId, oauthMap) {
     const s = p.spinner();
     s.start(`Authenticating with ${providerName}...`);
     try {
-        await authStorage.login(providerId, {
+        const loginCallbacks = {
             onAuth: (info) => {
                 s.stop(`Opening browser for ${providerName}`);
                 openBrowser(info.url);
@@ -377,7 +388,9 @@ async function runOAuthFlow(p, pc, authStorage, providerId, oauthMap) {
                     return result;
                 }
                 : undefined,
-        });
+        };
+        await authStorage.login(providerId, loginCallbacks);
+        persistDefaultProvider(providerId);
         p.log.success(`Authenticated with ${pc.green(providerName)}`);
         return true;
     }
@@ -416,6 +429,7 @@ async function runApiKeyFlow(p, pc, authStorage, providerId, providerLabel) {
         p.log.warn(`Key doesn't start with expected prefix (${expectedPrefixes.join(' or ')}). Saving anyway.`);
     }
     authStorage.set(providerId, { type: 'api_key', key: trimmed });
+    persistDefaultProvider(providerId);
     p.log.success(`API key saved for ${pc.green(providerLabel)}`);
     // Provider-specific post-setup hints
     if (providerId === 'openrouter') {
@@ -438,6 +452,7 @@ async function runOllamaLocalFlow(p, pc, authStorage) {
             s.stop(`Ollama is running at ${pc.green(host)}`);
             // Store a placeholder so the provider is recognized as authenticated
             authStorage.set('ollama', { type: 'api_key', key: 'ollama' });
+            persistDefaultProvider('ollama');
             p.log.success(`${pc.green('Ollama (Local)')} configured — no API key needed`);
             p.log.info(pc.dim('Models are discovered automatically from your local Ollama instance.'));
             return true;
@@ -460,6 +475,7 @@ async function runOllamaLocalFlow(p, pc, authStorage) {
     if (p.isCancel(proceed) || !proceed)
         return false;
     authStorage.set('ollama', { type: 'api_key', key: 'ollama' });
+    persistDefaultProvider('ollama');
     p.log.success(`${pc.green('Ollama (Local)')} saved — models will appear when Ollama is running`);
     return true;
 }
@@ -509,6 +525,7 @@ async function runCustomOpenAIFlow(p, pc, authStorage) {
     const trimmedModelId = modelId.trim();
     // Save API key to auth storage
     authStorage.set('custom-openai', { type: 'api_key', key: trimmedKey });
+    persistDefaultProvider('custom-openai');
     // Write or merge into models.json
     const modelsJsonPath = join(agentDir, 'models.json');
     let config = { providers: {} };
@@ -653,7 +670,9 @@ async function runToolKeysStep(p, pc, authStorage) {
 // ─── Remote Questions Step ────────────────────────────────────────────────────
 async function runRemoteQuestionsStep(p, pc, authStorage) {
     // Check existing config — use getCredentialsForProvider to skip empty-key entries
-    const hasValidKey = (provider) => authStorage.getCredentialsForProvider(provider).some((c) => c.type === 'api_key' && c.key);
+    const hasValidKey = (provider) => authStorage
+        .getCredentialsForProvider(provider)
+        .some((c) => c.type === 'api_key' && typeof c.key === 'string' && c.key.length > 0);
     const hasDiscord = hasValidKey('discord_bot');
     const hasSlack = hasValidKey('slack_bot');
     const hasTelegram = hasValidKey('telegram_bot');
@@ -858,7 +877,13 @@ async function runDiscordChannelStep(p, pc, token) {
     try {
         const res = await fetch(`https://discord.com/api/v10/guilds/${guildId}/channels`, { headers, signal: AbortSignal.timeout(15_000) });
         const data = await res.json();
-        channels = Array.isArray(data) ? data.filter((ch) => ch.type === 0 || ch.type === 5) : [];
+        channels = Array.isArray(data)
+            ? data.filter((ch) => typeof ch === 'object' &&
+                ch !== null &&
+                typeof ch.id === 'string' &&
+                typeof ch.name === 'string' &&
+                (ch.type === 0 || ch.type === 5))
+            : [];
     }
     catch {
         p.log.warn('Could not fetch channels — configure later with /gsd remote discord');

package/dist/resources/extensions/ask-user-questions.js

@@ -16,13 +16,16 @@ import { showInterviewRound, } from "./shared/tui.js";
 const OptionSchema = Type.Object({
     label: Type.String({ description: "User-facing label (1-5 words)" }),
     description: Type.String({ description: "One short sentence explaining impact/tradeoff if selected" }),
+    preview: Type.Optional(Type.String({
+        description: "Optional markdown content shown in a side-by-side preview panel when this option is highlighted. Use for showing code samples, config snippets, or detailed explanations. Keep under ~20 lines — longer content is truncated.",
+    })),
 });
 const QuestionSchema = Type.Object({
     id: Type.String({ description: "Stable identifier for mapping answers (snake_case)" }),
     header: Type.String({ description: "Short header label shown in the UI (12 or fewer chars)" }),
     question: Type.String({ description: "Single-sentence prompt shown to the user" }),
     options: Type.Array(OptionSchema, {
-        description: 'Provide 2-3 mutually exclusive choices for single-select, or any number for multi-select. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select; the client adds a free-form "None of the above" option automatically.',
+        description: 'Provide 2-3 mutually exclusive choices for single-select, or any number for multi-select. Put the recommended option first and suffix its label with "(Recommended)". Each option can include an optional "preview" field with markdown content shown in a side panel. Do not include an "Other" option for single-select; the client adds a free-form "None of the above" option automatically.',
     }),
     allowMultiple: Type.Optional(Type.Boolean({
         description: "If true, the user can select multiple options using SPACE to toggle and ENTER to confirm. No 'None of the above' option is added. Default: false.",
@@ -134,12 +137,14 @@ export default function AskUserQuestions(pi) {
     pi.registerTool({
         name: "ask_user_questions",
         label: "Request User Input",
-        description: "Request user input for one to three short questions and wait for the response. Single-select questions have 2-3 mutually exclusive options with a free-form 'None of the above' added automatically. Multi-select questions (allowMultiple: true) let the user toggle multiple options with SPACE and confirm with ENTER.",
+        description: "Request user input for one to three short questions and wait for the response. Single-select questions have 2-3 mutually exclusive options with a free-form 'None of the above' added automatically. Multi-select questions (allowMultiple: true) let the user toggle multiple options with SPACE and confirm with ENTER. Options can include an optional 'preview' field with markdown content shown in a side-by-side panel when highlighted.",
         promptGuidelines: [
             "Use ask_user_questions when you need the user to choose between concrete alternatives before proceeding.",
             "Keep questions to 1 when possible; never exceed 3.",
             "For single-select: each question must have 2-3 options. Put the recommended option first with '(Recommended)' suffix. Do not include an 'Other' or 'None of the above' option - the client adds one automatically.",
             "For multi-select: set allowMultiple: true. The user can pick any number of options. No 'None of the above' is added.",
+            "When options involve code patterns, config choices, or architecture decisions, add a 'preview' field with markdown content (code blocks, lists, headers, etc.). The preview renders in a side-by-side panel when the option is highlighted.",
+            "Preview content is rendered in a fixed-height panel (max ~20 lines visible). Keep previews concise — show the most relevant snippet, not exhaustive examples. Longer content is truncated with a '+N lines hidden' indicator.",
         ],
         parameters: AskUserQuestionsParams,
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -274,6 +279,10 @@ export default function AskUserQuestions(pi) {
                 const headers = qs.map((q) => q.header).join(", ");
                 text += theme.fg("dim", ` (${headers})`);
             }
+            const previewCount = qs.reduce((acc, q) => acc + (q.options || []).filter((o) => o.preview).length, 0);
+            if (previewCount > 0) {
+                text += theme.fg("accent", ` [${previewCount} preview${previewCount !== 1 ? "s" : ""}]`);
+            }
             for (const q of qs) {
                 const multiSel = !!q.allowMultiple;
                 text += `\n  ${theme.fg("text", q.question)}`;
@@ -307,10 +316,13 @@ export default function AskUserQuestions(pi) {
                             lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
                             continue;
                         }
-                        const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
+                        const selected = answer.selected;
+                        const answerText = Array.isArray(selected)
+                            ? (selected.length > 0 ? selected.join(", ") : "(custom)")
+                            : (selected || "(custom)");
                         let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-                        if (answer.user_note) {
-                            line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
+                        if (answer.notes) {
+                            line += ` ${theme.fg("muted", `[note: ${answer.notes}]`)}`;
                         }
                         lines.push(line);
                     }

package/dist/resources/extensions/claude-code-cli/models.js

@@ -19,6 +19,15 @@ export const CLAUDE_CODE_MODELS = [
         contextWindow: 1_000_000,
         maxTokens: 128_000,
     },
+    {
+        id: "claude-opus-4-7",
+        name: "Claude Opus 4.7 (via Claude Code)",
+        reasoning: true,
+        input: ["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/dist/resources/extensions/claude-code-cli/readiness.js

@@ -9,6 +9,16 @@
  * and check the exit code + output for an authenticated session.
  */
 import { execFileSync } from "node:child_process";
+/**
+ * Platform-correct binary name for the Claude Code CLI.
+ *
+ * On Windows, npm-global binaries are installed as `.cmd` shims and
+ * `execFileSync` does not auto-resolve the extension — calling bare
+ * `claude` would fail with ENOENT even when the CLI is installed and
+ * authenticated. Mirrors the `NPM_COMMAND` pattern in
+ * `src/resources/extensions/gsd/pre-execution-checks.ts`.
+ */
+const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
 let cachedBinaryPresent = null;
 let cachedAuthed = null;
 let lastCheckMs = 0;
@@ -22,7 +32,7 @@ function refreshCache() {
     lastCheckMs = now;
     // Check binary presence
     try {
-        execFileSync("claude", ["--version"], { timeout: 5_000, stdio: "pipe" });
+        execFileSync(CLAUDE_COMMAND, ["--version"], { timeout: 5_000, stdio: "pipe" });
         cachedBinaryPresent = true;
     }
     catch {
@@ -32,7 +42,7 @@ function refreshCache() {
     }
     // Check auth status — exit code 0 with non-error output means authenticated
     try {
-        const output = execFileSync("claude", ["auth", "status"], { timeout: 5_000, stdio: "pipe" })
+        const output = execFileSync(CLAUDE_COMMAND, ["auth", "status"], { timeout: 5_000, stdio: "pipe" })
             .toString()
             .toLowerCase();
         // The CLI outputs "not logged in", "no credentials", or similar when unauthenticated

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -6,12 +6,14 @@
  * AssistantMessageEvents for TUI rendering, then strips tool-call blocks from
  * the final AssistantMessage so GSD's agent loop doesn't try to dispatch them.
  */
-import { EventStream, mapThinkingLevelToEffort, supportsAdaptiveThinking } from "@gsd/pi-ai";
+import { EventStream } from "@gsd/pi-ai";
 import { execSync } from "node:child_process";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
 import { showInterviewRound } from "../shared/tui.js";
+/** Label used for the free-text fallback option in single-choice elicitation questions. */
 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;
 // ---------------------------------------------------------------------------
 // Stream factory
@@ -29,6 +31,7 @@ function createAssistantStream() {
         throw new Error("Unexpected event type for final result");
     });
 }
+/** Extract a human-readable error string from an SDK result message. */
 export function getResultErrorMessage(result) {
     if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
         return result.errors.join("; ");
@@ -41,10 +44,13 @@ export function getResultErrorMessage(result) {
 // ---------------------------------------------------------------------------
 // Claude binary resolution
 // ---------------------------------------------------------------------------
+/** Cached result of the `which`/`where claude` lookup so the shell is only spawned once per process. */
 let cachedClaudePath = null;
+/** Return the shell command used to locate the `claude` binary on the given platform. */
 export function getClaudeLookupCommand(platform = process.platform) {
     return platform === "win32" ? "where claude" : "which claude";
 }
+/** Extract the first line of `which`/`where` output as the resolved binary path. */
 export function parseClaudeLookupOutput(output) {
     return output
         .toString()
@@ -123,6 +129,7 @@ export function buildPromptFromContext(context) {
     }
     return parts.join("\n\n");
 }
+/** Strip the `data:<mime>;base64,` prefix from a data URI, returning only the raw base64 payload. */
 function stripDataUriPrefix(value) {
     const commaIndex = value.indexOf(",");
     if (value.startsWith("data:") && commaIndex !== -1) {
@@ -130,10 +137,12 @@ function stripDataUriPrefix(value) {
     }
     return value;
 }
+/** Extract the MIME type from a data URI string, or return `null` if the value is not a valid data URI. */
 function inferMimeTypeFromDataUri(value) {
     const match = /^data:([^;,]+);base64,/.exec(value);
     return match?.[1] ?? null;
 }
+/** Collect all base64 image blocks from user messages in the context for inclusion in the SDK prompt. */
 export function extractImageBlocksFromContext(context) {
     const imageBlocks = [];
     for (const msg of context.messages) {
@@ -162,6 +171,7 @@ export function extractImageBlocksFromContext(context) {
     }
     return imageBlocks;
 }
+/** Build the SDK query prompt, wrapping image blocks into an async iterable user message when present. */
 export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext(context)) {
     const imageBlocks = extractImageBlocksFromContext(context);
     if (imageBlocks.length === 0) {
@@ -183,6 +193,7 @@ export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext
 // ---------------------------------------------------------------------------
 // Error helper
 // ---------------------------------------------------------------------------
+/** Build a minimal error `AssistantMessage` with the given model ID and error text. */
 function makeErrorMessage(model, errorMsg) {
     return {
         role: "assistant",
@@ -209,6 +220,7 @@ export function makeStreamExhaustedErrorMessage(model, lastTextContent) {
     }
     return message;
 }
+/** Extract the string labels from an array of SDK elicitation option objects, filtering out blank entries. */
 function readElicitationChoices(options) {
     if (!Array.isArray(options))
         return [];
@@ -216,6 +228,7 @@ function readElicitationChoices(options) {
         .map((option) => (typeof option?.const === "string" ? option.const : typeof option?.title === "string" ? option.title : ""))
         .filter((option) => option.length > 0);
 }
+/** Parse an SDK elicitation request into structured multiple-choice questions, or null if the schema is unsupported. */
 export function parseAskUserQuestionsElicitation(request) {
     if (request.mode && request.mode !== "form")
         return null;
@@ -265,6 +278,7 @@ export function parseAskUserQuestionsElicitation(request) {
     }
     return questions.length > 0 ? questions : null;
 }
+/** Return true if the elicitation field should be treated as sensitive and rendered as a secure/password input. */
 function isSecureElicitationField(requestMessage, fieldId, field) {
     if (field.format === "password")
         return true;
@@ -283,6 +297,7 @@ function isSecureElicitationField(requestMessage, fieldId, field) {
         .toLowerCase();
     return SENSITIVE_FIELD_PATTERN.test(haystack);
 }
+/** Parse an SDK elicitation request into free-text input field descriptors, or null if unsupported. */
 export function parseTextInputElicitation(request) {
     if (request.mode && request.mode !== "form")
         return null;
@@ -315,6 +330,7 @@ export function parseTextInputElicitation(request) {
     }
     return fields.length > 0 ? fields : null;
 }
+/** Convert a TUI interview round result into the SDK elicitation content map. */
 export function roundResultToElicitationContent(questions, result) {
     const content = {};
     for (const question of questions) {
@@ -334,6 +350,7 @@ export function roundResultToElicitationContent(questions, result) {
     }
     return content;
 }
+/** Build the dialog title string for a multiple-choice elicitation question, combining server name, header, and question text. */
 function buildElicitationPromptTitle(request, question) {
     const parts = [
         request.serverName ? `[${request.serverName}]` : "",
@@ -342,6 +359,7 @@ function buildElicitationPromptTitle(request, question) {
     ].filter((part) => part && part.trim().length > 0);
     return parts.join("\n\n");
 }
+/** Drive each multiple-choice elicitation question through the extension UI's `select` dialog, collecting answers into an SDK result. */
 async function promptElicitationWithDialogs(request, questions, ui, signal) {
     const content = {};
     for (const question of questions) {
@@ -379,6 +397,7 @@ async function promptElicitationWithDialogs(request, questions, ui, signal) {
     }
     return { action: "accept", content };
 }
+/** Build the dialog title string for a free-text input field, combining server name, field title, and description. */
 function buildTextInputPromptTitle(request, field) {
     const parts = [
         request.serverName ? `[${request.serverName}]` : "",
@@ -387,6 +406,7 @@ function buildTextInputPromptTitle(request, field) {
     ].filter((part) => typeof part === "string" && part.trim().length > 0);
     return parts.join("\n\n");
 }
+/** Derive a placeholder hint for a free-text input field from its description, falling back to "Required" or "Leave empty to skip". */
 function buildTextInputPlaceholder(field) {
     const desc = field.description.trim();
     if (!desc)
@@ -400,6 +420,7 @@ function buildTextInputPlaceholder(field) {
     const hint = formatLine.replace(/^format:\s*/i, "").trim();
     return hint.length > 0 ? hint : field.required ? "Required" : "Leave empty to skip";
 }
+/** Collect each free-text input field via the extension UI's `input` dialog, returning the filled SDK elicitation result. */
 async function promptTextInputElicitation(request, fields, ui, signal) {
     const content = {};
     for (const field of fields) {
@@ -411,6 +432,7 @@ async function promptTextInputElicitation(request, fields, ui, signal) {
     }
     return { action: "accept", content };
 }
+/** Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available. */
 export function createClaudeCodeElicitationHandler(ui) {
     if (!ui)
         return undefined;
@@ -482,6 +504,42 @@ export async function resolveClaudePermissionMode(env = process.env) {
     }
     return "bypassPermissions";
 }
+// NOTE: These helpers intentionally mirror @gsd/pi-ai anthropic-shared
+// behavior so this extension remains typecheck-stable even when the published
+// @gsd/pi-ai barrel lags behind monorepo source exports.
+/** Return true for model IDs that support the adaptive thinking API (Opus 4.6/4.7, Sonnet 4.6/4.7, Haiku 4.5). */
+function modelSupportsAdaptiveThinking(modelId) {
+    return (modelId.includes("opus-4-6")
+        || modelId.includes("opus-4.6")
+        || modelId.includes("opus-4-7")
+        || modelId.includes("opus-4.7")
+        || modelId.includes("sonnet-4-6")
+        || modelId.includes("sonnet-4.6")
+        || modelId.includes("sonnet-4-7")
+        || modelId.includes("sonnet-4.7")
+        || modelId.includes("haiku-4-5")
+        || modelId.includes("haiku-4.5"));
+}
+/** Map a GSD thinking level to the Anthropic effort value, clamping xhigh to max for models that lack native xhigh support. */
+function mapThinkingLevelToAnthropicEffort(level, modelId) {
+    switch (level) {
+        case "minimal":
+        case "low":
+            return "low";
+        case "medium":
+            return "medium";
+        case "high":
+            return "high";
+        case "xhigh":
+            if (modelId.includes("opus-4-7") || modelId.includes("opus-4.7"))
+                return "xhigh";
+            if (modelId.includes("opus-4-6") || modelId.includes("opus-4.6"))
+                return "max";
+            return "high";
+        default:
+            return "high";
+    }
+}
 /**
  * Build the options object passed to the Claude Agent SDK's `query()` call.
  *
@@ -513,8 +571,17 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         "Bash(pwd)",
         ...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
     ];
-    const effort = reasoning && supportsAdaptiveThinking(modelId)
-        ? mapThinkingLevelToEffort(reasoning, modelId)
+    const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
+    const effort = reasoning && supportsAdaptive
+        ? mapThinkingLevelToAnthropicEffort(reasoning, modelId)
+        : undefined;
+    // Bug B: SDK requires thinking:{type:"adaptive"} alongside effort for adaptive thinking to activate.
+    // Bug C: SDK requires thinking:{type:"disabled"} to actually stop adaptive thinking when reasoning is off;
+    //        omitting the field leaves the SDK in its adaptive default (or persisted session state).
+    const thinkingConfig = supportsAdaptive
+        ? effort
+            ? { thinking: { type: "adaptive" } }
+            : { thinking: { type: "disabled" } }
         : undefined;
     return {
         pathToClaudeCodeExecutable: getClaudePath(),
@@ -529,11 +596,13 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         disallowedTools,
         ...(allowedTools.length > 0 ? { allowedTools } : {}),
         ...(mcpServers ? { mcpServers } : {}),
-        betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
+        betas: (modelId.includes("sonnet") || modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) ? ["context-1m-2025-08-07"] : [],
+        ...(thinkingConfig ?? {}),
         ...(effort ? { effort } : {}),
         ...sdkExtraOptions,
     };
 }
+/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
 function normalizeToolResultContent(content) {
     if (typeof content === "string") {
         return [{ type: "text", text: content }];
@@ -568,6 +637,7 @@ function normalizeToolResultContent(content) {
     }
     return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
 }
+/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
 export function extractToolResultsFromSdkUserMessage(message) {
     const extracted = [];
     const seen = new Set();
@@ -612,6 +682,7 @@ export function extractToolResultsFromSdkUserMessage(message) {
     }
     return extracted;
 }
+/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
 function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
     for (const block of toolBlocks) {
         if (block.type !== "toolCall" && block.type !== "serverToolUse")
@@ -659,6 +730,7 @@ export function streamViaClaudeCode(model, context, options) {
     void pumpSdkMessages(model, context, options, stream);
     return stream;
 }
+/** Async pump that drives the Claude Agent SDK's async-iterable message stream and pushes events into `stream`. */
 async function pumpSdkMessages(model, context, options, stream) {
     const modelId = model.id;
     let builder = null;

package/dist/resources/extensions/gsd/auto/detect-stuck.js

@@ -16,6 +16,7 @@ const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
  *
  * Rule 1: Same error string twice in a row → stuck immediately.
  * Rule 2: Same unit key 3+ consecutive times → stuck (preserves prior behavior).
+ * Rule 2b: Same unit key appears 3+ times anywhere in the active window → stuck.
  * Rule 3: Oscillation A→B→A→B in last 4 entries → stuck.
  * Rule 4: Same ENOENT path in any 2 entries within the window → stuck (#3575).
  *         Missing files don't self-heal between retries — retrying wastes budget.
@@ -48,6 +49,14 @@ export function detectStuck(window) {
             };
         }
     }
+    // Rule 2b: Same unit key 3+ times anywhere in the active window
+    const countInWindow = window.filter((entry) => entry.key === last.key).length;
+    if (countInWindow >= 3) {
+        return {
+            stuck: true,
+            reason: `${last.key} derived ${countInWindow} times in last ${window.length} attempts without progress${suffix}`,
+        };
+    }
     // Rule 3: Oscillation (A→B→A→B in last 4)
     if (window.length >= 4) {
         const w = window.slice(-4);

package/dist/resources/extensions/gsd/auto/loop.js

@@ -17,6 +17,7 @@ import { logWarning } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { scheduleSidecarQueue } from "../uok/execution-graph.js";
+import { ExecutionGraphScheduler } from "../uok/execution-graph.js";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 // ── Stuck detection persistence (#3704) ──────────────────────────────────
@@ -78,17 +79,73 @@ function checkMemoryPressure() {
     const pct = heapMB / limitMB;
     return { pressured: pct > MEMORY_PRESSURE_THRESHOLD, heapMB, limitMB, pct };
 }
+function resolveDispatchNodeKind(unitType, sidecarItem) {
+    if (sidecarItem?.kind === "hook")
+        return "hook";
+    if (sidecarItem?.kind === "triage")
+        return "verification";
+    if (sidecarItem?.kind === "quick-task")
+        return "team-worker";
+    if (unitType.startsWith("hook/"))
+        return "hook";
+    if (unitType === "reactive-execute")
+        return "subagent";
+    if (unitType === "gate-evaluate"
+        || unitType === "validate-milestone"
+        || unitType === "run-uat"
+        || unitType === "complete-slice") {
+        return "verification";
+    }
+    if (unitType === "replan-slice" || unitType === "reassess-roadmap") {
+        return "reprocess";
+    }
+    return "unit";
+}
+async function runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem) {
+    if (dispatchContract === "legacy-direct") {
+        return runUnitPhase(ic, iterData, loopState, sidecarItem);
+    }
+    const scheduler = new ExecutionGraphScheduler();
+    let outcome = null;
+    const executeNode = async () => {
+        outcome = await runUnitPhase(ic, iterData, loopState, sidecarItem);
+    };
+    const kinds = [
+        "unit",
+        "hook",
+        "subagent",
+        "team-worker",
+        "verification",
+        "reprocess",
+    ];
+    for (const kind of kinds)
+        scheduler.registerHandler(kind, executeNode);
+    const nodeId = `dispatch:${ic.iteration}:${iterData.unitType}:${iterData.unitId}`;
+    await scheduler.run([
+        {
+            id: nodeId,
+            kind: resolveDispatchNodeKind(iterData.unitType, sidecarItem),
+            dependsOn: [],
+            metadata: {
+                unitType: iterData.unitType,
+                unitId: iterData.unitId,
+            },
+        },
+    ], { parallel: false, maxWorkers: 1 });
+    return outcome ?? { action: "break", reason: "scheduler-dispatch-missing-result" };
+}
 /**
  * Main auto-mode execution loop. Iterates: derive → dispatch → guards →
  * runUnit → finalize → repeat. Exits when s.active becomes false or a
  * terminal condition is reached.
  *
  * This is the linear replacement for the recursive
- * dispatchNextUnit → handleAgentEnd → dispatchNextUnit chain.
+ * dispatchNextUnit → resolveAgentEnd → dispatchNextUnit chain.
  */
-export async function autoLoop(ctx, pi, s, deps) {
+export async function autoLoop(ctx, pi, s, deps, options) {
     debugLog("autoLoop", { phase: "enter" });
     let iteration = 0;
+    const dispatchContract = options?.dispatchContract ?? "legacy-direct";
     // Load persisted stuck state so counters survive session restarts (#3704)
     const persisted = loadStuckState(s.basePath);
     const loopState = {
@@ -273,7 +330,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     break;
                 }
                 // ── Unit execution (shared with dev path) ──
-                const unitPhaseResult = await runUnitPhase(ic, iterData, loopState);
+                const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState);
                 deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
                     unitType: iterData.unitType,
                     unitId: iterData.unitId,
@@ -410,7 +467,7 @@ export async function autoLoop(ctx, pi, s, deps) {
                     sidecarKind: sidecarItem.kind,
                 });
             }
-            const unitPhaseResult = await runUnitPhase(ic, iterData, loopState, sidecarItem);
+            const unitPhaseResult = await runUnitPhaseViaContract(dispatchContract, ic, iterData, loopState, sidecarItem);
             deps.uokObserver?.onPhaseResult("unit", unitPhaseResult.action, {
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,
@@ -528,3 +585,9 @@ export async function autoLoop(ctx, pi, s, deps) {
     _clearCurrentResolve();
     debugLog("autoLoop", { phase: "exit", totalIterations: iteration });
 }
+export async function runUokKernelLoop(ctx, pi, s, deps) {
+    return autoLoop(ctx, pi, s, deps, { dispatchContract: "uok-scheduler" });
+}
+export async function runLegacyAutoLoop(ctx, pi, s, deps) {
+    return autoLoop(ctx, pi, s, deps, { dispatchContract: "legacy-direct" });
+}