chainlesschain 0.162.154 → 0.162.156

package/src/runtime/agent-core.js

@@ -64,6 +64,7 @@ import {
   toOllamaMessages,
   imageUrlBlockToAnthropic,
 } from "../lib/image-input.js";
+import { executeToolSearch, gateDeferredMcpCall } from "./mcp-tool-search.js";
 
 /**
  * Names of MCP servers currently mounted by an in-flight run_skill call.
@@ -1439,6 +1440,7 @@ export async function executeTool(name, args, context = {}) {
       additionalDirectories: context.additionalDirectories || null,
       sandbox: context.sandbox || null,
       ruleAllowed,
+      settingsVerdict,
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
       interactiveApproval: context.interactiveApproval || false,
@@ -2057,6 +2059,7 @@ async function executeToolInner(
     additionalDirectories,
     sandbox,
     ruleAllowed = false,
+    settingsVerdict = null,
     subAgentDepth = 0,
     subAgentBudget = null,
     interactiveApproval = false,
@@ -2338,6 +2341,40 @@ async function executeToolInner(
           : {}),
         ...(classifyAllShell ? { classifyAllShell: true } : {}),
       };
+      // Layer-by-layer explanation chain for a blocked command: which layers
+      // were consulted and what each said (settings rules → shell policy →
+      // approval gate). Attached to denial results so `/permissions denials`
+      // and `cc permissions recent` can explain WHY, not just THAT.
+      const buildPermissionChain = (gated) => {
+        const chain = [
+          {
+            layer: "settings-rules",
+            outcome:
+              settingsVerdict?.decision || (ruleAllowed ? "allow" : "no-match"),
+            rule: settingsVerdict?.rule || null,
+          },
+          {
+            layer: "shell-policy",
+            outcome: shellPolicy?.decision || null,
+            rule: shellPolicy?.ruleId || null,
+            reason: shellPolicy?.reason || null,
+          },
+        ];
+        // A hard shell-policy deny returns before the gate is consulted
+        // (via === "shell-policy") — no approval-gate layer to explain then.
+        if (gated && gated.via !== "shell-policy") {
+          chain.push({
+            layer: "approval-gate",
+            outcome: gated.decision,
+            via: gated.via || null,
+            policy: gated.policy || null,
+            riskLevel: gated.riskLevel || null,
+            rule: gated.gateRule || null,
+            reason: gated.gateReason || null,
+          });
+        }
+        return chain;
+      };
       const override = getRuntimeToolDescriptorByCommand(args.command);
       let shellPolicy;
       let approvalOutcome = null;
@@ -2375,6 +2412,7 @@ async function executeToolInner(
                   : `[ApprovalGate] command denied by the ${tierLabel}approval policy (via ${gated.via}). Retrying the same command will not help — it needs user approval. Tell the user (they can run it themselves, approve it, or relax the policy) and continue with other work.`,
               shellCommandPolicy: shellPolicy,
               approval: approvalOutcome,
+              permissionChain: buildPermissionChain(gated),
             },
             override || runtimeDescriptor,
           );
@@ -2386,6 +2424,7 @@ async function executeToolInner(
             {
               error: `[Shell Policy] ${shellPolicy.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`,
               shellCommandPolicy: shellPolicy,
+              permissionChain: buildPermissionChain(null),
             },
             override || runtimeDescriptor,
           );
@@ -2971,6 +3010,100 @@ async function executeToolInner(
       }
     }
 
+    case "notify": {
+      try {
+        const { sendAgentNotification } =
+          await import("../lib/agent-notify.js");
+        const outcome = await sendAgentNotification({
+          title: args.title,
+          body: args.body,
+          level: args.level,
+        });
+        return attachDescriptor(outcome);
+      } catch (err) {
+        return attachDescriptor({ error: `notify failed: ${err.message}` });
+      }
+    }
+
+    case "schedule": {
+      try {
+        const { AgentScheduleStore } =
+          await import("../lib/agent-schedule-store.js");
+        const { parseDuration } = await import("../lib/loop.js");
+        const store = new AgentScheduleStore();
+        const action = String(args.action || "").toLowerCase();
+        if (action === "wakeup") {
+          if (!args.prompt) {
+            return attachDescriptor({
+              error: "schedule wakeup requires a prompt",
+            });
+          }
+          const delayMs = args.delay ? parseDuration(args.delay) : 0;
+          const entry = store.scheduleWakeup({
+            prompt: args.prompt,
+            delayMs,
+            label: args.label || null,
+          });
+          return attachDescriptor({
+            scheduled: entry,
+            hint: "Run `cc agenda run` (e.g. via cron or `cc loop`) to fire due entries.",
+          });
+        }
+        if (action === "cron") {
+          if (!args.prompt || !args.cron) {
+            return attachDescriptor({
+              error: "schedule cron requires a prompt and a cron expression",
+            });
+          }
+          const entry = store.createCron({
+            prompt: args.prompt,
+            cron: args.cron,
+            label: args.label || null,
+          });
+          return attachDescriptor({ scheduled: entry });
+        }
+        if (action === "monitor") {
+          if (!args.command) {
+            return attachDescriptor({
+              error: "schedule monitor requires a command",
+            });
+          }
+          const intervalMs = args.interval
+            ? parseDuration(args.interval)
+            : 60000;
+          const entry = store.createMonitor({
+            command: args.command,
+            intervalMs,
+            stopWhen: args.stop_when || null,
+            notify: args.notify_title ? { title: args.notify_title } : null,
+            maxChecks: args.max_checks ?? null,
+            label: args.label || null,
+          });
+          return attachDescriptor({ scheduled: entry });
+        }
+        if (action === "list") {
+          return attachDescriptor({ entries: store.list() });
+        }
+        if (action === "cancel") {
+          if (!args.id) {
+            return attachDescriptor({
+              error: "schedule cancel requires an id",
+            });
+          }
+          const removed = store.cancel(args.id);
+          return attachDescriptor({
+            cancelled: removed ? removed.id : null,
+            found: Boolean(removed),
+          });
+        }
+        return attachDescriptor({
+          error: `unknown schedule action "${args.action}". Valid: wakeup, cron, monitor, list, cancel.`,
+        });
+      } catch (err) {
+        return attachDescriptor({ error: `schedule failed: ${err.message}` });
+      }
+    }
+
     case "search_files": {
       // An explicit directory scopes the search to one root; otherwise span
       // cwd plus any --add-dir roots so cross-package searches find matches.
@@ -3347,6 +3480,15 @@ async function executeToolInner(
         }
       }
 
+      // Internal tool-search tool (MCP context scaling): resolves deferred
+      // MCP tool schemas from the registry attached at setup time. Read-only,
+      // local — same risk class as list_skills, so no approval gate.
+      if (localToolExecutor?.kind === "tool-search") {
+        return attachDescriptor(
+          executeToolSearch(localToolExecutor.registry, args || {}),
+        );
+      }
+
       if (localToolExecutor?.kind === "mcp") {
         if (!mcpClient || typeof mcpClient.callTool !== "function") {
           return attachDescriptor({
@@ -3354,6 +3496,15 @@ async function executeToolInner(
           });
         }
 
+        // Deferred-schema gate: a direct call to a tool whose schema was never
+        // loaded returns a self-healing error embedding the schema (and marks
+        // it loaded), instead of forwarding likely-malformed arguments to the
+        // server. No-op unless tool search deferred this tool.
+        const deferredGate = gateDeferredMcpCall(name, localToolExecutor);
+        if (deferredGate) {
+          return attachDescriptor(deferredGate);
+        }
+
         try {
           const result = await mcpClient.callTool(
             localToolExecutor.serverName,
@@ -6285,6 +6436,16 @@ export function formatToolArgs(name, args) {
       return `[${args.role}] ${(args.task || "").substring(0, 60)}`;
     case "search_sessions":
       return `"${(args.query || "").substring(0, 60)}"`;
+    case "notify":
+      return `${args.level || "info"}: ${(args.title || "").substring(0, 50)}`;
+    case "schedule":
+      return args.action === "cron"
+        ? `cron ${args.cron || ""}`.trim()
+        : args.action === "monitor"
+          ? `monitor ${(args.command || "").substring(0, 40)}`.trim()
+          : args.action === "wakeup"
+            ? `wakeup +${args.delay || "0s"}`
+            : String(args.action || "");
     default:
       return JSON.stringify(args).substring(0, 60);
   }

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

@@ -849,6 +849,110 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
       tags: ["tool:search_sessions", "contract:coding-agent", "tier:extension"],
     },
   },
+  {
+    name: "notify",
+    title: "Send Notification",
+    kind: "notify",
+    tier: "extension",
+    description:
+      "Push a notification to the user's configured channels (Telegram / WeCom / DingTalk / Feishu) and/or a paired mobile device. Use for long-running tasks: report completion, flag that you need a human decision, or surface an error. Best-effort: reports which channels delivered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short notification title" },
+        body: { type: "string", description: "Notification body text" },
+        level: {
+          type: "string",
+          enum: ["info", "success", "failure"],
+          description: "Severity (default: info)",
+        },
+      },
+      required: ["title"],
+    },
+    ...TOOL_POLICY_METADATA.notify,
+    permissions: {
+      level: "standard",
+      scopes: ["network:notify"],
+    },
+    telemetry: {
+      category: "notify",
+      tags: ["tool:notify", "contract:coding-agent", "tier:extension"],
+    },
+  },
+  {
+    name: "schedule",
+    title: "Schedule / Monitor",
+    kind: "schedule",
+    tier: "extension",
+    description:
+      "Set up work that outlives this turn (persisted for `cc agenda run` to execute). Actions: `wakeup` — run a prompt once after a delay; `cron` — run a prompt on a 5-field cron schedule; `monitor` — run a shell command every interval and notify when its output matches a regex; `list` — show scheduled items; `cancel` — remove one by id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["wakeup", "cron", "monitor", "list", "cancel"],
+          description: "What to do",
+        },
+        prompt: {
+          type: "string",
+          description:
+            "For wakeup/cron: the agent prompt to run (via `cc agent -p`) when it fires",
+        },
+        delay: {
+          type: "string",
+          description:
+            "For wakeup: how long from now before it fires (e.g. 30s, 5m, 1h)",
+        },
+        cron: {
+          type: "string",
+          description:
+            'For cron: a 5-field cron expression, e.g. "0 9 * * 1" (09:00 every Monday)',
+        },
+        command: {
+          type: "string",
+          description: "For monitor: the shell command to run each interval",
+        },
+        interval: {
+          type: "string",
+          description:
+            "For monitor: how often to run the command (e.g. 30s, 5m)",
+        },
+        stop_when: {
+          type: "string",
+          description:
+            "For monitor: a regex; when the command output matches, the monitor fires its notification and stops",
+        },
+        notify_title: {
+          type: "string",
+          description: "For monitor: notification title sent when it matches",
+        },
+        max_checks: {
+          type: "number",
+          description:
+            "For monitor: give up after this many checks (optional safety cap)",
+        },
+        label: {
+          type: "string",
+          description: "Optional human label for list/cancel",
+        },
+        id: {
+          type: "string",
+          description: "For cancel: the schedule entry id to remove",
+        },
+      },
+      required: ["action"],
+    },
+    ...TOOL_POLICY_METADATA.schedule,
+    permissions: {
+      level: "standard",
+      scopes: ["schedule:write"],
+    },
+    telemetry: {
+      category: "schedule",
+      tags: ["tool:schedule", "contract:coding-agent", "tier:extension"],
+    },
+  },
 ]);
 
 const CODING_AGENT_MVP_TOOL_NAMES = Object.freeze(

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

@@ -261,6 +261,34 @@ const TOOL_POLICY_METADATA = Object.freeze({
     approvalFlow: "auto",
     isReadOnly: true,
   },
+  // Sends an outbound notification to the user's own channels/device. No
+  // workspace mutation and no un-gated shell; blocked in plan mode (an
+  // external side effect) but otherwise auto — it targets the user, not a
+  // third party.
+  notify: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.WRITE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: false,
+  },
+  // Persists a wakeup/cron/monitor entry for `cc agenda run` to execute later.
+  // Writing the schedule is itself harmless (a JSONL row under the user's
+  // config dir); the eventual `cc agent`/shell run is gated when the agenda
+  // consumer executes it. Blocked in plan mode (schedules future side effects).
+  schedule: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.WRITE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: false,
+  },
 });
 
 function normalizeGitCommand(command) {

package/src/runtime/headless-runner.js

@@ -15,9 +15,11 @@
  * Permission model: headless cannot show an interactive approval prompt, so the
  * default is fail-closed (deny MEDIUM/HIGH-risk shell). --permission-mode opts
  * into a looser tier:
- *  - (default) / plan   → STRICT  + deny-confirmer  (plan also restricts tools)
- *  - acceptEdits        → TRUSTED + deny-confirmer  (HIGH-risk shell still denied)
- *  - bypassPermissions  → AUTOPILOT (everything allowed, no confirm)
+ *  - (default) / manual / dontAsk / plan → STRICT + deny-confirmer
+ *    (plan also restricts tools)
+ *  - auto / acceptEdits                  → TRUSTED + deny-confirmer
+ *    (HIGH-risk shell still denied)
+ *  - bypassPermissions                   → AUTOPILOT (everything allowed)
  */
 
 import { bootstrap } from "./bootstrap.js";
