gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-next.9c0ec0ba1

package/README.md

@@ -27,85 +27,120 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.71
+## What's New in v2.75
 
-### MCP Secure Env Collect
+### Knowledge Graph & Learning Extraction
 
-- **Secure credential collection over MCP** — the new `secure_env_collect` tool uses MCP form elicitation to collect secrets (API keys, tokens) from external clients without exposing values in tool output. Masks input in interactive mode.
-- **Hardened elicitation schema** — MCP elicitation schema handling is stricter, with proper validation and fallback for providers that don't support forms.
+- **Knowledge graph system** — GSD now builds a structured knowledge graph from project artifacts. Learnings, decisions, and patterns are parsed into queryable graph nodes.
+- **`/gsd extract-learnings`** — new command extracts decisions, lessons, patterns, and surprises from completed phase artifacts into `LEARNINGS.md`, which feeds the knowledge graph automatically.
 
-### MCP Reliability
+### Unified Orchestration Kernel (UOK)
 
-- **Stream ordering preserved** — MCP tool output now renders in the correct order, fixing interleaved output in Claude Code and other MCP clients.
-- **isError flag propagation** — workflow tool execution failures now correctly return `isError: true`, so MCP clients can distinguish success from failure.
-- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates.
+- **UOK is now the default** — the unified orchestration kernel replaces the legacy execution path. Plan-v2 compile gates, unified audit envelopes, turn-level git transaction modes, reactive/parallel scheduling via execution graph, and model policy filtering are all enforced by default. Legacy fallback remains as an emergency escape.
 
-### Model Selection Hardening
+### Extension API
 
