@sayknow-cli/coding-agent 0.3.1 → 0.3.4

package/src/tools/ask.ts

@@ -260,7 +260,11 @@ async function askSingleQuestion(
 			? "up/down navigate  enter select  ←/→ question  esc cancel"
 			: "up/down navigate  enter select  esc cancel";
 		const helpText =
-			scrollTitleRows === undefined ? baseHelpText : `${baseHelpText}  wheel/PgUp/PgDn scroll question`;
+			scrollTitleRows === undefined
+				? baseHelpText
+				: navigation
+					? "↑/↓ select  enter  ←/→ question  esc  PgUp/PgDn/Ctrl+u/d: question · Wheel: transcript"
+					: "↑/↓ select  enter  esc  PgUp/PgDn/Ctrl+u/d: question · Wheel: transcript";
 		const dialogOptions = {
 			initialIndex,
 			timeout,

package/src/tools/bash.ts

@@ -25,6 +25,7 @@ import { type BashInteractiveResult, runInteractiveBashPty } from "./bash-intera
 import { checkBashInterception } from "./bash-interceptor";
 import { canUseInteractiveBashPty } from "./bash-pty-selection";
 import { expandInternalUrls, type InternalUrlExpansionOptions } from "./bash-skill-urls";
+import { checkComposerBashPolicy } from "./composer-bash-policy";
 import { formatStyledTruncationWarning, type OutputMeta, stripOutputNotice } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
 import { formatToolWorkingDirectory, replaceTabs } from "./render-utils";
@@ -570,6 +571,14 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			}
 		}
 
