chainlesschain 0.162.34 → 0.162.36

package/src/runtime/agent-core.js

@@ -16,10 +16,15 @@
 
 import fs from "fs";
 import path from "path";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
 import os from "os";
 import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
 import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
+import sharedPermissionRules from "../lib/permission-rules.cjs";
+import sharedSettingsHooks from "../lib/settings-hooks.cjs";
+import sharedHookRunner from "../lib/hook-runner.cjs";
+import sharedHookEvents from "../lib/settings-hook-events.cjs";
+import { mergeProviderOptions } from "../lib/provider-options.js";
 import { getPlanModeManager } from "../lib/plan-mode.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
 import { executeHooks, HookEvents } from "../lib/hook-manager.js";
@@ -47,6 +52,11 @@ import {
   mountSkillMcpServers,
   unmountSkillMcpServers,
 } from "../lib/skill-mcp.js";
+import {
+  hasImageContent,
+  toOllamaMessages,
+  imageUrlBlockToAnthropic,
+} from "../lib/image-input.js";
 
 /**
  * Names of MCP servers currently mounted by an in-flight run_skill call.
@@ -62,6 +72,182 @@ export function getActiveMcpServers() {
 
 const { isReadOnlyGitCommand, normalizeGitCommand } = sharedCodingAgentPolicy;
 const { evaluateShellCommandPolicy } = sharedShellPolicy;
+const { evaluatePermissionRules } = sharedPermissionRules;
+const { collectHooks, umbrellaFor } = sharedSettingsHooks;
+const { runHooks: runCommandHooks } = sharedHookRunner;
+const { runObserveHooks } = sharedHookEvents;
+
+// ─── Background shell tasks ────────────────────────────────────────────────
+//
+// run_shell is synchronous (execSync) and capped at a foreground timeout, which
+// is the right default for quick commands but blocks the whole agent loop on
+// long-running ones (builds, full test suites, `npm run dev`). When the model
+// passes run_in_background:true the command is spawned instead, returns a
+// task_id immediately, and streams its output into this registry. The agent
+// then polls completion + incremental output via the check_shell tool — the
+// run_in_background + BashOutput pattern from Claude Code.
+//
+// In-memory, process-lifetime: a task_id is only valid within the agent process
+// that spawned it, which is exactly the polling window (one REPL session / one
+// headless run). Buffers are bounded (MAX_BG_BUFFER per stream, tail-retained)
+// so a chatty long task can't exhaust memory.
+const MAX_BG_BUFFER = 1024 * 1024; // 1 MB retained tail per stream
+const _backgroundShellTasks = new Map();
+let _backgroundTaskSeq = 0;
+
+function _newBgStream() {
+  return { buf: "", total: 0, dropped: 0, cursor: 0 };
+}
+
+function _appendBgStream(stream, text) {
+  stream.buf += text;
+  stream.total += text.length;
+  if (stream.buf.length > MAX_BG_BUFFER) {
+    const over = stream.buf.length - MAX_BG_BUFFER;
+    stream.buf = stream.buf.slice(over);
+    stream.dropped += over;
+  }
+}
+
+// Read everything produced since the last read and advance the cursor. When the
+// cursor points into a region already dropped from the retained tail, the gap
+// is reported so the caller knows output was lost to the buffer cap.
+function _readBgStream(stream) {
+  const bufStart = stream.total - stream.buf.length;
+  let from = stream.cursor;
+  let droppedGap = 0;
+  if (from < bufStart) {
+    droppedGap = bufStart - from;
+    from = bufStart;
+  }
+  const text = stream.buf.slice(from - bufStart);
+  stream.cursor = stream.total;
+  return { text, droppedGap };
+}
+
+/**
+ * Snapshot of background shell tasks (for REPL/host status surfaces).
+ * @returns {Array<{id:string,status:string,command:string,exitCode:number|null}>}
+ */
+export function listBackgroundShellTasks() {
+  return Array.from(_backgroundShellTasks.values()).map((t) => ({
+    id: t.id,
+    status: t.status,
+    command: t.command,
+    exitCode: t.exitCode,
+    startedAt: t.startedAt,
+    endedAt: t.endedAt,
+  }));
+}
+
+// Kill a background task's whole process tree. Because tasks are spawned with
+// shell:true, the child is a shell whose real command runs as a grandchild — a
+// plain child.kill() on POSIX only signals the shell (and often orphans the
+// command), so a backgrounded `npm run dev` would survive. POSIX: the task is
+// spawned detached (its own process group), so signal the group via the
+// negative pid. Windows: `taskkill /T` walks and kills the whole tree.
+// Returns true if a running task was signalled.
+function _killTask(task) {
+  const child = task?.child;
+  if (!child || child.killed || task?.status !== "running") return false;
+  try {
+    if (process.platform === "win32") {
+      if (child.pid) {
+        spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+          windowsHide: true,
+        });
+      } else {
+        child.kill();
+      }
+    } else if (child.pid) {
+      // Negative pid → signal the whole process group (requires detached spawn).
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch (_err) {
+        child.kill("SIGTERM");
+      }
+    } else {
+      child.kill("SIGTERM");
+    }
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Kill every still-running background shell task. Callers (REPL exit, headless
+ * shutdown) invoke this so a backgrounded `npm run dev` doesn't outlive the
+ * agent. Best-effort: kill failures are swallowed.
+ * @returns {number} count of tasks signalled
+ */
+export function killAllBackgroundShellTasks() {
+  let killed = 0;
+  for (const task of _backgroundShellTasks.values()) {
+    if (_killTask(task)) {
+      killed += 1;
+    }
+  }
+  return killed;
+}
+
+// Foreground (synchronous) run_shell timeout. Configurable per-call via the
+// optional `timeout` arg; defaults to 60s and is hard-capped at 10 min so a
+// synchronous call can never wedge the loop indefinitely (use run_in_background
+// for genuinely long work).
+const DEFAULT_SHELL_TIMEOUT_MS = 60000;
+const MAX_SHELL_TIMEOUT_MS = 600000;
+function _resolveShellTimeout(raw) {
+  if (raw == null) return DEFAULT_SHELL_TIMEOUT_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SHELL_TIMEOUT_MS;
+  return Math.min(Math.floor(n), MAX_SHELL_TIMEOUT_MS);
+}
+
+/**
+ * Run settings.json `PreToolUse` hooks (decision-capable). DB hooks are handled
+ * separately + stay observe-only. A `block` decision stops the tool; an `ask`
+ * routes to the confirmer (headless without one falls closed). spawnSync is
+ * synchronous but each hook is timeout-capped.
+ * @returns {Promise<{blocked:boolean, reason?:string, hook?:string}>}
+ */
+async function runSettingsPreToolUseHooks(name, args, context, cwd) {
+  const matched = collectHooks(context.settingsHooks, "PreToolUse", name);
+  if (!matched || matched.length === 0) return { blocked: false };
+  const payload = {
+    hook_event_name: "PreToolUse",
+    tool_name: umbrellaFor(name),
+    raw_tool_name: name,
+    tool_input: args,
+    cwd,
+    session_id: context.sessionId || null,
+  };
+  const outcome = runCommandHooks(matched, payload, { cwd, event: "PreToolUse" });
+  if (outcome.decision === "block") {
+    return { blocked: true, reason: outcome.reason, hook: outcome.hook };
+  }
+  if (outcome.decision === "ask") {
+    const confirm = context.permissionConfirm || context.shellConfirm || null;
+    const ok =
+      typeof confirm === "function"
+        ? await confirm({
+            tool: name,
+            args,
+            rule: `hook:${outcome.hook}`,
+            reason:
+              outcome.reason || "a PreToolUse hook requests confirmation",
+          })
+        : false;
+    return ok
+      ? { blocked: false }
+      : {
+          blocked: true,
+          reason: outcome.reason || "PreToolUse hook ask denied",
+          hook: outcome.hook,
+        };
+  }
+  return { blocked: false };
+}
 
 // ─── Tool definitions ────────────────────────────────────────────────────
 
