chainlesschain 0.162.35 → 0.162.36

package/src/runtime/coding-agent-contract-shared.cjs

@@ -145,7 +145,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "shell",
     tier: "mvp",
     description:
-      "Execute a shell command and return the output. Use for running tests, linting, builds, and other non-git workspace commands.",
+      "Execute a shell command and return the output. Use for running tests, linting, builds, and other non-git workspace commands. For long-running commands (builds, full test suites, dev servers) pass run_in_background:true to return a task_id immediately and poll with check_shell instead of blocking.",
     inputSchema: {
       type: "object",
       properties: {
@@ -154,6 +154,16 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           type: "string",
           description: "Working directory (optional)",
         },
+        run_in_background: {
+          type: "boolean",
+          description:
+            "Run the command in the background and return a task_id immediately instead of blocking. Use for long-running commands (builds, test suites, dev servers). Poll output and completion with the check_shell tool.",
+        },
+        timeout: {
+          type: "number",
+          description:
+            "Foreground (synchronous) timeout in milliseconds. Default 60000, max 600000. Ignored when run_in_background is true.",
+        },
       },
       required: ["command"],
     },
@@ -168,6 +178,40 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
       tags: ["tool:run_shell", "contract:coding-agent", "tier:mvp"],
     },
   },
+  {
+    name: "check_shell",
+    title: "Check Shell",
+    kind: "shell",
+    tier: "mvp",
+    description:
+      "Poll a background run_shell task: returns its status, exit code, and any new stdout/stderr since the last check. Omit task_id to list all background tasks. Pass kill:true to terminate a still-running task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: {
+          type: "string",
+          description:
+            "The task_id returned by run_shell { run_in_background: true }. Omit to list all known background tasks.",
+        },
+        kill: {
+          type: "boolean",
+          description:
+            "Terminate the task if it is still running (e.g. a dev server you no longer need).",
+        },
+      },
+      required: [],
+    },
+    ...TOOL_POLICY_METADATA.check_shell,
+    runtimeDescriptor: "shell",
+    permissions: {
+      level: "readonly",
+      scopes: ["process:read"],
+    },
+    telemetry: {
+      category: "shell",
+      tags: ["tool:check_shell", "contract:coding-agent", "tier:mvp"],
+    },
+  },
   {
     name: "git",
     title: "Git",
@@ -366,14 +410,19 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "agent",
     tier: "extension",
     description:
-      "Spawn an isolated sub-agent to handle a subtask. The sub-agent has its own context and message history, and only returns a summary result. Use this for tasks that benefit from focused, independent execution (e.g. code review, summarization, translation).",
+      "Spawn an isolated sub-agent to handle a subtask. The sub-agent has its own context and message history, and only returns a summary result. Use this for tasks that benefit from focused, independent execution (e.g. code review, summarization, translation). Pass `agent` to delegate to a named, pre-defined subagent (its persona + tool scope come from its .md file); otherwise give an ad-hoc `role`.",
     inputSchema: {
       type: "object",
       properties: {
+        agent: {
+          type: "string",
+          description:
+            'Optional name of a pre-defined subagent from .chainlesschain/agents/ or .claude/agents/ (e.g. "review:security"). Loads that file\'s system prompt + tool allow-list. Run `cc agents list` to see them. Explicit `role`/`tools` override the agent\'s values.',
+        },
         role: {
           type: "string",
           description:
-            "Sub-agent role (e.g. code-review, summarizer, translator, debugger)",
+            "Sub-agent role (e.g. code-review, summarizer, translator, debugger). Required unless `agent` is given.",
         },
         task: {
           type: "string",
@@ -397,7 +446,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
             "Optional declarative profile (from sub-agent-profiles). When set, seeds systemPrompt / tool allowlist / iteration cap. Explicit `tools` overrides the profile allowlist.",
         },
       },
-      required: ["role", "task"],
+      required: ["task"],
     },
     ...TOOL_POLICY_METADATA.spawn_sub_agent,
     permissions: {
@@ -449,6 +498,47 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
       tags: ["tool:web_fetch", "contract:coding-agent", "tier:extension"],
     },
   },
