@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.0

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

@@ -22,7 +22,11 @@ export const driveAgentToolDef = {
         "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. " +
+        "with the result. " +
+        "Before launching writable work in a cwd, call DriveAgentJobs(action:'list', cwd) to see any " +
+        "already-running DriveAgent jobs there, their prompt summaries, owner sessions, CLI kind, and " +
+        "known changed files; use DriveAgentJobs(action:'cancel', jobId) if you must stop one. " +
+        "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 " +
@@ -55,6 +59,10 @@ export const driveAgentToolDef = {
                 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.",
             },
+            model: {
+                type: "string",
+                description: "Optional model override, passed through to `claude --model` / `codex exec --model`. Omit to use the CLI default; only pass when the user explicitly requests a model.",
+            },
             cwd: { type: "string", description: "Working directory the run operates in." },
             attachmentPaths: {
                 type: "array",
@@ -80,6 +88,7 @@ const defaultRunner = (opts) => {
         command,
         prompt: opts.prompt,
         resumeSessionId: opts.resumeSessionId,
+        model: opts.model,
         cwd: opts.cwd,
         permissionMode: opts.permissionMode ?? "default",
         imagePaths: opts.imagePaths,
@@ -88,6 +97,64 @@ const defaultRunner = (opts) => {
 function newDriveJobId() {
     return `cc-${process.hrtime.bigint().toString(36)}`;
 }
+function summarizePrompt(prompt, max = 120) {
+    const oneLine = prompt.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, Math.max(0, max - 3))}...`;
+}
+function isDriveAgentJob(job) {
+    return job.kind === "drive-agent" || job.description.startsWith("DriveAgent(");
+}
+function changedFilesSummary(job) {
+    const files = job.changedFiles ?? [];
+    if (files.length === 0)
+        return "unknown";
+    if (files.length <= 4)
+        return files.join(",");
+    return `${files.slice(0, 4).join(",")} (+${files.length - 4} more)`;
+}
+/**
+ * Canonicalize external transcript paths against the DriveAgent cwd. Claude
+ * normally records absolute paths while Codex apply_patch normally records
+ * relative paths; returning a cwd-relative display path for in-workspace files
+ * gives the renderer one stable identity and removes duplicate transcript hits.
+ */
+function normalizeChangedFiles(cwd, files) {
+    const seen = new Set();
+    const out = [];
+    for (const file of files) {
+        if (typeof file !== "string" || !file.trim())
+            continue;
+        const absolute = resolve(cwd, file.trim());
+        if (seen.has(absolute))
+            continue;
+        seen.add(absolute);
+        const rel = relative(cwd, absolute);
+        out.push(rel && rel !== ".." && !rel.startsWith(`..${sep}`) ? rel : absolute);
+    }
+    return out;
+}
+function jobDurationSeconds(job) {
+    const end = job.finishedAt ?? Date.now();
+    return `${Math.max(0, (end - job.startedAt) / 1000).toFixed(1)}s`;
+}
+function formatDriveJobListLine(job) {
+    const prompt = job.promptSummary || job.description || "(no prompt summary)";
+    const cwd = job.cwd ?? "(unknown cwd)";
+    const cli = job.cli ?? "unknown";
+    return [
+        `${job.jobId}`,
+        `status=${job.status}`,
+        `cli=${cli}`,
+        `session=${job.sessionId}`,
+        `cwd=${cwd}`,
+        `startedAt=${new Date(job.startedAt).toISOString()}`,
+        `duration=${jobDurationSeconds(job)}`,
+        `changedFiles=${changedFilesSummary(job)}`,
+        `prompt="${prompt}"`,
+    ].join("  ");
+}
 function isValidSessionId(sessionId) {
     return typeof sessionId === "string" && sessionId.length > 0;
 }
@@ -140,8 +207,8 @@ function appendAttachmentPrompt(prompt, paths) {
     }
     return `${prompt}\n${lines.join("\n")}`;
 }
-function recordSuccessfulSession(store, cli, cwd, result) {
-    if (result.isError || !result.sessionId)
+function recordSuccessfulSession(store, cli, cwd, result, includeErroredSession = false) {
+    if ((!includeErroredSession && result.isError) || !result.sessionId)
         return;
     try {
         store.record({ cli, sessionId: result.sessionId, cwd });
@@ -159,17 +226,60 @@ function recordSuccessfulSession(store, cli, cwd, result) {
 function duplicateCwdWarning(cwd, writable) {
     if (!writable)
         return undefined;
-    const running = backgroundJobRegistry.listRunningByCwd(cwd);
+    const running = backgroundJobRegistry.listRunningByCwd(cwd).filter(isDriveAgentJob);
     if (running.length === 0)
         return undefined;
-    const ids = running.map((j) => j.jobId).join(", ");
-    return `Warning: another DriveAgent job is already running in cwd ${cwd} (jobId ${ids}). Concurrent writable agents in the same directory can overwrite each other's work.`;
+    const jobs = running.map(formatDriveJobListLine).join("; ");
+    return (`Warning: another DriveAgent job is already running in cwd ${cwd}. ` +
+        "Concurrent writable agents in the same directory can overwrite each other's work. " +
+        `Run DriveAgentJobs(action:"list", cwd:"${cwd}") before dispatching parallel work for details/cancellation. ` +
+        `Running: ${jobs}`);
 }
 function attachDriveCompletion(params) {
-    const { jobId, sessionId, label, cli, cwd, run, sessionStore } = params;
+    const { jobId, sessionId, label, cli, cwd, run, sessionStore, readChangedFiles, recordExternalFileChanges, originClientMessageId, } = params;
     void run
         .then((r) => {
-        recordSuccessfulSession(sessionStore, cli, cwd, r);
+        const jobStatus = backgroundJobRegistry.get(jobId)?.status;
+        if (jobStatus !== "running" && jobStatus !== "cancelling")
+            return;
+        const cancelling = jobStatus === "cancelling";
+        recordSuccessfulSession(sessionStore, cli, cwd, r, cancelling);
+        // Attribute external changes BEFORE publishing completion. Previously the
+        // notification event was emitted first and carried no files; changedFiles
+        // only reached the background-work registry/panel, so the chat turn card
+        // could never count DriveAgent edits.
+        const rawChangedFiles = r.sessionId ? readChangedFiles(cli, cwd, r.sessionId) : [];
+        const changedFiles = normalizeChangedFiles(cwd, rawChangedFiles);
+        if (changedFiles.length > 0) {
+            recordExternalFileChanges?.({
+                jobId,
+                description: label,
+                cli,
+                cwd,
+                status: cancelling ? "cancelled" : r.isError ? "failed" : "completed",
+                changedFiles,
+                ...(originClientMessageId ? { originClientMessageId } : {}),
+            });
+        }
+        logger.debug("changed_files.drive_completion", {
+            cat: "changed_files",
+            jobId,
+            sessionId,
+            externalSessionId: r.sessionId || undefined,
+            cli,
+            cwd,
+            originClientMessageId,
+            rawSize: rawChangedFiles.length,
+            size: changedFiles.length,
+            files: changedFiles,
+        });
+        if (cancelling) {
+            backgroundJobRegistry.recordArtifacts(jobId, {
+                ccSessionId: r.sessionId || undefined,
+                changedFiles,
+            });
+            return;
+        }
         // 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.
@@ -181,6 +291,8 @@ function attachDriveCompletion(params) {
                 workKind: "cc",
                 error: r.finalText || "(no output)",
                 ccSessionId: r.sessionId || undefined,
+                ...(changedFiles.length ? { changedFiles, cwd } : {}),
+                ...(originClientMessageId ? { originClientMessageId } : {}),
                 enqueuedAt: Date.now(),
             }
             : {
@@ -190,12 +302,10 @@ function attachDriveCompletion(params) {
                 workKind: "cc",
                 finalText: r.finalText,
                 ccSessionId: r.sessionId || undefined,
+                ...(changedFiles.length ? { changedFiles, cwd } : {}),
+                ...(originClientMessageId ? { originClientMessageId } : {}),
                 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, {
@@ -206,6 +316,8 @@ function attachDriveCompletion(params) {
         });
     })
         .catch((err) => {
+        if (backgroundJobRegistry.get(jobId)?.status !== "running")
+            return;
         const msg = err?.message ?? String(err);
         notificationQueue.enqueue({
             agentId: jobId,
@@ -221,8 +333,19 @@ function attachDriveCompletion(params) {
 function trackBackgroundRun(params) {
     const warning = duplicateCwdWarning(params.cwd, params.writable);
     const jobId = newDriveJobId();
-    backgroundJobRegistry.start(jobId, params.sessionId, params.label, { cwd: params.cwd });
-    attachDriveCompletion({ ...params, jobId });
+    const run = params.start();
+    backgroundJobRegistry.start(jobId, params.sessionId, params.label, {
+        kind: "drive-agent",
+        cwd: params.cwd,
+        cli: params.cli,
+        promptSummary: params.promptSummary,
+        originClientMessageId: params.originClientMessageId,
+        abort: async () => {
+            params.abort();
+            await run.catch(() => undefined);
+        },
+    });
+    attachDriveCompletion({ ...params, jobId, run });
     return { jobId, ...(warning ? { warning } : {}) };
 }
 async function waitForForegroundOrHandoff(run, handoffMs) {
@@ -243,6 +366,18 @@ async function waitForForegroundOrHandoff(run, handoffMs) {
             clearTimeout(timer);
     }
 }
+function makeAbortController(parent, linkParent = false) {
+    const controller = new AbortController();
+    if (!parent)
+        return controller;
+    if (parent.aborted) {
+        controller.abort(parent.reason);
+    }
+    else if (linkParent) {
+        parent.addEventListener("abort", () => controller.abort(parent.reason), { once: true });
+    }
+    return controller;
+}
 /** 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, options = {}) {
@@ -261,6 +396,7 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
         if (cli === "invalid")
             return `Error: unknown cli "${String(args.cli)}" (expected "claude" or "codex")`;
         const resumeSessionId = typeof args.resumeSessionId === "string" ? args.resumeSessionId : undefined;
+        const model = typeof args.model === "string" && args.model.trim() ? args.model : undefined;
         const sessionStore = options.sessionStore ?? externalAgentSessionStore;
         let cwd = requestedCwd;
         let resumeNote = "";
@@ -306,13 +442,15 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             : [];
         const cliName = cli === "codex" ? "Codex" : "Claude Code";
         const label = `DriveAgent(${cli}): ${prompt.slice(0, 40)}`;
-        const runOpts = {
+        const promptSummary = summarizePrompt(prompt);
+        const callerSignal = ctx?.signal ?? argSignal(args);
+        const runOptsBase = {
             cli,
             prompt: promptWithAttachments,
             resumeSessionId,
+            model,
             cwd,
             permissionMode,
-            signal: ctx?.signal ?? argSignal(args),
             imagePaths,
         };
         const foregroundHandoffMs = options.foregroundHandoffMs ?? DRIVE_AGENT_FOREGROUND_HANDOFF_MS;
@@ -329,14 +467,20 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
             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 abortController = makeAbortController(callerSignal, false);
             const tracked = trackBackgroundRun({
                 sessionId,
                 label,
                 cli,
                 cwd,
-                run: startRun(runner, runOpts),
+                promptSummary,
+                start: () => startRun(runner, { ...runOptsBase, signal: abortController.signal }),
+                abort: () => abortController.abort(),
                 sessionStore,
                 writable: isWritableRun,
+                readChangedFiles: options.readChangedFiles ?? readExternalChangedFiles,
+                recordExternalFileChanges: ctx?.recordExternalFileChanges,
+                originClientMessageId: ctx?.originClientMessageId,
             });
             return [
                 resumeNote,
@@ -346,7 +490,8 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 .filter(Boolean)
                 .join("\n");
         }
-        const run = startRun(runner, runOpts);
+        const foregroundAbort = makeAbortController(callerSignal, true);
+        const run = startRun(runner, { ...runOptsBase, signal: foregroundAbort.signal });
         const result = await waitForForegroundOrHandoff(run, foregroundHandoffMs);
         if (result.kind === "handoff" && isValidSessionId(ctx?.sessionId)) {
             const tracked = trackBackgroundRun({
@@ -354,9 +499,14 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
                 label,
                 cli,
                 cwd,
-                run,
+                promptSummary,
+                start: () => run,
+                abort: () => foregroundAbort.abort(),
                 sessionStore,
                 writable: isWritableRun,
+                readChangedFiles: options.readChangedFiles ?? readExternalChangedFiles,
+                recordExternalFileChanges: ctx?.recordExternalFileChanges,
+                originClientMessageId: ctx?.originClientMessageId,
             });
             return [
                 resumeNote,
@@ -375,6 +525,142 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {
     };
 }
 export const driveAgentTool = makeDriveAgentTool();
+export const driveAgentJobsToolDef = {
+    name: "DriveAgentJobs",
+    description: "List, inspect, or cancel background DriveAgent jobs. Use action:'list' before launching " +
+        "writable DriveAgent work in a cwd to see already-running jobs there, including prompt " +
+        "summary, owner session, cwd, CLI kind, status, start time, and known changed files. " +
+        "Use action:'inspect' with jobId for full details, or action:'cancel' with jobId to abort " +
+        "a running DriveAgent external CLI process and deliver a cancellation notification.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["list", "inspect", "cancel"],
+                description: "What to do. Defaults to list.",
+            },
+            jobId: {
+                type: "string",
+                description: "DriveAgent jobId for inspect or cancel.",
+            },
+            cwd: {
+                type: "string",
+                description: "When listing, restrict to DriveAgent jobs in this cwd. This is cross-session so it can catch same-directory write conflicts before dispatch.",
+            },
+            status: {
+                type: "string",
+                enum: ["running", "all"],
+                description: "When listing: running (default) or all retained DriveAgent jobs.",
+            },
+            all: {
+                type: "boolean",
+                description: "When listing without cwd: true lists DriveAgent jobs from every session; default lists only this session when session context exists.",
+            },
+        },
+    },
+};
+function jobIdArg(args) {
+    const camel = typeof args.jobId === "string" ? args.jobId.trim() : "";
+    if (camel)
+        return camel;
+    const snake = typeof args.job_id === "string" ? args.job_id.trim() : "";
+    return snake || undefined;
+}
+function listDriveAgentJobs(args, ctx) {
+    const rawCwd = typeof args.cwd === "string" && args.cwd.trim() ? args.cwd : undefined;
+    const cwd = rawCwd ? normalizeCwdPath(rawCwd) : undefined;
+    const sessionId = ctx?.sessionId;
+    const listAllSessions = args.all === true || !!cwd || !sessionId;
+    const status = args.status === "all" ? "all" : "running";
+    let jobs = listAllSessions || !sessionId
+        ? backgroundJobRegistry.list()
+        : backgroundJobRegistry.listForSession(sessionId);
+    jobs = jobs.filter(isDriveAgentJob);
+    if (cwd)
+        jobs = jobs.filter((job) => job.cwd === cwd);
+    if (status === "running") {
+        jobs = jobs.filter((job) => job.status === "running" || job.status === "cancelling");
+    }
+    if (jobs.length === 0) {
+        if (cwd)
+            return `No ${status} DriveAgent jobs in cwd ${cwd}.`;
+        if (listAllSessions)
+            return `No ${status} DriveAgent jobs in this process.`;
+        return `No ${status} DriveAgent jobs in this session.`;
+    }
+    return jobs.map(formatDriveJobListLine).join("\n");
+}
+function inspectDriveAgentJob(jobId) {
+    if (!jobId)
+        return "Error: jobId is required.";
+    const job = backgroundJobRegistry.get(jobId);
+    if (!job || !isDriveAgentJob(job))
+        return `Error: DriveAgent jobId "${jobId}" not found.`;
+    const lines = [
+        `jobId: ${job.jobId}`,
+        `status: ${job.status}`,
+        `cli: ${job.cli ?? "unknown"}`,
+        `session: ${job.sessionId}`,
+        `cwd: ${job.cwd ?? "(unknown cwd)"}`,
+        `startedAt: ${new Date(job.startedAt).toISOString()}`,
+        `duration: ${jobDurationSeconds(job)}`,
+        `prompt: ${job.promptSummary || job.description || "(no prompt summary)"}`,
+        `description: ${job.description}`,
+    ];
+    if (job.finishedAt !== undefined)
+        lines.push(`finishedAt: ${new Date(job.finishedAt).toISOString()}`);
+    if (job.ccSessionId)
+        lines.push(`ccSessionId: ${job.ccSessionId}`);
+    if (job.changedFiles && job.changedFiles.length > 0) {
+        lines.push("changedFiles:", ...job.changedFiles.map((file) => `- ${file}`));
+    }
+    else {
+        lines.push("changedFiles: unknown");
+    }
+    if (job.finalText)
+        lines.push("finalText:", job.finalText);
+    return lines.join("\n");
+}
+async function cancelDriveAgentJob(jobId) {
+    if (!jobId)
+        return "Error: jobId is required.";
+    const job = backgroundJobRegistry.get(jobId);
+    if (!job || !isDriveAgentJob(job))
+        return `Error: DriveAgent jobId "${jobId}" not found.`;
+    if (job.status !== "running") {
+        return `DriveAgent job ${jobId} is already ${job.status}; nothing to cancel.`;
+    }
+    if (!job.abort) {
+        return `Error: DriveAgent job ${jobId} has no cancellation handle recorded.`;
+    }
+    const finalText = `DriveAgent job ${jobId} cancelled by DriveAgentJobs.`;
+    const ok = await backgroundJobRegistry.cancel(jobId, { finalText });
+    if (!ok)
+        return `Failed to cancel DriveAgent job ${jobId}.`;
+    notificationQueue.enqueue({
+        agentId: jobId,
+        description: job.description,
+        status: "cancelled",
+        workKind: "cc",
+        error: finalText,
+        ccSessionId: job.ccSessionId,
+        ...(job.changedFiles?.length ? { changedFiles: job.changedFiles, cwd: job.cwd } : {}),
+        ...(job.originClientMessageId ? { originClientMessageId: job.originClientMessageId } : {}),
+        enqueuedAt: Date.now(),
+    }, job.sessionId);
+    return `DriveAgent job ${jobId} cancelled.`;
+}
+export async function driveAgentJobsTool(args, ctx) {
+    const action = args.action === "inspect" || args.action === "cancel" || args.action === "list"
+        ? args.action
+        : "list";
+    if (action === "inspect")
+        return inspectDriveAgentJob(jobIdArg(args));
+    if (action === "cancel")
+        return await cancelDriveAgentJob(jobIdArg(args));
+    return listDriveAgentJobs(args, ctx);
+}
 // ── 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").
@@ -394,6 +680,7 @@ export const driveClaudeCodeToolDef = {
                 type: "string",
                 description: "Existing CC session id to resume (keeps context). Omit for a fresh session.",
             },
+            model: driveAgentToolDef.inputSchema.properties.model,
             cwd: driveAgentToolDef.inputSchema.properties.cwd,
             attachmentPaths: driveAgentToolDef.inputSchema.properties.attachmentPaths,
             permissionMode: driveAgentToolDef.inputSchema.properties.permissionMode,
@@ -404,7 +691,7 @@ export const driveClaudeCodeToolDef = {
 };
 export function makeDriveClaudeCodeTool(runner, options) {
     const generic = runner
-        ? ({ prompt, resumeSessionId, cwd, permissionMode, signal }) => runner({ prompt, resumeSessionId, cwd, permissionMode, signal })
+        ? ({ prompt, resumeSessionId, model, cwd, permissionMode, signal }) => runner({ prompt, resumeSessionId, model, cwd, permissionMode, signal })
         : undefined;
     return makeDriveAgentTool(generic ?? defaultRunner, "claude", options);
 }

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

@@ -20,12 +20,14 @@ import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanM
 import { toolSearchToolDef, toolSearchTool } from "./tool-search.js";
 import { todoWriteToolDef, todoWriteTool } from "./task.js";
 import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool, switchSessionWorkspaceToolDef, switchSessionWorkspaceTool, } from "./worktree.js";
-import { sleepToolDef, sleepTool } from "./sleep.js";
+import { sleepToolDef } from "./sleep.definition.js";
+import { sleepTool } from "./sleep.js";
 import { configToolDef, configTool } from "./config.js";
 import { notebookEditToolDef, notebookEditTool } from "./notebook-edit.js";
 import { lspToolDef, lspTool } from "./lsp.js";
-import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool, } from "./cron.js";
-import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS, } from "./drive-claude-code.js";
+import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListTool, } from "./cron.js";
+import { cronListToolDef } from "./cron-list.definition.js";
+import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, driveAgentJobsToolDef, driveAgentJobsTool, DRIVE_AGENT_TOOL_TIMEOUT_MS, } from "./drive-claude-code.js";
 import { checkQuotaToolDef, checkQuotaTool } from "./check-quota.js";
 import { skillToolDef, skillTool } from "./skill.js";
 import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool, } from "./mcp-tools.js";
@@ -448,6 +450,16 @@ export const BUILTIN_TOOLS = [
         },
         execute: driveAgentTool,
     },
+    {
+        definition: {
+            ...driveAgentJobsToolDef,
+            source: "builtin",
+            permissionDefault: "allow",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: driveAgentJobsTool,
+    },
     // Back-compat alias: DriveClaudeCode = DriveAgent pinned to cli:claude. Kept
     // registered so old prompts/memories that name DriveClaudeCode still resolve.
     {

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

@@ -1,6 +1,5 @@
 /**
  * SleepTool — pause execution for a specified duration.
  */
-import type { ToolDefinition } from "../../types.js";
-export declare const sleepToolDef: ToolDefinition;
+export { sleepToolDef } from "./sleep.definition.js";
 export declare function sleepTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/sleep.definition.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sleep tool metadata.
+ *
+ * Kept separate from the executor so registration and presets can consume the
+ * definition without importing implementation code.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const sleepToolDef: ToolDefinition;

package/dist/tool-system/builtin/sleep.definition.js

@@ -0,0 +1,28 @@
+/**
+ * Sleep tool metadata.
+ *
+ * Kept separate from the executor so registration and presets can consume the
+ * definition without importing implementation code.
+ */
+export const sleepToolDef = {
+    name: "Sleep",
+    description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
+        "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
+        "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
+        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
+        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
+        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
+        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
+        "That returns control to you at the interval without burning a turn spinning. " +
+        "Maximum duration is 300 seconds (5 minutes).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            seconds: {
+                type: "number",
+                description: "Number of seconds to sleep (max 300)",
+            },
+        },
+        required: ["seconds"],
+    },
+};

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

@@ -1,28 +1,7 @@
 /**
  * SleepTool — pause execution for a specified duration.
  */
-export const sleepToolDef = {
-    name: "Sleep",
-    description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
-        "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
-        "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
-        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
-        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
-        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
-        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
-        "That returns control to you at the interval without burning a turn spinning. " +
-        "Maximum duration is 300 seconds (5 minutes).",
-    inputSchema: {
-        type: "object",
-        properties: {
-            seconds: {
-                type: "number",
-                description: "Number of seconds to sleep (max 300)",
-            },
-        },
-        required: ["seconds"],
-    },
-};
+export { sleepToolDef } from "./sleep.definition.js";
 export async function sleepTool(args) {
     const seconds = Math.min(Math.max(Number(args.seconds) || 1, 0.1), 300);
     const signal = args.__signal;

package/dist/tool-system/context.d.ts

@@ -184,6 +184,15 @@ export interface ToolVisibilityContext {
     hasGoal: boolean;
     settingsScope?: import("../settings/manager.js").SettingsScope;
 }
+export interface ExternalFileChangesRecord {
+    jobId: string;
+    description: string;
+    cli: "claude" | "codex";
+    cwd: string;
+    status: "completed" | "failed" | "cancelled";
+    changedFiles: string[];
+    originClientMessageId?: string;
+}
 export interface ToolContext {
     /** Active working directory for this Engine. */
     cwd: string;
@@ -261,6 +270,15 @@ export interface ToolContext {
      * narrow context, or standalone tool tests. (B2 — Gate 1, standard §S3.)
      */
     sessionId?: string;
+    /** Stable id of the real user turn that owns async work launched here. */
+    originClientMessageId?: string;
+    /**
+     * Persist file attribution from an async external DriveAgent completion in
+     * the owning CodeShell transcript. The callback closes over the live parent
+     * transcript, so a background job can record its files after the run that
+     * launched it has already returned.
+     */
+    recordExternalFileChanges?: (record: ExternalFileChangesRecord) => void;
     /**
      * Skill names the user has hidden from the LLM (full namespaced names
      * for plugin skills, e.g. "docs:pdf"). The skill builtin tool uses

package/dist/tool-system/mcp-manager.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
 import type { MCPServerConfig, RegisteredTool } from "../types.js";
+import type { CredentialType } from "../credentials/types.js";
 import { ToolRegistry } from "./registry.js";
 import { type CredentialAccess } from "../credentials/access.js";
 interface MCPResourceInfo {
@@ -21,6 +22,16 @@ interface MCPResourceInfo {
  * and the env var.
  */
 export declare function readRequiredEnv(serverName: string, field: string, envName: string): string;
+export interface ResolvedMcpCredential {
+    secret: string;
+    type?: CredentialType;
+    label?: string;
+}
+export type HttpCredentialResolverResult = string | ResolvedMcpCredential | undefined;
+export interface BuildHttpHeadersOptions {
+    now?: () => number;
+    oauthRefreshSkewMs?: number;
+}
 /**
  * Build the spawned stdio server's environment. Priority (lowest → highest):
  * a minimal inherited allowlist < forwarded `envVars` (read from process.env by
@@ -34,8 +45,9 @@ export declare function buildStdioEnv(serverName: string, config: MCPServerConfi
  * base; env-sourced secrets (`bearerTokenEnvVar`, `envHeaders`) layer on top
  * and win on conflict. Pure + exported for unit testing.
  */
-export declare function buildHttpHeaders(serverName: string, config: MCPServerConfig, resolveCredential?: (id: string) => string | undefined): Record<string, string>;
-export declare function buildHttpHeadersWithCredentialAccess(serverName: string, config: MCPServerConfig, access?: Pick<CredentialAccess, "resolveValue">): Promise<Record<string, string>>;
+export declare function buildHttpHeaders(serverName: string, config: MCPServerConfig, resolveCredential?: (id: string) => HttpCredentialResolverResult, options?: BuildHttpHeadersOptions): Record<string, string>;
+export declare function bearerTokenFromMcpCredential(serverName: string, credentialId: string, credential: ResolvedMcpCredential, options?: BuildHttpHeadersOptions): string;
+export declare function buildHttpHeadersWithCredentialAccess(serverName: string, config: MCPServerConfig, access?: Pick<CredentialAccess, "resolveValue"> & Partial<Pick<CredentialAccess, "resolveMeta">>, options?: BuildHttpHeadersOptions): Promise<Record<string, string>>;
 /**
  * Infer the transport when the config doesn't name one: a url-only entry is
  * HTTP, everything else stdio. This is the CC `.mcp.json` convention —