@@ -220,6 +406,7 @@ Key behaviors:
 - When asked to modify code, read the file first, then edit it
 - When asked to create something, use write_file to create it
 - When asked to run/test something, use run_shell to execute it
+- For long-running commands (builds, full test suites, dev servers) set run_shell { run_in_background: true } to get a task_id back immediately, then poll output and completion with check_shell { task_id }. Kill a backgrounded server with check_shell { task_id, kill: true } when finished
 - When asked about git status, diff, log, or other repository operations, use the git tool instead of run_shell
 - When asked about files or code, use read_file and search_files to find information
 - You have multi-layer skills (built-in, marketplace, global, project-level) — use list_skills to discover them and run_skill to execute them
@@ -451,6 +638,44 @@ export async function executeTool(name, args, context = {}) {
     };
   }
 
+  // ── Permission resolution (most-restrictive-wins; denies before prompts) ──
+  // Two policy sources gate a tool call: the user's .claude/settings.json rules
+  // (deny/ask/allow) and the desktop host's synced policy (hostManagedToolPolicy,
+  // usually null in CLI). Precedence, evaluated in this exact order:
+  //   1. settings `deny`  → block.
+  //   2. host  `deny`     → block. A settings `allow` NEVER relaxes a host deny
+  //                         (the desktop runtime authority outranks project
+  //                         config); symmetrically a settings `deny` (step 1)
+  //                         outranks a host `allow`. Net effect: any deny wins.
+  //   3. settings `ask`   → confirm (headless w/o confirmer falls closed).
+  //                         Reached only after BOTH denies clear, so a denied
+  //                         tool never wastes a confirmation round-trip.
+  //   4. settings `allow` → pre-authorize (ruleAllowed): short-circuit the
+  //                         plan-mode block + run_shell ApprovalGate. The hard
+  //                         shell-policy denylist still applies — allow never
+  //                         re-enables an unsafe `rm -rf /`.
+  // No matching rule + no host policy → every existing layer runs unchanged
+  // (default behaviour is byte-for-byte).
+  const settingsVerdict = context.permissionRules
+    ? evaluatePermissionRules({
+        tool: name,
+        args,
+        cwd,
+        rules: context.permissionRules,
+      })
+    : { decision: null, rule: null };
+
+  // 1. settings deny
+  if (settingsVerdict.decision === "deny") {
+    return {
+      error: `[Permission] Tool "${name}" denied by settings rule: ${settingsVerdict.rule}`,
+      policy: { decision: "deny", rule: settingsVerdict.rule, via: "settings" },
+    };
+  }
+
+  // Resolve the host policy (needed for the host-deny check + the plan-mode
+  // block below). Computed once here so a host deny can short-circuit before
+  // any settings `ask` prompt.
   const toolPolicies =
     context.hostManagedToolPolicy?.tools ||
     context.hostManagedToolPolicy?.toolPolicies ||