@@ -33,6 +35,7 @@ import {
   resolvePermissionPromptTool,
   makePermissionPromptConfirmer,
 } from "./mcp-config.js";
+import { maybeApplyToolSearch } from "./mcp-tool-search.js";
 import { IterationBudget } from "../lib/iteration-budget.js";
 import {
   startSession as jsonlStartSession,
@@ -68,6 +71,9 @@ export const READ_ONLY_TOOLS = Object.freeze([
 
 const VALID_PERMISSION_MODES = Object.freeze([
   "default",
+  "manual",
+  "auto",
+  "dontAsk",
   "plan",
   "acceptEdits",
   "bypassPermissions",
@@ -81,19 +87,30 @@ export { installPipeSafety } from "./pipe-safety.js";
 import { installPipeSafety } from "./pipe-safety.js";
 
 /**
- * Resolve a --permission-mode string into the session-policy tier + a
- * non-interactive confirmer + whether to clamp tools to the read-only set.
+ * Normalize a public --permission-mode spelling to the canonical internal mode.
  *
- * @param {string} mode
- * @returns {{ sessionPolicy: string, confirmer: (ctx:any)=>Promise<boolean>, readOnly: boolean }}
+ * @param {string} [mode]
+ * @returns {string}
  */
-export function resolvePermissionMode(mode = "default") {
+export function normalizePermissionMode(mode = "default") {
   const m = mode || "default";
   if (!VALID_PERMISSION_MODES.includes(m)) {
     throw new Error(
       `Invalid --permission-mode "${m}". Expected one of: ${VALID_PERMISSION_MODES.join(", ")}`,
     );
   }
+  return m;
+}
+
+/**
+ * Resolve a --permission-mode string into the session-policy tier + a
+ * non-interactive confirmer + whether to clamp tools to the read-only set.
+ *
+ * @param {string} mode
+ * @returns {{ sessionPolicy: string, confirmer: (ctx:any)=>Promise<boolean>, readOnly: boolean, allowInteractiveApprovals: boolean }}
+ */
+export function resolvePermissionMode(mode = "default") {
+  const m = normalizePermissionMode(mode);
   // Headless can't ask a human — deny when a confirm would be required.
   const denyConfirmer = async () => false;
   const allowConfirmer = async () => true;
@@ -103,25 +120,38 @@ export function resolvePermissionMode(mode = "default") {
         sessionPolicy: "autopilot",
         confirmer: allowConfirmer,
         readOnly: false,
+        allowInteractiveApprovals: false,
       };
+    case "auto":
     case "acceptEdits":
       return {
         sessionPolicy: "trusted",
         confirmer: denyConfirmer,
         readOnly: false,
+        allowInteractiveApprovals: true,
       };
     case "plan":
       return {
         sessionPolicy: "strict",
         confirmer: denyConfirmer,
         readOnly: true,
+        allowInteractiveApprovals: true,
+      };
+    case "dontAsk":
+      return {
+        sessionPolicy: "strict",
+        confirmer: denyConfirmer,
+        readOnly: false,
+        allowInteractiveApprovals: false,
       };
+    case "manual":
     case "default":
     default:
       return {
         sessionPolicy: "strict",
         confirmer: denyConfirmer,
         readOnly: false,
+        allowInteractiveApprovals: true,
       };
   }
 }
@@ -610,6 +640,28 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   let approvalGate = null;
   try {
     approvalGate = await getApprovalGate();
+    if (approvalGate && (options.permissionMode || "default") === "auto") {
+      // autoMode.decisions: user-configured riskLevel → allow/ask/deny
+      // classifier. Only wrap when settings actually customize the map so the
+      // unconfigured auto path keeps the byte-identical trusted-tier mapping.
+      try {
+        const {
+          loadAutoModeConfig,
+          resolveAutoModeDecisions,
+          createAutoModeApprovalGate,
+        } = await import("../lib/auto-mode-config.js");
+        const autoConfig = loadAutoModeConfig({
+          cwd,
+          settingsFile: options.settingsFile,
+        });
+        const resolved = resolveAutoModeDecisions(autoConfig.effective);
+        if (resolved.customized) {
+          approvalGate = createAutoModeApprovalGate(approvalGate, resolved);
+        }
+      } catch {
+        // fail to the default trusted mapping — never block the run
+      }
+    }
     if (approvalGate) {
       if (typeof approvalGate.setSessionPolicy === "function") {
         approvalGate.setSessionPolicy(sessionId, perm.sessionPolicy);
@@ -800,6 +852,22 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           writeErr(`  mcp: ${c.server} (${c.tools} tools)\n`);
         }
       }
+      // MCP tool search (context scaling): when the tool schemas would eat a
+      // significant share of the context window, defer them behind the
+      // internal tool_search tool. Below-threshold / disabled → no-op, the
+      // wiring object is untouched.
+      if (mcp) {
+        try {
+          (deps.maybeApplyToolSearch || maybeApplyToolSearch)(mcp, {
+            model,
+            provider,
+            cwd: options.cwd || process.cwd(),
+            writeErr: isText ? writeErr : () => {},
+          });
+        } catch {
+          // best-effort — full schemas still work without deferral
+        }
+      }
     } catch (err) {
       writeErr(`Error: ${err.message}\n`);
       emitHeadlessError(err.message);
@@ -861,6 +929,35 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   }
 
+  // --remote-control: route CONFIRM-tier approvals to paired mobile/web
+  // devices (第四阶段 #2). Self-hosts a lightweight WS server + approval
+  // bridge for THIS run's session, prints the pairing URI/QR to stderr, and
+  // installs the remote confirmer on the gate (same override point as
+  // --permission-prompt-tool; that flag wins when both are given since it is
+  // installed above and this block skips). Fail-closed on timeout.
+  let _remoteApproval = null;
+  if (options.remoteControl && !options.permissionPromptTool) {
+    try {
+      const { startHeadlessRemoteApproval } =
+        await import("../lib/remote-approval-bridge.js");
+      _remoteApproval = await (
+        deps.startHeadlessRemoteApproval || startHeadlessRemoteApproval
+      )({
+        agentSessionId: sessionId,
+        writeErr,
+        isText,
+      });
+      if (approvalGate && typeof approvalGate.setConfirmer === "function") {
+        approvalGate.setConfirmer(_remoteApproval.confirmer);
+      }
+    } catch (err) {
+      // Remote approval could not come up → keep headless fail-closed rather
+      // than running un-gated; say why so the user can fix pairing.
+      writeErr(`  remote-control: unavailable (${err.message})\n`);
+      _remoteApproval = null;
+    }
+  }
+
   // --otlp <file>: attach an OpenTelemetry recorder so the real agent loop's
   // model/tool/retry spans are captured and exported as OTLP/JSON on exit.
   // Off by default (zero cost) — only built when a path is requested.
@@ -1350,6 +1447,15 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     } catch {
       // best-effort — never mask the run's own outcome
     }
+    // Tear down the --remote-control approval bridge + its self-hosted WS
+    // server so the run's port/socket never outlives the invocation.
+    if (_remoteApproval) {
+      try {
+        await _remoteApproval.close();
+      } catch {
+        // best-effort — never mask the run's own outcome
+      }
+    }
     // settings.json Stop + SessionEnd hooks when the run finishes. Stop is the
     // canonical async-hook trigger ("run the test suite at turn end"); fire its
     // async hooks fire-and-forget, then settle so a fast background check can
@@ -1502,6 +1608,18 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     } else if (isStream) {
       emitStream({ type: "denials_summary", count: denials.length, denials });
     }
+    try {
+      const { appendRecentDenials } =
+        await import("../lib/permission-denial-store.js");
+      appendRecentDenials(denials, {
+        sessionId,
+        permissionMode: options.permissionMode || "default",
+        cwd,
+        source: "headless",
+      });
+    } catch {
+      // Persisting the review surface is best-effort; never affect the run.
+    }
   }
 
   if (isStream) {