@draht/coding-agent 2026.3.14 → 2026.3.25

package/docs/rpc.md

@@ -58,7 +58,7 @@ With images:
 {"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}
 ```
 
-- `"steer"`: Interrupt the agent mid-run. Message is delivered after current tool execution, remaining tools are skipped.
+- `"steer"`: Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
 - `"followUp"`: Wait until the agent finishes. Message is delivered only when agent stops.
 
 If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.
@@ -76,7 +76,7 @@ The `images` field is optional. Each image uses `ImageContent` format: `{"type":
 
 #### steer
 
-Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
+Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
 
 ```json
 {"type": "steer", "message": "Stop and do this instead"}
@@ -321,8 +321,8 @@ Control how steering messages (from `steer`) are delivered.
 ```
 
 Modes:
-- `"all"`: Deliver all steering messages at the next interruption point
-- `"one-at-a-time"`: Deliver one steering message per interruption (default)
+- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls
+- `"one-at-a-time"`: Deliver one steering message per completed assistant turn (default)
 
 Response:
 ```json
@@ -494,7 +494,7 @@ Response:
 
 #### get_session_stats
 
-Get token usage and cost statistics.
+Get token usage, cost statistics, and current context window usage.
 
 ```json
 {"type": "get_session_stats"}
@@ -521,11 +521,20 @@ Response:
       "cacheWrite": 5000,
       "total": 105000
     },
-    "cost": 0.45
+    "cost": 0.45,
+    "contextUsage": {
+      "tokens": 60000,
+      "contextWindow": 200000,
+      "percent": 30
+    }
   }
 }
 ```
 
+`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.
+
+`contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.
+
 #### export_html
 
 Export session to an HTML file.

package/docs/sdk.md

@@ -78,7 +78,7 @@ interface AgentSession {
   prompt(text: string, options?: PromptOptions): Promise<void>;
   
   // Queue messages during streaming
-  steer(text: string): Promise<void>;    // Interrupt: delivered after current tool, skips remaining
+  steer(text: string): Promise<void>;    // Queue for delivery after the current assistant turn finishes its tool calls
   followUp(text: string): Promise<void>; // Wait: delivered only when agent finishes
   
   // Subscribe to events (returns unsubscribe function)
@@ -150,7 +150,7 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
 For explicit queueing during streaming:
 
 ```typescript
-// Interrupt the agent (delivered after current tool, skips remaining tools)
+// Queue a steering message for delivery after the current assistant turn finishes its tool calls
 await session.steer("New instruction");
 
 // Wait for agent to finish (delivered only when agent stops)

package/docs/settings.md

@@ -117,6 +117,15 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 |---------|------|---------|-------------|
 | `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows) |
 | `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
+| `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
+
+```json
+{
+  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
+}
+```
+
+`npmCommand` is used for all npm package-manager operations, including `npm root -g`, installs, uninstalls, and `npm install` inside git packages. Use argv-style entries exactly as the process should be launched.
 
 ### Model Cycling
 

package/docs/terminal-setup.md

@@ -86,6 +86,17 @@ Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward
 
 If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
 
+## xfce4-terminal, terminator
+
+These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
+
+For the best experience, use a terminal that supports the Kitty keyboard protocol:
+- [Kitty](https://sw.kovidgoyal.net/kitty/)
+- [Ghostty](https://ghostty.org/)
+- [WezTerm](https://wezfurlong.org/wezterm/)
+- [iTerm2](https://iterm2.com/)
+- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
+
 ## IntelliJ IDEA (Integrated Terminal)
 
 The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.

package/docs/tui.md

@@ -394,7 +394,7 @@ Components accept theme objects for styling.
 **In `renderCall`/`renderResult`**, use the `theme` parameter:
 
 ```typescript
