chainlesschain 0.162.34 → 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

@@ -0,0 +1,199 @@
+/**
+ * cc agents — user-defined subagents (Claude-Code parity, `.claude/agents/*.md`).
+ *
+ *   cc agents list [--json]                  list discovered agents
+ *   cc agents show <name>                    show metadata + system prompt
+ *   cc agents run <name> <task...> [opts]    run the task as this agent (headless)
+ *   cc agents new <name> [--description <d>]  scaffold an agent file
+ *
+ * Each `.claude/agents/<name>.md` (project, recursive) or `~/.claude/agents/`
+ * (personal) defines a subagent: the body is its system prompt; frontmatter
+ * declares `description`, `tools` (allow-list), `model`. `run` maps the agent
+ * onto a one-shot headless run (system prompt + tool scope + model), so a
+ * portable Claude-Code agent definition is runnable as-is. Distinct from `cc
+ * command` (prompt macros) and `cc skill` (AI-invoked capabilities).
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+
+export function registerAgentsCommand(program) {
+  const cmd = program
+    .command("agents")
+    .description("User-defined subagents (.claude/agents/*.md)");
+
+  // ── list ──────────────────────────────────────────────────────────────
+  cmd
+    .command("list")
+    .alias("ls")
+    .description("List discovered subagents (project + personal)")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const { discoverAgents } = await import("../lib/agents.js");
+        const all = discoverAgents(process.cwd());
+        if (options.json) {
+          console.log(JSON.stringify(all, null, 2));
+          return;
+        }
+        if (all.length === 0) {
+          logger.log(
+            chalk.gray(
+              "No subagents found. Create one with: cc agents new <name>",
+            ),
+          );
+          return;
+        }
+        logger.log(chalk.bold(`Subagents (${all.length})`));
+        for (const a of all) {
+          const tools = a.tools ? a.tools.join(",") : "(all)";
+          logger.log(
+            `  ${chalk.cyan(a.name.padEnd(22))} ${chalk.gray(`[${a.scope}]`)} ` +
+              `${a.description || ""}`,
+          );
+          logger.log(
+            chalk.gray(
+              `    tools: ${tools}${a.model ? ` · model: ${a.model}` : ""}`,
+            ),
+          );
+        }
+      } catch (err) {
+        logger.error(chalk.red(`agents list failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── show ──────────────────────────────────────────────────────────────
+  cmd
+    .command("show <name>")
+    .description("Show an agent's metadata + system prompt")
+    .option("--json", "Output as JSON")
+    .action(async (name, options) => {
+      try {
+        const { getAgent } = await import("../lib/agents.js");
+        const a = getAgent(name, process.cwd());
+        if (!a) {
+          logger.error(chalk.red(`no such agent: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        if (options.json) {
+          console.log(JSON.stringify(a, null, 2));
+          return;
+        }
+        logger.log(chalk.bold(a.name) + chalk.gray(`  [${a.scope}]`));
+        if (a.description) logger.log(chalk.gray(`  ${a.description}`));
+        logger.log(
+          chalk.gray(
+            `  tools: ${a.tools ? a.tools.join(",") : "(all)"}` +
+              `${a.model ? ` · model: ${a.model}` : ""}`,
+          ),
+        );
+        logger.log(chalk.gray(`  file: ${a.file}`));
+        logger.log("");
+        logger.log(a.systemPrompt || chalk.gray("(empty system prompt)"));
+      } catch (err) {
+        logger.error(chalk.red(`agents show failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── run ───────────────────────────────────────────────────────────────
+  cmd
+    .command("run <name> [task...]")
+    .description("Run a task headlessly as the named subagent")
+    .option("--output-format <fmt>", "text | json | stream-json", "text")
+    .option("--model <model>", "Override the agent's model")
+    .option("--permission-mode <mode>", "ApprovalGate tier (see cc agent)")
+    .option("--add-dir <dir...>", "Extra workspace roots")
+    .action(async (name, task, options) => {
+      try {
+        const { getAgent } = await import("../lib/agents.js");
+        const a = getAgent(name, process.cwd());
+        if (!a) {
+          logger.error(chalk.red(`no such agent: ${name}`));
+          process.exitCode = 1;
+          return;
+        }
+        const prompt = Array.isArray(task) ? task.join(" ").trim() : "";
+        if (!prompt) {
+          logger.error(
+            chalk.red(`agents run requires a task, e.g. cc agents run ${name} "review @src/x.js"`),
+          );
+          process.exitCode = 1;
+          return;
+        }
+        const { runAgentHeadless } = await import("../runtime/headless-runner.js");
+        const outcome = await runAgentHeadless({
+          prompt,
+          // The agent file's body becomes the system prompt (its persona).
+          systemPrompt: a.systemPrompt || undefined,
+          // Frontmatter `tools` scopes the run; null = inherit all.
+          allowedTools: a.tools || undefined,
+          model: options.model || a.model || undefined,
+          outputFormat: options.outputFormat,
+          permissionMode: options.permissionMode,
+          additionalDirectories: Array.isArray(options.addDir)
+            ? options.addDir
+            : [],
+        });
+        process.exit(outcome.exitCode);
+      } catch (err) {
+        logger.error(chalk.red(`agents run failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── new (scaffold) ────────────────────────────────────────────────────
+  cmd
+    .command("new <name>")
+    .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 {
+        const fs = await import("node:fs");
+        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")
+          : 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}`));
+          process.exitCode = 1;
+          return;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const toolsLine = options.tools
+          ? `tools: ${options.tools}\n`
+          : "# tools: read_file, search_files   # omit to inherit all tools\n";
+        const tpl = `---
+name: ${safe.replace(/\//g, ":")}
+description: ${options.description || name}
+${toolsLine}---
+
+You are a focused subagent. Describe its role, constraints, and output format
+here — this whole body becomes the system prompt for \`cc agents run ${safe.replace(/\//g, ":")}\`.
+`;
+        fs.writeFileSync(file, tpl, "utf-8");
+        logger.log(chalk.green(`✓ created ${file}`));
+        logger.log(
+          chalk.gray(
+            `  run it with: cc agents run ${safe.replace(/\//g, ":")} "<task>"`,
+          ),
+        );
+      } catch (err) {
+        logger.error(chalk.red(`agents new failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

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