-- **Unconfigured models blocked** — models without a configured provider are filtered from selection surfaces, preventing dispatch failures.
-- **Provider readiness required** — saved default model selection now verifies the provider is ready before accepting it.
-- **Session override honored** — `/gsd model` selection persists as a session override across all dispatch phases.
-- **Minimal context guard** — model override logic is skipped in minimal command contexts where it doesn't apply.
+- **GSD Extension API** — third-party extensions can now be loaded from `.gsd/extensions/`, with a formal API surface for hooking into the GSD lifecycle (#3338).
 
-### Auto-Mode Resilience
+### v1 Command Parity
 
-- **Credential cooldown recovery** — auto-mode survives transient 429 rate-limit responses with structured cooldown errors and a bounded retry budget.
-- **Fire-and-forget auto start** — auto start is detached from active turns to prevent blocking.
-- **Scoped forensics** — stuck-loop forensics are now scoped to auto sessions only, preventing false positives in interactive use.
+- **12 missing commands added** — GSD v2 now covers all v1 commands, closing the migration gap.
 
 ### TUI Improvements
 
-- **Overlay subscription fix** — resolved overlay subscription lifecycle and `Ctrl+Shift+P` shortcut conflict.
-- **Improved overlays and shortcuts** — GSD overlays, keyboard shortcuts, and notification flows redesigned for consistency.
-- **Pinned output restored** — pinned output bar displays above the editor during tool execution again.
-- **Turn completion cleanup** — pinned latest output is cleared on turn completion, preventing stale output from persisting.
-- **Secure input masking** — extension input values are masked in interactive mode when collecting secrets.
+- **Chat frame redesign** — compaction notices, tool execution cards, and the chat frame now share a unified styling with timestamps and model headers.
+- **Inline tool calls** — assistant tool calls render inline with text instead of grouped at the end.
+- **Compaction and success fixes** — tool cards no longer stick after compaction; success notifications are properly promoted.
 
-### Provider Fixes
+### Auto-Mode & Reliability
 
-- **Full OAuth login URLs** — OAuth login URLs are now displayed in full instead of being truncated.
-- **MiniMax bearer auth** — MiniMax Anthropic API requests use proper bearer authentication.
-- **Case-insensitive tool rendering** — renderable tool matching is now case-insensitive, fixing missed tool output.
-- **Headless idle timeout** — idle timeout is kept off during interactive tool execution in headless mode.
+- **Session timeout recovery** — auto-resume timer handles session creation timeouts; timeout counter resets on resume.
+- **Compaction checkpoint fix** — all session phases are checkpointed during compaction, not just the executing phase.
+- **MCP worktree routing** — tool writes are routed to the active worktree when a milestone has one; worktree paths are accepted in the project root guard.
+- **Single-writer DB invariant** — the engine database now enforces a single-writer invariant, preventing corruption from concurrent access.
 
-### Reliability & Internals
+### Providers & CI
 
-- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition.
-- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers.
-- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI.
-- **Model routing transparency** — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner.
-- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction.
-- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths.
-- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses.
-- **Milestone worktree cleanup** — merged worktree cleanup uses the milestone branch instead of generic lookups.
-- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching.
+- **Alibaba DashScope** — added as a standalone provider (#3891).
+- **Persistent language preference** — `/gsd language` sets a persistent language preference.
+- **Flat-rate provider detection** — extended to custom and externalCli providers.
+- **Thinking level as effort** — Claude Code now passes thinking level as an effort parameter.
+- **Hardened release pipeline** — workspace versions synced in release commits, package-lock.json regenerated during bumps, incremental build cache issues resolved.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 <details>
-<summary>Previous highlights (v2.70 and earlier)</summary>
+<summary>v2.74 highlights</summary>
+
+- **DB-authoritative milestone completeness** — milestone completion state is derived from the database, not file markers (#4179)
+- **Flat-rate provider detection** — extended to custom and externalCli providers
+- **Thinking level as effort** — Claude Code passes thinking level as an effort parameter
+- **False milestone merge prevention** — auto-mode no longer falsely merges after a `complete-milestone` failure (#4175)
+- **Premature auto-stop fix** — prevents auto-mode from stopping early on blocked phase + missing reassessment
+- **Inline tool call rendering** — assistant tool calls render inline with text instead of grouped at the end
+- **Custom model preservation** — custom model selection preserved on `/gsd auto` bootstrap (#4122)
+
+</details>
+
+<details>
+<summary>v2.73 highlights</summary>
+
+- **Alibaba DashScope provider** — added as a standalone provider (#3891)
+- **Layered depth enforcement** — discuss phase enforces depth gates for thorough requirements gathering (#4079)
+- **Memory pressure watchdog** — stuck detection state persisted across sessions (#3708)
+- **Ollama cloud auth** — cloud auth support and real context window resolution via `/api/show` (#4017)
+- **DB corruption prevention** — direct writes to `gsd.db` blocked via hooks (#3674)
+- **Circular dependency cleanup** — 3 circular dependencies broken in extension modules (#3730)
+- **Subagent permissions** — GSD subagents default to `bypassPermissions` with safe built-ins pre-authorized
+- **Security hardening** — auth middleware activated, shutdown/update routes hardened (#4023)
+- **Stale slice reconciliation** — stale slice rows reconciled and STATE.md rebuilt before DB close (#3658)
+- **Subagent model preference** — `subagent_model` preference wired through to dispatch prompt builders
+- **Pipeline integrity** — 5 pipeline issues addressed from release audit, package-lock.json regenerated during bumps
+
+</details>
+
+<details>
+<summary>v2.72 highlights</summary>
+
+- **8 specialist subagents** — new specialist subagents and slim pro agents with GSD phase guard to prevent conflicts
+- **Model selection hardening** — unconfigured models blocked from selection, provider readiness required, session override honored
+- **Auto-mode resilience** — credential cooldown recovery with bounded retry budget, fire-and-forget auto start, scoped forensics
+- **TUI overhaul** — overlays, keyboard shortcuts, and notification flows redesigned for consistency
+- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction
+- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths
+- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses
+- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI
+- **MCP reliability** — every registered tool exposed, SDK subpath resolution fixed, abort signals threaded through
+- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching
+
+</details>
+
+<details>
+<summary>v2.71 highlights</summary>
+
+- **Secure credential collection over MCP** — `secure_env_collect` tool uses MCP form elicitation to collect secrets without exposing values in tool output
+- **MCP stream ordering** — tool output renders in correct order, fixing interleaved output in Claude Code and other MCP clients
+- **isError flag propagation** — workflow tool execution failures correctly return `isError: true`
+- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates
+- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking fixed with atomic lock acquisition
+- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers
+- **Pinned output fixes** — restored above editor during tool execution, cleared on turn completion
+
+</details>
+
+<details>
+<summary>v2.70 and earlier</summary>
 
 - **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP
 - **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically
 - **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state
 - **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations
 - **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction
-- **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions
-- **Anthropic subscription routing** — auto-routed through Claude Code CLI provider with proper display names
 - **5-wave state machine hardening** — critical data integrity fixes across atomic writes, event log reconciliation, session recovery
-- **Discussion gate enforcement** — mechanical enforcement with fail-closed behavior
 - **Slice-level parallelism** — dependency-aware parallel dispatch within a milestone
-- **Persistent notification panel** — TUI overlay, widget, and web API for real-time notifications
 - **MCP server** — 6 read-only project state tools for external integrations, auto-wrapup guard, and question dedup
 - **Ollama extension** — first-class local LLM support via Ollama, with dynamic routing enabled by default
-- **Discord bot & daemon** — dedicated daemon package, Discord bot, and headless text mode with tool calls
-- **Capability-aware model routing (ADR-004)** — capability scoring, `before_model_select` hook, and task metadata extraction
 - **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking
-- **`/gsd parallel watch`** — native TUI overlay for real-time worker monitoring
-- **Codebase map** — automatic codebase map injection for fresh agent contexts
-- **`--resume` flag** — resume previous sessions from the CLI
-- **Concurrent invocation guard** — prevents overlapping auto-mode runs
-- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens
 - **Skills overhaul** — 30+ skill packs covering major frameworks, databases, and cloud platforms
 - **Single-writer state engine** — disciplined state transitions with machine guards and TOCTOU hardening
 - **DB-backed planning tools** — atomic SQLite tool calls for state transitions
@@ -389,6 +424,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format             |
 | `/gsd help`             | Categorized command reference for all GSD subcommands           |
 | `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults      |
+| `/gsd workflow`         | Unified workflow plugins — list, run `<name>`, install, info, validate |
+| `/gsd start <template>` | Launch a bundled or custom workflow template (bugfix, release, etc.) |
 | `/gsd forensics`        | Full-access GSD debugger for auto-mode failure investigation    |
 | `/gsd cleanup`          | Archive phase directories from completed milestones             |
 | `/gsd doctor`           | Runtime health checks — issues surface across widget, visualizer, and reports |
@@ -497,7 +534,7 @@ version: 1
 models:
   research: claude-sonnet-4-6
   planning:
-    model: claude-opus-4-6
+    model: claude-opus-4-7
     fallbacks:
       - openrouter/z-ai/glm-5
       - openrouter/minimax/minimax-m2.5
@@ -756,7 +793,7 @@ In your preferences (`/gsd prefs`), assign different models to different phases:
 models:
   research: openrouter/deepseek/deepseek-r1
   planning:
-    model: claude-opus-4-6
+    model: claude-opus-4-7
     fallbacks:
       - openrouter/z-ai/glm-5
   execution: claude-sonnet-4-6

package/dist/headless-events.d.ts

@@ -47,4 +47,4 @@ export declare function isInteractiveHeadlessTool(toolName: string | undefined):
 export declare function shouldArmHeadlessIdleTimeout(toolCallCount: number, interactiveToolCount: number): boolean;
 export declare const FIRE_AND_FORGET_METHODS: Set<string>;
 export declare const QUICK_COMMANDS: Set<string>;
-export declare function isQuickCommand(command: string): boolean;
+export declare function isQuickCommand(command: string, commandArgs?: readonly string[]): boolean;

package/dist/headless-events.js

@@ -100,6 +100,9 @@ export const QUICK_COMMANDS = new Set([
     'cleanup', 'migrate', 'doctor', 'remote', 'help', 'steer',
     'triage', 'visualize',
 ]);
-export function isQuickCommand(command) {
-    return QUICK_COMMANDS.has(command);
+const QUICK_WORKFLOW_SUBCOMMANDS = new Set(['list', 'validate']);
+export function isQuickCommand(command, commandArgs = []) {
+    if (QUICK_COMMANDS.has(command))
+        return true;
+    return command === 'workflow' && QUICK_WORKFLOW_SUBCOMMANDS.has(commandArgs[0] ?? '');
 }

package/dist/headless.js

@@ -606,7 +606,7 @@ async function runHeadlessOnce(options, restartCount) {
             }
         }
         // Quick commands: resolve on first agent_end
-        if (eventObj.type === 'agent_end' && isQuickCommand(options.command) && !completed) {
+        if (eventObj.type === 'agent_end' && isQuickCommand(options.command, options.commandArgs) && !completed) {
             completed = true;
             resolveCompletion();
             return;
@@ -622,10 +622,9 @@ async function runHeadlessOnce(options, restartCount) {
         // Kill child process — don't await, just fire and exit.
         // The main flow may be awaiting a promise that resolves when the child dies,
         // which would race with this handler. Exit synchronously to ensure correct exit code.
-        try {
-            client.stop().catch(() => { });
-        }
-        catch { }
+        void client.stop().catch((error) => {
+            process.stderr.write(`[headless] Warning: failed to stop child process: ${error instanceof Error ? error.message : String(error)}\n`);
+        });
         if (timeoutTimer)
             clearTimeout(timeoutTimer);
         if (idleTimer)
@@ -707,7 +706,7 @@ async function runHeadlessOnce(options, restartCount) {
         process.stdin.resume();
     }
     // Detect child process crash (read-only exit event subscription — not stdin access)
-    const internalProcess = client.process;
+    const internalProcess = Reflect.get(client, 'process');
     if (internalProcess) {
         internalProcess.on('exit', (code) => {
             if (!completed) {

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)}`;

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/stream-adapter.js

@@ -6,7 +6,7 @@
  * 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";
@@ -482,6 +482,36 @@ 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.
+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"));
+}
+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 +543,8 @@ 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 effort = reasoning && modelSupportsAdaptiveThinking(modelId)
+        ? mapThinkingLevelToAnthropicEffort(reasoning, modelId)
         : undefined;
     return {
         pathToClaudeCodeExecutable: getClaudePath(),
@@ -529,7 +559,7 @@ 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"] : [],
         ...(effort ? { effort } : {}),
         ...sdkExtraOptions,
     };

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);