-renderResult(result, options, theme) {
+renderResult(result, options, theme, context) {
   // Use theme.fg() for foreground colors
   return new Text(theme.fg("success", "Done!"), 0, 0);
   
@@ -428,7 +428,7 @@ renderResult(result, options, theme) {
 import { getMarkdownTheme } from "@draht/coding-agent";
 import { Markdown } from "@draht/tui";
 
-renderResult(result, options, theme) {
+renderResult(result, options, theme, context) {
   const mdTheme = getMarkdownTheme();
   return new Markdown(result.details.markdown, 0, 0, mdTheme);
 }

package/examples/extensions/README.md

@@ -1,6 +1,6 @@
 # Extension Examples
 
-Example extensions for pi-coding-agent.
+Example extensions for @draht/coding-agent.
 
 ## Usage
 
@@ -119,7 +119,7 @@ cp permission-gate.ts ~/.draht/agent/extensions/
 | Extension | Description |
 |-----------|-------------|
 | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
-| `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+| `custom-provider-gitlab-duo/` | GitLab Duo provider using @draht/ai's built-in Anthropic/OpenAI streaming via proxy |
 | `custom-provider-qwen-cli/` | Qwen CLI provider with OAuth device flow and OpenAI-compatible models |
 
 ### External Dependencies

package/examples/extensions/antigravity-image-gen.ts

@@ -30,7 +30,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { StringEnum } from "@draht/ai";
-import { type ExtensionAPI, getAgentDir } from "@draht/coding-agent";
+import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@draht/coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 
 const PROVIDER = "google-antigravity";
@@ -228,12 +228,14 @@ function imageExtension(mimeType: string): string {
 }
 
 async function saveImage(base64Data: string, mimeType: string, outputDir: string): Promise<string> {
-	await mkdir(outputDir, { recursive: true });
 	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
 	const ext = imageExtension(mimeType);
 	const filename = `image-${timestamp}-${randomUUID().slice(0, 8)}.${ext}`;
 	const filePath = join(outputDir, filename);
-	await writeFile(filePath, Buffer.from(base64Data, "base64"));
+	await withFileMutationQueue(filePath, async () => {
+		await mkdir(outputDir, { recursive: true });
+		await writeFile(filePath, Buffer.from(base64Data, "base64"));
+	});
 	return filePath;
 }
 

package/examples/extensions/built-in-tool-renderer.ts

@@ -42,7 +42,7 @@ export default function (pi: ExtensionAPI) {
 			return originalRead.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("read "));
 			text += theme.fg("accent", args.path);
 			if (args.offset || args.limit) {
@@ -54,7 +54,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded, isPartial }, theme) {
+		renderResult(result, { expanded, isPartial }, theme, _context) {
 			if (isPartial) return new Text(theme.fg("warning", "Reading..."), 0, 0);
 
 			const details = result.details as ReadToolDetails | undefined;
@@ -101,7 +101,7 @@ export default function (pi: ExtensionAPI) {
 			return originalBash.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("$ "));
 			const cmd = args.command.length > 80 ? `${args.command.slice(0, 77)}...` : args.command;
 			text += theme.fg("accent", cmd);
@@ -111,7 +111,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded, isPartial }, theme) {
+		renderResult(result, { expanded, isPartial }, theme, _context) {
 			if (isPartial) return new Text(theme.fg("warning", "Running..."), 0, 0);
 
 			const details = result.details as BashToolDetails | undefined;
@@ -160,13 +160,13 @@ export default function (pi: ExtensionAPI) {
 			return originalEdit.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("edit "));
 			text += theme.fg("accent", args.path);
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded, isPartial }, theme) {
+		renderResult(result, { expanded, isPartial }, theme, _context) {
 			if (isPartial) return new Text(theme.fg("warning", "Editing..."), 0, 0);
 
 			const details = result.details as EditToolDetails | undefined;
@@ -224,7 +224,7 @@ export default function (pi: ExtensionAPI) {
 			return originalWrite.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("write "));
 			text += theme.fg("accent", args.path);
 			const lineCount = args.content.split("\n").length;
@@ -232,7 +232,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { isPartial }, theme) {
+		renderResult(result, { isPartial }, theme, _context) {
 			if (isPartial) return new Text(theme.fg("warning", "Writing..."), 0, 0);
 
 			const content = result.content[0];

package/examples/extensions/commands.ts

@@ -60,10 +60,10 @@ export default function commandsExtension(pi: ExtensionAPI) {
 			if (selected && !selected.startsWith("---")) {
 				const cmdName = selected.split(" - ")[0].slice(1); // Remove leading /
 				const cmd = commands.find((c) => c.name === cmdName);
-				if (cmd?.path) {
-					const showPath = await ctx.ui.confirm(cmd.name, `View source path?\n${cmd.path}`);
+				if (cmd?.sourceInfo.path) {
+					const showPath = await ctx.ui.confirm(cmd.name, `View source path?\n${cmd.sourceInfo.path}`);
 					if (showPath) {
-						ctx.ui.notify(cmd.path, "info");
+						ctx.ui.notify(cmd.sourceInfo.path, "info");
 					}
 				}
 			}

package/examples/extensions/minimal-mode.ts

@@ -80,7 +80,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.read.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
 
@@ -94,7 +94,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(`${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			// Minimal mode: show nothing in collapsed state
 			if (!expanded) {
 				return new Text("", 0, 0);
@@ -127,7 +127,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.bash.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const command = args.command || "...";
 			const timeout = args.timeout as number | undefined;
 			const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
@@ -135,7 +135,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(theme.fg("toolTitle", theme.bold(`$ ${command}`)) + timeoutSuffix, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			// Minimal mode: show nothing in collapsed state
 			if (!expanded) {
 				return new Text("", 0, 0);
@@ -176,7 +176,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.write.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
 			const lineCount = args.content ? args.content.split("\n").length : 0;
@@ -185,7 +185,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			// Minimal mode: show nothing (file was written)
 			if (!expanded) {
 				return new Text("", 0, 0);
@@ -218,14 +218,14 @@ export default function (pi: ExtensionAPI) {
 			return tools.edit.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
 
 			return new Text(`${theme.fg("toolTitle", theme.bold("edit"))} ${pathDisplay}`, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			// Minimal mode: show nothing in collapsed state
 			if (!expanded) {
 				return new Text("", 0, 0);
@@ -263,7 +263,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.find.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const pattern = args.pattern || "";
 			const path = shortenPath(args.path || ".");
 			const limit = args.limit;
@@ -277,7 +277,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			if (!expanded) {
 				// Minimal: just show count
 				const textContent = result.content.find((c) => c.type === "text");
@@ -321,7 +321,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.grep.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const pattern = args.pattern || "";
 			const path = shortenPath(args.path || ".");
 			const glob = args.glob;
@@ -339,7 +339,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			if (!expanded) {
 				// Minimal: just show match count
 				const textContent = result.content.find((c) => c.type === "text");
@@ -383,7 +383,7 @@ export default function (pi: ExtensionAPI) {
 			return tools.ls.execute(toolCallId, params, signal, onUpdate);
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || ".");
 			const limit = args.limit;
 
@@ -395,7 +395,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			if (!expanded) {
 				// Minimal: just show entry count
 				const textContent = result.content.find((c) => c.type === "text");

package/examples/extensions/question.ts

@@ -227,7 +227,7 @@ export default function question(pi: ExtensionAPI) {
 			};
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("question ")) + theme.fg("muted", args.question);
 			const opts = Array.isArray(args.options) ? args.options : [];
 			if (opts.length) {
@@ -238,7 +238,7 @@ export default function question(pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, _options, theme) {
+		renderResult(result, _options, theme, _context) {
 			const details = result.details as QuestionDetails | undefined;
 			if (!details) {
 				const text = result.content[0];

package/examples/extensions/questionnaire.ts

@@ -393,7 +393,7 @@ export default function questionnaire(pi: ExtensionAPI) {
 			};
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const qs = (args.questions as Question[]) || [];
 			const count = qs.length;
 			const labels = qs.map((q) => q.label || q.id).join(", ");
@@ -405,7 +405,7 @@ export default function questionnaire(pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, _options, theme) {
+		renderResult(result, _options, theme, _context) {
 			const details = result.details as QuestionnaireResult | undefined;
 			if (!details) {
 				const text = result.content[0];

package/examples/extensions/subagent/index.ts

@@ -19,7 +19,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@draht/agent-core";
 import type { Message } from "@draht/ai";
 import { StringEnum } from "@draht/ai";
-import { type ExtensionAPI, getMarkdownTheme } from "@draht/coding-agent";
+import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@draht/coding-agent";
 import { Container, Markdown, Spacer, Text } from "@draht/tui";
 import { Type } from "@sinclair/typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
@@ -207,14 +207,31 @@ async function mapWithConcurrencyLimit<TIn, TOut>(
 	return results;
 }
 
-function writePromptToTempFile(agentName: string, prompt: string): { dir: string; filePath: string } {
-	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	fs.writeFileSync(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+	await withFileMutationQueue(filePath, async () => {
+		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+	});
 	return { dir: tmpDir, filePath };
 }
 
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	const currentScript = process.argv[1];
+	if (currentScript && fs.existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+
+	const execName = path.basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) {
+		return { command: process.execPath, args };
+	}
+
+	return { command: "pi", args };
+}
+
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
 async function runSingleAgent(
@@ -274,7 +291,7 @@ async function runSingleAgent(
 
 	try {
 		if (agent.systemPrompt.trim()) {
-			const tmp = writePromptToTempFile(agent.name, agent.systemPrompt);
+			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
 			tmpPromptDir = tmp.dir;
 			tmpPromptPath = tmp.filePath;
 			args.push("--append-system-prompt", tmpPromptPath);
@@ -284,7 +301,12 @@ async function runSingleAgent(
 		let wasAborted = false;
 
 		const exitCode = await new Promise<number>((resolve) => {
-			const proc = spawn("pi", args, { cwd: cwd ?? defaultCwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+			const invocation = getPiInvocation(args);
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: cwd ?? defaultCwd,
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
 			let buffer = "";
 
 			const processLine = (line: string) => {
@@ -646,7 +668,7 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const scope: AgentScope = args.agentScope ?? "user";
 			if (args.chain && args.chain.length > 0) {
 				let text =
@@ -690,7 +712,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			const details = result.details as SubagentDetails | undefined;
 			if (!details || details.results.length === 0) {
 				const text = result.content[0];

package/examples/extensions/titlebar-spinner.ts

@@ -16,7 +16,7 @@ const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧",
 function getBaseTitle(pi: ExtensionAPI): string {
 	const cwd = path.basename(process.cwd());
 	const session = pi.getSessionName();
-	return session ? `π - ${session} - ${cwd}` : `π - ${cwd}`;
+	return session ? `D - ${session} - ${cwd}` : `D - ${cwd}`;
 }
 
 export default function (pi: ExtensionAPI) {
@@ -38,7 +38,7 @@ export default function (pi: ExtensionAPI) {
 			const frame = BRAILLE_FRAMES[frameIndex % BRAILLE_FRAMES.length];
 			const cwd = path.basename(process.cwd());
 			const session = pi.getSessionName();
-			const title = session ? `${frame} π - ${session} - ${cwd}` : `${frame} π - ${cwd}`;
+			const title = session ? `${frame} D - ${session} - ${cwd}` : `${frame} D - ${cwd}`;
 			ctx.ui.setTitle(title);
 			frameIndex++;
 		}, 80);

package/examples/extensions/todo.ts

@@ -220,14 +220,14 @@ export default function (pi: ExtensionAPI) {
 			}
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
 			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
 			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			const details = result.details as TodoDetails | undefined;
 			if (!details) {
 				const text = result.content[0];

package/examples/extensions/tool-override.ts

@@ -21,10 +21,10 @@
  */
 
 import type { TextContent } from "@draht/ai";
-import { type ExtensionAPI, getAgentDir } from "@draht/coding-agent";
+import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@draht/coding-agent";
 import { Type } from "@sinclair/typebox";
-import { appendFileSync, constants, readFileSync } from "fs";
-import { access, readFile } from "fs/promises";
+import { constants, readFileSync } from "fs";
+import { access, appendFile, readFile } from "fs/promises";
 import { join, resolve } from "path";
 
 const LOG_FILE = join(getAgentDir(), "read-access.log");
@@ -44,14 +44,16 @@ function isBlockedPath(path: string): boolean {
 	return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
 }
 
-function logAccess(path: string, allowed: boolean, reason?: string) {
+async function logAccess(path: string, allowed: boolean, reason?: string) {
 	const timestamp = new Date().toISOString();
 	const status = allowed ? "ALLOWED" : "BLOCKED";
 	const msg = reason ? ` (${reason})` : "";
 	const line = `[${timestamp}] ${status}: ${path}${msg}\n`;
 
 	try {
-		appendFileSync(LOG_FILE, line);
+		await withFileMutationQueue(LOG_FILE, async () => {
+			await appendFile(LOG_FILE, line);
+		});
 	} catch {
 		// Ignore logging errors
 	}
@@ -77,7 +79,7 @@ export default function (pi: ExtensionAPI) {
 
 			// Check if path is blocked
 			if (isBlockedPath(absolutePath)) {
-				logAccess(absolutePath, false, "matches blocked pattern");
+				await logAccess(absolutePath, false, "matches blocked pattern");
 				return {
 					content: [
 						{
@@ -90,7 +92,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Log allowed access
-			logAccess(absolutePath, true);
+			await logAccess(absolutePath, true);
 
 			// Perform the actual read (simplified implementation)
 			try {

package/examples/extensions/truncated-tool.ts

@@ -14,6 +14,7 @@
  * built-in `grep` tool in src/core/tools/grep.ts for a more complete implementation.
  */
 
+import { mkdtemp, writeFile } from "node:fs/promises";
 import type { ExtensionAPI } from "@draht/coding-agent";
 import {
 	DEFAULT_MAX_BYTES,
@@ -21,11 +22,11 @@ import {
 	formatSize,
 	type TruncationResult,
 	truncateHead,
+	withFileMutationQueue,
 } from "@draht/coding-agent";
 import { Text } from "@draht/tui";
 import { Type } from "@sinclair/typebox";
 import { execSync } from "child_process";
-import { mkdtempSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 
@@ -108,9 +109,11 @@ export default function (pi: ExtensionAPI) {
 
 			if (truncation.truncated) {
 				// Save full output to a temp file so LLM can access it if needed
-				const tempDir = mkdtempSync(join(tmpdir(), "pi-rg-"));
+				const tempDir = await mkdtemp(join(tmpdir(), "pi-rg-"));
 				const tempFile = join(tempDir, "output.txt");
-				writeFileSync(tempFile, output);
+				await withFileMutationQueue(tempFile, async () => {
+					await writeFile(tempFile, output, "utf8");
+				});
 
 				details.truncation = truncation;
 				details.fullOutputPath = tempFile;
@@ -132,7 +135,7 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		// Custom rendering of the tool call (shown before/during execution)
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("rg "));
 			text += theme.fg("accent", `"${args.pattern}"`);
 			if (args.path) {
@@ -145,7 +148,7 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		// Custom rendering of the tool result
-		renderResult(result, { expanded, isPartial }, theme) {
+		renderResult(result, { expanded, isPartial }, theme, _context) {
 			const details = result.details as RgDetails | undefined;
 
 			// Handle streaming/partial results