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

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

@@ -6,7 +6,7 @@
  * Supports AbortSignal for cascading cancellation.
  * Supports onStream for real-time output passthrough.
  */
-import { asyncAgentRegistry } from "./agent-registry.js";
+import { asyncAgentRegistry, MAX_BACKGROUND_AGENTS } from "./agent-registry.js";
 import { createTranscriptTranslator } from "./agent-transcript-translator.js";
 import { notificationQueue } from "./agent-notifications.js";
 import { nanoid } from "nanoid";
@@ -32,18 +32,107 @@ function safeEmit(sink, event) {
         });
     }
 }
+/** Preferred default role when the caller omits agent_type but roles exist. */
+const DEFAULT_AGENT_TYPE = "general-purpose";
+/**
+ * Resolve an `agent_type` against the role registry into spawn overrides.
+ *
+ * - Omitted type + non-empty registry → fall back to a configured role
+ *   ("general-purpose" if present, else the first available) instead of
+ *   running a nameless ephemeral agent. Relaxed from the earlier "throw when
+ *   agent_type omitted": the model habitually omits it, and a hard error just
+ *   turned every spawn into a failure. Falling back to a real role keeps the
+ *   tool-allowlist / system-prompt benefits without breaking the call.
+ * - Omitted type + empty registry → empty overrides (true ephemeral; nothing
+ *   to fall back to).
+ * - Unknown explicit type → throw, so the LLM gets a clear correction rather
+ *   than silently running a generic agent.
+ */
+export function resolveAgentTypeOverrides(agentType, registry) {
+    const available = registry?.list().map((d) => d.name) ?? [];
+    let resolvedType = agentType;
+    if (!resolvedType) {
+        if (available.length === 0)
+            return {};
+        resolvedType = available.includes(DEFAULT_AGENT_TYPE) ? DEFAULT_AGENT_TYPE : available[0];
+    }
+    const def = registry?.get(resolvedType);
+    if (!def) {
+        const list = available.join(", ") || "(none defined)";
+        throw new Error(`unknown agent_type '${resolvedType}'. Available: ${list}`);
+    }
+    return {
+        resolvedType,
+        model: def.model,
+        maxTurns: def.maxTurns,
+        toolAllowlist: def.tools,
+        appendSystemPrompt: def.systemPrompt,
+    };
+}
+/**
+ * Render the "Available agent types" block injected into the Agent tool's
+ * description, listing the roles defined in .code-shell/agents/*.md so the
+ * model knows it can pass `agent_type` instead of hand-rolling an ad-hoc
+ * agent. Without this the model never sees the registry (it lives per-engine,
+ * not in the static tool def) and falls back to nameless ephemeral agents —
+ * see the Core A/B/C incident. Returns "" when no roles are defined, so the
+ * base description is left untouched.
+ */
+export function buildAgentTypesBlock(registry) {
+    const defs = registry?.list() ?? [];
+    if (defs.length === 0)
+        return "";
+    const lines = defs.map((d) => {
+        const tools = d.tools && d.tools.length > 0 ? d.tools.join(", ") : "all parent tools";
+        return `- ${d.name}: ${d.description} (tools: ${tools})`;
+    });
+    return [
+        "",
+        "Available agent types (pass one as `agent_type` to reuse its role, tool allowlist, and turn cap):",
+        ...lines,
+        "Pass the closest matching agent_type (e.g. read-only investigation → researcher/explorer, planning → planner, full multi-step work → general-purpose). If you omit agent_type it defaults to general-purpose (or the first available role) — passing an explicit one is preferred.",
+    ].join("\n");
+}
+/**
+ * Produce an Agent tool definition whose description ends with the live
+ * available-agent-types listing. Pure: takes the registry, returns a new def
+ * (the base `agentToolDef` const is never mutated). When no roles exist the
+ * base def is returned unchanged.
+ */
+export function agentToolDefWithTypes(registry) {
+    const block = buildAgentTypesBlock(registry);
+    if (!block)
+        return agentToolDef;
+    return { ...agentToolDef, description: agentToolDef.description + "\n" + block };
+}
+/**
+ * Emit a sub-agent lifecycle event via the existing `notification` hook,
+ * tagged with a `kind`. No-op when hooks are absent. Fire-and-forget: emit is
+ * async, we deliberately `void` it so bookkeeping never blocks on a handler
+ * (mirrors the background-completion notification below).
+ */
+export function emitSubAgentHook(hooks, kind, payload) {
+    void hooks?.emit("notification", { kind, ...payload });
+}
 export const agentToolDef = {
     name: "Agent",
-    description: "Launch a sub-agent to handle a complex task autonomously. " +
-        "The sub-agent has access to the same tools and runs independently. " +
-        "Use this for tasks that can be delegated, parallelized, or require deep exploration. " +
-        "Provide a clear, complete description of what the agent should do.\n\n" +
-        "When you launch multiple agents for independent work, send them in a single " +
-        "message with multiple tool uses so they run concurrently.\n\n" +
-        "You can optionally run agents in the background using the run_in_background " +
-        "parameter. When an agent runs in the background, you will be automatically " +
-        "notified when it completes — do NOT sleep, poll, or proactively check on its " +
-        "progress. Continue with other work or respond to the user instead.",
+    description: "Launch a sub-agent to handle a task in its own clean, isolated context. " +
+        "The sub-agent runs independently with access to the same tools, and its final " +
+        "report is the ONLY thing returned to you — it is stateless, so you cannot send " +
+        "follow-up messages. Write a complete, self-contained task description.\n\n" +
+        "PRIMARY USE — context isolation: when a task needs to read many files or run a " +
+        "broad investigation but you only need the conclusion, delegate it. The sub-agent " +
+        "absorbs the noisy intermediate output in its own context; you keep the answer, not " +
+        "the file dumps. This protects your main context from being flooded.\n\n" +
+        "DON'T use this for a quick lookup where you know the file/symbol and expect a few " +
+        "matches — use Read/Grep/Glob directly instead; spawning an agent wastes a turn.\n\n" +
+        "Parallel fan-out is the EXCEPTION: only launch several agents in one message when " +
+        "the work truly splits into independent pieces with no shared state. Prefer one " +
+        "well-scoped delegation over a swarm.\n\n" +
+        "You can optionally run an agent in the background using the run_in_background " +
+        "parameter. When it runs in the background, you will be automatically notified when " +
+        "it completes — do NOT sleep, poll, or proactively check on its progress. Continue " +
+        "with other work or respond to the user instead.",
     inputSchema: {
         type: "object",
         properties: {
@@ -53,6 +142,15 @@ export const agentToolDef = {
                     "Shown in the agent dock to identify what kind of work this sub-agent is doing. " +
                     "Keep it 1-2 words. Defaults to 'Agent' if omitted.",
             },
+            agent_type: {
+                type: "string",
+                description: "Optional reusable role defined in .code-shell/agents/*.md (e.g. 'researcher'). " +
+                    "Loads that role's model, tool allowlist, turn cap, and system prompt. " +
+                    "Disabled roles are not available. If you pass an unknown role you'll get " +
+                    "an error listing the currently available roles. " +
+                    "If omitted, defaults to a configured role (general-purpose or the first available); " +
+                    "with no roles configured it runs an ephemeral agent. Passing an explicit role is preferred.",
+            },
             description: {
                 type: "string",
                 description: "A short (3-5 word) description of the task",
@@ -97,16 +195,18 @@ uiStream,
  * sub-agents.
  */
 streamOverride) {
-    const { agentId, name, description } = opts;
+    const { agentId, name, description, agentType } = opts;
     const startEndSink = uiStream ?? spawner.parentStream;
-    safeEmit(startEndSink, { type: "agent_start", agentId, name, description });
+    safeEmit(startEndSink, { type: "agent_start", agentId, name, description, agentType });
+    emitSubAgentHook(opts.hooks, "subagent_start", { agentId, description });
     // `resetPlanMode` / `restorePlanMode` operated on a module-level singleton
     // that no longer exists. The child Engine is a fresh instance; plan-mode
     // isolation between parent and child is enforced via separate Engine
     // instances (finalized in T6).
     const text = await spawner.spawn({ ...opts, streamOverride });
     const finalText = text || `Agent completed but produced no text output.`;
-    safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText });
+    safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText, agentType });
+    emitSubAgentHook(opts.hooks, "subagent_finish", { agentId, description, text: finalText });
     return finalText;
 }
 export async function agentTool(args, ctx) {
@@ -132,7 +232,15 @@ export async function agentTool(args, ctx) {
     if (parentSignal?.aborted) {
         return "Agent aborted before starting.";
     }
-    const maxTurns = args.max_turns || 15;
+    const agentType = args.agent_type?.trim() || undefined;
+    let overrides;
+    try {
+        overrides = resolveAgentTypeOverrides(agentType, ctx?.agentDefinitions);
+    }
+    catch (err) {
+        return `Error: ${err.message}`;
+    }
+    const maxTurns = args.max_turns || overrides.maxTurns || 15;
     const runInBackground = args.run_in_background === true;
     const agentId = nanoid(8);
     const parentStream = spawner.parentStream;
@@ -142,11 +250,19 @@ export async function agentTool(args, ctx) {
     // (background agents survive the spawning turn). Cancellation goes
     // through AgentCancel(agent_id).
     if (runInBackground) {
+        if (asyncAgentRegistry.runningCount() >= MAX_BACKGROUND_AGENTS) {
+            return `Error: too many background agents running (limit ${MAX_BACKGROUND_AGENTS}). ` +
+                `Wait for some to finish or cancel one with AgentCancel(agent_id) before launching more.`;
+        }
         const controller = new AbortController();
         asyncAgentRegistry.register({
             agentId,
             name,
+            agentType: overrides.resolvedType,
             description,
+            // Tag with the spawning session so the parent Engine.run waits only on
+            // its own background agents (hasRunningForSession).
+            sessionId: ctx?.sessionId,
             status: "running",
             startedAt: Date.now(),
             abort: () => controller.abort(),
@@ -169,8 +285,14 @@ export async function agentTool(args, ctx) {
             agentId,
             name,
             description,
+            agentType: overrides.resolvedType,
             prompt,
             maxTurns,
+            model: overrides.model,
+            toolAllowlist: overrides.toolAllowlist,
+            appendSystemPrompt: overrides.appendSystemPrompt,
+            readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
+            hooks: ctx?.hooks,
             signal: controller.signal,
         }, parentStream, // uiStream: agent_start/end → main feed
         transcriptSink)
@@ -262,22 +384,48 @@ export async function agentTool(args, ctx) {
         ].join("\n");
     }
     // ─── Synchronous path ──────────────────────────────────────────
+    // No wall-clock timeout on the sub-agent lifecycle — that matches Claude
+    // Code / Codex, where a sub-agent (Task) is bounded by maxTurns + per-tool
+    // timeouts (Bash etc. carry their own) + parent/user abort, NOT by a global
+    // countdown that kills legitimate heavy work mid-task. The old
+    // runWithTimeout(5min) both (a) murdered a "read 40 files" agent at 5:00 and
+    // (b) raced with the normal completion path: the timeout aborted the child,
+    // the catch emitted agent_end{error}, AND the aborted child still let
+    // runSubAgent reach its line-280 agent_end{text} — two agent_end events for
+    // one agent, the later text one overwriting the error so a timed-out agent
+    // rendered as "done". Dropping the timeout removes the race entirely: a
+    // genuine spawn error throws BEFORE the success emit, so only the catch
+    // fires; a clean run emits agent_end{text} exactly once. (fix:
+    // subagent-timeout-double-agent-end)
+    const syncController = new AbortController();
+    const onParentAbort = () => syncController.abort();
+    parentSignal?.addEventListener("abort", onParentAbort, { once: true });
     try {
         return await runSubAgent(spawner, {
             agentId,
             name,
             description,
+            agentType: overrides.resolvedType,
             prompt,
             maxTurns,
-            signal: parentSignal ?? new AbortController().signal,
+            model: overrides.model,
+            toolAllowlist: overrides.toolAllowlist,
+            appendSystemPrompt: overrides.appendSystemPrompt,
+            readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
+            hooks: ctx?.hooks,
+            signal: syncController.signal,
         });
     }
     catch (err) {
-        safeEmit(parentStream, { type: "agent_end", agentId, name, description, error: err.message });
+        emitSubAgentHook(ctx?.hooks, "subagent_error", { agentId, description, error: err.message });
+        safeEmit(parentStream, { type: "agent_end", agentId, name, description, error: err.message, agentType: overrides.resolvedType });
         if (parentSignal?.aborted)
             return "Agent was aborted.";
         return `Agent error: ${err.message}`;
     }
+    finally {
+        parentSignal?.removeEventListener("abort", onParentAbort);
+    }
 }
 // ─── AgentStatus / AgentCancel — companions to run_in_background ─
 export const agentStatusToolDef = {

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

@@ -17,6 +17,8 @@
 import { fileCache } from "../file-cache.js";
 import { applyPatch } from "./applier.js";
 import { parsePatch } from "./parser.js";
+import { enforcePathPolicy } from "../../path-policy.js";
+import { resolve as resolvePath } from "node:path";
 export const applyPatchToolDef = {
     name: "ApplyPatch",
     description: "Apply a V4A-format patch atomically across one or more files. " +
@@ -68,6 +70,20 @@ export async function applyPatchTool(args, ctx) {
     // A4: resolve relative patch paths against the Engine's cwd, not the
     // host process cwd. See standard §S5.
     const cwd = ctx?.cwd ?? process.cwd();
+    // Path-policy gate every target before any IO. A multi-file patch is
+    // atomic — if *any* target is blocked the whole patch must reject so we
+    // don't end up writing some files and refusing others.
+    for (const hunk of parsed.hunks) {
+        const targets = [resolvePath(cwd, hunk.path)];
+        if (hunk.kind === "update" && hunk.movePath) {
+            targets.push(resolvePath(cwd, hunk.movePath));
+        }
+        for (const t of targets) {
+            const blocked = enforcePathPolicy(t, "write", cwd);
+            if (blocked)
+                return blocked;
+        }
+    }
     let result;
     try {
         result = await applyPatch(parsed.hunks, { cwd });
@@ -75,11 +91,14 @@ export async function applyPatchTool(args, ctx) {
     catch (err) {
         return `Error applying patch: ${err.message}`;
     }
-    // Invalidate file cache for every touched path.
+    // Invalidate file cache for every touched path. The cache is keyed by
+    // ABSOLUTE path (see file-cache.ts), and patch paths are relative to the
+    // Engine cwd — resolve them the same way the path-policy gate did above, or
+    // the stale entry survives and a later Read returns pre-patch content.
     for (const hunk of parsed.hunks) {
-        fileCache.invalidate(hunk.path);
+        fileCache.invalidate(resolvePath(cwd, hunk.path));
         if (hunk.kind === "update" && hunk.movePath) {
-            fileCache.invalidate(hunk.movePath);
+            fileCache.invalidate(resolvePath(cwd, hunk.movePath));
         }
     }
     const parts = [];

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

@@ -123,9 +123,8 @@ function resolveParticipant(nameOrPath, llmConfig, pool) {
                 maxTokens: preset.maxOutputTokens,
                 baseUrl: fallbackBaseUrl,
                 apiKey: fallbackApiKey,
-                temperature: ARENA_TEMPERATURE,
-                enableStreaming: false,
             },
+            clientDefaults: { temperature: ARENA_TEMPERATURE },
         };
     }
     // (3) Raw model path
@@ -138,9 +137,8 @@ function resolveParticipant(nameOrPath, llmConfig, pool) {
             maxTokens: getMaxOutputTokens(nameOrPath),
             baseUrl: fallbackBaseUrl,
             apiKey: fallbackApiKey,
-            temperature: ARENA_TEMPERATURE,
-            enableStreaming: false,
         },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
     };
 }
 function participantFromPool(entry, llmConfig) {
@@ -156,9 +154,8 @@ function participantFromPool(entry, llmConfig) {
             maxTokens: entry.maxOutputTokens ?? getMaxOutputTokens(entry.model),
             baseUrl: entry.baseUrl ?? llmConfig.baseUrl,
             apiKey: entry.apiKey ?? llmConfig.apiKey,
-            temperature: ARENA_TEMPERATURE,
-            enableStreaming: false,
         },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
     };
 }
 /**
@@ -411,6 +408,8 @@ export async function arenaTool(args, ctx) {
     catch (err) {
         if (signal?.aborted)
             return "Arena aborted.";
-        return `Arena error: ${err.message}`;
+        // err may be a non-Error (string/null); `(err as Error).message` would be
+        // undefined → "Arena error: undefined", masking the real cause.
+        return `Arena error: ${err instanceof Error ? err.message : String(err)}`;
     }
 }

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

@@ -0,0 +1,25 @@
+/**
+ * complete_goal — Goal mode P0.
+ *
+ * The model calls this to explicitly DECLARE the current goal complete
+ * (mirrors Codex's update_goal(status=Complete)). When the turn loop sees
+ * this tool call it short-circuits to a "completed" stop WITHOUT running the
+ * judge LLM (wired in Task 4). This tool itself just records an
+ * acknowledgement string into the transcript; the loop-level short-circuit
+ * lives in turn-loop.ts.
+ *
+ * Shape note: builtin tools in this codebase are a `ToolDefinition`
+ * (name/description/inputSchema only — see types.ts) plus a separate executor
+ * `(args: Record<string, unknown>) => Promise<string>`. The runtime metadata
+ * (source/permissionDefault/isReadOnly/...) is attached in builtin/index.ts at
+ * registration time, NOT on the def. Registration is Task 6.
+ */
+import type { ToolDefinition } from "../../types.js";
+/**
+ * The tool name, shared with turn-loop.ts's short-circuit check so a rename
+ * can't silently break completion detection (the name lives in exactly one
+ * place).
+ */
+export declare const COMPLETE_GOAL_TOOL_NAME = "complete_goal";
+export declare const completeGoalToolDef: ToolDefinition;
+export declare function completeGoalTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,45 @@
+/**
+ * complete_goal — Goal mode P0.
+ *
+ * The model calls this to explicitly DECLARE the current goal complete
+ * (mirrors Codex's update_goal(status=Complete)). When the turn loop sees
+ * this tool call it short-circuits to a "completed" stop WITHOUT running the
+ * judge LLM (wired in Task 4). This tool itself just records an
+ * acknowledgement string into the transcript; the loop-level short-circuit
+ * lives in turn-loop.ts.
+ *
+ * Shape note: builtin tools in this codebase are a `ToolDefinition`
+ * (name/description/inputSchema only — see types.ts) plus a separate executor
+ * `(args: Record<string, unknown>) => Promise<string>`. The runtime metadata
+ * (source/permissionDefault/isReadOnly/...) is attached in builtin/index.ts at
+ * registration time, NOT on the def. Registration is Task 6.
+ */
+/**
+ * The tool name, shared with turn-loop.ts's short-circuit check so a rename
+ * can't silently break completion detection (the name lives in exactly one
+ * place).
+ */
+export const COMPLETE_GOAL_TOOL_NAME = "complete_goal";
+export const completeGoalToolDef = {
+    name: COMPLETE_GOAL_TOOL_NAME,
+    description: "声明当前目标已完全达成。仅当目标确实完整完成时才调用本工具(模型在目标完全达成时显式调用以声明完成)。" +
+        "调用后应当停止。可选传入 summary 作为一句话完成总结。\n" +
+        "Declare the current goal complete. Call this ONLY when the goal is fully achieved. " +
+        "After calling, you should stop. Optionally pass a one-line summary of what was accomplished.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "可选:一句话总结所完成的工作。Optional one-line summary of what was accomplished.",
+            },
+        },
+        required: [],
+    },
+};
+export async function completeGoalTool(args) {
+    const summary = typeof args.summary === "string" ? args.summary.trim() : "";
+    return summary
+        ? `目标已完成 (goal complete). Summary: ${summary}`
+        : "目标已完成 (goal complete).";
+}

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

