@workerdeck/core 2.15.0 → 3.0.1

package/build/index.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
 import { createSdkMcpServer, getSessionInfo, getSessionMessages, listSessions, query, tool } from "@anthropic-ai/claude-agent-sdk";
-import { CHECKLIST_TEXT_MAX, ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_CONTEXT_FLUSH_MAX_CHARS, SHELL_CONTEXT_HEAD_CHARS, SHELL_CONTEXT_HEAD_LINES, SHELL_CONTEXT_TAIL_CHARS, SHELL_CONTEXT_TAIL_LINES, SHELL_INLINE_CHARS, SHELL_INLINE_LINES, SHELL_INLINE_LINE_CHARS, SHELL_READ_DEFAULT_LINES, SHELL_READ_MAX_LINES, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, addTokenUsage, byModelTotalTokens, canonicalModel, contextReading, costOfByModel, emptyTokenUsage, imagePartRef, logCoalesceKey, mergeByModel, parseTodoWriteInput, peerDeliveredPrefix, replayCoalesceKey, replayRetains, sanitizeToolTitle, snapshotRetains, tokenUsageFromWire, totalTokens, transcriptActivity, transcriptContent, transcriptProse } from "@workerdeck/protocol";
+import { CHECKLIST_TEXT_MAX, ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_COMMAND_MAX, SHELL_CONTEXT_FLUSH_MAX_CHARS, SHELL_CONTEXT_HEAD_CHARS, SHELL_CONTEXT_HEAD_LINES, SHELL_CONTEXT_TAIL_CHARS, SHELL_CONTEXT_TAIL_LINES, SHELL_INLINE_CHARS, SHELL_INLINE_LINES, SHELL_INLINE_LINE_CHARS, SHELL_INPUT_MAX, SHELL_INTERACTIVE_NOTE, SHELL_READ_DEFAULT_LINES, SHELL_READ_MAX_LINES, SHELL_WAIT_DEFAULT_MS, SHELL_WAIT_MAX_MS, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, addTokenUsage, byModelTotalTokens, canonicalModel, contextReading, costOfByModel, emptyTokenUsage, imagePartRef, logCoalesceKey, mergeByModel, parseTodoWriteInput, peerDeliveredPrefix, replayCoalesceKey, replayRetains, sanitizeToolTitle, snapshotRetains, tokenUsageFromWire, totalTokens, transcriptActivity, transcriptContent, transcriptProse } from "@workerdeck/protocol";
 import { z } from "zod";
 import { ToolLoopAgent, generateText, isStepCount, tool as tool$1 } from "ai";
 import { execFile, spawn } from "node:child_process";
