@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/tool-system/builtin/cancel-goal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * cancel_goal — user-initiated goal ABANDONMENT (distinct from complete_goal).
+ *
+ * complete_goal = "the goal is fully achieved, stop." cancel_goal = "the user
+ * explicitly asked to STOP pursuing this goal even though it isn't done." Both
+ * short-circuit the turn loop to a stop and clear the persisted goal so a later
+ * bare send won't re-inherit it — but cancel_goal is a controlled escape hatch,
+ * NOT a self-judgment the model may make on its own.
+ *
+ * "Strong intent" guard (the whole point of this tool): the model must NOT
+ * cancel a goal on its own initiative — only when the user has clearly asked to
+ * stop/abandon it. To make that hard to do accidentally, the schema REQUIRES:
+ *   - confirm: true         — an explicit boolean gate (a bare call is invalid)
+ *   - reason: string        — the user's own words / paraphrase of the request
+ * The turn loop only honors the cancellation when confirm === true; anything
+ * else records a refusal string and does NOT stop or clear the goal.
+ *
+ * Shape note: like complete_goal, this is a ToolDefinition + a separate executor
+ * returning a string. The loop-level short-circuit lives in turn-loop.ts and
+ * keys off CANCEL_GOAL_TOOL_NAME.
+ */
+import type { ToolDefinition } from "../../types.js";
+/** Shared with turn-loop.ts's short-circuit check — the name lives in one place. */
+export declare const CANCEL_GOAL_TOOL_NAME = "cancel_goal";
+export declare const cancelGoalToolDef: ToolDefinition;
+/**
+ * Executor. Returns a human-readable acknowledgement. The ACTUAL cancellation
+ * (stop + clear persisted goal) is enforced in turn-loop.ts, which re-checks
+ * confirm===true — this executor's string is only what lands in the transcript.
+ */
+export declare function cancelGoalTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/cancel-goal.js

@@ -0,0 +1,64 @@
+/**
+ * cancel_goal — user-initiated goal ABANDONMENT (distinct from complete_goal).
+ *
+ * complete_goal = "the goal is fully achieved, stop." cancel_goal = "the user
+ * explicitly asked to STOP pursuing this goal even though it isn't done." Both
+ * short-circuit the turn loop to a stop and clear the persisted goal so a later
+ * bare send won't re-inherit it — but cancel_goal is a controlled escape hatch,
+ * NOT a self-judgment the model may make on its own.
+ *
+ * "Strong intent" guard (the whole point of this tool): the model must NOT
+ * cancel a goal on its own initiative — only when the user has clearly asked to
+ * stop/abandon it. To make that hard to do accidentally, the schema REQUIRES:
+ *   - confirm: true         — an explicit boolean gate (a bare call is invalid)
+ *   - reason: string        — the user's own words / paraphrase of the request
+ * The turn loop only honors the cancellation when confirm === true; anything
+ * else records a refusal string and does NOT stop or clear the goal.
+ *
+ * Shape note: like complete_goal, this is a ToolDefinition + a separate executor
+ * returning a string. The loop-level short-circuit lives in turn-loop.ts and
+ * keys off CANCEL_GOAL_TOOL_NAME.
+ */
+/** Shared with turn-loop.ts's short-circuit check — the name lives in one place. */
+export const CANCEL_GOAL_TOOL_NAME = "cancel_goal";
+export const cancelGoalToolDef = {
+    name: CANCEL_GOAL_TOOL_NAME,
+    description: "取消(放弃)当前的持久目标。⚠️ 仅当用户明确要求停止/取消/放弃当前目标时才调用本工具;" +
+        "绝不要自行判断放弃目标(“目标太难”“暂时做不完”都不是取消理由——那种情况应继续或用 complete_goal)。" +
+        "必须传 confirm=true 并在 reason 里复述用户要求取消的原话/意图。调用后目标会被清除,agent 停止。\n" +
+        "Cancel (abandon) the current persistent goal. ⚠️ Call this ONLY when the user has EXPLICITLY asked to " +
+        "stop/cancel/abandon the goal. NEVER decide to abandon a goal on your own (a hard or unfinished goal is " +
+        "NOT a reason to cancel). You MUST pass confirm=true and put the user's own words/intent in `reason`. " +
+        "After calling, the goal is cleared and the agent stops.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            confirm: {
+                type: "boolean",
+                description: "必须为 true 才会真正取消目标。缺省或 false 视为无效调用,不会取消。" +
+                    "Must be true to actually cancel. Missing/false is treated as an invalid call and cancels nothing.",
+            },
+            reason: {
+                type: "string",
+                description: "用户要求取消目标的原话或意图复述(必填)。Required: the user's own words / paraphrased request to cancel.",
+            },
+        },
+        required: ["confirm", "reason"],
+    },
+};
+/**
+ * Executor. Returns a human-readable acknowledgement. The ACTUAL cancellation
+ * (stop + clear persisted goal) is enforced in turn-loop.ts, which re-checks
+ * confirm===true — this executor's string is only what lands in the transcript.
+ */
+export async function cancelGoalTool(args) {
+    const confirmed = args.confirm === true;
+    const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+    if (!confirmed) {
+        return ("cancel_goal 未生效:confirm 必须为 true 且需说明用户要求取消的原因。" +
+            "(cancel_goal ignored: confirm must be true and a reason is required.)");
+    }
+    return reason
+        ? `目标已按用户要求取消 (goal cancelled by user). Reason: ${reason}`
+        : "目标已按用户要求取消 (goal cancelled by user).";
+}