@@ -1,17 +1,41 @@
 /**
  * Cron tools — CronCreate, CronDelete, CronList.
  */
-import { cronScheduler } from "../../cron/scheduler.js";
+import { cronScheduler } from "../../automation/scheduler.js";
 export const cronCreateToolDef = {
     name: "CronCreate",
-    description: "Create a scheduled recurring task. The task will run automatically at the specified interval. " +
-        "Schedule format: '30s', '5m', '1h', '1d'.",
+    description: "Create a scheduled automation job that runs a prompt on a recurring schedule. " +
+        "Use this when the user asks to set up a recurring/automated/scheduled task " +
+        "(monitoring, daily reports, periodic checks, etc.).\n\n" +
+        "Translate the user's natural-language timing into the `schedule` field. Two forms:\n" +
+        "  • Interval: '30s', '5m', '1h', '1d' (runs every N from creation).\n" +
+        "  • Cron expression (5 fields: minute hour day-of-month month day-of-week) for " +
+        "calendar times. Examples: '0 9 * * 1-5' = 9am every weekday; '0 */6 * * *' = every 6 hours; " +
+        "'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.",
     inputSchema: {
         type: "object",
         properties: {
-            name: { type: "string", description: "Name for the cron job" },
-            schedule: { type: "string", description: "Interval (e.g. '5m', '1h', '30s')" },
-            prompt: { type: "string", description: "The task prompt to run on each execution" },
+            name: { type: "string", description: "Short human-readable name for the job (e.g. '工作日晨间简报')" },
+            schedule: {
+                type: "string",
+                description: "Interval ('5m','1h','1d') or a 5-field cron expression ('0 9 * * 1-5'). " +
+                    "Derive this from the user's described timing.",
+            },
+            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.",
+            },
+            cwd: { type: "string", description: "Working directory / project the job runs in. Optional." },
+            permissionLevel: {
+                type: "string",
+                enum: ["read-only", "workspace-write", "full"],
+                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.",
+            },
         },
         required: ["name", "schedule", "prompt"],
     },