@@ -281,9 +281,14 @@ const STRING_SEQUENCE = /(?:\x1b[PX^_]|[\x90\x98\x9e\x9f])[\s\S]*?(?:\x1b\\|\x9c
 const CSI_SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -/]*[@-~]/g;
 const ESCAPE_SEQUENCE = /\x1b[ -/]*[0-~]/g;
 const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+const REDRAW_SEQUENCE = /(?:\x1b\[|\x9b)(?:\?(?:1049|1047|47)h|\d*[AF]|\d+;\d+[Hf]|\d+d)/;
+const TTY_REDRAW_CARRY = 16;
 function ttyText(raw) {
 	return raw.replace(OSC_SEQUENCE, "").replace(STRING_SEQUENCE, "").replace(CSI_SEQUENCE, "").replace(ESCAPE_SEQUENCE, "").replace(CONTROL_CHARS, "").replace(/\r\n/g, "\n").split("\n").map((line) => overwritten(line).trimEnd()).join("\n");
 }
+function ttyRedraws(raw) {
+	return REDRAW_SEQUENCE.test(raw);
+}
 function splitLines(text) {
 	if (text === "") return [];
 	return (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
@@ -414,9 +419,13 @@ function localCommandEvent(text, uuid, shell) {
 	};
 }
 function shellInlineText(shell, text) {
-	const head = inlineHead(text);
-	const body = [`$ ${shell.command}`, ...head.lines];
-	if (head.more) body.push(INLINE_MORE);
+	const body = [`$ ${shell.command}`];
+	if (shell.interactive) body.push(`[${SHELL_INTERACTIVE_NOTE}]`);
+	else {
+		const head = inlineHead(text);
+		body.push(...head.lines);
+		if (head.more) body.push(INLINE_MORE);
+	}
 	const end = shellEndLine(shell);
 	if (end) body.push(end);
 	return frame(shellTag(shell), body);
@@ -451,6 +460,7 @@ function shellContextText(shell, text, options = {}) {
 }
 var LocalCommandQueue = class {
 	#entries = [];
+	#rows = /* @__PURE__ */ new Set();
 	#emit;
 	constructor(emit) {
 		this.#emit = emit;
@@ -470,6 +480,22 @@ var LocalCommandQueue = class {
 			const info = { ...input.info() };
 			this.#emit(shellInlineText(info, input.text()), uuid, info);
 		};
+		if (input.info().owner === "agent") {
+			const settle = () => {
+				if (input.info().status !== "running") {
+					unsubscribe();
+					this.#rows.delete(unsubscribe);
+				}
+			};
+			const unsubscribe = input.subscribe(() => {
+				row();
+				settle();
+			});
+			this.#rows.add(unsubscribe);
+			row();
+			settle();
+			return;
+		}
 		row();
 		const unsubscribe = input.subscribe(row);
 		this.#entries.push({
@@ -507,6 +533,8 @@ var LocalCommandQueue = class {
 	clear() {
 		for (const entry of this.#entries) if (entry.kind === "shell") entry.unsubscribe();
 		this.#entries = [];
+		for (const unsubscribe of this.#rows) unsubscribe();
+		this.#rows.clear();
 	}
 };
 function render(entry) {
@@ -1499,23 +1527,125 @@ function peerDirectoryHandle() {
 //#endregion
 //#region src/lib/shells.ts
 const SHELL_REFUSAL = "shell commands are not available on this session";
+const SHELL_WRITE_REFUSAL = "the agent may not start, type into or kill shells on this session (shell.agentWrite is read-only)";
+const SHELL_KEYS_MAX = 64;
 const SHELL_DIRECTORY_SLOT = Symbol.for("workerdeck.shells.directory");
+const CTRL_LETTERS = "abcdefghijklmnopqrstuvwxyz";
+const NAMED_KEYS = {
+	enter: "\r",
+	return: "\r",
+	tab: "	",
+	"shift-tab": "\x1B[Z",
+	escape: "\x1B",
+	esc: "\x1B",
+	backspace: "",
+	delete: "\x1B[3~",
+	insert: "\x1B[2~",
+	pageup: "\x1B[5~",
+	pagedown: "\x1B[6~",
+	space: " ",
+	f1: "\x1BOP",
+	f2: "\x1BOQ",
+	f3: "\x1BOR",
+	f4: "\x1BOS",
+	f5: "\x1B[15~",
+	f6: "\x1B[17~",
+	f7: "\x1B[18~",
+	f8: "\x1B[19~",
+	f9: "\x1B[20~",
+	f10: "\x1B[21~",
+	f11: "\x1B[23~",
+	f12: "\x1B[24~"
+};
+const CURSOR_KEYS = {
+	up: "A",
+	down: "B",
+	right: "C",
+	left: "D",
+	home: "H",
+	end: "F"
+};
+const SHELL_KEY_NAMES = [
+	"enter",
+	"tab",
+	"shift-tab",
+	"escape",
+	"backspace",
+	"delete",
+	"insert",
+	"up",
+	"down",
+	"left",
+	"right",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"space",
+	"f1 to f12",
+	"ctrl-a to ctrl-z",
+	"any single printable character"
+];
+const waitForShape = z.union([z.string().min(1), z.array(z.string().min(1)).min(1).max(8)]).optional().describe("Wait until this text (or any of these) appears, the shell exits, or timeoutMs passes, then return the view. A plain case-sensitive substring, not a pattern.");
+const timeoutShape = z.number().int().min(0).max(SHELL_WAIT_MAX_MS).optional().describe(`With waitFor: how long to wait (default ${SHELL_WAIT_DEFAULT_MS}, at most ${SHELL_WAIT_MAX_MS})`);
 const SHELL_TOOL_SHAPES = {
 	shell_list: {
-		description: "List the shell commands your user has run in this session with `$`: id, command, whether it is still running, its exit code and how much output it produced. Call this before shell_read to find the shell id.",
+		description: "List the shells of this session: the commands your user ran with `$` and the ones you started with shell_run. Each has an id, a command, an owner (user or agent), whether it is still running, its exit code, how much output it produced and whether it is interactive (a program that redraws the screen). Call this before shell_read, shell_write or shell_kill to find the shell id.",
 		shape: {}
 	},
 	shell_read: {
-		description: "Read the end of one shell command's output, as a terminal would show it. Use it to answer \"what is the dev server printing now\" or to see more of a command whose output was summarised in the conversation. Reading never writes to the shell and never interrupts it.",
+		description: "Read one shell's output. Use it to answer \"what is the dev server printing now\", to see more of a command whose output was summarised in the conversation, or with waitFor to block until a server is ready. Reading never writes to the shell and never interrupts it.",
 		shape: {
 			shellId: z.string().describe("The shell id from shell_list"),
-			tail: z.number().int().min(1).optional().describe(`How many trailing lines to return (default ${SHELL_READ_DEFAULT_LINES}, capped at ${SHELL_READ_MAX_LINES})`)
+			view: z.enum(["lines", "screen"]).optional().describe("lines: the trailing lines of the output as plain text. screen: what the terminal shows right now, the only readable view of a program that redraws (a TUI, a dev server dashboard, a multi-line progress display). Defaults to screen for an interactive shell and lines otherwise."),
+			tail: z.number().int().min(1).optional().describe(`With view lines: how many trailing lines to return (default ${SHELL_READ_DEFAULT_LINES}, capped at ${SHELL_READ_MAX_LINES})`),
+			waitFor: z.union([z.string().min(1), z.array(z.string().min(1)).min(1).max(8)]).optional().describe("Wait until the view contains this text (or any of these), the shell exits, or timeoutMs passes, then read. A plain case-sensitive substring, not a pattern. Text already there counts, so a server that was ready before the call returns at once."),
+			timeoutMs: timeoutShape
+		}
+	},
+	shell_run: {
+		description: "Start a shell command of your own in the session's working directory, in a real terminal (a PTY) that keeps running after this call returns: a dev server, a watcher, a TUI. The result names the new shell id; use shell_read to watch it, shell_write to type into it and shell_kill to stop it. With waitFor the call blocks until the output contains that text (or the command exits or timeoutMs passes), so \"start vite and wait for 'ready in'\" is one call. This needs the user's approval and every shell you start is visible to them. For a command that just runs and finishes, prefer your ordinary shell tool.",
+		shape: {
+			command: z.string().min(1).max(SHELL_COMMAND_MAX).refine((command) => command.trim() !== "" && !command.includes("\0"), "command must be non-empty text").describe("The command line, run by the user's login shell in the session's working directory"),
+			waitFor: waitForShape,
+			timeoutMs: timeoutShape
+		}
+	},
+	shell_write: {
+		description: `Type into a shell you started with shell_run: literal text in data, named keys in keys, or both (data is sent first, then the keys in order). To press Enter use keys ["enter"]; a "\\n" in data ends a line only for line-mode programs, not for a TUI. Key names: ${SHELL_KEY_NAMES.join(", ")}. With waitFor the call blocks until the shell prints that text AFTER your keystrokes (earlier output never counts), then returns the view, so "press r and wait for 'reloaded'" is one call. Typing into a shell the user started is refused unless they granted it through shell_request_write.`,
+		shape: {
+			shellId: z.string().describe("The shell id from shell_run or shell_list"),
+			data: z.string().max(SHELL_INPUT_MAX).optional().describe("Literal text to type, sent as-is"),
+			keys: z.array(z.string().min(1)).min(1).max(64).optional().describe("Named keys to press after data, in order, e.g. [\"r\"], [\"enter\"], [\"ctrl-c\"], [\"down\", \"down\", \"enter\"]"),
+			waitFor: waitForShape,
+			timeoutMs: timeoutShape
+		}
+	},
+	shell_kill: {
+		description: "Stop a shell you started with shell_run, killing its whole process tree. Use it when the user asks you to stop the server or when you are done with it. Killing a shell the user started is refused unless they granted it through shell_request_write.",
+		shape: { shellId: z.string().describe("The shell id from shell_run or shell_list") }
+	},
+	shell_request_write: {
+		description: "Ask the user to let you type into (and kill) a shell THEY started with `$`, for example to answer a prompt in a script or to drive a TUI they launched. The user sees the shell and your reason and allows or denies; once allowed, shell_write and shell_kill work on it until the shell ends or the user revokes the grant. Never needed for a shell you started with shell_run.",
+		shape: {
+			shellId: z.string().describe("The id of a running shell the user started, from shell_list"),
+			reason: z.string().min(1).max(500).describe("One sentence the user reads on the approval card: what you will type and why")
 		}
 	}
 };
 const SHELL_TOOL_NAMES = Object.keys(SHELL_TOOL_SHAPES);
-function shellToolSpecs() {
-	return SHELL_TOOL_NAMES.map((name) => {
+const SHELL_READ_TOOL_NAMES = ["shell_list", "shell_read"];
+const SHELL_WRITE_TOOL_NAMES = [
+	"shell_run",
+	"shell_write",
+	"shell_kill",
+	"shell_request_write"
+];
+function shellToolNames(write) {
+	return write ? [...SHELL_READ_TOOL_NAMES, ...SHELL_WRITE_TOOL_NAMES] : [...SHELL_READ_TOOL_NAMES];
+}
+function shellToolSpecs(write = false) {
+	return shellToolNames(write).map((name) => {
 		const { description, shape } = SHELL_TOOL_SHAPES[name];
 		return {
 			name,
@@ -1527,10 +1657,59 @@ function shellToolSpecs() {
 function isShellToolName(name) {
 	return Object.hasOwn(SHELL_TOOL_SHAPES, name);
 }
+function isShellWriteToolName(name) {
+	return SHELL_WRITE_TOOL_NAMES.includes(name);
+}
+function shellWriteToolOf(toolName) {
+	const bare = toolName.startsWith("mcp__") ? toolName.slice(toolName.indexOf("__", 5) + 2) : toolName;
+	return isShellWriteToolName(bare) ? bare : void 0;
+}
+function shellToolOf(toolName) {
+	const bare = toolName.startsWith("mcp__") ? toolName.slice(toolName.indexOf("__", 5) + 2) : toolName;
+	return isShellToolName(bare) ? bare : void 0;
+}
+function shellToolNeedsCard(toolName, agentWrite) {
+	const tool = shellWriteToolOf(toolName);
+	if (tool === void 0 || agentWrite === void 0) return false;
+	return agentWrite === "gated" || tool === "shell_request_write";
+}
 function clampShellTail(tail) {
 	if (tail === void 0 || !Number.isFinite(tail)) return SHELL_READ_DEFAULT_LINES;
 	return Math.max(1, Math.min(Math.floor(tail), SHELL_READ_MAX_LINES));
 }
+function agentMayWrite(shell, from) {
+	return shell.sessionId === from && (shell.owner === "agent" || shell.agentWrite === true);
+}
+function shellOwnershipRefusal(shellId) {
+	return `shell ${shellId} was started by the user; the agent may only type into or kill shells it started, or one the user granted through shell_request_write`;
+}
+function shellWriteDeniedText(name, message) {
+	return `the user denied this ${name}${message ? `: ${message}` : ""}`;
+}
+function encodeShellKey(key, options = {}) {
+	if ([...key].length === 1) {
+		const code = key.codePointAt(0);
+		return code < 32 || code === 127 ? void 0 : key;
+	}
+	const name = key.toLowerCase().replace(/\+/g, "-").replace(/^control-/, "ctrl-").replace(/^c-/, "ctrl-");
+	const named = NAMED_KEYS[name];
+	if (named !== void 0) return named;
+	const cursor = CURSOR_KEYS[name];
+	if (cursor !== void 0) return `\x1b${options.applicationCursorKeys ? "O" : "["}${cursor}`;
+	if (name.startsWith("ctrl-") && name.length === 6) {
+		const index = CTRL_LETTERS.indexOf(name[5]);
+		if (index !== -1) return String.fromCharCode(index + 1);
+	}
+}
+function encodeShellKeys(keys, options = {}) {
+	let out = "";
+	for (const key of keys) {
+		const encoded = encodeShellKey(key, options);
+		if (encoded === void 0) throw new Error(`unknown key ${JSON.stringify(key)}; use one of ${SHELL_KEY_NAMES.join(", ")}`);
+		out += encoded;
+	}
+	return out;
+}
 function shellSummary(info) {
 	return {
 		id: info.id,
@@ -1545,7 +1724,9 @@ function shellSummary(info) {
 		exitCode: info.exitCode,
 		endReason: info.endReason,
 		bytes: info.bytes,
-		capped: info.capped
+		capped: info.capped,
+		interactive: info.interactive,
+		agentWrite: info.agentWrite
 	};
 }
 function shellTail(text, tail) {
@@ -1553,17 +1734,22 @@ function shellTail(text, tail) {
 	const all = body.length === 0 ? [] : body.split("\n");
 	const kept = all.slice(Math.max(0, all.length - tail));
 	return {
+		view: "lines",
 		text: kept.join("\n"),
 		lines: kept.length,
 		totalLines: all.length,
 		truncated: kept.length < all.length
 	};
 }
-async function runShellTool(shells, from, name, args) {
+async function runShellTool(shells, from, name, args, options = {}) {
 	if (!isShellToolName(name)) return {
 		text: `unknown shell tool: ${name}`,
 		isError: true
 	};
+	if (isShellWriteToolName(name) && options.write !== true) return {
+		text: SHELL_WRITE_REFUSAL,
+		isError: true
+	};
 	try {
 		switch (name) {
 			case "shell_list": {
@@ -1576,7 +1762,13 @@ async function runShellTool(shells, from, name, args) {
 			case "shell_read": {
 				const input = z.object(SHELL_TOOL_SHAPES.shell_read.shape).safeParse(args ?? {});
 				if (!input.success) return invalidArguments(name, input.error);
-				const result = await shells.read(from, input.data.shellId, { tail: clampShellTail(input.data.tail) });
+				const { shellId, view, tail, waitFor, timeoutMs } = input.data;
+				const result = await shells.read(from, shellId, {
+					tail: clampShellTail(tail),
+					view,
+					waitFor: needles(waitFor),
+					timeoutMs
+				});
 				if (!result) return {
 					text: `no such shell: ${input.data.shellId}`,
 					isError: true
@@ -1586,6 +1778,76 @@ async function runShellTool(shells, from, name, args) {
 					isError: false
 				};
 			}
+			case "shell_run": {
+				const input = z.object(SHELL_TOOL_SHAPES.shell_run.shape).safeParse(args ?? {});
+				if (!input.success) return invalidArguments(name, input.error);
+				const { command, waitFor, timeoutMs } = input.data;
+				return {
+					text: shellReadText(await shells.run(from, {
+						command,
+						waitFor: needles(waitFor),
+						timeoutMs
+					}), "started"),
+					isError: false
+				};
+			}
+			case "shell_write": {
+				const input = z.object(SHELL_TOOL_SHAPES.shell_write.shape).safeParse(args ?? {});
+				if (!input.success) return invalidArguments(name, input.error);
+				const { shellId, data, keys, waitFor, timeoutMs } = input.data;
+				if (!data && !keys) return {
+					text: `invalid arguments for ${name}: give data, keys or both`,
+					isError: true
+				};
+				try {
+					encodeShellKeys(keys ?? []);
+				} catch (error) {
+					return {
+						text: `invalid arguments for ${name}: ${error instanceof Error ? error.message : String(error)}`,
+						isError: true
+					};
+				}
+				const result = await shells.write(from, shellId, {
+					data,
+					keys,
+					waitFor: needles(waitFor),
+					timeoutMs
+				});
+				if (!result) return {
+					text: `no such shell: ${shellId}`,
+					isError: true
+				};
+				return {
+					text: shellReadText(result, "typed"),
+					isError: false
+				};
+			}
+			case "shell_kill": {
+				const input = z.object(SHELL_TOOL_SHAPES.shell_kill.shape).safeParse(args ?? {});
+				if (!input.success) return invalidArguments(name, input.error);
+				const result = await shells.kill(from, input.data.shellId);
+				if (!result) return {
+					text: `no such shell: ${input.data.shellId}`,
+					isError: true
+				};
+				return {
+					text: shellKillText(result),
+					isError: false
+				};
+			}
+			case "shell_request_write": {
+				const input = z.object(SHELL_TOOL_SHAPES.shell_request_write.shape).safeParse(args ?? {});
+				if (!input.success) return invalidArguments(name, input.error);
+				const shell = await shells.grant(from, input.data.shellId);
+				if (!shell) return {
+					text: `no such shell: ${input.data.shellId}`,
+					isError: true
+				};
+				return {
+					text: `granted: you may now type into and kill shell #${shell.ordinal} ${shell.id} ($ ${shell.command}) until it ends or the user revokes it`,
+					isError: false
+				};
+			}
 		}
 	} catch (error) {
 		return {
@@ -1594,18 +1856,43 @@ async function runShellTool(shells, from, name, args) {
 		};
 	}
 }
+function needles(waitFor) {
+	if (waitFor === void 0) return;
+	return typeof waitFor === "string" ? [waitFor] : waitFor;
+}
 function invalidArguments(name, error) {
 	return {
 		text: `invalid arguments for ${name}: ${error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ")}`,
 		isError: true
 	};
 }
-function shellReadText(result) {
+function shellReadText(result, verb) {
 	const { shell } = result;
-	const scope = result.truncated ? `showing the last ${result.lines} of ${result.totalLines} lines` : `showing all ${result.lines} lines`;
-	const head = `[shell #${shell.ordinal} ${shell.id}: $ ${shell.command}, ${shellState(shell)}, ${scope}]`;
+	const scope = result.view === "screen" ? "the current screen" : result.truncated ? `showing the last ${result.lines} of ${result.totalLines} lines` : `showing all ${result.lines} lines`;
+	const parts = [
+		`$ ${shell.command}`,
+		...verb ? [verb] : [],
+		shellState(shell),
+		...shell.interactive ? ["interactive"] : [],
+		scope
+	];
+	if (result.wait) parts.push(waitText(result.wait));
+	const head = `[shell #${shell.ordinal} ${shell.id}: ${parts.join(", ")}]`;
 	return result.text ? `${head}\n${result.text}` : `${head}\n(no output)`;
 }
+function shellKillText(result) {
+	const { shell } = result;
+	const name = `shell #${shell.ordinal} ${shell.id} ($ ${shell.command})`;
+	return result.killed ? `killed ${name}` : `${name} had already ended (${shellState(shell)})`;
+}
+function waitText(wait) {
+	const seconds = `${(wait.ms / 1e3).toFixed(1)}s`;
+	switch (wait.outcome) {
+		case "matched": return `found ${JSON.stringify(wait.match)} after ${seconds}`;
+		case "exited": return `the shell ended before the text appeared (${seconds})`;
+		case "timeout": return `the text did not appear within ${seconds}`;
+	}
+}
 function shellState(shell) {
 	if (shell.status === "running") return "still running";
 	if (shell.exitCode !== void 0) return `exited ${shell.exitCode}`;
@@ -1625,7 +1912,11 @@ function shellDirectoryHandle() {
 	};
 	return {
 		list: async (from) => resolve().list(from),
-		read: async (from, shellId, options) => resolve().read(from, shellId, options)
+		read: async (from, shellId, options) => resolve().read(from, shellId, options),
+		run: async (from, options) => resolve().run(from, options),
+		write: async (from, shellId, options) => resolve().write(from, shellId, options),
+		kill: async (from, shellId) => resolve().kill(from, shellId),
+		grant: async (from, shellId) => resolve().grant(from, shellId)
 	};
 }
 //#endregion
@@ -1887,6 +2178,7 @@ var SessionRunner = class {
 			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "claude",
+			shellAgentWrite: this.#config.shells ? this.#config.shellAgentWrite : void 0,
 			capabilities: ENGINE_CAPABILITIES.claude,
 			model: this.#model ?? this.#config.model,
 			permissionMode: this.#permissionMode,
@@ -2154,8 +2446,8 @@ var SessionRunner = class {
 				}],
 				isError: output.isError
 			};
-		})) : [], ...shells ? SHELL_TOOL_NAMES.map((name) => tool(name, SHELL_TOOL_SHAPES[name].description, SHELL_TOOL_SHAPES[name].shape, async (args) => {
-			const output = await runShellTool(shells, this.id, name, args);
+		})) : [], ...shells ? shellToolNames(this.#config.shellAgentWrite !== void 0).map((name) => tool(name, SHELL_TOOL_SHAPES[name].description, SHELL_TOOL_SHAPES[name].shape, async (args) => {
+			const output = await runShellTool(shells, this.id, name, args, { write: this.#config.shellAgentWrite !== void 0 });
 			return {
 				content: [{
 					type: "text",
@@ -2390,6 +2682,10 @@ var SessionRunner = class {
 			delete request.expiresAt;
 			return Promise.resolve(this.#resolveQuestionByPolicy(request, questionBehavior));
 		}
+		if (this.#allowsShellToolByPolicy(toolName)) {
+			delete request.expiresAt;
+			return Promise.resolve(this.#allowByPolicy(request));
+		}
 		return new Promise((resolve) => {
 			const timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
 				const pending = this.#pending.get(id);
@@ -2417,6 +2713,27 @@ var SessionRunner = class {
 			this.#setStatus("awaiting_approval");
 		});
 	};
+	#allowsShellToolByPolicy(toolName) {
+		if ((this.#config.shells ? shellToolOf(toolName) : void 0) === void 0) return false;
+		return shellWriteToolOf(toolName) === void 0 || !shellToolNeedsCard(toolName, this.#config.shellAgentWrite);
+	}
+	#allowByPolicy(request) {
+		this.#emit({
+			type: "permission_requested",
+			request
+		});
+		this.#emit({
+			type: "permission_resolved",
+			requestId: request.id,
+			behavior: "allow",
+			resolvedBy: "policy"
+		});
+		return {
+			behavior: "allow",
+			updatedInput: request.input,
+			toolUseID: request.toolUseId
+		};
+	}
 	#resolveQuestionByPolicy(request, mode) {
 		this.#emit({
 			type: "permission_requested",
@@ -2619,6 +2936,7 @@ var AiSdkRunner = class {
 			cwd: this.#config.cwd ?? "",
 			profile: this.#config.profile,
 			engine: "provider",
+			shellAgentWrite: this.#config.shells ? this.#config.shellAgentWrite : void 0,
 			capabilities: this.#config.shouldApprove ? {
 				...ENGINE_CAPABILITIES.provider,
 				interactiveApprovals: true
@@ -3831,15 +4149,16 @@ function createToolContext(options) {
 	}
 	if (options.shells) {
 		const shells = options.shells;
+		const write = options.shellWrite === true;
 		const selfId = options.selfId ?? (() => options.sessionId);
-		for (const name of SHELL_TOOL_NAMES) definitions.push({
+		for (const name of shellToolNames(write)) definitions.push({
 			name,
 			trust: "authoritative",
 			tool: tool$1({
 				description: SHELL_TOOL_SHAPES[name].description,
 				inputSchema: z.object(SHELL_TOOL_SHAPES[name].shape),
 				execute: async (args) => {
-					const output = await runShellTool(shells, selfId(), name, args);
+					const output = await runShellTool(shells, selfId(), name, args, { write });
 					return output.isError ? { error: output.text } : { result: output.text };
 				}
 			})
@@ -4206,6 +4525,7 @@ function createEngineSession(options) {
 		onFileDelivered: options.capabilities?.deliverFiles === false || !isGranted("deliverFiles") ? void 0 : (file) => runner?.emitFileDelivered(file),
 		peers: options.config.peers,
 		shells: options.config.shells,
+		shellWrite: options.config.shellAgentWrite !== void 0,
 		selfId: () => runner?.id ?? "pending"
 	});
 	const declaredServers = options.profile?.session?.mcpServers;
@@ -5148,6 +5468,28 @@ function codexAnswers(questions, answers) {
 	}
 	return out;
 }
+const SHELL_WRITE_CHANNEL = {
+	describe: (raw) => {
+		const call = raw;
+		const input = typeof call.arguments === "object" && call.arguments !== null ? call.arguments : {};
+		return {
+			toolName: call.tool,
+			input,
+			title: `Agent wants to run ${call.tool}`,
+			displayName: call.tool
+		};
+	},
+	itemId: (raw) => raw.callId,
+	allow: (_raw, updatedInput) => ({ response: {
+		allowed: true,
+		updatedInput
+	} }),
+	deny: (_raw, _interrupt, _offered, message) => ({ response: {
+		allowed: false,
+		message
+	} })
+};
+const SHELL_WRITE_GATE_MODES = /* @__PURE__ */ new Set(["default", "acceptEdits"]);
 function decisionChannel(describe, itemId) {
 	return {
 		describe,
@@ -5368,6 +5710,7 @@ var CodexRunner = class {
 			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "codex",
+			shellAgentWrite: this.#config.shells ? this.#config.shellAgentWrite : void 0,
 			capabilities: ENGINE_CAPABILITIES.codex,
 			model: this.#model ?? this.#resolvedModel,
 			permissionMode: this.#permissionMode,
@@ -5755,7 +6098,7 @@ var CodexRunner = class {
 			};
 			if (this.#model) options.model = this.#model;
 			if (this.#instructions !== void 0) options.developerInstructions = this.#instructions;
-			const dynamic = [...this.#config.peers ? peerToolSpecs() : [], ...this.#config.shells ? shellToolSpecs() : []];
+			const dynamic = [...this.#config.peers ? peerToolSpecs() : [], ...this.#config.shells ? shellToolSpecs(this.#config.shellAgentWrite !== void 0) : []];
 			if (dynamic.length) options.dynamicTools = dynamic.map((spec) => ({
 				type: "function",
 				...spec
@@ -6193,7 +6536,20 @@ var CodexRunner = class {
 				};
 			}
 			if (shells && isShellToolName(call.tool)) {
-				const output = await runShellTool(shells, this.id, call.tool, call.arguments);
+				const write = this.#config.shellAgentWrite !== void 0;
+				let args = call.arguments;
+				if (write && shellToolNeedsCard(call.tool, this.#config.shellAgentWrite) && SHELL_WRITE_GATE_MODES.has(this.#permissionMode)) {
+					const verdict = await this.#requestApproval(SHELL_WRITE_CHANNEL, method, call, void 0);
+					if (!verdict.allowed) return {
+						success: false,
+						contentItems: [{
+							type: "inputText",
+							text: shellWriteDeniedText(call.tool, verdict.message)
+						}]
+					};
+					args = verdict.updatedInput ?? args;
+				}
+				const output = await runShellTool(shells, this.id, call.tool, args, { write });
 				return {
 					success: !output.isError,
 					contentItems: [{
@@ -6292,7 +6648,7 @@ var CodexRunner = class {
 				message = "codex offered no plain accept for this request (only broader session/policy grants), denied instead";
 				sent = pending.channel.deny(pending.params, false, pending.offered);
 			}
-		} else sent = pending.channel.deny(pending.params, decision.interrupt === true, pending.offered);
+		} else sent = pending.channel.deny(pending.params, decision.interrupt === true, pending.offered, message);
 		pending.respond(sent.response);
 		this.#emit({
 			type: "permission_resolved",
@@ -6962,6 +7318,6 @@ function getEngineAdapter(engine) {
 	return ADAPTERS[engine ?? "claude"];
 }
 //#endregion
-export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, CostLedger, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, LocalCommandQueue, PEER_MCP_SERVER, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, PEER_TOOL_NAMES, PendingRequestRegistry, QuickJsExecutor, SHELL_REFUSAL, SHELL_TOOL_NAMES, SHELL_TOOL_SHAPES, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, clampShellTail, claudeAdapter, codexAdapter, composeInstructions, connectAppServer, connectMcpTools, countLines, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, headTail, htmlToMarkdown, installPeerDirectory, installShellDirectory, installedPeerDirectory, installedShellDirectory, isHostAllowed, isLocalShellSource, isPrivateAddress, isShellToolName, isSlashCommand, listCodexSessions, localCommandContext, localCommandEvent, localCommandTranscript, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, peerDirectoryHandle, peerMentionsEnvelope, peerMessageEnvelope, peerSummary, peerToolSpecs, providerAdapter, recentLines, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, resolveInstructions, runPeerTool, runShellTool, shellContextText, shellDirectoryHandle, shellInlineText, shellReadText, shellSummary, shellTail, shellToolSpecs, splitLines, toApiMessage, toExecutionResult, truncateResultBlocks, ttyText, withHostTools, withMcpTools, withPeerContext };
+export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, CostLedger, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, LocalCommandQueue, PEER_MCP_SERVER, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, PEER_TOOL_NAMES, PendingRequestRegistry, QuickJsExecutor, SHELL_KEYS_MAX, SHELL_KEY_NAMES, SHELL_READ_TOOL_NAMES, SHELL_REFUSAL, SHELL_TOOL_NAMES, SHELL_TOOL_SHAPES, SHELL_WRITE_REFUSAL, SHELL_WRITE_TOOL_NAMES, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, TTY_REDRAW_CARRY, agentMayWrite, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, clampShellTail, claudeAdapter, codexAdapter, composeInstructions, connectAppServer, connectMcpTools, countLines, createEngineSession, createToolContext, createWebFetch, encodeShellKey, encodeShellKeys, getEngineAdapter, headTail, htmlToMarkdown, installPeerDirectory, installShellDirectory, installedPeerDirectory, installedShellDirectory, isHostAllowed, isLocalShellSource, isPrivateAddress, isShellToolName, isShellWriteToolName, isSlashCommand, listCodexSessions, localCommandContext, localCommandEvent, localCommandTranscript, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, peerDirectoryHandle, peerMentionsEnvelope, peerMessageEnvelope, peerSummary, peerToolSpecs, providerAdapter, recentLines, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, resolveInstructions, runPeerTool, runShellTool, shellContextText, shellDirectoryHandle, shellInlineText, shellKillText, shellOwnershipRefusal, shellReadText, shellSummary, shellTail, shellToolNames, shellToolNeedsCard, shellToolOf, shellToolSpecs, shellWriteDeniedText, shellWriteToolOf, splitLines, toApiMessage, toExecutionResult, truncateResultBlocks, ttyRedraws, ttyText, withHostTools, withMcpTools, withPeerContext };
 
 //# sourceMappingURL=index.mjs.map