+  {
+    name: "web_search",
+    title: "Web Search",
+    kind: "network",
+    tier: "extension",
+    description:
+      "Search the web for a query and return ranked results (title, url, snippet) plus an optional synthesized answer. Use this to discover URLs, then web_fetch to read a page. Backend is configured via .chainlesschain/config.json:webSearch (default provider: auto — uses whichever API key is set, else keyless DuckDuckGo).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query (natural-language keywords)",
+        },
+        provider: {
+          type: "string",
+          enum: ["auto", "tavily", "brave", "bocha", "qianfan", "duckduckgo", "searxng", "baidu"],
+          description:
+            "Override the configured search backend for this call (default: from config / auto)",
+        },
+        maxResults: {
+          type: "number",
+          description: "Maximum number of results to return (default: 8)",
+        },
+        timeout: {
+          type: "number",
+          description: "Request timeout in ms (default: 15000)",
+        },
+      },
+      required: ["query"],
+    },
+    ...TOOL_POLICY_METADATA.web_search,
+    permissions: {
+      level: "readonly",
+      scopes: ["network:read"],
+    },
+    telemetry: {
+      category: "network",
+      tags: ["tool:web_search", "contract:coding-agent", "tier:extension"],
+    },
+  },
   {
     name: "todo_write",
     title: "Todo Write",

package/src/runtime/coding-agent-policy.cjs

@@ -115,6 +115,20 @@ const TOOL_POLICY_METADATA = Object.freeze({
     isReadOnly: false,
     readOnlySubcommands: READ_ONLY_GIT_SUBCOMMANDS,
   },
+  // Polls a background run_shell task (output + completion). Read-only: it never
+  // starts new work — the spawn already happened, gated, under run_shell. The
+  // optional kill flag terminates a task the agent itself launched, so it stays
+  // low-risk and is allowed during plan mode.
+  check_shell: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.READ,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
   list_skills: {
     riskLevel: RISK_LEVELS.LOW,
     category: TOOL_CATEGORIES.SKILL,
@@ -175,6 +189,16 @@ const TOOL_POLICY_METADATA = Object.freeze({
     approvalFlow: "auto",
     isReadOnly: true,
   },
+  web_search: {
+    riskLevel: RISK_LEVELS.MEDIUM,
+    category: TOOL_CATEGORIES.READ,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
   todo_write: {
     riskLevel: RISK_LEVELS.LOW,
     category: TOOL_CATEGORIES.WRITE,

package/src/runtime/headless-runner.js

@@ -25,9 +25,10 @@ import {
   buildSystemPrompt,
   agentLoop as coreAgentLoop,
   formatToolArgs,
+  killAllBackgroundShellTasks,
 } from "./agent-core.js";
 import {
-  loadMcpConfig,
+  resolveAgentMcp,
   resolvePermissionPromptTool,
   makePermissionPromptConfirmer,
 } from "./mcp-config.js";
@@ -44,6 +45,7 @@ import {
 } from "../harness/jsonl-session-store.js";
 import { expandFileRefs } from "./file-ref-expander.js";
 import { composeSystemPrompt } from "./system-prompt.js";
+import { buildUserContent } from "../lib/image-input.js";
 import { withQuietStdout } from "./quiet-stdout.js";
 
 /** Tools that cannot mutate the filesystem or run commands. */
@@ -229,6 +231,41 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     ? options.additionalDirectories.filter(Boolean)
     : [];
 
+  // .claude/settings.json permission rules (deny > ask > allow). A `deny` hard-
+  // blocks, an `allow` pre-authorizes (so a safe op isn't fail-closed headless),
+  // an `ask` falls closed (no human to confirm in headless). No file → null →
+  // every existing risk-tier / shell-policy layer runs unchanged.
+  let permissionRules = options.permissionRules || null;
+  if (!permissionRules) {
+    try {
+      const { loadSettings } = await import("../lib/settings-loader.cjs");
+      const loaded = loadSettings({ cwd, settingsFile: options.settingsFile });
+      const total =
+        loaded.rules.allow.length +
+        loaded.rules.ask.length +
+        loaded.rules.deny.length;
+      permissionRules = total > 0 ? loaded.rules : null;
+    } catch {
+      permissionRules = null; // fail-open
+    }
+  }
+
+  // .claude/settings.json `hooks` block — decision-capable PreToolUse/
+  // PostToolUse hooks (see settings-hooks/hook-runner). null = no hooks.
+  let settingsHooks = options.settingsHooks || null;
+  if (!settingsHooks) {
+    try {
+      const { loadHooks } = await import("../lib/settings-hooks.cjs");
+      const loaded = loadHooks({ cwd, settingsFile: options.settingsFile });
+      settingsHooks =
+        loaded.hooks && Object.keys(loaded.hooks).length > 0
+          ? loaded.hooks
+          : null;
+    } catch {
+      settingsHooks = null; // fail-open
+    }
+  }
+
   const runLoop = deps.agentLoop || coreAgentLoop;
   const doBootstrap = deps.bootstrap || bootstrap;
   const getApprovalGate =
@@ -340,18 +377,89 @@ export async function runAgentHeadless(options = {}, deps = {}) {
 
   // Effective system prompt: built-in base, optionally replaced by
   // --system-prompt and/or extended by --append-system-prompt.
+  // --output-style (or settings.json `outputStyle`) → a persona appended to the
+  // system prompt. Resolved best-effort; a missing style is ignored with a warn.
+  let outputStyleBody = null;
+  try {
+    const { resolveOutputStyle } = await import("../lib/output-styles.js");
+    const st = resolveOutputStyle(options.outputStyle, cwd);
+    if (st && st.missing && options.outputStyle) {
+      writeErr(`  output-style: unknown style "${options.outputStyle}"\n`);
+    } else if (st && st.body) {
+      outputStyleBody = st.body;
+    }
+  } catch {
+    outputStyleBody = null;
+  }
+
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, { additionalDirectories }),
     {
       systemPrompt: options.systemPrompt,
       appendSystemPrompt: options.appendSystemPrompt,
+      outputStyle: outputStyleBody,
     },
   );
 
+  // settings.json UserPromptSubmit hooks. block → abort the run; context → inject.
+  if (settingsHooks) {
+    try {
+      const { runUserPromptSubmitHooks } = await import(
+        "../lib/settings-hook-events.cjs"
+      );
+      const ups = runUserPromptSubmitHooks(settingsHooks, {
+        prompt: userContent,
+        cwd,
+        sessionId,
+      });
+      if (ups.blocked) {
+        writeErr(
+          `[hook] prompt blocked${ups.reason ? ": " + ups.reason : ""}\n`,
+        );
+        return {
+          exitCode: 2,
+          result: ups.reason || "blocked by UserPromptSubmit hook",
+          isError: true,
+        };
+      }
+      if (ups.additionalContext) {
+        userContent += `\n\n[hook context]\n${ups.additionalContext}`;
+      }
+    } catch (_err) {
+      // settings hook dispatch is best-effort
+    }
+  }
+
+  // settings.json SessionStart hooks → inject session context (observe-only).
+  let sessionStartContext = null;
+  if (settingsHooks) {
+    try {
+      const { runSessionStartHooks } = await import(
+        "../lib/settings-hook-events.cjs"
+      );
+      sessionStartContext = runSessionStartHooks(settingsHooks, {
+        source: resumeId ? "resume" : "startup",
+        cwd,
+        sessionId,
+      }).additionalContext;
+    } catch (_err) {
+      sessionStartContext = null;
+    }
+  }
+
+  // --image <path>: attach vision input to the user turn. buildUserContent
+  // returns the plain string when there are no images, so text-only runs are
+  // byte-for-byte unchanged; with images it builds an OpenAI-style multimodal
+  // content array (agent-core converts it per-provider for ollama/anthropic).
+  const userMessageContent = buildUserContent(userContent, options.images);
+
   const messages = [
     { role: "system", content: systemContent },
+    ...(sessionStartContext
+      ? [{ role: "system", content: sessionStartContext }]
+      : []),
     ...history,
-    { role: "user", content: userContent },
+    { role: "user", content: userMessageContent },
   ];
 
   // Persist the user turn up front (best-effort) so a session is recoverable
@@ -378,12 +486,30 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // tools to the LLM (Claude-Code parity). Connection is best-effort — a server
   // that fails to connect is logged to stderr and contributes no tools; a
   // missing/empty config file fails fast (the user explicitly asked for MCP).
+  // Combine the ad-hoc --mcp-config file with the servers registered via
+  // `cc mcp add` (their --auto-connect ones) into ONE client, exposing every
+  // tool to the LLM. A bad --mcp-config file fails fast; registered connects
+  // are best-effort. --no-mcp disables the registered set (ad-hoc still loads).
   let mcp = null;
-  if (options.mcpConfig) {
-    const doLoadMcp = deps.loadMcpConfig || loadMcpConfig;
+  {
+    const doResolve = deps.resolveAgentMcp || resolveAgentMcp;
     try {
-      mcp = await doLoadMcp(options.mcpConfig, { writeErr });
-      if (isText) {
+      mcp = await doResolve(
+        {
+          mcpConfigPath: options.mcpConfig || null,
+          db: db?.getDatabase?.() || null,
+          includeRegistered: options.useRegisteredMcp !== false,
+          ide: options.ide,
+          cwd: options.cwd || process.cwd(),
+        },
+        {
+          writeErr,
+          loadMcpConfig: deps.loadMcpConfig,
+          loadRegisteredMcp: deps.loadRegisteredMcp,
+          loadIdeMcp: deps.loadIdeMcp,
+        },
+      );
+      if (mcp && isText) {
         for (const c of mcp.connected) {
           writeErr(`  mcp: ${c.server} (${c.tools} tools)\n`);
         }
@@ -422,6 +548,11 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   const loopOptions = {
     model,
     provider,
+    // Extended thinking (Anthropic; opt-in via --think/--ultrathink). null/off
+    // → chatWithTools sends no thinking field. thinkingBudget (--thinking-budget)
+    // is the legacy-model budget_tokens override; ignored when thinking is off.
+    thinking: options.thinking || null,
+    thinkingBudget: options.thinkingBudget || null,
     baseUrl,
     apiKey,
     cwd,
@@ -431,6 +562,8 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     checkpointSession: options.checkpointSession || sessionId,
     hookDb: db,
     approvalGate,
+    permissionRules,
+    settingsHooks,
     enabledToolNames,
     disabledTools,
     iterationBudget: budget,
@@ -623,6 +756,29 @@ export async function runAgentHeadless(options = {}, deps = {}) {
         // ignore — disconnect is best-effort
       }
     }
+    // Kill any background run_shell tasks this run spawned so a backgrounded
+    // command (e.g. a dev server) doesn't outlive the headless invocation.
+    try {
+      killAllBackgroundShellTasks();
+    } catch {
+      // best-effort — never mask the run's own outcome
+    }
+    // settings.json SessionEnd hooks (observe-only) when the run finishes.
+    if (settingsHooks) {
+      try {
+        const { runObserveHooks } = await import(
+          "../lib/settings-hook-events.cjs"
+        );
+        runObserveHooks(
+          settingsHooks,
+          "SessionEnd",
+          { reason: "completed", cwd, session_id: sessionId },
+          { cwd },
+        );
+      } catch {
+        // observe-only
+      }
+    }
   }
 
   // coreAgentLoop emits run-ended reason "budget-exhausted" when the iteration

package/src/runtime/headless-stream.js

@@ -21,7 +21,7 @@ import { buildSystemPrompt, agentLoop as coreAgentLoop } from "./agent-core.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 import { expandFileRefs } from "./file-ref-expander.js";
 import {
-  loadMcpConfig,
+  resolveAgentMcp,
   resolvePermissionPromptTool,
   makePermissionPromptConfirmer,
 } from "./mcp-config.js";
@@ -145,6 +145,38 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     ? options.additionalDirectories.filter(Boolean)
     : [];
 
+  // .claude/settings.json permission rules (deny > ask > allow); see
+  // runAgentHeadless for the full semantics. null = no file → unchanged.
+  let permissionRules = options.permissionRules || null;
+  if (!permissionRules) {
+    try {
+      const { loadSettings } = await import("../lib/settings-loader.cjs");
+      const loaded = loadSettings({ cwd, settingsFile: options.settingsFile });
+      const total =
+        loaded.rules.allow.length +
+        loaded.rules.ask.length +
+        loaded.rules.deny.length;
+      permissionRules = total > 0 ? loaded.rules : null;
+    } catch {
+      permissionRules = null; // fail-open
+    }
+  }
+
+  // .claude/settings.json `hooks` block (decision-capable PreToolUse/PostToolUse).
+  let settingsHooks = options.settingsHooks || null;
+  if (!settingsHooks) {
+    try {
+      const { loadHooks } = await import("../lib/settings-hooks.cjs");
+      const loaded = loadHooks({ cwd, settingsFile: options.settingsFile });
+      settingsHooks =
+        loaded.hooks && Object.keys(loaded.hooks).length > 0
+          ? loaded.hooks
+          : null;
+    } catch {
+      settingsHooks = null; // fail-open
+    }
+  }
+
   const input = deps.input || process.stdin;
   const runLoop = deps.agentLoop || coreAgentLoop;
   const doBootstrap = deps.bootstrap || bootstrap;
@@ -191,15 +223,42 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     approvalGate = null;
   }
 
+  // --output-style (or settings.json `outputStyle`) persona, appended.
+  let outputStyleBody = null;
+  try {
+    const { resolveOutputStyle } = await import("../lib/output-styles.js");
+    const st = resolveOutputStyle(options.outputStyle, cwd);
+    if (st && st.body) outputStyleBody = st.body;
+  } catch {
+    outputStyleBody = null;
+  }
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, { additionalDirectories }),
     {
       systemPrompt: options.systemPrompt,
       appendSystemPrompt: options.appendSystemPrompt,
+      outputStyle: outputStyleBody,
     },
   );
   const messages = [{ role: "system", content: systemContent }];
 
+  // settings.json SessionStart hooks → inject session context once (observe-only).
+  if (settingsHooks) {
+    try {
+      const { runSessionStartHooks } = await import(
+        "../lib/settings-hook-events.cjs"
+      );
+      const ctx = runSessionStartHooks(settingsHooks, {
+        source: "startup",
+        cwd,
+        sessionId,
+      }).additionalContext;
+      if (ctx) messages.push({ role: "system", content: ctx });
+    } catch (_err) {
+      // best-effort
+    }
+  }
+
   emit({
     type: "system",
     subtype: "init",
@@ -232,14 +291,29 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     }
   }
 
-  // --mcp-config: connect ad-hoc MCP servers for the whole stream session and
-  // expose their tools to the LLM (Claude-Code parity). Best-effort connect; a
-  // missing/empty config fails the session up front.
+  // Combine the ad-hoc --mcp-config file with the registered (cc mcp add)
+  // auto-connect servers into one client for the whole stream session, exposing
+  // every tool to the LLM. A bad --mcp-config file fails up front; registered
+  // connects are best-effort. --no-mcp disables the registered set.
   let mcp = null;
-  if (options.mcpConfig) {
-    const doLoadMcp = deps.loadMcpConfig || loadMcpConfig;
+  {
+    const doResolve = deps.resolveAgentMcp || resolveAgentMcp;
     try {
-      mcp = await doLoadMcp(options.mcpConfig, { writeErr });
+      mcp = await doResolve(
+        {
+          mcpConfigPath: options.mcpConfig || null,
+          db: db?.getDatabase?.() || null,
+          includeRegistered: options.useRegisteredMcp !== false,
+          ide: options.ide,
+          cwd: options.cwd || process.cwd(),
+        },
+        {
+          writeErr,
+          loadMcpConfig: deps.loadMcpConfig,
+          loadRegisteredMcp: deps.loadRegisteredMcp,
+          loadIdeMcp: deps.loadIdeMcp,
+        },
+      );
     } catch (err) {
       emit({
         type: "result",
@@ -281,6 +355,10 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   const loopOptionsBase = {
     model,
     provider,
+    // Extended thinking (Anthropic; opt-in via --think/--ultrathink).
+    // thinkingBudget (--thinking-budget) = legacy-model budget_tokens override.
+    thinking: options.thinking || null,
+    thinkingBudget: options.thinkingBudget || null,
     baseUrl,
     apiKey,
     cwd,
@@ -288,6 +366,8 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     sessionId,
     hookDb: db,
     approvalGate,
+    permissionRules,
+    settingsHooks,
     enabledToolNames,
     disabledTools,
     prepareCall: goalPrepareCallFn,
@@ -345,6 +425,35 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
       for (const w of expanded.warnings) writeErr(`  @ref: ${w}\n`);
     }
 
+    // settings.json UserPromptSubmit hooks. block → skip this turn; context → inject.
+    if (settingsHooks) {
+      try {
+        const { runUserPromptSubmitHooks } = await import(
+          "../lib/settings-hook-events.cjs"
+        );
+        const ups = runUserPromptSubmitHooks(settingsHooks, {
+          prompt: userContent,
+          cwd,
+          sessionId,
+        });
+        if (ups.blocked) {
+          emit({
+            type: "result",
+            subtype: "blocked",
+            is_error: true,
+            result: ups.reason || "blocked by UserPromptSubmit hook",
+            session_id: sessionId,
+          });
+          continue;
+        }
+        if (ups.additionalContext) {
+          userContent += `\n\n[hook context]\n${ups.additionalContext}`;
+        }
+      } catch (_err) {
+        // settings hook dispatch is best-effort
+      }
+    }
+
     messages.push({ role: "user", content: userContent });
     turns += 1;
 
@@ -396,6 +505,23 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     }
   }
 
+  // settings.json SessionEnd hooks (observe-only) when stdin closes.
+  if (settingsHooks) {
+    try {
+      const { runObserveHooks } = await import(
+        "../lib/settings-hook-events.cjs"
+      );
+      runObserveHooks(
+        settingsHooks,
+        "SessionEnd",
+        { reason: "stdin_closed", cwd, session_id: sessionId },
+        { cwd },
+      );
+    } catch {
+      // observe-only
+    }
+  }
+
   emit({ type: "system", subtype: "end", session_id: sessionId, turns });
   return { exitCode: sawError ? 1 : 0, turns };
 }