@@ -471,6 +696,8 @@ export async function executeTool(name, args, context = {}) {
     isExternalLocalTool &&
     planManager.isActive() &&
     localToolDescriptor?.isReadOnly === true;
+
+  // 2. host deny (a settings `allow` does not relax this)
   if (
     hostToolPolicy &&
     hostToolPolicy.allowed === false &&
@@ -487,9 +714,34 @@ export async function executeTool(name, args, context = {}) {
     };
   }
 
-  // Plan mode: check if tool is allowed
+  // 3 + 4. settings ask / allow (only reached when neither layer denied)
+  let ruleAllowed = false;
+  if (settingsVerdict.decision === "ask") {
+    const confirm = context.permissionConfirm || context.shellConfirm || null;
+    const ok =
+      typeof confirm === "function"
+        ? await confirm({
+            tool: name,
+            args,
+            rule: settingsVerdict.rule,
+            reason: `settings rule ${settingsVerdict.rule} requires confirmation`,
+          })
+        : false;
+    if (!ok) {
+      return {
+        error: `[Permission] Tool "${name}" requires confirmation (settings rule: ${settingsVerdict.rule}) — denied.`,
+        policy: { decision: "ask", rule: settingsVerdict.rule, via: "settings" },
+      };
+    }
+    ruleAllowed = true; // confirmed → treat like allow downstream
+  } else if (settingsVerdict.decision === "allow") {
+    ruleAllowed = true;
+  }
+
+  // Plan mode: check if tool is allowed (a settings `allow` rule pre-authorizes)
   if (
     planManager.isActive() &&
+    !ruleAllowed &&
     !(name === "git" && isReadOnlyGitCommand(args.command)) &&
     !planManager.isToolAllowed(name) &&
     !(isExternalHostTool && hostToolPolicy?.allowed === true) &&
@@ -514,7 +766,11 @@ export async function executeTool(name, args, context = {}) {
     };
   }
 
-  // PreToolUse hook
+  // PreToolUse hooks. DB hooks (cc hook add) stay observe-only — a failure
+  // never blocks. settings.json hooks (context.settingsHooks) are decision-
+  // capable: a `block` (exit 2 / {decision:block}) stops the tool here, an
+  // `ask` routes to the confirmer. Runs after permission resolution so a
+  // settings deny / host deny short-circuits before any hook process spawns.
   if (hookDb) {
     try {
       await executeHooks(hookDb, HookEvents.PreToolUse, {
@@ -528,6 +784,15 @@ export async function executeTool(name, args, context = {}) {
       // Hook failure should not block tool execution
     }
   }
+  if (context.settingsHooks) {
+    const pre = await runSettingsPreToolUseHooks(name, args, context, cwd);
+    if (pre.blocked) {
+      return {
+        error: `[Hook] PreToolUse blocked "${name}"${pre.reason ? ": " + pre.reason : ""}`,
+        policy: { decision: "block", via: "hook", hook: pre.hook || null },
+      };
+    }
+  }
 
   const startTime = Date.now();
   let toolResult;
@@ -546,6 +811,7 @@ export async function executeTool(name, args, context = {}) {
       approvalGate: context.approvalGate || null,
       shellConfirm: context.shellConfirm || null,
       additionalDirectories: context.additionalDirectories || null,
+      ruleAllowed,
     });
   } catch (err) {
     if (hookDb) {
@@ -592,6 +858,36 @@ export async function executeTool(name, args, context = {}) {
       // Non-critical
     }
   }
+  // settings.json PostToolUse hooks: can't un-run the tool, but a `block`
+  // reason is attached as `hookFeedback` to be surfaced back to the model.
+  if (context.settingsHooks && toolResult && typeof toolResult === "object") {
+    try {
+      const matched = collectHooks(context.settingsHooks, "PostToolUse", name);
+      if (matched && matched.length > 0) {
+        const outcome = runCommandHooks(
+          matched,
+          {
+            hook_event_name: "PostToolUse",
+            tool_name: umbrellaFor(name),
+            raw_tool_name: name,
+            tool_input: args,
+            tool_response:
+              typeof toolResult === "object"
+                ? JSON.stringify(toolResult).substring(0, 2000)
+                : String(toolResult).substring(0, 2000),
+            cwd,
+            session_id: context.sessionId || null,
+          },
+          { cwd, event: "PostToolUse" },
+        );
+        if (outcome.decision === "block" && outcome.reason) {
+          toolResult.hookFeedback = outcome.reason;
+        }
+      }
+    } catch (_err) {
+      // PostToolUse hooks are best-effort
+    }
+  }
 
   return toolResult;
 }
@@ -612,10 +908,12 @@ async function executeToolInner(
     externalToolDescriptors,
     externalToolExecutors,
     mcpClient,
+    llmOptions,
     shellPolicyOverrides,
     approvalGate,
     shellConfirm,
     additionalDirectories,
+    ruleAllowed = false,
   },
 ) {
   const localToolDescriptor =
@@ -760,7 +1058,10 @@ async function executeToolInner(
       const override = getRuntimeToolDescriptorByCommand(args.command);
       let shellPolicy;
       let approvalOutcome = null;
-      if (approvalGate) {
+      // A settings `allow` rule (ruleAllowed) pre-authorizes: skip the
+      // ApprovalGate tier confirm, but still run the hard shell-policy denylist
+      // below so an allow rule can never re-enable a blocked unsafe command.
+      if (approvalGate && !ruleAllowed) {
         const { evaluateShellCommandWithApproval } =
           await import("../lib/shell-approval.js");
         const gated = await evaluateShellCommandWithApproval({
@@ -802,11 +1103,86 @@ async function executeToolInner(
         }
       }
 
+      // Background: spawn, register, return a task_id immediately. The agent
+      // polls output + completion via check_shell. No timeout — that's the whole
+      // point of backgrounding (builds, test suites, dev servers).
+      if (args.run_in_background === true) {
+        const id = `bg_${++_backgroundTaskSeq}`;
+        const task = {
+          id,
+          command: args.command,
+          cwd: args.cwd || cwd,
+          status: "running",
+          exitCode: null,
+          signal: null,
+          error: null,
+          startedAt: new Date().toISOString(),
+          endedAt: null,
+          out: _newBgStream(),
+          err: _newBgStream(),
+          child: null,
+        };
+        try {
+          const child = spawn(args.command, {
+            cwd: task.cwd,
+            shell: true,
+            windowsHide: true,
+            // POSIX: own process group so check_shell{kill}/teardown can signal
+            // the whole tree (shell + its grandchild command). No-op on Windows
+            // where the tree is killed via taskkill /T instead.
+            detached: process.platform !== "win32",
+          });
+          task.child = child;
+          if (child.stdout) {
+            child.stdout.setEncoding("utf8");
+            child.stdout.on("data", (d) => _appendBgStream(task.out, d));
+          }
+          if (child.stderr) {
+            child.stderr.setEncoding("utf8");
+            child.stderr.on("data", (d) => _appendBgStream(task.err, d));
+          }
+          child.on("error", (err) => {
+            task.status = "error";
+            task.error = String(err?.message || err).substring(0, 2000);
+            task.endedAt = new Date().toISOString();
+          });
+          // 'close' (not 'exit') so stdout/stderr are fully drained before the
+          // status leaves "running" — otherwise a poll can observe completion
+          // with the final output chunk not yet buffered.
+          child.on("close", (code, signal) => {
+            // 'error' may have already set a terminal state; don't overwrite it.
+            if (task.status === "running") {
+              task.status = code === 0 ? "exited" : "failed";
+            }
+            task.exitCode = code;
+            task.signal = signal;
+            task.endedAt = new Date().toISOString();
+          });
+        } catch (err) {
+          task.status = "error";
+          task.error = String(err?.message || err).substring(0, 2000);
+          task.endedAt = new Date().toISOString();
+        }
+        _backgroundShellTasks.set(id, task);
+        return attachDescriptor(
+          {
+            background: true,
+            task_id: id,
+            status: task.status,
+            command: task.command,
+            hint: "Poll output and completion with the check_shell tool using this task_id. Kill long-lived servers with check_shell { task_id, kill: true } when done.",
+            shellCommandPolicy: shellPolicy,
+            approval: approvalOutcome,
+          },
+          override || runtimeDescriptor,
+        );
+      }
+
       try {
         const output = execSync(args.command, {
           cwd: args.cwd || cwd,
           encoding: "utf8",
-          timeout: 60000,
+          timeout: _resolveShellTimeout(args.timeout),
           maxBuffer: 1024 * 1024,
         });
         return attachDescriptor(
@@ -831,6 +1207,51 @@ async function executeToolInner(
       }
     }
 
+    case "check_shell": {
+      const taskId = args.task_id;
+      // No task_id → list known background tasks (lightweight status surface).
+      if (!taskId) {
+        return attachDescriptor({
+          tasks: listBackgroundShellTasks(),
+        });
+      }
+      const task = _backgroundShellTasks.get(taskId);
+      if (!task) {
+        return attachDescriptor({
+          error: `No background shell task with id "${taskId}".`,
+          tasks: listBackgroundShellTasks(),
+        });
+      }
+      let killed = false;
+      if (args.kill === true) {
+        // _killTask signals the whole process tree (see its doc); the close
+        // handler flips status. Best-effort.
+        killed = _killTask(task);
+      }
+      const out = _readBgStream(task.out);
+      const err = _readBgStream(task.err);
+      return attachDescriptor({
+        task_id: task.id,
+        status: task.status,
+        running: task.status === "running",
+        command: task.command,
+        exitCode: task.exitCode,
+        signal: task.signal,
+        ...(task.error ? { error: task.error } : {}),
+        stdout: out.text.substring(0, 30000),
+        stderr: err.text.substring(0, 30000),
+        ...(out.droppedGap
+          ? { stdout_dropped_bytes: out.droppedGap }
+          : {}),
+        ...(err.droppedGap
+          ? { stderr_dropped_bytes: err.droppedGap }
+          : {}),
+        ...(killed ? { killed: true } : {}),
+        startedAt: task.startedAt,
+        endedAt: task.endedAt,
+      });
+    }
+
     case "git": {
       const normalizedCommand = normalizeGitCommand(args.command);
       if (!normalizedCommand) {
@@ -874,6 +1295,7 @@ async function executeToolInner(
           parentMessages,
           interaction,
           sessionId,
+          llmOptions,
         }),
       );
     }
@@ -905,6 +1327,33 @@ async function executeToolInner(
       }
     }
 
+    case "web_search": {
+      try {
+        const { webSearch } = await import("../lib/web-search.js");
+        let webSearchConfig = {};
+        try {
+          const { loadProjectConfig: _lpc, findProjectRoot: _fpr } =
+            await import("../lib/project-detector.js");
+          const projectRoot = _fpr(cwd);
+          if (projectRoot) {
+            const cfg = _lpc(projectRoot);
+            webSearchConfig = cfg?.webSearch || {};
+          }
+        } catch (_err) {
+          // Config optional — use defaults (auto provider / keyless fallback)
+        }
+        const result = await webSearch(args.query, {
+          provider: args.provider,
+          maxResults: args.maxResults,
+          timeout: args.timeout,
+          config: webSearchConfig,
+        });
+        return attachDescriptor(result);
+      } catch (err) {
+        return attachDescriptor({ error: `web_search failed: ${err.message}` });
+      }
+    }
+
     case "todo_write": {
       try {
         const { writeTodos } = await import("../lib/todo-manager.js");
@@ -1470,7 +1919,7 @@ async function _executeRunCode(args, cwd) {
  * @returns {Promise<object>}
  */
 async function _executeSpawnSubAgent(args, ctx) {
-  const {
+  let {
     role,
     task,
     context: inheritedContext,
@@ -1478,8 +1927,37 @@ async function _executeSpawnSubAgent(args, ctx) {
     profile: profileName,
   } = args;
 
-  if (!role || !task) {
-    return { error: "Both 'role' and 'task' are required for spawn_sub_agent" };
+  // Named subagent delegation (cc agents / .chainlesschain|.claude/agents/*.md):
+  // load the agent's persona (its body = system prompt) + tool allow-list.
+  // Explicit role/tools still win over the agent file's values.
+  let mdProfile = null;
+  let mdModel = null;
+  if (args.agent) {
+    try {
+      const { getAgent } = await import("../lib/agents.js");
+      const md = getAgent(args.agent, ctx.cwd);
+      if (!md) {
+        return {
+          error: `Unknown subagent "${args.agent}". List them with: cc agents list`,
+        };
+      }
+      role = role || md.name;
+      if (!explicitTools && Array.isArray(md.tools)) explicitTools = md.tools;
+      if (md.model) mdModel = md.model;
+      if (md.systemPrompt) {
+        mdProfile = { name: md.name, systemPrompt: md.systemPrompt };
+      }
+    } catch (err) {
+      return {
+        error: `Failed to load subagent "${args.agent}": ${err.message}`,
+      };
+    }
+  }
+
+  if (!task || (!role && !args.agent)) {
+    return {
+      error: "spawn_sub_agent requires 'task' and either 'role' or 'agent'",
+    };
   }
 
   // Phase 3: resolve declarative profile if requested. Explicit tools/context
@@ -1500,6 +1978,10 @@ async function _executeSpawnSubAgent(args, ctx) {
     }
   }
 
+  // A named subagent's body becomes the sub-agent system prompt (via the
+  // profile.systemPrompt seam) when no declarative profile was requested.
+  if (!profile && mdProfile) profile = mdProfile;
+
   const allowedTools = Array.isArray(explicitTools)
     ? explicitTools
     : profile?.toolAllowlist || null;
@@ -1521,6 +2003,14 @@ async function _executeSpawnSubAgent(args, ctx) {
   const parentSessionId = ctx.sessionId || null;
   const interaction = ctx.interaction || null;
 
+  // Inherit the parent's provider / base-url / key; a named subagent's `model:`
+  // frontmatter (mdModel) overrides just the model, else keep the parent's.
+  const parentLlm = ctx.llmOptions || {};
+  const subLlmOptions = {
+    ...parentLlm,
+    model: mdModel || parentLlm.model || undefined,
+  };
+
   const subCtx = SubAgentContext.create({
     role,
     task,
@@ -1529,6 +2019,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     allowedTools: allowedTools || null,
     cwd: ctx.cwd,
     profile: profile || null,
+    llmOptions: subLlmOptions,
   });
 
   const emit = (type, payload) => {
@@ -1664,6 +2155,12 @@ export async function chatWithTools(rawMessages, options) {
 
   if (provider === "ollama") {
     const apiUrl = `${baseUrl}/api/chat`;
+    // Multimodal (`cc agent --image`): ollama wants `{content, images:[base64]}`
+    // not OpenAI-style `image_url` blocks. Convert only when an image part is
+    // present so text-only runs keep the identical request shape.
+    const ollamaMessages = hasImageContent(messages)
+      ? toOllamaMessages(messages)
+      : messages;
     // Real-time token deltas (Claude-Code `--include-partial-messages`): when
     // the caller supplies an onToken hook, stream the response and forward each
     // content chunk as it arrives. Tool calls + usage are accumulated and the
@@ -1672,7 +2169,7 @@ export async function chatWithTools(rawMessages, options) {
     if (typeof options.onToken === "function") {
       return await _chatOllamaStreaming(
         apiUrl,
-        { model, messages, tools },
+        { model, messages: ollamaMessages, tools },
         options.onToken,
         signal,
       );
@@ -1683,7 +2180,7 @@ export async function chatWithTools(rawMessages, options) {
       signal,
       body: JSON.stringify({
         model,
-        messages,
+        messages: ollamaMessages,
         tools,
         stream: false,
       }),
@@ -1714,12 +2211,35 @@ export async function chatWithTools(rawMessages, options) {
       input_schema: t.function.parameters,
     }));
 
+    // Model-aware max_tokens (Opus → 16384, Haiku → 4096, else 8192) via
+    // provider-options. We read ONLY maxTokens: the module's `temperature`
+    // default is never forwarded (400s on Opus 4.7/4.8).
+    const effModel = model || "claude-sonnet-4-20250514";
+    const { maxTokens: anthropicMaxTokens } = mergeProviderOptions(
+      "anthropic",
+      effModel,
+    );
     const body = {
-      model: model || "claude-sonnet-4-20250514",
-      max_tokens: 8192,
-      messages: otherMsgs,
+      model: effModel,
+      max_tokens: anthropicMaxTokens || 8192,
+      // Convert cc's internal OpenAI-shaped history (role:"tool" results,
+      // assistant tool_calls[]) into Anthropic content blocks. Without this,
+      // multi-turn tool use 400s on turn 2 (Anthropic rejects role:"tool" and
+      // assistant `tool_calls`). Also replays preserved thinking blocks.
+      messages: _toAnthropicMessages(otherMsgs),
       tools: anthropicTools,
     };
+    // Extended thinking — OPT-IN via options.thinking; off by default so the
+    // request is byte-identical to before. Model-aware (adaptive+effort on Opus
+    // 4.6+/Sonnet 4.6, legacy enabled+budget else; nothing on Haiku). temperature
+    // is never sent. RUNTIME-UNVERIFIED: no Anthropic key here to E2E the
+    // thinking-block signature replay (see cli_claude_code_parity_landed memory).
+    const thinkingParams = _anthropicThinkingParams(
+      effModel,
+      options,
+      body.max_tokens,
+    );
+    if (thinkingParams) Object.assign(body, thinkingParams);
     if (systemMsgs.length > 0) {
       body.system = systemMsgs.map((m) => m.content).join("\n");
     }
@@ -1999,7 +2519,11 @@ function _anthropicReduceLine(state, raw, onToken) {
     state.blocks[obj.index] =
       cb.type === "tool_use"
         ? { type: "tool_use", id: cb.id, name: cb.name, json: "" }
-        : { type: "text" };
+        : cb.type === "thinking"
+          ? { type: "thinking", thinking: "", signature: "" }
+          : cb.type === "redacted_thinking"
+            ? { type: "redacted_thinking", data: cb.data || "" }
+            : { type: "text" };
   } else if (obj.type === "content_block_delta") {
     const d = obj.delta || {};
     if (d.type === "text_delta" && d.text) {
@@ -2013,6 +2537,12 @@ function _anthropicReduceLine(state, raw, onToken) {
       }
     } else if (d.type === "input_json_delta" && state.blocks[obj.index]) {
       state.blocks[obj.index].json += d.partial_json || "";
+    } else if (d.type === "thinking_delta" && state.blocks[obj.index]) {
+      state.blocks[obj.index].thinking =
+        (state.blocks[obj.index].thinking || "") + (d.thinking || "");
+    } else if (d.type === "signature_delta" && state.blocks[obj.index]) {
+      state.blocks[obj.index].signature =
+        (state.blocks[obj.index].signature || "") + (d.signature || "");
     }
   } else if (obj.type === "message_delta") {
     state.outputTokens = Number(obj.usage?.output_tokens) || state.outputTokens;
@@ -2022,7 +2552,10 @@ function _anthropicReduceLine(state, raw, onToken) {
 
 function _anthropicFinalize(state) {
   const toolCalls = [];
-  for (const k of Object.keys(state.blocks)) {
+  const thinkingBlocks = [];
+  for (const k of Object.keys(state.blocks).sort(
+    (a, b) => Number(a) - Number(b),
+  )) {
     const b = state.blocks[k];
     if (b.type === "tool_use") {
       let input = {};
@@ -2036,10 +2569,21 @@ function _anthropicFinalize(state) {
         type: "function",
         function: { name: b.name, arguments: JSON.stringify(input) },
       });
+    } else if (b.type === "thinking") {
+      thinkingBlocks.push({
+        type: "thinking",
+        thinking: b.thinking || "",
+        signature: b.signature || "",
+      });
+    } else if (b.type === "redacted_thinking") {
+      thinkingBlocks.push({ type: "redacted_thinking", data: b.data || "" });
     }
   }
   const message = { role: "assistant", content: state.text };
   if (toolCalls.length) message.tool_calls = toolCalls;
+  // Preserve thinking blocks verbatim (incl. signature) for replay on the next
+  // tool turn — required by the API when extended thinking is on.
+  if (thinkingBlocks.length) message._thinkingBlocks = thinkingBlocks;
   const out = { message };
   if (state.inputTokens || state.outputTokens) {
     out.usage = {
@@ -2187,10 +2731,154 @@ async function _chatOpenAIStreaming(apiUrl, body, apiKey, onToken, signal, provi
   return _openaiFinalize(state);
 }
 
-function _normalizeAnthropicResponse(data) {
+/**
+ * Convert cc's internal OpenAI-shaped messages into Anthropic content-block
+ * messages. Internal shape: {role:"user"|"assistant"|"tool", content,
+ * tool_calls?, _thinkingBlocks?}. Anthropic shape: {role:"user"|"assistant",
+ * content: string | block[]} — assistant tool calls become {type:"tool_use"}
+ * blocks; tool results become {type:"tool_result"} blocks inside a USER turn,
+ * with consecutive results merged. Preserved thinking blocks (with signature)
+ * are replayed FIRST in the assistant turn (the API requires them ahead of
+ * tool_use when continuing a thinking+tool turn). Exported for tests.
+ */
+export function _toAnthropicMessages(msgs) {
+  const out = [];
+  let pendingResults = [];
+  const flush = () => {
+    if (pendingResults.length) {
+      out.push({ role: "user", content: pendingResults });
+      pendingResults = [];
+    }
+  };
+  for (const m of msgs || []) {
+    if (!m) continue;
+    if (m.role === "tool") {
+      pendingResults.push({
+        type: "tool_result",
+        tool_use_id: m.tool_call_id,
+        content:
+          typeof m.content === "string"
+            ? m.content
+            : JSON.stringify(m.content ?? ""),
+      });
+      continue;
+    }
+    flush();
+    if (m.role === "assistant") {
+      const blocks = [];
+      if (Array.isArray(m._thinkingBlocks)) {
+        for (const tb of m._thinkingBlocks) blocks.push(tb);
+      }
+      if (typeof m.content === "string" && m.content.trim()) {
+        blocks.push({ type: "text", text: m.content });
+      } else if (Array.isArray(m.content)) {
+        for (const b of m.content) blocks.push(b);
+      }
+      if (Array.isArray(m.tool_calls)) {
+        for (const tc of m.tool_calls) {
+          const raw = tc.function?.arguments;
+          let input = {};
+          try {
+            input =
+              typeof raw === "string" ? JSON.parse(raw || "{}") : raw || {};
+          } catch {
+            input = {};
+          }
+          blocks.push({
+            type: "tool_use",
+            id: tc.id,
+            name: tc.function?.name,
+            input,
+          });
+        }
+      }
+      out.push({
+        role: "assistant",
+        content: blocks.length ? blocks : m.content || "",
+      });
+    } else {
+      // user turn: pass content through (string or already-block array). When
+      // it carries OpenAI-style `image_url` parts (`cc agent --image`), convert
+      // them to Anthropic `image` blocks; text parts and any other blocks pass
+      // through unchanged.
+      let content = m.content;
+      if (Array.isArray(content)) {
+        content = content.map((b) =>
+          b?.type === "image_url" ? imageUrlBlockToAnthropic(b) || b : b,
+        );
+      }
+      out.push({ role: "user", content });
+    }
+  }
+  flush();
+  return out;
+}
+
+/** Map a Claude-Code-style intensity to an Anthropic effort level. */
+function _intensityToEffort(want) {
+  switch (String(want)) {
+    case "ultra":
+    case "ultrathink":
+      return "xhigh";
+    case "hard":
+    case "think-hard":
+    case "harder":
+      return "high";
+    case "think":
+      return "medium";
+    default:
+      return "high"; // bare `true` → a sensible default for intelligence work
+  }
+}
+
+/**
+ * Decide the Anthropic `thinking` request params for a model. Returns null
+ * (off) unless the caller opts in via options.thinking (true | "think" |
+ * "hard" | "ultra"). Model-aware per the Claude API:
+ *   - Opus 4.6/4.7/4.8, Sonnet 4.6 → adaptive thinking + output_config.effort
+ *   - Sonnet 4.5 / Opus 4.0-4.5 / older → legacy enabled+budget (< max_tokens)
+ *   - anything else (e.g. Haiku) → null (no thinking)
+ * temperature is never added (it 400s on Opus 4.7/4.8). Note: `xhigh`/`max`
+ * effort are Opus-tier — on Sonnet they may error; left to the caller's intent.
+ * RUNTIME-UNVERIFIED — no Anthropic key to validate the wire shape live.
+ * Exported for tests.
+ */
+export function _anthropicThinkingParams(model, options = {}, maxTokens = 8192) {
+  const want = options?.thinking;
+  if (!want) return null; // off by default → request unchanged
+  const m = String(model || "").toLowerCase();
+  const adaptive = /opus-4-(6|7|8)/.test(m) || /sonnet-4-6/.test(m);
+  const legacy =
+    /sonnet-4-5/.test(m) ||
+    /opus-4-(0|1|5)/.test(m) ||
+    /sonnet-4-0/.test(m) ||
+    /sonnet-3/.test(m) ||
+    /opus-3/.test(m);
+  if (adaptive) {
+    const params = { thinking: { type: "adaptive" } };
+    const effort =
+      typeof options.thinkingEffort === "string"
+        ? options.thinkingEffort
+        : _intensityToEffort(want);
+    if (effort) params.output_config = { effort };
+    return params;
+  }
+  if (legacy) {
+    let budget = Number(options.thinkingBudget) || 8000;
+    // budget_tokens must be strictly < max_tokens (min 1024) on legacy models
+    if (budget >= maxTokens) budget = Math.max(1024, Math.floor(maxTokens / 2));
+    return { thinking: { type: "enabled", budget_tokens: budget } };
+  }
+  return null; // unknown / Haiku → no thinking
+}
+
+export function _normalizeAnthropicResponse(data) {
   const content = data.content || [];
   const textBlocks = content.filter((b) => b.type === "text");
   const toolBlocks = content.filter((b) => b.type === "tool_use");
+  const thinkingBlocks = content.filter(
+    (b) => b.type === "thinking" || b.type === "redacted_thinking",
+  );
 
   const message = {
     role: "assistant",
@@ -2208,6 +2896,13 @@ function _normalizeAnthropicResponse(data) {
     }));
   }
 
+  // Preserve thinking blocks VERBATIM (incl. signature) so the agent loop can
+  // replay them on the next tool turn — required when extended thinking is on,
+  // harmless (absent) otherwise. _toAnthropicMessages re-emits them first.
+  if (thinkingBlocks.length > 0) {
+    message._thinkingBlocks = thinkingBlocks;
+  }
+
   return { message };
 }
 
@@ -2322,12 +3017,23 @@ export async function* agentLoop(messages, options) {
     externalToolDescriptors: options.externalToolDescriptors || null,
     externalToolExecutors: options.externalToolExecutors || null,
     mcpClient: options.mcpClient || null,
+    // Parent LLM config — forwarded to spawn_sub_agent so a delegated subagent
+    // inherits the provider/key and can override just the model (cc agents `model:`).
+    llmOptions: {
+      provider: options.provider || null,
+      model: options.model || null,
+      baseUrl: options.baseUrl || null,
+      apiKey: options.apiKey || null,
+    },
     parentMessages: messages, // pass parent messages for sub-agent auto-condensation
     interaction: options.interaction || null,
     shellPolicyOverrides: options.shellPolicyOverrides || null,
     approvalGate: options.approvalGate || null,
     shellConfirm: options.shellConfirm || null,
     additionalDirectories: options.additionalDirectories || null,
+    permissionRules: options.permissionRules || null,
+    permissionConfirm: options.permissionConfirm || null,
+    settingsHooks: options.settingsHooks || null,
     autoCheckpoint: options.autoCheckpoint || false,
     checkpointSession:
       options.checkpointSession || options.sessionId || "agent",
@@ -2401,6 +3107,10 @@ export async function* agentLoop(messages, options) {
     sessionId: options.sessionId || null,
   };
 
+  // True once a Stop hook has forced a continuation — passed to the next Stop
+  // hook as `stop_hook_active` so a well-behaved hook won't block forever.
+  let stopHookActive = false;
+
   while (budget.hasRemaining()) {
     budget.consume();
     throwIfAborted(signal);
@@ -2445,10 +3155,37 @@ export async function* agentLoop(messages, options) {
       try {
         const compactor = await _getAutoCompactor(options);
         if (compactor && compactor.shouldAutoCompact(messages)) {
-          const { messages: compacted, stats } = await compactor.compress(
-            messages,
-            { preserveToolPairs: true },
-          );
+          // settings.json PreCompact hooks: a `block` decision SKIPS this
+          // compaction round (e.g. the hook archived / owns the history). Fires
+          // right before the history would be compacted.
+          let preCompactBlocked = false;
+          let preCompactReason = null;
+          if (options.settingsHooks) {
+            try {
+              const pc = runObserveHooks(
+                options.settingsHooks,
+                "PreCompact",
+                {
+                  trigger: "auto",
+                  message_count: messages.length,
+                  session_id: options.sessionId || null,
+                },
+                { cwd: options.cwd || process.cwd() },
+              );
+              if (pc && pc.decision === "block") {
+                preCompactBlocked = true;
+                preCompactReason = pc.reason || null;
+              }
+            } catch (_err) {
+              // observe-only
+            }
+          }
+          if (preCompactBlocked) {
+            yield { type: "compaction-skipped", runId, reason: preCompactReason };
+          }
+          const { messages: compacted, stats } = preCompactBlocked
+            ? { messages, stats: { saved: 0 } }
+            : await compactor.compress(messages, { preserveToolPairs: true });
           if (stats.saved > 0 && compacted.length < messages.length) {
             messages.splice(0, messages.length, ...compacted);
             // Persist the compaction so a later --resume rebuilds from the
@@ -2538,6 +3275,43 @@ export async function* agentLoop(messages, options) {
 
     if (!toolCalls || toolCalls.length === 0) {
       yield { type: "response-complete", content: msg.content || "" };
+      // settings.json Stop hooks: a `block` decision FORCES the agent to keep
+      // going instead of stopping — the reason is injected as a new instruction.
+      // `stop_hook_active` lets the hook avoid an infinite loop; the iteration
+      // budget is the hard backstop.
+      if (options.settingsHooks) {
+        let stopOutcome = null;
+        try {
+          stopOutcome = runObserveHooks(
+            options.settingsHooks,
+            "Stop",
+            {
+              stop_hook_active: stopHookActive,
+              final_response: String(msg.content || "").substring(0, 2000),
+              session_id: options.sessionId || null,
+            },
+            { cwd: options.cwd || process.cwd() },
+          );
+        } catch (_err) {
+          stopOutcome = null; // never affect the run outcome
+        }
+        if (stopOutcome && stopOutcome.decision === "block") {
+          stopHookActive = true;
+          messages.push({ role: "assistant", content: msg.content || "" });
+          messages.push({
+            role: "user",
+            content:
+              stopOutcome.reason ||
+              "A Stop hook requested that you keep working.",
+          });
+          yield {
+            type: "stop-hook-continue",
+            runId,
+            reason: stopOutcome.reason || null,
+          };
+          continue;
+        }
+      }
       yield { type: "run-ended", runId, reason: "complete" };
       return;
     }
@@ -2626,7 +3400,11 @@ export function formatToolArgs(name, args) {
     case "edit_file_hashed":
       return `${args.path} @${args.anchor_hash}`;
     case "run_shell":
-      return args.command;
+      return args.run_in_background ? `${args.command} (background)` : args.command;
+    case "check_shell":
+      return args.task_id
+        ? `${args.task_id}${args.kill ? " (kill)" : ""}`
+        : "list";
     case "git":
       return args.command;
     case "search_files":