package/dist/tool-system/builtin/check-quota.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CheckQuota builtin — thin shell over the `quota/` module.
+ *
+ * Lets an orchestrating agent read how much CC/Codex quota is left before/while
+ * delegating work (DriveAgent), so it can plan: how many to spawn, whether to
+ * wait for a reset, or switch providers. See quota/index.ts for the sources.
+ *
+ * NOTE the cost asymmetry (surfaced in the description): Codex is a free GET;
+ * Claude costs ~1 output token because Anthropic only returns quota via
+ * response headers. So restrict with `provider` when you only need one.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const checkQuotaToolDef: ToolDefinition;
+export declare function checkQuotaTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/check-quota.js

@@ -0,0 +1,34 @@
+import { checkQuota, formatQuota } from "../../quota/index.js";
+import { resolveQuotaCredentials } from "../../quota/credentials.js";
+export const checkQuotaToolDef = {
+    name: "CheckQuota",
+    description: "Check remaining usage/rate-limit quota for the external coding-agent CLIs (Claude Code and/or " +
+        "Codex) — the same 5h/7d subscription windows their status lines show. Use before or during " +
+        "orchestration (DriveAgent) to plan how much work to hand off, whether to wait for a reset, or " +
+        "which provider to use. Returns each provider's 5h/7d used-% and reset time. " +
+        "COST: 'codex' is free (reads a usage endpoint). 'claude' costs ~1 token (Anthropic exposes " +
+        "quota only via a response header, so this sends a 1-token probe). Pass `provider` to query " +
+        "just one and avoid the other's cost/latency.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            provider: {
+                type: "string",
+                enum: ["claude", "codex", "both"],
+                description: "Which to check. 'both' (default) queries Claude Code and Codex. 'claude' sends a 1-token probe; 'codex' is free.",
+            },
+        },
+        required: [],
+    },
+};
+export async function checkQuotaTool(args, ctx) {
+    const which = args.provider === "claude" ? ["claude"] : args.provider === "codex" ? ["codex"] : ["claude", "codex"];
+    const creds = await resolveQuotaCredentials();
+    const result = await checkQuota({
+        creds,
+        providers: which,
+        signal: ctx?.signal,
+    });
+    const nowSec = Math.floor(Date.now() / 1000);
+    return formatQuota(result, nowSec);
+}

package/dist/tool-system/builtin/config.js

@@ -59,6 +59,13 @@ export async function configTool(args) {
             obj = obj[parts[i]];
         }
         obj[parts[parts.length - 1]] = value;
+        // Never resurrect a deleted project root: a recursive mkdir of
+        // <cwd>/.code-shell would recreate `cwd` itself as an empty shell when the
+        // directory has been deleted (e.g. a stale session pointing at a removed
+        // dir). If the project root is gone, the project is gone — don't write.
+        if (!existsSync(cwd)) {
+            return `Error: project directory does not exist: ${cwd}`;
+        }
         mkdirSync(join(cwd, ".code-shell"), { recursive: true });
         writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
         return `Updated ${key} = ${JSON.stringify(value)}`;

package/dist/tool-system/builtin/cron.d.ts

