chainlesschain 0.162.35 → 0.162.36

package/src/commands/agent.js

@@ -11,6 +11,8 @@ import fs from "node:fs";
 import { createAgentRuntimeFactory } from "../runtime/runtime-factory.js";
 import { resolvePromptText } from "../runtime/system-prompt.js";
 import { makeFallbackChatFn } from "../runtime/fallback-model.js";
+import { resolveImages, resolveVisionLlm } from "../lib/image-input.js";
+import { loadConfig } from "../lib/config-manager.js";
 
 /**
  * Resolve + validate `--add-dir` values into absolute, existing, de-duped
@@ -37,6 +39,23 @@ export function resolveAddDirs(rawDirs) {
   return out;
 }
 
+/**
+ * Parse `--thinking-budget <n>` into a positive integer (Anthropic legacy-model
+ * thinking `budget_tokens`), or undefined when unset/invalid. Pure; exported for
+ * tests. The companion `thinking` toggle comes from --think/--ultrathink; a
+ * budget without that toggle is a no-op (chatWithTools only reads it when
+ * thinking is on, and only for legacy models — adaptive models use effort).
+ *
+ * @param {string|number} [raw]
+ * @returns {number|undefined}
+ */
+export function resolveThinkingBudget(raw) {
+  if (raw === undefined || raw === null || raw === "") return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.floor(n);
+}
+
 /**
  * Read all of stdin as a UTF-8 string. Resolves "" immediately when stdin is a
  * TTY (nothing piped) so we never block an interactive invocation.
@@ -75,6 +94,27 @@ export function registerAgentCommand(program) {
     )
     .option("--base-url <url>", "API base URL")
     .option("--api-key <key>", "API key")
+    .option(
+      "--think [level]",
+      "Enable Anthropic extended thinking (level: think | hard | ultra; Anthropic models only)",
+    )
+    .option(
+      "--ultrathink",
+      "Maximum Anthropic extended thinking (= --think ultra)",
+    )
+    .option(
+      "--thinking-budget <n>",
+      "Thinking token budget for legacy Claude models (Sonnet 4.5 / Opus 4.0-4.5 / older); clamped below max_tokens. Adaptive-thinking models ignore it (they use --think's effort). Requires --think/--ultrathink.",
+    )
+    .option(
+      "--image <path>",
+      "Attach an image (png/jpg/jpeg/gif/webp) to the prompt for a vision-capable model (headless; repeatable)",
+      (val, prev) => (prev || []).concat([val]),
+    )
+    .option(
+      "--vision-model <id>",
+      "Model to use when an image is attached (default: config llm.visionModel or doubao-seed-1-6-vision-250815)",
+    )
     .option("--session <id>", "Resume a previous agent session")
     .option(
       "-c, --continue",
@@ -141,6 +181,10 @@ export function registerAgentCommand(program) {
       "--append-system-prompt <text>",
       "Append extra guidance to the system prompt (literal text or @file)",
     )
+    .option(
+      "--output-style <name>",
+      "Apply a named output-style persona (.claude/output-styles/<name>.md or a built-in: explanatory | learning)",
+    )
     .option(
       "--input-format <fmt>",
       "Headless input: text | stream-json (NDJSON user events on stdin, multi-turn)",
@@ -166,10 +210,23 @@ export function registerAgentCommand(program) {
       "--mcp-config <file>",
       "Load ad-hoc MCP servers from a JSON file for this run (headless); their tools become callable (mcp__<server>__<tool>)",
     )
+    .option(
+      "--no-mcp",
+      "Don't auto-connect MCP servers registered with `cc mcp add --auto-connect` (--mcp-config still loads)",
+    )
+    .option(
+      "--ide",
+      "Force-enable IDE bridge auto-connect: discover a running editor's MCP server via ~/.chainlesschain/ide/*.json (default: auto inside an IDE integrated terminal)",
+    )
+    .option("--no-ide", "Disable IDE bridge auto-connect")
     .option(
       "--permission-prompt-tool <tool>",
       "Defer tool approvals to an MCP tool (mcp__<server>__<tool>; requires --mcp-config) instead of headless fail-closed",
     )
+    .option(
+      "--settings <file>",
+      "Merge an extra .claude/settings.json-shaped file for this run: permission rules (allow/ask/deny) + native config overrides (model, env)",
+    )
     .action(async (task, options) => {
       // `--continue` / `--resume` resolve a session id so the user need not
       // copy it. Explicit `--session <id>` always wins. `--resume <id>` targets
@@ -235,9 +292,76 @@ export function registerAgentCommand(program) {
         process.exit(1);
       }
 
+      // The explicit `--model` the user typed, captured BEFORE the --settings
+      // block below may default options.model — so vision input can tell an
+      // explicit model from a settings default.
+      const explicitCliModel = options.model;
+
+      // --settings native config overrides: a .claude/settings.json-shaped file
+      // (and the discovered .claude settings) may set `model` + `env` for this
+      // run, without editing .chainlesschain/config.json. `--model` still wins
+      // over a settings model. Applied once here so every branch (headless +
+      // interactive, which all read options.model) picks it up; env vars are
+      // set on the process so the agent loop + child tools inherit them.
+      try {
+        const { loadSettingsConfig } =
+          await import("../lib/settings-loader.cjs");
+        const sc = loadSettingsConfig({
+          cwd: process.cwd(),
+          settingsFile: options.settings || null,
+        });
+        for (const [k, v] of Object.entries(sc.env || {})) {
+          process.env[k] = v;
+        }
+        if (!options.model && sc.model) options.model = sc.model;
+      } catch {
+        // settings overrides are best-effort — never block the run
+      }
+
       // Extra workspace roots (--add-dir) — shared by headless + interactive.
       const additionalDirectories = resolveAddDirs(options.addDir);
 
+      // --image <path> (repeatable): read into {mediaType, base64} for the
+      // headless prompt's vision input. A bad extension fails loudly here
+      // rather than sending a broken request.
+      let images = [];
+      if (Array.isArray(options.image) && options.image.length) {
+        try {
+          images = resolveImages(options.image);
+        } catch (err) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          process.exit(1);
+        }
+      }
+
+      // When an image is attached, default the run to the configured vision LLM
+      // (config.llm provider/baseUrl/apiKey + llm.visionModel | --vision-model |
+      // doubao default) so `cc agent --image foo.png` works without extra flags.
+      // Explicit --provider/--model/etc. always win; no image → unchanged.
+      const visionLlm = resolveVisionLlm({
+        hasImage: images.length > 0,
+        flags: {
+          provider: options.provider,
+          model: explicitCliModel,
+          baseUrl: options.baseUrl,
+          apiKey: options.apiKey,
+          visionModel: options.visionModel,
+        },
+        llm: loadConfig().llm || {},
+      });
+
+      // --think / --ultrathink → options.thinking for the agent loop (Anthropic
+      // extended thinking; ignored by other providers). --think with no value →
+      // true; --think <level> → that level; --ultrathink wins as "ultra".
+      const thinking = options.ultrathink
+        ? "ultra"
+        : options.think === true
+          ? true
+          : options.think || undefined;
+      // --thinking-budget <n>: legacy-model thinking budget (no-op without
+      // --think/--ultrathink and on adaptive models). undefined → engine default.
+      const thinkingBudget = resolveThinkingBudget(options.thinkingBudget);
+
       // --fallback-model: a chatFn that retries once on the backup model when
       // the primary errors out (overload / rate-limit / network). Passed into
       // the headless runners via options.chatFn (the agent loop's seam), so no
@@ -265,6 +389,8 @@ export function registerAgentCommand(program) {
         try {
           outcome = await runAgentHeadlessStream({
             model: options.model,
+            thinking,
+            thinkingBudget,
             provider: options.provider,
             baseUrl: options.baseUrl,
             apiKey: options.apiKey,
@@ -284,7 +410,12 @@ export function registerAgentCommand(program) {
             includePartialMessages: options.includePartialMessages === true,
             goal: options.goal,
             mcpConfig: options.mcpConfig || null,
+            useRegisteredMcp: options.mcp !== false,
+            ide: options.ide,
+            cwd,
             permissionPromptTool: options.permissionPromptTool || null,
+            settingsFile: options.settings || null,
+            outputStyle: options.outputStyle || null,
             chatFn: fallbackChatFn,
           });
         } catch (err) {
@@ -347,10 +478,13 @@ export function registerAgentCommand(program) {
         try {
           outcome = await runAgentHeadless({
             prompt,
-            model: options.model,
-            provider: options.provider,
-            baseUrl: options.baseUrl,
-            apiKey: options.apiKey,
+            images,
+            model: visionLlm.model || options.model,
+            thinking,
+            thinkingBudget,
+            provider: visionLlm.provider || options.provider,
+            baseUrl: visionLlm.baseUrl || options.baseUrl,
+            apiKey: visionLlm.apiKey || options.apiKey,
             sessionId: options.session,
             // A resolved --session/--continue/--resume id means "replay this
             // conversation and persist the new turns"; the runner loads prior
@@ -380,8 +514,16 @@ export function registerAgentCommand(program) {
             goalAssess: options.goalAssess === true,
             // --mcp-config: connect ad-hoc MCP servers + expose their tools
             mcpConfig: options.mcpConfig || null,
+            // --no-mcp: skip registered (cc mcp add) auto-connect servers
+            useRegisteredMcp: options.mcp !== false,
+            // --ide / --no-ide: auto-connect a running editor's MCP bridge
+            ide: options.ide,
+            cwd: process.cwd(),
             // --permission-prompt-tool: defer approvals to an MCP tool
             permissionPromptTool: options.permissionPromptTool || null,
+            // --settings: extra .claude/settings.json permission rules
+            settingsFile: options.settings || null,
+            outputStyle: options.outputStyle || null,
             // --fallback-model: retry once on a backup model on transient errors
             chatFn: fallbackChatFn,
           });
@@ -393,8 +535,18 @@ export function registerAgentCommand(program) {
         return;
       }
 
+      // Reached only for an interactive session, where --image has no turn to
+      // attach to — warn instead of silently dropping the attachment.
+      if (images.length) {
+        process.stderr.write(
+          "--image is only used in headless mode (-p / a task / piped stdin); ignoring for the interactive session.\n",
+        );
+      }
+
       const runtime = createAgentRuntimeFactory().createAgentRuntime({
         model: options.model,
+        thinking,
+        thinkingBudget,
         provider: options.provider,
         baseUrl: options.baseUrl,
         apiKey: options.apiKey,
@@ -418,9 +570,12 @@ export function registerAgentCommand(program) {
         }),
         // --fallback-model also applies interactively (wrapper built in the REPL)
         fallbackModel: options.fallbackModel || null,
-        // --mcp-config: connect ad-hoc MCP servers for the interactive session
-        // too (the REPL loads them via the same mcp-config engine as headless).
+        // --mcp-config + registered (cc mcp add) servers also apply to the
+        // interactive session (the REPL resolves both via the mcp-config engine).
         mcpConfig: options.mcpConfig || null,
+        useRegisteredMcp: options.mcp !== false,
+        // --ide / --no-ide: IDE bridge auto-connect for the interactive session
+        ide: options.ide,
       });
       await runtime.startAgentSession();
     });

package/src/commands/agents.js

@@ -147,9 +147,10 @@ export function registerAgentsCommand(program) {
   // ── new (scaffold) ────────────────────────────────────────────────────
   cmd
     .command("new <name>")
-    .description("Scaffold a new agent file under .claude/agents/")
+    .description("Scaffold a new agent file (project-native .chainlesschain/agents/)")
     .option("--description <d>", "Frontmatter description")
     .option("--tools <list>", "Comma-separated tool allow-list")
+    .option("--claude", "Create under .claude/agents (Claude-Code-portable)")
     .option("--personal", "Create under ~/.claude/agents instead of project")
     .action(async (name, options) => {
       try {
@@ -157,9 +158,14 @@ export function registerAgentsCommand(program) {
         const path = await import("node:path");
         const { homedir } = await import("node:os");
         const safe = String(name).replace(/^\//, "").replace(/:/g, "/");
+        // New project agents go to the native `.chainlesschain/agents/`; use
+        // --claude for the Claude-Code-portable `.claude/agents/`, or --personal
+        // for `~/.claude/agents/`. All three are read back by discoverAgents.
         const root = options.personal
           ? path.join(homedir(), ".claude", "agents")
-          : path.join(process.cwd(), ".claude", "agents");
+          : options.claude
+            ? path.join(process.cwd(), ".claude", "agents")
+            : path.join(process.cwd(), ".chainlesschain", "agents");
         const file = path.join(root, `${safe}.md`);
         if (fs.existsSync(file)) {
           logger.error(chalk.red(`already exists: ${file}`));

package/src/commands/command.js

@@ -145,8 +145,9 @@ export function registerCommandCommand(program) {
   // ── new (scaffold) ────────────────────────────────────────────────────
   cmd
     .command("new <name>")
-    .description("Scaffold a new command file under .claude/commands/")
+    .description("Scaffold a new command file (project-native .chainlesschain/commands/)")
     .option("--description <d>", "Frontmatter description")
+    .option("--claude", "Create under .claude/commands (Claude-Code-portable)")
     .option("--personal", "Create under ~/.claude/commands instead of project")
     .action(async (name, options) => {
       try {
@@ -154,9 +155,13 @@ export function registerCommandCommand(program) {
         const path = await import("node:path");
         const { homedir } = await import("node:os");
         const safe = String(name).replace(/^\//, "").replace(/:/g, "/");
+        // Project commands go to the native `.chainlesschain/commands/`; use
+        // --claude for the portable `.claude/commands/`, --personal for home.
         const root = options.personal
           ? path.join(homedir(), ".claude", "commands")
-          : path.join(process.cwd(), ".claude", "commands");
+          : options.claude
+            ? path.join(process.cwd(), ".claude", "commands")
+            : path.join(process.cwd(), ".chainlesschain", "commands");
         const file = path.join(root, `${safe}.md`);
         if (fs.existsSync(file)) {
           logger.error(chalk.red(`already exists: ${file}`));

package/src/commands/hook.js

@@ -29,9 +29,10 @@ export function registerHookCommand(program) {
   // hook list
   hook
     .command("list", { isDefault: true })
-    .description("List all registered hooks")
+    .description("List registered hooks (DB) + .claude/settings.json hooks")
     .option("--event <name>", "Filter by event name")
     .option("--enabled", "Show only enabled hooks")
+    .option("--settings <file>", "Also merge an explicit settings file")
     .option("--json", "Output as JSON")
     .action(async (options) => {
       try {
@@ -46,43 +47,76 @@ export function registerHookCommand(program) {
           enabledOnly: options.enabled,
         });
 
+        // .claude/settings.json `hooks` block (Claude-Code parity, decision-
+        // capable; distinct from the DB registry above which is observe-only).
+        const { loadHooks } = await import("../lib/settings-hooks.cjs");
+        const { hooks: settingsHooks, files: settingsFiles } = loadHooks({
+          cwd: process.cwd(),
+          settingsFile: options.settings,
+        });
+
         if (options.json) {
           console.log(
             JSON.stringify(
-              hooks.map((h) => ({
-                id: h.id,
-                event: h.event,
-                name: h.name,
-                type: h.type,
-                priority: h.priority,
-                enabled: h.enabled === 1,
-                matcher: h.matcher,
-                description: h.description,
-              })),
+              {
+                hooks: hooks.map((h) => ({
+                  id: h.id,
+                  event: h.event,
+                  name: h.name,
+                  type: h.type,
+                  priority: h.priority,
+                  enabled: h.enabled === 1,
+                  matcher: h.matcher,
+                  description: h.description,
+                })),
+                settingsHooks,
+                settingsFiles,
+              },
               null,
               2,
             ),
           );
-        } else if (hooks.length === 0) {
-          logger.info(
-            'No hooks registered. Add one with "chainlesschain hook add <event> <name>"',
-          );
         } else {
-          logger.log(chalk.bold(`Hooks (${hooks.length}):\n`));
-          for (const h of hooks) {
-            const status = h.enabled
-              ? chalk.green("enabled")
-              : chalk.gray("disabled");
-            const pLabel = Object.entries(HookPriority).find(
-              ([, v]) => v === h.priority,
+          if (hooks.length === 0) {
+            logger.info(
+              'No DB hooks. Add one with "chainlesschain hook add <event> <name>"',
             );
-            const priorityStr = pLabel ? pLabel[0] : String(h.priority);
-            logger.log(
-              `  ${chalk.cyan(h.name)} [${h.event}] priority=${priorityStr} type=${h.type} [${status}]`,
+          } else {
+            logger.log(chalk.bold(`DB hooks (${hooks.length}):\n`));
+            for (const h of hooks) {
+              const status = h.enabled
+                ? chalk.green("enabled")
+                : chalk.gray("disabled");
+              const pLabel = Object.entries(HookPriority).find(
+                ([, v]) => v === h.priority,
+              );
+              const priorityStr = pLabel ? pLabel[0] : String(h.priority);
+              logger.log(
+                `  ${chalk.cyan(h.name)} [${h.event}] priority=${priorityStr} type=${h.type} [${status}]`,
+              );
+              if (h.description) logger.log(`    ${chalk.gray(h.description)}`);
+              if (h.matcher)
+                logger.log(`    matcher: ${chalk.yellow(h.matcher)}`);
+            }
+          }
+          const events = Object.keys(settingsHooks);
+          if (events.length > 0) {
+            const n = events.reduce(
+              (a, e) => a + settingsHooks[e].length,
+              0,
             );
-            if (h.description) logger.log(`    ${chalk.gray(h.description)}`);
-            if (h.matcher)
-              logger.log(`    matcher: ${chalk.yellow(h.matcher)}`);
+            logger.log(chalk.bold(`\n.claude/settings.json hooks (${n}):`));
+            for (const ev of events) {
+              if (options.event && ev !== options.event) continue;
+              for (const g of settingsHooks[ev]) {
+                for (const h of g.hooks) {
+                  logger.log(
+                    `  ${chalk.cyan(ev)} matcher=${chalk.yellow(g.matcher || "*")}  ${chalk.gray(h.command)}`,
+                  );
+                }
+              }
+            }
+            logger.log(chalk.dim(`  sources: ${settingsFiles.join(", ")}`));
           }
         }
 
@@ -93,6 +127,80 @@ export function registerHookCommand(program) {
       }
     });
 
+  // hook test — dry-run .claude/settings.json hooks for an event + tool
+  hook
+    .command("test <event> <tool> [args...]")
+    .description(
+      'Show which settings.json hooks fire for an event+tool (e.g. hook test PreToolUse run_shell "git push"); --run executes them',
+    )
+    .option("--settings <file>", "Also merge an explicit settings file")
+    .option("--run", "Actually execute the matched hooks and show decisions")
+    .option("--json", "Output as JSON")
+    .action(async (event, tool, args, options) => {
+      try {
+        const { loadHooks, collectHooks } =
+          await import("../lib/settings-hooks.cjs");
+        const { hooks } = loadHooks({
+          cwd: process.cwd(),
+          settingsFile: options.settings,
+        });
+        const matched = collectHooks(hooks, event, tool);
+        const toolInput = args && args.length ? { command: args.join(" "), args } : {};
+        const payload = {
+          hook_event_name: event,
+          tool_name: tool,
+          tool_input: toolInput,
+          cwd: process.cwd(),
+          session_id: "test",
+        };
+
+        if (!options.run) {
+          if (options.json) {
+            console.log(JSON.stringify({ event, tool, matched, payload }, null, 2));
+          } else if (matched.length === 0) {
+            logger.log(
+              chalk.gray(`no settings.json hooks match ${event} / ${tool}`),
+            );
+          } else {
+            logger.log(
+              chalk.bold(`${matched.length} hook(s) would fire for ${event} / ${tool}:`),
+            );
+            for (const h of matched) logger.log(`  ${chalk.gray(h.command)}`);
+            logger.log(chalk.dim("  (use --run to execute and see decisions)"));
+          }
+          return;
+        }
+
+        const { runHooks } = await import("../lib/hook-runner.cjs");
+        const outcome = runHooks(matched, payload, {
+          cwd: process.cwd(),
+          event,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(outcome, null, 2));
+          return;
+        }
+        const color =
+          outcome.decision === "block"
+            ? chalk.red
+            : outcome.decision === "ask"
+              ? chalk.yellow
+              : chalk.green;
+        logger.log(`decision: ${color.bold(outcome.decision)}`);
+        if (outcome.reason) logger.log(`reason:   ${outcome.reason}`);
+        if (outcome.hook) logger.log(`from:     ${chalk.gray(outcome.hook)}`);
+        for (const r of outcome.results) {
+          logger.log(
+            `  ${chalk.gray(r.command)} → ${r.decision}` +
+              (r.exitCode != null ? ` (exit ${r.exitCode})` : ""),
+          );
+        }
+      } catch (err) {
+        logger.error(`hook test failed: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   // hook add
   hook
     .command("add")

package/src/commands/ide.js

@@ -0,0 +1,168 @@
+/**
+ * `cc ide` — inspect IDE bridge discovery (Phase 0).
+ *
+ * The agent auto-connects a running editor's MCP server when inside an IDE
+ * integrated terminal (or with `cc agent --ide`). These subcommands make that
+ * discovery visible and debuggable WITHOUT running an agent:
+ *
+ *   cc ide list             list live IDE lockfiles found
+ *   cc ide status           which server `cc agent` would connect to (+ its MCP config)
+ *   cc ide doctor           explain WHY discovery did / didn't pick a server
+ *
+ * Pure read-only over ~/.chainlesschain/ide/*.json — see
+ * docs/design/modules/98_IDE桥接对标方案.md.
+ */
+import chalk from "chalk";
+import {
+  readIdeLocks,
+  discoverIdeServer,
+  ideServerToMcpConfig,
+  isInIdeTerminal,
+  ideLockDir,
+  diagnoseIde,
+} from "../lib/ide-bridge.js";
+
+function emit(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+export function registerIdeCommand(program) {
+  const ide = program
+    .command("ide")
+    .description("Inspect IDE bridge discovery (editor MCP server auto-connect)");
+
+  ide
+    .command("list")
+    .description("List live IDE lockfiles (editor MCP servers advertised)")
+    .option("--json", "Machine-readable output")
+    .action((options) => {
+      const locks = readIdeLocks();
+      if (options.json) {
+        // Never surface the raw bearer token or internal _file path.
+        const safe = locks.map(({ token, _file, ...rest }) => ({
+          ...rest,
+          hasToken: !!token,
+        }));
+        emit({ lockDir: ideLockDir(), count: safe.length, locks: safe });
+        return;
+      }
+      if (!locks.length) {
+        console.log(
+          chalk.gray(`No live IDE lockfiles in ${ideLockDir()}`),
+        );
+        console.log(
+          chalk.gray(
+            "Start an IDE extension that advertises one, or run `cc ide doctor`.",
+          ),
+        );
+        return;
+      }
+      console.log(chalk.bold(`IDE servers (${locks.length}) in ${ideLockDir()}:`));
+      for (const l of locks) {
+        console.log(
+          `  ${chalk.cyan(l.ide)}  port ${l.port}  ${l.transport}  ` +
+            `${l.token ? chalk.green("token") : chalk.yellow("no-token")}`,
+        );
+        console.log(chalk.gray(`    url ${l.url}`));
+        if (l.workspaceFolders.length) {
+          console.log(chalk.gray(`    ws  ${l.workspaceFolders.join(", ")}`));
+        }
+      }
+    });
+
+  ide
+    .command("status")
+    .description("Show the IDE server `cc agent` would connect to right now")
+    .option("--ide", "Force selection even outside an IDE terminal")
+    .option("--json", "Machine-readable output")
+    .action((options) => {
+      const env = process.env;
+      const cwd = process.cwd();
+      const inIde = isInIdeTerminal(env);
+      const lock = discoverIdeServer({ cwd, env, force: options.ide === true });
+      const cfg = lock ? ideServerToMcpConfig(lock) : null;
+      // Redact the bearer token in the previewed config.
+      const safeCfg = cfg
+        ? {
+            ...cfg,
+            headers: cfg.headers?.Authorization
+              ? { ...cfg.headers, Authorization: "Bearer ***" }
+              : cfg.headers,
+          }
+        : null;
+      if (options.json) {
+        // Strip the raw token + internal _file from the chosen lock.
+        const safeChosen = lock
+          ? (({ token, _file, ...rest }) => ({ ...rest, hasToken: !!token }))(
+              lock,
+            )
+          : null;
+        emit({
+          inIdeTerminal: inIde,
+          chosen: safeChosen,
+          mcpConfig: safeCfg,
+        });
+        return;
+      }
+      console.log(
+        `In IDE terminal: ${inIde ? chalk.green("yes") : chalk.gray("no")}`,
+      );
+      if (!lock) {
+        console.log(
+          chalk.gray(
+            "No IDE server would be connected. Try `cc ide doctor` for why.",
+          ),
+        );
+        return;
+      }
+      console.log(
+        `Would connect: ${chalk.cyan(lock.ide)} on port ${lock.port} ` +
+          `(${lock.transport}) as MCP server ${chalk.bold("ide")}`,
+      );
+      console.log(chalk.gray("MCP config:"));
+      console.log(chalk.gray("  " + JSON.stringify(safeCfg)));
+    });
+
+  ide
+    .command("doctor")
+    .description("Explain why IDE discovery did / didn't pick a server")
+    .option("--ide", "Diagnose as if --ide (force) were passed")
+    .option("--json", "Machine-readable output")
+    .action((options) => {
+      const diag = diagnoseIde({
+        cwd: process.cwd(),
+        env: process.env,
+        force: options.ide === true,
+      });
+      if (options.json) {
+        emit(diag);
+        return;
+      }
+      console.log(chalk.bold("IDE bridge discovery"));
+      console.log(`  lock dir       : ${diag.lockDir}`);
+      console.log(
+        `  in IDE terminal: ${diag.inIdeTerminal ? chalk.green("yes") : chalk.gray("no")}`,
+      );
+      console.log(`  live locks     : ${diag.locks.length}`);
+      for (const l of diag.locks) {
+        const m =
+          l.matchScore >= 0
+            ? chalk.green(`workspace-match(${l.matchScore})`)
+            : chalk.yellow("no-workspace-match");
+        console.log(
+          `    - ${chalk.cyan(l.ide)} port ${l.port} ${l.transport} ` +
+            `${l.hasToken ? "token" : chalk.yellow("no-token")} ${m}`,
+        );
+      }
+      console.log(
+        `  result         : ${
+          diag.chosen
+            ? chalk.green(`connect ${diag.chosen.ide}:${diag.chosen.port}`)
+            : chalk.yellow("nothing to connect")
+        }`,
+      );
+      console.log(`  reason         : ${diag.reason}`);
+    });
+
+  return ide;
+}