+		const composerPolicy = checkComposerBashPolicy({
+			modelId: this.session.getActiveModelString?.() ?? this.session.getModelString?.() ?? this.session.model?.id,
+			commands: rawCommand === command ? [command] : [rawCommand, command],
+		});
+		if (!composerPolicy.allowed) {
+			throw new ToolError(composerPolicy.message);
+		}
+
 		const internalUrlOptions: InternalUrlExpansionOptions = {
 			skills: this.session.skills ?? [],
 			internalRouter: InternalUrlRouter.instance(),

package/src/tools/browser/tab-supervisor.ts

@@ -57,6 +57,10 @@ export interface TabSession {
 	kindTag: BrowserKindTag;
 	/** Session that acquired this tab; used for session-scoped teardown (F13). */
 	ownerId?: string;
+	/** Unix-ms timestamp of the last acquire/run activity; drives GC idle + LRU ordering. */
+	lastUsedAt: number;
+	/** Set synchronously by the shared begin-release guard so concurrent release is a no-op. */
+	releasing?: boolean;
 }
 
 export interface AcquireTabOptions {
@@ -94,6 +98,76 @@ export function getTab(name: string): TabSession | undefined {
 	return tabs.get(name);
 }
 
+/**
+ * Shared synchronous begin-release guard. Returns true for the first caller (which then
+ * owns teardown) and false for any concurrent/repeat caller, so `releaseBrowser` and the
+ * `BrowserHandle.refCount` decrement happen exactly once even when the idle sweep, the RSS
+ * sweep, a manual close, and `forceKillTab` race on the same tab.
+ */
+function beginRelease(tab: TabSession): boolean {
+	if (tab.releasing) return false;
+	tab.releasing = true;
+	return true;
+}
+
+/** Read-only, GC-facing projection of a live tab. Never exposes the mutable `tabs` map. */
+export interface TabGcSnapshot {
+	name: string;
+	ownerId?: string;
+	state: TabSession["state"];
+	pendingCount: number;
+	kindTag: BrowserKindTag;
+	lastUsedAt: number;
+	browserRefCount: number;
+}
+
+export interface BrowserGcEligibilityPolicy {
+	now: () => number;
+	idleMs: number;
+}
+
+/** Snapshot every live tab for GC ordering/diagnostics. */
+export function listTabsForGc(): TabGcSnapshot[] {
+	return [...tabs.values()].map(tab => ({
+		name: tab.name,
+		ownerId: tab.ownerId,
+		state: tab.state,
+		pendingCount: tab.pending.size,
+		kindTag: tab.kindTag,
+		lastUsedAt: tab.lastUsedAt,
+		browserRefCount: tab.browser.refCount,
+	}));
+}
+
+/**
+ * Evict a tab only if it is still GC-eligible against the LIVE supervisor state. The full
+ * predicate is checked synchronously and `releaseTab` is invoked with no intervening await,
+ * so a tab that became busy after a GC snapshot cannot be closed (its run rejected). Returns
+ * true only when the tab was actually released.
+ */
+export async function releaseTabIfGcEligible(name: string, policy: BrowserGcEligibilityPolicy): Promise<boolean> {
+	const tab = tabs.get(name);
+	if (!tab) return false;
+	if (tab.releasing) return false;
+	if (tab.state !== "alive") return false;
+	if (tab.pending.size !== 0) return false;
+	if (tab.kindTag !== "headless" && tab.kindTag !== "spawned") return false;
+	if (policy.now() - tab.lastUsedAt <= policy.idleMs) return false;
+	// All predicates passed synchronously; releaseTab applies the shared begin-release guard
+	// on the same microtask, so no other code runs between the check and the state transition.
+	return await releaseTab(name, { kill: false });
+}
+
+/** Test-only: install a fabricated tab session. */
+export function setTabForTest(tab: TabSession): void {
+	tabs.set(tab.name, tab);
+}
+
+/** Test-only: clear the tab registry between cases. */
+export function clearTabsForTest(): void {
+	tabs.clear();
+}
+
 export async function acquireTab(
 	name: string,
 	browser: BrowserHandle,
@@ -105,6 +179,7 @@ export async function acquireTab(
 			if (opts.dialogs !== undefined && opts.dialogs !== existing.dialogPolicy) {
 				await releaseTab(name, { kill: false });
 			} else {
+				existing.lastUsedAt = Date.now();
 				if (opts.url) {
 					await runInTabWithSnapshot(
 						name,
@@ -166,6 +241,7 @@ export async function acquireTab(
 		dialogPolicy: opts.dialogs,
 		kindTag: browser.kind.kind,
 		ownerId: opts.ownerId,
+		lastUsedAt: Date.now(),
 	};
 	worker.onMessage(msg => handleTabMessage(tab, msg));
 	tabs.set(name, tab);
@@ -188,6 +264,7 @@ async function runInTabWithSnapshot(
 	const tab = tabs.get(name);
 	if (!tab || tab.state === "dead") throw new ToolError(`Tab ${JSON.stringify(name)} is not alive. Reopen it.`);
 	if (tab.pending.size > 0) throw new ToolError(`Tab ${JSON.stringify(name)} is busy`);
+	tab.lastUsedAt = Date.now();
 	const id = Snowflake.next();
 	const { promise, resolve, reject } = Promise.withResolvers<RunResultOk>();
 	const pending: PendingRun = {
@@ -224,6 +301,10 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 		logger.debug("releaseTab: unknown tab", { name });
 		return false;
 	}
+	if (!beginRelease(tab)) {
+		logger.debug("releaseTab: already releasing", { name });
+		return false;
+	}
 	const wasAlive = tab.state === "alive";
 	tab.state = "dead";
 	const closeError = new ToolError(`Tab ${JSON.stringify(name)} was closed`);
@@ -246,7 +327,9 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 	await tab.worker.terminate().catch(() => undefined);
 	if (forced && tab.kindTag === "headless") await closeOrphanTarget(tab);
 	await releaseBrowser(tab.browser, { kill: opts.kill ?? false });
-	tabs.delete(name);
+	// Only delete if the map still holds THIS tab: a same-name reacquire during our async
+	// teardown may have installed a fresh tab that we must not evict.
+	if (tabs.get(name) === tab) tabs.delete(name);
 	return true;
 }
 
@@ -392,6 +475,7 @@ function toErrorPayload(error: unknown): RunErrorPayload {
 async function forceKillTab(name: string, reason: string): Promise<void> {
 	const tab = tabs.get(name);
 	if (!tab) return;
+	if (!beginRelease(tab)) return;
 	tab.state = "dead";
 	const error = new ToolError(reason);
 	for (const pending of tab.pending.values()) pending.reject(error);
@@ -399,7 +483,7 @@ async function forceKillTab(name: string, reason: string): Promise<void> {
 	await tab.worker.terminate().catch(() => undefined);
 	if (tab.kindTag === "headless") await closeOrphanTarget(tab);
 	await releaseBrowser(tab.browser, { kill: false });
-	tabs.delete(name);
+	if (tabs.get(name) === tab) tabs.delete(name);
 }
 
 async function closeOrphanTarget(tab: TabSession): Promise<void> {

package/src/tools/composer-bash-policy.ts

@@ -0,0 +1,96 @@
+import { isComposerHarnessModel } from "@sayknow-cli/ai/providers/composer-discipline";
+
+export const COMPOSER_BASH_POLICY_ERROR =
+	"Composer bash policy blocked repository file I/O. Use find, search, read, and edit tools for file discovery, file inspection, and file mutation.";
+
+type ComposerBashPolicyResult =
+	| { allowed: true }
+	| {
+			allowed: false;
+			reason: string;
+			message: string;
+	  };
+
+const BLOCK_PATTERNS: Array<{ id: string; pattern: RegExp }> = [
+	{ id: "pipe", pattern: /\|/ },
+	{ id: "process-substitution", pattern: /<[>(]/ },
+	{ id: "heredoc", pattern: /<<[-~]?/ },
+	{ id: "command-substitution", pattern: /\$\(|`/ },
+	{ id: "redirection", pattern: /(^|[^<>])(?:>>?|<)(?!=)/ },
+	{ id: "tee", pattern: /(?:^|[;&|\s])tee(?:\s|$)/ },
+	{
+		id: "shell-file-read-discovery",
+		pattern: /(?:^|[;&|()\s])(?:\S*\/)?(?:cat|head|tail|less|more|grep|rg|find|fd|tree|ls)\b/,
+	},
+	{
+		id: "shell-file-mutation",
+		pattern: /(?:^|[;&|()\s])(?:\S*\/)?(?:cp|mv|rm|touch|mkdir|chmod|chown|ln)\b/,
+	},
+	{ id: "sed-print", pattern: /(?:^|[;&|()\s])sed\s+(?:-[^\s]*n\b|.*\bp\b)/ },
+	{ id: "awk-print", pattern: /(?:^|[;&|()\s])awk\b/ },
+	{ id: "git-ls-files", pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+ls-files\b/ },
+	{ id: "git-grep", pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+grep\b/ },
+	{ id: "git-show-path", pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+show\s+\S+:\S+/ },
+	{ id: "git-diff", pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+diff(?:\s|$)/ },
+	{ id: "git-cat-file", pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+cat-file\b/ },
+	{
+		id: "git-show-discovery",
+		pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+show\b.*(?:--name-only|--name-status|--stat)/,
+	},
+	{
+		id: "git-log-path-discovery",
+		pattern: /(?:^|[;&|()\s])git(?:\s+-C\s+\S+)?\s+log\b.*(?:--name-only|--name-status|--stat)/,
+	},
+	{ id: "sed-in-place", pattern: /(?:^|[;&|()\s])sed\s+-[^\s]*i\b/ },
+	{ id: "perl-in-place", pattern: /(?:^|[;&|()\s])perl\s+-[^\s]*p[^\s]*i\b/ },
+	{
+		id: "script-file-io",
+		pattern:
+			/(?:^|[;&|()\s])(?:python3?|node|bun)\s+(?:-\s*<<|-c\b|-e\b|--eval\b).*?(?:read_text|read_bytes|write_text|iterdir|listdir|glob\.glob|readFile|readFileSync|writeFile|writeFileSync|readdir|readdirSync|stat|statSync|cpSync|rmSync|mkdirSync|createReadStream|createWriteStream|Bun\.file|Bun\.write|fs\.readFile|fs\.writeFile|fs\.readdir|fs\.stat|fs\.cp|fs\.rm|fs\.mkdir|open\s*\()/s,
+	},
+	{
+		id: "contaminated-command",
+		pattern: /```|^\s*(?:I\s+(?:will|need|am going)|We\s+(?:need|will)|First[, ]|Now[, ]|Let's)\b/im,
+	},
+];
+
+const ALLOWED_TERMINAL_PATTERNS: RegExp[] = [
+	/^bun\s+test(?:\s+[\w./:@=-]+)*$/,
+	/^bun\s+run\s+(?:check(?::[\w-]+)?|test(?::[\w-]+)?|build(?::[\w-]+)?)(?:\s+[\w./:@=-]+)*$/,
+	/^bun\s+--version$/,
+	/^mise\s+x\s+bun@\d+\.\d+\.\d+\s+--\s+bun\s+test(?:\s+[\w./:@=-]+)*$/,
+	/^mise\s+x\s+bun@\d+\.\d+\.\d+\s+--\s+bun\s+run\s+(?:check(?::[\w-]+)?|test(?::[\w-]+)?|build(?::[\w-]+)?)(?:\s+[\w./:@=-]+)*$/,
+	/^cargo\s+(?:test|check|build)(?:\s+[\w./:@=-]+)*$/,
+	/^git\s+status(?:\s+--short)?(?:\s+--branch)?$/,
+	/^git\s+rev-parse\s+HEAD$/,
+	/^npm\s+--version$/,
+	/^pnpm\s+--version$/,
+	/^yarn\s+--version$/,
+];
+
+function isAllowedComposerTerminalCommand(command: string): boolean {
+	const normalized = command.trim().replace(/\s+/g, " ");
+	return ALLOWED_TERMINAL_PATTERNS.some(pattern => pattern.test(normalized));
+}
+
+export function isComposerBashPolicyModel(modelId: string | undefined): boolean {
+	return Boolean(modelId && isComposerHarnessModel(modelId));
+}
+
+export function checkComposerBashPolicy(input: {
+	modelId?: string;
+	commands: readonly string[];
+}): ComposerBashPolicyResult {
+	if (!isComposerBashPolicyModel(input.modelId)) return { allowed: true };
+	for (const command of input.commands) {
+		for (const block of BLOCK_PATTERNS) {
+			if (block.pattern.test(command)) {
+				return { allowed: false, reason: block.id, message: COMPOSER_BASH_POLICY_ERROR };
+			}
+		}
+		if (!isAllowedComposerTerminalCommand(command)) {
+			return { allowed: false, reason: "not-allowlisted", message: COMPOSER_BASH_POLICY_ERROR };
+		}
+	}
+	return { allowed: true };
+}

package/src/tools/computer-gc.ts

@@ -0,0 +1,66 @@
+import type { Dirent } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@sayknow-cli/utils";
+
+/** Prefix of every computer-use screenshot fallback directory created under the OS temp dir. */
+export const SCREENSHOT_FALLBACK_DIR_PREFIX = "skc-computer-screenshots-";
+
+let screenshotFallbackDirsCreated = false;
+
+/** Lazy-arm marker: called when the first screenshot fallback dir is created this process. */
+export function markScreenshotFallbackDirCreatedForGc(): void {
+	screenshotFallbackDirsCreated = true;
+}
+
+/** Whether any screenshot fallback dir has been created this process (GC lazy-arm gate). */
+export function hasCreatedScreenshotFallbackDir(): boolean {
+	return screenshotFallbackDirsCreated;
+}
+
+/** Test-only: reset the lazy-arm marker between cases. */
+export function resetScreenshotFallbackGcForTest(): void {
+	screenshotFallbackDirsCreated = false;
+}
+
+export interface ScreenshotGcOptions {
+	now: () => number;
+	staleMs: number;
+	/** Base dir to scan; defaults to os.tmpdir(). Injectable for tests. */
+	tmpDir?: string;
+}
+
+/**
+ * Disk-only GC for stale computer-use screenshot fallback directories. Scans the temp dir for
+ * `skc-computer-screenshots-*` directories and removes those whose mtime is older than `staleMs`.
+ * Never throws on a per-directory failure; the whole sweep is best-effort.
+ */
+export async function cleanupStaleScreenshotFallbackDirs(
+	options: ScreenshotGcOptions,
+): Promise<{ scanned: number; removed: number }> {
+	const base = options.tmpDir ?? os.tmpdir();
+	const entries: Dirent[] = await fs.readdir(base, { withFileTypes: true }).catch(err => {
+		logger.debug("screenshot GC: failed to read temp dir", { base, error: (err as Error).message });
+		return [] as Dirent[];
+	});
+
+	const now = options.now();
+	let scanned = 0;
+	let removed = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		if (!entry.name.startsWith(SCREENSHOT_FALLBACK_DIR_PREFIX)) continue;
+		scanned++;
+		const dir = path.join(base, entry.name);
+		try {
+			const stat = await fs.stat(dir);
+			if (now - stat.mtimeMs <= options.staleMs) continue;
+			await fs.rm(dir, { recursive: true, force: true });
+			removed++;
+		} catch (err) {
+			logger.debug("screenshot GC: failed to remove stale dir", { dir, error: (err as Error).message });
+		}
+	}
+	return { scanned, removed };
+}

package/src/tools/computer.ts

@@ -7,6 +7,7 @@ import { prompt } from "@sayknow-cli/utils";
 import * as z from "zod/v4";
 import computerDescription from "../prompts/tools/computer.md" with { type: "text" };
 import { resizeImage } from "../utils/image-resize";
+import { markScreenshotFallbackDirCreatedForGc } from "./computer-gc";
 import type { ToolSession } from "./index";
 import type { OutputMeta } from "./output-meta";
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
@@ -547,6 +548,7 @@ function getScreenshotFallbackDir(session: ToolSession): Promise<string> {
 async function createScreenshotFallbackDir(): Promise<string> {
 	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "skc-computer-screenshots-"));
 	await fs.chmod(dir, 0o700);
+	markScreenshotFallbackDirCreatedForGc();
 	return dir;
 }
 

package/src/tools/cron.ts

@@ -19,34 +19,36 @@ const MAX_RECURRING_JITTER_MS = 30 * 60 * 1000;
 const MAX_ONE_SHOT_EARLY_JITTER_MS = 90 * 1000;
 const MAX_TIMEOUT_MS = 2_147_483_647;
 
-const cronCreateSchema = z.object({
-	cron_expression: z
-		.string()
-		.describe(
-			"Standard 5-field cron expression in the user's local timezone: 'minute hour day-of-month month day-of-week'. Examples: '*/5 * * * *' (every 5 min), '0 9 * * *' (9am daily), '0 9 * * 1-5' (weekdays at 9am). Day-of-week uses 0/7 for Sunday through 6 for Saturday. When both day-of-month and day-of-week are constrained, a date matches if either field matches (vixie-cron semantics).",
-		),
-	prompt: z
-		.string()
-		.describe(
-			"Prompt to inject between turns when the cron fires. May reference slash commands (e.g. '/review-pr 1234') or natural-language instructions.",
-		),
-	recurring: z
-		.boolean()
-		.default(true)
-		.describe(
-			"true to fire on every match of the cron expression (recurring, auto-expires after 7 days); false to fire once at the next match and then self-delete.",
-		),
-});
-
-export type CronCreateParams = z.infer<typeof cronCreateSchema>;
-
-const cronListSchema = z.object({});
-export type CronListParams = z.infer<typeof cronListSchema>;
-
-const cronDeleteSchema = z.object({
-	id: z.string().min(1).describe("The 8-character job ID returned by CronCreate."),
-});
-export type CronDeleteParams = z.infer<typeof cronDeleteSchema>;
+const cronSchema = z
+	.object({
+		op: z
+			.enum(["create", "list", "delete"])
+			.describe(
+				"operation: 'create' schedules a prompt on a cron expression, 'list' enumerates scheduled tasks, 'delete' cancels a task by id",
+			),
+		cron_expression: z
+			.string()
+			.optional()
+			.describe(
+				"(op=create, required) Standard 5-field cron expression in the user's local timezone: 'minute hour day-of-month month day-of-week'. Examples: '*/5 * * * *' (every 5 min), '0 9 * * *' (9am daily), '0 9 * * 1-5' (weekdays at 9am). Day-of-week uses 0/7 for Sunday through 6 for Saturday. When both day-of-month and day-of-week are constrained, a date matches if either field matches (vixie-cron semantics).",
+			),
+		prompt: z
+			.string()
+			.optional()
+			.describe(
+				"(op=create, required) Prompt to inject between turns when the cron fires. May reference slash commands (e.g. '/review-pr 1234') or natural-language instructions.",
+			),
+		recurring: z
+			.boolean()
+			.optional()
+			.describe(
+				"(op=create) true to fire on every match of the cron expression (recurring, auto-expires after 7 days); false to fire once at the next match and then self-delete.",
+			),
+		id: z.string().optional().describe("(op=delete, required) The 8-character job ID returned by op=create."),
+	})
+	.strict();
+
+export type CronParams = z.infer<typeof cronSchema>;
 
 export interface CronJobSnapshot {
 	id: string;
@@ -68,20 +70,14 @@ export interface CronListJobDetails {
 	humanSchedule: string;
 }
 
-export interface CronCreateToolDetails {
-	id: string;
-	cron_expression: string;
-	recurring: boolean;
+export interface CronToolDetails {
+	op: "create" | "list" | "delete";
+	id?: string;
+	cron_expression?: string;
+	recurring?: boolean;
 	nextFireAt?: number;
-}
-
-export interface CronListToolDetails {
-	jobs: CronListJobDetails[];
-}
-
-export interface CronDeleteToolDetails {
-	id: string;
-	deleted: boolean;
+	jobs?: CronListJobDetails[];
+	deleted?: boolean;
 }
 
 interface CronTimerHandle {
@@ -543,12 +539,12 @@ function isCronDisabled(): boolean {
 	return process.env.CLAUDE_CODE_DISABLE_CRON === "1";
 }
 
-export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCreateToolDetails> {
-	readonly name = "CronCreate";
-	readonly label = "CronCreate";
-	readonly summary = "Schedule a prompt on a 5-field cron expression";
+export class CronTool implements AgentTool<typeof cronSchema, CronToolDetails> {
+	readonly name = "cron";
+	readonly label = "Cron";
+	readonly summary = "Schedule, list, and cancel cron-style prompts (op: create | list | delete)";
 	readonly description: string;
-	readonly parameters = cronCreateSchema;
+	readonly parameters = cronSchema;
 	readonly strict = true;
 	readonly loadMode = "discoverable";
 
@@ -556,19 +552,30 @@ export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCr
 		this.description = prompt.render(cronDescription);
 	}
 
-	static createIf(session: ToolSession): CronCreateTool | null {
+	static createIf(session: ToolSession): CronTool | null {
 		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
 		if (isCronDisabled()) return null;
-		return new CronCreateTool(session);
+		return new CronTool(session);
 	}
 
 	async execute(
 		_toolCallId: string,
-		params: CronCreateParams,
+		params: CronParams,
 		_signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<CronCreateToolDetails>,
+		_onUpdate?: AgentToolUpdateCallback<CronToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<CronCreateToolDetails>> {
+	): Promise<AgentToolResult<CronToolDetails>> {
+		switch (params.op) {
+			case "create":
+				return this.#create(params);
+			case "list":
+				return this.#list();
+			case "delete":
+				return this.#delete(params);
+		}
+	}
+
+	async #create(params: CronParams): Promise<AgentToolResult<CronToolDetails>> {
 		const manager = AsyncJobManager.instance();
 		if (!manager) {
 			throw new ToolError("Async execution is disabled; cron is unavailable in this session.");
@@ -576,26 +583,30 @@ export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCr
 		if (isCronDisabled()) {
 			throw new ToolError("Cron is disabled by CLAUDE_CODE_DISABLE_CRON=1.");
 		}
+		if (!params.cron_expression || !params.prompt) {
+			throw new ToolError("cron op=create requires both 'cron_expression' and 'prompt'.");
+		}
 		validateCronExpression(params.cron_expression);
 
 		const ownerId = this.session.getAgentId?.() ?? undefined;
 		const state = getOrCreateOwnerState(ownerId);
 		if (state.jobs.size >= MAX_CRON_TASKS_PER_OWNER) {
 			throw new ToolError(
-				`Cron task limit reached (${MAX_CRON_TASKS_PER_OWNER}). Cancel an existing task with CronDelete first.`,
+				`Cron task limit reached (${MAX_CRON_TASKS_PER_OWNER}). Cancel an existing task with cron op=delete first.`,
 			);
 		}
 		ensureOwnerCleanup(ownerId, manager, state);
 
 		const id = generateCronId(new Set(state.jobs.keys()));
 		const now = Date.now();
+		const recurring = params.recurring ?? true;
 		const snapshot: CronJobSnapshot = {
 			id,
 			cron_expression: params.cron_expression.trim(),
 			prompt: params.prompt,
-			recurring: params.recurring,
+			recurring,
 			createdAt: now,
-			expiresAt: params.recurring ? now + CRON_RECURRING_MAX_AGE_MS : undefined,
+			expiresAt: recurring ? now + CRON_RECURRING_MAX_AGE_MS : undefined,
 			humanSchedule: humanizeCronExpression(params.cron_expression.trim()),
 			ownerId,
 		};
@@ -604,7 +615,7 @@ export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCr
 		scheduleExpiry(ownerId, record);
 		scheduleRecord(ownerId, state, record);
 
-		logger.debug("CronCreate: scheduled task", {
+		logger.debug("cron op=create: scheduled task", {
 			id,
 			ownerId,
 			cron: snapshot.cron_expression,
@@ -614,6 +625,7 @@ export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCr
 		return {
 			content: [{ type: "text", text: `Scheduled ${id} (${snapshot.humanSchedule})` }],
 			details: {
+				op: "create",
 				id,
 				cron_expression: snapshot.cron_expression,
 				recurring: snapshot.recurring,
@@ -621,34 +633,8 @@ export class CronCreateTool implements AgentTool<typeof cronCreateSchema, CronCr
 			},
 		};
 	}
-}
-
-export class CronListTool implements AgentTool<typeof cronListSchema, CronListToolDetails> {
-	readonly name = "CronList";
-	readonly label = "CronList";
-	readonly summary = "List scheduled cron jobs";
-	readonly description: string;
-	readonly parameters = cronListSchema;
-	readonly strict = true;
-	readonly loadMode = "discoverable";
-
-	constructor(private readonly session: ToolSession) {
-		this.description = prompt.render(cronDescription);
-	}
 
-	static createIf(session: ToolSession): CronListTool | null {
-		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
-		if (isCronDisabled()) return null;
-		return new CronListTool(session);
-	}
-
-	async execute(
-		_toolCallId: string,
-		_params: CronListParams,
-		_signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<CronListToolDetails>,
-		_context?: AgentToolContext,
-	): Promise<AgentToolResult<CronListToolDetails>> {
+	async #list(): Promise<AgentToolResult<CronToolDetails>> {
 		const ownerId = this.session.getAgentId?.() ?? undefined;
 		const state = schedulesByOwner.get(ownerKey(ownerId));
 		const records = state
@@ -658,7 +644,7 @@ export class CronListTool implements AgentTool<typeof cronListSchema, CronListTo
 		if (jobs.length === 0) {
 			return {
 				content: [{ type: "text", text: "No scheduled jobs" }],
-				details: { jobs: [] },
+				details: { op: "list", jobs: [] },
 			};
 		}
 		const lines = jobs.map(job => {
@@ -667,43 +653,20 @@ export class CronListTool implements AgentTool<typeof cronListSchema, CronListTo
 		});
 		return {
 			content: [{ type: "text", text: lines.join("\n") }],
-			details: { jobs },
+			details: { op: "list", jobs },
 		};
 	}
-}
 
-export class CronDeleteTool implements AgentTool<typeof cronDeleteSchema, CronDeleteToolDetails> {
-	readonly name = "CronDelete";
-	readonly label = "CronDelete";
-	readonly summary = "Cancel a scheduled cron job by ID";
-	readonly description: string;
-	readonly parameters = cronDeleteSchema;
-	readonly strict = true;
-	readonly loadMode = "discoverable";
-
-	constructor(private readonly session: ToolSession) {
-		this.description = prompt.render(cronDescription);
-	}
-
-	static createIf(session: ToolSession): CronDeleteTool | null {
-		if (!isBackgroundJobSupportEnabled(session.settings)) return null;
-		if (isCronDisabled()) return null;
-		return new CronDeleteTool(session);
-	}
-
-	async execute(
-		_toolCallId: string,
-		params: CronDeleteParams,
-		_signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<CronDeleteToolDetails>,
-		_context?: AgentToolContext,
-	): Promise<AgentToolResult<CronDeleteToolDetails>> {
+	async #delete(params: CronParams): Promise<AgentToolResult<CronToolDetails>> {
+		if (!params.id) {
+			throw new ToolError("cron op=delete requires 'id'.");
+		}
 		const ownerId = this.session.getAgentId?.() ?? undefined;
 		const deleted = deleteRecord(ownerId, params.id);
 		const text = deleted ? `Cancelled ${params.id}` : `No scheduled task '${params.id}' found; nothing to cancel.`;
 		return {
 			content: [{ type: "text", text }],
-			details: { id: params.id, deleted },
+			details: { op: "delete", id: params.id, deleted },
 		};
 	}
 }