@@ -2,9 +2,16 @@
  * Cron tools — CronCreate, CronDelete, CronList.
  */
 import type { ToolDefinition } from "../../types.js";
+/** Sink notified after a cron job is created/deleted, so the host (Electron
+ *  main) can reload+arm the scheduler that actually executes jobs. The worker
+ *  process only persists cron jobs (executionEnabled=false); without this the
+ *  host never learns about an AI-created job until the user opens the UI. */
+type CronChangedSink = () => void;
+export declare function setCronChangedSink(sink: CronChangedSink | null): void;
 export declare const cronCreateToolDef: ToolDefinition;
 export declare function cronCreateTool(args: Record<string, unknown>): Promise<string>;
 export declare const cronDeleteToolDef: ToolDefinition;
 export declare function cronDeleteTool(args: Record<string, unknown>): Promise<string>;
 export declare const cronListToolDef: ToolDefinition;
 export declare function cronListTool(_args: Record<string, unknown>): Promise<string>;
+export {};

package/dist/tool-system/builtin/cron.js

@@ -2,6 +2,19 @@
  * Cron tools — CronCreate, CronDelete, CronList.
  */
 import { cronScheduler } from "../../automation/scheduler.js";
+import { getCurrentSid } from "../../logging/logger.js";
+let cronChangedSink = null;
+export function setCronChangedSink(sink) {
+    cronChangedSink = sink;
+}
+function fireCronChanged() {
+    try {
+        cronChangedSink?.();
+    }
+    catch {
+        // Notifying the host is best-effort; never break the tool on it.
+    }
+}
 export const cronCreateToolDef = {
     name: "CronCreate",
     description: "Create a scheduled automation job that runs a prompt on a recurring schedule. " +
@@ -14,7 +27,14 @@ export const cronCreateToolDef = {
         "'30 8 * * 1' = 8:30am every Monday. Day-of-week: 0=Sunday..6=Saturday.\n\n" +
         "For calendar schedules, set `timezone` to the user's IANA zone (e.g. 'Asia/Shanghai', " +
         "'America/New_York'); ask the user if unknown. Set `cwd` to the project the job operates on. " +
-        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.",
+        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.\n\n" +
+        "SELF-WAKEUP / background-task safety net: you can also schedule THIS job for yourself, with no user " +
+        "request, to re-check on a long-running background task (a download, a build, a background shell/agent) " +
+        "that might hang and never signal completion. Use a short interval + `once: true` + `continueInSession: true` " +
+        "and a `prompt` that reminds you what to check, e.g. schedule '5m', once true, continueInSession true, " +
+        "prompt 'check whether the yt-dlp download finished (BashOutput/ListShells); if still running, wait again'. " +
+        "You wake back in THIS conversation with full context, inspect the task, and either finish or reschedule. " +
+        "This is the right pattern for a simple poll-until-done loop or a hang safety net — prefer it over looping Sleep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -27,7 +47,7 @@ export const cronCreateToolDef = {
             prompt: { type: "string", description: "The task prompt the agent runs on each execution" },
             timezone: {
                 type: "string",
-                description: "IANA timezone for cron-expression schedules (e.g. 'Asia/Shanghai'). Optional; defaults to UTC.",
+                description: "IANA timezone for cron-expression schedules (e.g. 'Asia/Shanghai'). Optional; defaults to the host system's timezone.",
             },
             cwd: { type: "string", description: "Working directory / project the job runs in. Optional." },
             permissionLevel: {
@@ -36,6 +56,23 @@ export const cronCreateToolDef = {
                 description: "What the job may do: 'read-only' (monitoring; default), 'workspace-write' (edit files), " +
                     "'full' (edit + run git/gh to open PRs). Use the least privilege the task needs.",
             },
+            once: {
+                type: "boolean",
+                description: "true = one-shot: run once at the scheduled time, then auto-delete (for 'in N minutes / " +
+                    "at <time>, do X once' reminders, tasks, or a self-wakeup to re-check a background task). " +
+                    "Default false = recurring per `schedule`. " +
+                    "A one-shot still uses `schedule` for its time: interval '10m' = 10 minutes from now; " +
+                    "cron '0 7 25 6 *' = once at 07:00 on June 25.",
+            },
+            continueInSession: {
+                type: "boolean",
+                description: "true = when the job fires, CONTINUE THE CURRENT conversation: the prompt is appended as " +
+                    "a new user turn to THIS chat session (restored from disk if needed), carrying its full " +
+                    "transcript / goal / context. Set this when the user says things like '一小时后接着做 / " +
+                    "继续 / in this conversation'. Default false = a fresh standalone session per run (right " +
+                    "for independent recurring tasks like daily reports). The current session id is resolved " +
+                    "automatically — you do NOT supply it.",
+            },
         },
         required: ["name", "schedule", "prompt"],
     },
@@ -46,27 +83,48 @@ export async function cronCreateTool(args) {
     const prompt = args.prompt;
     if (!name || !schedule || !prompt)
         return "Error: name, schedule, and prompt are required";
-    const timezone = typeof args.timezone === "string" ? args.timezone : undefined;
+    const timezone = typeof args.timezone === "string"
+        ? args.timezone
+        : (() => {
+            try {
+                return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
     const cwd = typeof args.cwd === "string" ? args.cwd : undefined;
+    const once = args.once === true;
     const permissionLevel = args.permissionLevel === "read-only" ||
         args.permissionLevel === "workspace-write" ||
         args.permissionLevel === "full"
         ? args.permissionLevel
         : undefined;
+    // Resolve "continue this conversation" to the current session id at create
+    // time (the model never supplies it — getCurrentSid() reads the running
+    // Engine's ALS context). Empty/unknown sid → treat as standalone.
+    const resumeSessionId = args.continueInSession === true && getCurrentSid() ? getCurrentSid() : undefined;
     let job;
     try {
         job = cronScheduler.create(name, schedule, prompt, {
             ...(timezone !== undefined ? { timezone } : {}),
             ...(cwd !== undefined ? { cwd } : {}),
             ...(permissionLevel !== undefined ? { permissionLevel } : {}),
+            ...(once ? { once: true } : {}),
+            ...(resumeSessionId !== undefined ? { resumeSessionId } : {}),
         });
     }
     catch (err) {
         return `Error: ${err instanceof Error ? err.message : String(err)}`;
     }
+    fireCronChanged();
     const tz = job.timezone ? ` (${job.timezone})` : "";
     const next = job.nextRun ? new Date(job.nextRun).toLocaleString() : "n/a";
-    return `Cron job #${job.id} "${job.name}" created. Schedule: ${job.schedule}${tz}. Next run: ${next}.`;
+    const cont = job.resumeSessionId ? "(到点续接当前对话,带上下文)" : "";
+    if (job.once) {
+        return `一次性任务 #${job.id} "${job.name}" 已创建${cont}。将于 ${next}${tz} 执行一次后自动删除。`;
+    }
+    return `Cron job #${job.id} "${job.name}" created${cont}. Schedule: ${job.schedule}${tz}. Next run: ${next}.`;
 }
 export const cronDeleteToolDef = {
     name: "CronDelete",
@@ -84,6 +142,8 @@ export async function cronDeleteTool(args) {
     if (!id)
         return "Error: jobId is required";
     const deleted = cronScheduler.delete(id);
+    if (deleted)
+        fireCronChanged();
     return deleted ? `Cron job #${id} deleted.` : `Cron job #${id} not found.`;
 }
 export const cronListToolDef = {

package/dist/tool-system/builtin/drive-claude-code.d.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "../../types.js";
+import type { AgentRunResult } from "../../cc-orchestrator/external-agent-driver.js";
+import type { ToolContext } from "../context.js";
+export type DriveCli = "claude" | "codex";
+export declare const driveAgentToolDef: ToolDefinition;
+type PermMode = "default" | "acceptEdits" | "bypassPermissions";
+type Runner = (opts: {
+    cli: DriveCli;
+    prompt: string;
+    resumeSessionId?: string;
+    cwd: string;
+    permissionMode?: PermMode;
+}) => Promise<AgentRunResult>;
+/** Factory so tests can inject a fake runner. `fixedCli` (back-compat) forces a
+ *  cli and hides the `cli` arg — that's how DriveClaudeCode stays a thin alias. */
+export declare function makeDriveAgentTool(runner?: Runner, fixedCli?: DriveCli): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveAgentTool: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveClaudeCodeToolDef: ToolDefinition;
+/** Back-compat factory: a DriveAgent pinned to cli:"claude" with the `cli` arg
+ *  hidden. The injected `runner` here keeps the old shape (no `cli` field); we
+ *  adapt it to the generic Runner so existing tests' fakes still work. */
+type LegacyRunner = (opts: {
+    prompt: string;
+    resumeSessionId?: string;
+    cwd: string;
+    permissionMode?: PermMode;
+}) => Promise<AgentRunResult>;
+export declare function makeDriveClaudeCodeTool(runner?: LegacyRunner): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveClaudeCodeTool: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export {};

package/dist/tool-system/builtin/drive-claude-code.js

@@ -0,0 +1,157 @@
+import { runAgentOnce } from "../../cc-orchestrator/external-agent-driver.js";
+import { claudeAdapter, codexAdapter } from "../../cc-orchestrator/agent-adapter.js";
+import { backgroundJobRegistry } from "./background-jobs.js";
+import { readExternalChangedFiles } from "../../cc-orchestrator/external-agent-changes.js";
+import { notificationQueue } from "./agent-notifications.js";
+const CLI_ADAPTERS = {
+    claude: { adapter: claudeAdapter, command: "claude" },
+    codex: { adapter: codexAdapter, command: "codex" },
+};
+export const driveAgentToolDef = {
+    name: "DriveAgent",
+    description: "Delegate a task to an external coding-agent CLI — drives `claude` (Claude Code) or `codex` " +
+        "(OpenAI Codex) for one turn. Pick with `cli` (defaults to claude). Use to hand a coding/" +
+        "research task to the agent, or continue an existing session of it. " +
+        "Runs in the BACKGROUND by default — these tasks are typically long (minutes to hours), so this " +
+        "returns immediately and the result is delivered to you later via a completion notification " +
+        "that wakes you. Do NOT sleep-poll for it; just continue or end your turn — you'll be woken " +
+        "with the result. For a quick task where you want the answer inline, pass background:false. " +
+        "It has NO time concept of its own: for 'in N minutes' / 'every N' / looping, use CronCreate " +
+        "instead (never sleep). A scheduled CronCreate job runs one codeshell turn whose prompt can " +
+        "instruct it to call DriveAgent; to continue a prior session across runs, have that turn pass " +
+        "the sessionId this tool returned as resumeSessionId (same cli). To make the single turn work " +
+        "longer/deeper, write that into `prompt` (e.g. 'keep working until done'). " +
+        "Pass `resumeSessionId` to continue a prior session of the SAME cli (keeps context); omit to start fresh.\n" +
+        "SCOPE & BUDGET (read before fanning out): each driven agent consumes a large, SHARED token budget. " +
+        "Do NOT launch many agents at once to 'cover more ground' — that burns the budget and leaves every " +
+        "task half-done. Default to ONE agent at a time; only run a few in parallel when the work TRULY splits " +
+        "into independent pieces, and even then keep the count small (≈2-3). Prefer finishing one task before " +
+        "starting the next. " +
+        "Make each `prompt` a COMPLETE, self-contained task that instructs the agent to finish the whole thing " +
+        "end-to-end and verify its own work before returning — never a vague 'start looking into X'. " +
+        "Give it a concrete definition of done and, for open-ended work, a bound (files/scope/steps) so it " +
+        "doesn't sprawl. If a big job must be split, split it into a SEQUENCE you drive one at a time (resume " +
+        "the same session), not a swarm launched simultaneously.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            prompt: { type: "string", description: "The task for the agent. Make it COMPLETE and self-contained: state the goal, a concrete definition of done, and (for open-ended work) an explicit scope bound so it finishes end-to-end and verifies its own work rather than sprawling or stopping half-way." },
+            cli: { type: "string", enum: ["claude", "codex"], description: "Which external CLI to drive. 'claude' = Claude Code (default), 'codex' = OpenAI Codex. resumeSessionId is only valid against the same cli that produced it." },
+            resumeSessionId: { type: "string", description: "Existing session id to resume (keeps context). Must come from a prior run of the SAME cli. Omit for a fresh session." },
+            cwd: { type: "string", description: "Working directory the run operates in." },
+            permissionMode: { type: "string", enum: ["default", "acceptEdits", "bypassPermissions"], description: "Permission/sandbox level. Defaults to 'bypassPermissions' (full auto — needed so the agent's tools run unattended; there is no interactive approval loop here). For codex: default→read-only sandbox, acceptEdits→workspace-write, bypassPermissions→no sandbox. Pass 'default'/'acceptEdits' to gate." },
+            background: { type: "boolean", description: "Defaults to TRUE: run in the background and notify you on completion (right for long tasks). Pass false to run in the foreground and get the result inline (only for quick tasks)." },
+        },
+        required: ["prompt", "cwd"],
+    },
+};
+const defaultRunner = (opts) => {
+    const { adapter, command } = CLI_ADAPTERS[opts.cli];
+    return runAgentOnce(adapter, { command, prompt: opts.prompt, resumeSessionId: opts.resumeSessionId, cwd: opts.cwd, permissionMode: opts.permissionMode ?? "default" });
+};
+/** Factory so tests can inject a fake runner. `fixedCli` (back-compat) forces a
+ *  cli and hides the `cli` arg — that's how DriveClaudeCode stays a thin alias. */
+export function makeDriveAgentTool(runner = defaultRunner, fixedCli) {
+    return async (args, ctx) => {
+        const prompt = typeof args.prompt === "string" ? args.prompt : "";
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        if (!prompt)
+            return "Error: prompt is required";
+        const cli = fixedCli ?? (args.cli === "codex" ? "codex" : args.cli === "claude" || args.cli === undefined ? "claude" : "invalid");
+        if (cli === "invalid")
+            return `Error: unknown cli "${String(args.cli)}" (expected "claude" or "codex")`;
+        const resumeSessionId = typeof args.resumeSessionId === "string" ? args.resumeSessionId : undefined;
+        // Default to bypassPermissions: this tool is a fire-one-turn delegation to
+        // an external CLI with nobody watching for approvals, and there is no
+        // interactive approval loop here — so under "default" a tool that needs
+        // approval (WebSearch/WebFetch/Write) silently can't run (the
+        // "DriveClaudeCode 没有联网能力" report). A caller that wants gating passes
+        // an explicit mode, which is honored. (For codex, the mode maps to a sandbox
+        // tier inside codexAdapter.)
+        const permissionMode = args.permissionMode === "default" ||
+            args.permissionMode === "acceptEdits" ||
+            args.permissionMode === "bypassPermissions"
+            ? args.permissionMode
+            : "bypassPermissions";
+        const cliName = cli === "codex" ? "Codex" : "Claude Code";
+        const label = `DriveAgent(${cli}): ${prompt.slice(0, 40)}`;
+        // Background by default (these tasks are typically long). Only an explicit
+        // background:false runs in the foreground and returns the result inline.
+        const background = args.background !== false;
+        if (background) {
+            // Fail loud on a missing sessionId: a background job whose completion
+            // notification can't be routed (enqueue drops invalid/empty sessionId)
+            // would run to completion and then silently vanish — nobody gets woken
+            // with the result. Refuse up front instead of launching disappearing work.
+            const sessionId = ctx?.sessionId;
+            if (typeof sessionId !== "string" || sessionId.length === 0) {
+                return `Error: cannot start a background ${cliName} job without a session — its result notification would be dropped. Retry with background:false, or ensure the tool runs inside a session.`;
+            }
+            const jobId = `cc-${process.hrtime.bigint().toString(36)}`;
+            backgroundJobRegistry.start(jobId, sessionId, label);
+            void runner({ cli, prompt, resumeSessionId, cwd, permissionMode })
+                .then((r) => {
+                // Deliver the result back so the woken agent actually sees the answer
+                // (not just "a job finished"). Mirrors the video/sub-agent completion
+                // path — enqueue lands in the same notificationQueue the wakeup drains.
+                notificationQueue.enqueue(r.isError
+                    ? { agentId: jobId, description: label, status: "failed", workKind: "cc", error: r.finalText || "(no output)", ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }
+                    : { agentId: jobId, description: label, status: "completed", workKind: "cc", finalText: r.finalText, ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }, sessionId);
+                // Attribute the files the external agent changed by parsing its own
+                // transcript (#6) — those Edit/Write calls are invisible to the host's
+                // in-session aggregator. Best-effort; [] on any failure.
+                const changedFiles = r.sessionId
+                    ? readExternalChangedFiles(cli, cwd, r.sessionId)
+                    : [];
+                // Retain the job in the panel with its result + the external CLI
+                // session id + changed files.
+                backgroundJobRegistry.finish(jobId, {
+                    status: r.isError ? "failed" : "completed",
+                    finalText: r.finalText || undefined,
+                    ccSessionId: r.sessionId || undefined,
+                    ...(changedFiles.length ? { changedFiles } : {}),
+                });
+            })
+                .catch((err) => {
+                const msg = err?.message ?? String(err);
+                notificationQueue.enqueue({ agentId: jobId, description: label, status: "failed", workKind: "cc", error: msg, enqueuedAt: Date.now() }, sessionId);
+                backgroundJobRegistry.finish(jobId, { status: "failed", finalText: msg });
+            });
+            return `已在后台启动 ${cliName}（jobId ${jobId}）。完成后会通知你结果，无需轮询。`;
+        }
+        const r = await runner({ cli, prompt, resumeSessionId, cwd, permissionMode });
+        if (r.isError)
+            return `${cliName} 运行出错（session ${r.sessionId}）：\n${r.finalText}`;
+        return `${cliName} 完成（session ${r.sessionId}）：\n${r.finalText}`;
+    };
+}
+export const driveAgentTool = makeDriveAgentTool();
+// ── Back-compat: DriveClaudeCode = DriveAgent pinned to cli:"claude" ──────────
+// Kept so old prompts / memories / call sites that reference DriveClaudeCode
+// keep working. It's a thin alias over the same machinery (fixedCli "claude").
+export const driveClaudeCodeToolDef = {
+    ...driveAgentToolDef,
+    name: "DriveClaudeCode",
+    description: "(Alias of DriveAgent with cli:claude.) Delegate a task to the external Claude Code CLI " +
+        "(drives `claude` for one turn). Prefer DriveAgent for new calls; this name is kept for " +
+        "compatibility. " + driveAgentToolDef.description,
+    inputSchema: {
+        type: "object",
+        properties: {
+            // intentionally omit `cli` — this alias is always claude
+            prompt: driveAgentToolDef.inputSchema.properties.prompt,
+            resumeSessionId: { type: "string", description: "Existing CC session id to resume (keeps context). Omit for a fresh session." },
+            cwd: driveAgentToolDef.inputSchema.properties.cwd,
+            permissionMode: driveAgentToolDef.inputSchema.properties.permissionMode,
+            background: driveAgentToolDef.inputSchema.properties.background,
+        },
+        required: ["prompt", "cwd"],
+    },
+};
+export function makeDriveClaudeCodeTool(runner) {
+    const generic = runner
+        ? ({ prompt, resumeSessionId, cwd, permissionMode }) => runner({ prompt, resumeSessionId, cwd, permissionMode })
+        : undefined;
+    return makeDriveAgentTool(generic ?? defaultRunner, "claude");
+}
+export const driveClaudeCodeTool = makeDriveClaudeCodeTool();

package/dist/tool-system/builtin/edit-model-catalog.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../../types.js";
+export declare const editModelCatalogToolDef: ToolDefinition;
+export declare function editModelCatalogTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/edit-model-catalog.js

@@ -0,0 +1,104 @@
+/**
+ * EditModelCatalog tool — add or update a provider/model template in the user
+ * model catalog (~/.code-shell/model-catalog.user.json). Pairs with the
+ * model-fact-finder skill: the skill researches a model's facts (modalities,
+ * params, context), then this tool writes them into a CatalogEntry so the
+ * connection page picks it up. Backs up before writing; validates against the
+ * schema; never touches API keys/credentials (those go through the user's own
+ * Edit, by design). See docs/.../2026-06-15-unified-model-catalog-design.md §7.
+ */
+import { randomBytes } from "node:crypto";
+import { userCatalogPath } from "../../model-catalog/index.js";
+import { saveCatalogEntry } from "../../model-catalog/save-entry.js";
+import { catalogEntrySchema } from "../../model-catalog/types.js";
+export const editModelCatalogToolDef = {
+    name: "EditModelCatalog",
+    description: "Add or update a provider/model template in the user model catalog so it " +
+        "appears in the connection page (text/image/video). Keyed by `id`: a new id " +
+        "adds a provider, an existing id replaces that user-catalog entry. Backs up " +
+        "the file before writing and " +
+        "validates the entry. Use after researching a model's real facts (id, context " +
+        "window, supported params, modalities) — do NOT guess; verify against the " +
+        "provider's official docs first (see the model-fact-finder skill). Does NOT set " +
+        "API keys: the user enters keys in the connection page (credentials), not here.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            entry: {
+                type: "object",
+                description: "A full CatalogEntry. Required: id, tag (text|image|video), adapterKind " +
+                    "(an already-wired adapter: openai|anthropic|google|fal), displayName, " +
+                    "description, defaultBaseUrl. Optional: protocol (openai-compat|anthropic-style), " +
+                    "defaultModel, needsKey, signupUrl, test, modelPresets[] (each {value, label?, " +
+                    "maxContextTokens?, maxOutputTokens?, supportsVision?, params?[]}). Each param: " +
+                    "{name, label?, control (enum|number|toggle|text), options?[], min?, max?, default?, " +
+                    "doc?, wire?{field}}. Fill maxContextTokens with the model's REAL window; declare " +
+                    "params per-model (only what that model supports). To keep a custom provider " +
+                    "beside a built-in one, use a distinct id.",
+            },
+        },
+        required: ["entry"],
+    },
+};
+export async function editModelCatalogTool(args) {
+    const entry = args.entry;
+    if (!entry || typeof entry !== "object") {
+        return "Error: `entry` (a CatalogEntry object) is required.";
+    }
+    const parsed = catalogEntrySchema.safeParse(entry);
+    if (!parsed.success) {
+        return `Error: invalid catalog entry: ${parsed.error.issues.map((i) => i.message).join("; ")}`;
+    }
+    const stamp = `${Date.now()}-${randomBytes(3).toString("hex")}`;
+    const r = saveCatalogEntry(parsed.data, {
+        path: userCatalogPath(),
+        stamp,
+    });
+    if (!r.ok)
+        return `Error: ${r.error}`;
+    return summarizeWrite(parsed.data, r.action ?? "added", r.backup);
+}
+/**
+ * Build a structured completion summary so the user can SEE exactly what was
+ * written and catch a wrong value at a glance — every param's options/default
+ * is echoed back, because that's where catalog entries go wrong (e.g. listing a
+ * gateway's input aliases as if they were the model's native effort levels).
+ * The LLM is told to relay this and ask the user to verify against the docs.
+ */
+function summarizeWrite(entry, action, backup) {
+    const id = entry.id ?? "(unknown)";
+    const lines = [];
+    lines.push(`✅ ${action === "updated" ? "Updated" : "Added"} catalog entry "${id}".`);
+    lines.push(`tag: ${entry.tag ?? "?"} | adapter: ${entry.adapterKind ?? "?"}` +
+        (entry.defaultModel ? ` | defaultModel: ${entry.defaultModel}` : "") +
+        (entry.defaultBaseUrl ? ` | baseUrl: ${entry.defaultBaseUrl}` : ""));
+    const presets = entry.modelPresets ?? [];
+    if (presets.length === 0) {
+        lines.push("(no modelPresets)");
+    }
+    for (const p of presets) {
+        const ctx = p.maxContextTokens ? `ctx ${p.maxContextTokens}` : "";
+        const out = p.maxOutputTokens ? `out ${p.maxOutputTokens}` : "";
+        const limits = [ctx, out].filter(Boolean).join(", ");
+        lines.push(`\nmodel: ${p.value ?? "?"}${p.label ? ` (${p.label})` : ""}${limits ? ` — ${limits}` : ""}`);
+        const params = p.params ?? [];
+        if (params.length === 0) {
+            lines.push("  (no params declared)");
+        }
+        for (const pa of params) {
+            let detail = "";
+            if (pa.control === "enum")
+                detail = `options=[${(pa.options ?? []).join(", ")}]`;
+            else if (pa.control === "number")
+                detail = `range ${pa.min ?? "?"}..${pa.max ?? "?"}`;
+            const def = pa.default !== undefined ? ` default=${JSON.stringify(pa.default)}` : "";
+            lines.push(`  - ${pa.name ?? "?"} (${pa.control ?? "?"}) ${detail}${def}`.trimEnd());
+        }
+    }
+    lines.push(`\nWritten to ${userCatalogPath()}.` + (backup ? ` Backup: ${backup}.` : ""));
+    lines.push("Hot-reloads — the connection page refreshes once this turn completes.");
+    lines.push("⚠️ Relay this summary to the user and ask them to verify each param's options/default " +
+        "match the provider's OFFICIAL docs — especially enum levels (a gateway's input aliases " +
+        "are NOT the model's native values). To fix: edit this file directly, or ask me to.");
+    return lines.join("\n");
+}