@@ -22,8 +46,27 @@ export async function cronCreateTool(args) {
     const prompt = args.prompt;
     if (!name || !schedule || !prompt)
         return "Error: name, schedule, and prompt are required";
-    const job = cronScheduler.create(name, schedule, prompt);
-    return `Cron job #${job.id} "${job.name}" created. Schedule: every ${job.schedule}.`;
+    const timezone = typeof args.timezone === "string" ? args.timezone : undefined;
+    const cwd = typeof args.cwd === "string" ? args.cwd : undefined;
+    const permissionLevel = args.permissionLevel === "read-only" ||
+        args.permissionLevel === "workspace-write" ||
+        args.permissionLevel === "full"
+        ? args.permissionLevel
+        : undefined;
+    let job;
+    try {
+        job = cronScheduler.create(name, schedule, prompt, {
+            ...(timezone !== undefined ? { timezone } : {}),
+            ...(cwd !== undefined ? { cwd } : {}),
+            ...(permissionLevel !== undefined ? { permissionLevel } : {}),
+        });
+    }
+    catch (err) {
+        return `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    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}.`;
 }
 export const cronDeleteToolDef = {
     name: "CronDelete",
@@ -55,7 +98,8 @@ export async function cronListTool(_args) {
     const lines = jobs.map((j) => {
         const status = j.enabled ? "active" : "paused";
         const lastRun = j.lastRun ? new Date(j.lastRun).toLocaleString() : "never";
-        return `  #${j.id} "${j.name}" [${status}] every ${j.schedule} | runs: ${j.runCount} | last: ${lastRun}`;
+        const tz = j.timezone ? ` ${j.timezone}` : "";
+        return `  #${j.id} "${j.name}" [${status}] ${j.schedule}${tz} | runs: ${j.runCount} | last: ${lastRun}`;
     });
     return `Cron Jobs (${jobs.length}):\n${lines.join("\n")}`;
 }

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

@@ -2,5 +2,6 @@
  * Built-in Edit file tool — exact string replacement.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const editToolDef: ToolDefinition;
-export declare function editTool(args: Record<string, unknown>): Promise<string>;
+export declare function editTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -4,6 +4,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const editToolDef = {
     name: "Edit",
     description: "Perform exact string replacements in a file. " +
@@ -30,7 +31,7 @@ export const editToolDef = {
         required: ["file_path", "old_string", "new_string"],
     },
 };
-export async function editTool(args) {
+export async function editTool(args, ctx) {
     const filePath = args.file_path;
     const oldString = args.old_string;
     const newString = args.new_string;
@@ -45,6 +46,10 @@ export async function editTool(args) {
         return "Error: old_string and new_string must be different";
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
+    // Path policy gate before any IO.
+    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
+    if (blocked)
+        return blocked;
     try {
         const content = await readFile(filePath, "utf-8");
         if (!content.includes(oldString)) {

package/dist/tool-system/builtin/generate-image.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in GenerateImage tool — text-to-image via the OpenAI Images API
+ * (`gpt-image-2`).
+ *
+ * Credentials come from config, not env: the tool finds the `kind: "openai"`
+ * entry in `settings.providers[]` and uses its `apiKey` + `baseUrl`. No
+ * `OPENAI_API_KEY` required, no new config — an existing OpenAI provider is
+ * reused as-is.
+ *
+ * The generated PNG is decoded from the API's base64 payload and written to
+ * `<cwd>/.code-shell/generated_images/<timestamp>.png`; the tool returns the
+ * absolute path so the model can Read or reference it on later turns. This
+ * mirrors codex's imagegen CLI fallback (`scripts/image_gen.py`): call API →
+ * take b64_json → decode → write → report path.
+ *
+ * Scope is deliberately narrow (text-to-image only). Edit/mask/transparent/
+ * batch are out of scope — see the design doc.
+ *
+ * Uses the native `fetch` (codeshell does not depend on the `openai` SDK).
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const generateImageToolDef: ToolDefinition;
+export declare function isGenerateImageAvailable(cwd?: string, nowMs?: number): boolean;
+export declare function generateImageTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;