@oh-my-pi/pi-coding-agent 17.1.1 → 17.1.3

package/src/launch/broker-list-order.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { TempDir } from "@oh-my-pi/pi-utils";
+import { createDaemonBrokerClient, type DaemonBrokerClient } from "./client";
+import type { DaemonSnapshot, DaemonSpec } from "./protocol";
+
+const TERMINAL_HISTORY_LIMIT = 10;
+
+function spec(name: string, cwd: string): DaemonSpec {
+	return {
+		name,
+		application: process.execPath,
+		args: [],
+		env: {},
+		cwd,
+		pty: false,
+		restart: "no",
+		persist: false,
+		detached: false,
+	};
+}
+
+function terminalSnapshot(index: number): DaemonSnapshot {
+	const name = `exited-${index}`;
+	return {
+		name,
+		id: name,
+		state: index % 2 === 0 ? "exited" : "failed",
+		createdAt: index * 10,
+		startedAt: index * 10,
+		exitedAt: index * 10 + 1,
+		exitReason: `historical exit ${index}`,
+		restartCount: 0,
+		outputBytes: 0,
+		persist: false,
+		detached: false,
+	};
+}
+
+async function seedTerminalRecord(runtimeDir: string, cwd: string, snapshot: DaemonSnapshot): Promise<void> {
+	const metaPath = path.join(runtimeDir, "daemons", snapshot.name, "meta.json");
+	await Bun.write(metaPath, JSON.stringify({ daemon: snapshot, spec: spec(snapshot.name, cwd) }));
+}
+
+async function shutdown(client: DaemonBrokerClient, activeName: string): Promise<void> {
+	await client.request({ op: "stop", name: activeName, timeoutMs: 2_000 }).catch(() => undefined);
+	await client.request({ op: "shutdown" }).catch(() => undefined);
+	client.close();
+}
+
+describe("broker list", () => {
+	it("returns active daemons first and caps recovered terminal history by real exit time", async () => {
+		using tempDir = TempDir.createSync("@omp-launch-list-");
+		const projectDir = path.join(tempDir.path(), "project");
+		const runtimeDir = path.join(tempDir.path(), "runtime");
+		await fs.mkdir(projectDir);
+
+		for (let index = 0; index < TERMINAL_HISTORY_LIMIT + 5; index++) {
+			await seedTerminalRecord(runtimeDir, projectDir, terminalSnapshot(index));
+		}
+
+		const client = await createDaemonBrokerClient(projectDir, { runtimeDir, idleGraceMs: 5_000 });
+		const activeName = "active-server";
+		try {
+			const started = await client.request({
+				op: "start",
+				spec: {
+					...spec(activeName, projectDir),
+					args: ["-e", "process.stdin.resume()"],
+				},
+			});
+			expect(started.op).toBe("start");
+
+			const listed = await client.request({ op: "list" });
+			expect(listed.op).toBe("list");
+			if (listed.op !== "list") throw new Error(`Unexpected broker result: ${listed.op}`);
+
+			expect(listed.daemons.map(daemon => daemon.name)).toEqual([
+				activeName,
+				...Array.from({ length: TERMINAL_HISTORY_LIMIT }, (_, offset) => `exited-${14 - offset}`),
+			]);
+			expect(listed.daemons[0]?.state).toBe("running");
+			expect(listed.daemons.at(-1)?.exitedAt).toBe(51);
+		} finally {
+			await shutdown(client, activeName);
+		}
+	}, 20_000);
+});

package/src/launch/broker.ts

@@ -33,6 +33,12 @@ const MAX_LOG_BYTES = 25 * 1024 * 1024;
 const LOG_READ_BYTES = 2 * 1024 * 1024;
 const READINESS_BUFFER_CHARS = 64 * 1024;
 const RESTART_MAX_DELAY_MS = 30_000;
+/**
+ * Cap on terminal (exited/failed) daemons surfaced by `list`. Active daemons
+ * are always shown in full; older history is truncated so the response stays
+ * bounded over a long-lived project (issue #6517).
+ */
+const MAX_TERMINAL_DAEMONS_LISTED = 10;
 const TOKEN_FILE = "broker.token";
 const PID_FILE = "broker.pid";
 const META_FILE = "meta.json";
@@ -95,6 +101,41 @@ function terminalState(state: DaemonSnapshot["state"]): boolean {
 	return state === "exited" || state === "failed";
 }
 
+/**
+ * Order daemons for the `list` response: non-terminal (active) daemons first,
+ * oldest to newest, so the process the user is acting on is immediately visible
+ * instead of buried behind exited history; then the most recently exited/failed
+ * ones, capped at {@link MAX_TERMINAL_DAEMONS_LISTED} to keep the response from
+ * growing without bound. Truncated terminal records stay addressable by name
+ * via `describe`/`logs`/`restart`.
+ */
+function orderDaemonsForListing(snapshots: DaemonSnapshot[]): DaemonSnapshot[] {
+	const active: DaemonSnapshot[] = [];
+	const terminal: DaemonSnapshot[] = [];
+	for (const snapshot of snapshots) {
+		(terminalState(snapshot.state) ? terminal : active).push(snapshot);
+	}
+	active.sort((left, right) => left.createdAt - right.createdAt);
+	terminal.sort((left, right) => (right.exitedAt ?? right.createdAt) - (left.exitedAt ?? left.createdAt));
+	return [...active, ...terminal.slice(0, MAX_TERMINAL_DAEMONS_LISTED)];
+}
+
+/**
+ * Reap a recovered non-detached daemon snapshot in place. Already-terminal
+ * records are left untouched so `list` keeps their real {@link DaemonSnapshot.exitedAt}
+ * for recency ranking; records that were still alive when the previous broker
+ * exited are marked `exited` at `now`, since their process died with that broker
+ * (issue #6517). Returns whether the record was reaped.
+ */
+function reapRecoveredSnapshot(snapshot: DaemonSnapshot, now: number): boolean {
+	if (terminalState(snapshot.state)) return false;
+	snapshot.pid = undefined;
+	snapshot.state = "exited";
+	snapshot.exitedAt = now;
+	snapshot.exitReason = "previous broker exited";
+	return true;
+}
+
 /** Mirror per-condition readiness progress into the snapshot so clients can see which condition is unmet. */
 function syncReadyPending(record: ManagedDaemon): void {
 	if (record.snapshot.state !== "starting") {
@@ -402,9 +443,7 @@ class DaemonBroker {
 				await Promise.all([...this.#records.values()].map(record => this.#refreshDetached(record)));
 				return {
 					op: "list",
-					daemons: [...this.#records.values()]
-						.sort((left, right) => left.snapshot.createdAt - right.snapshot.createdAt)
-						.map(record => record.snapshot),
+					daemons: orderDaemonsForListing([...this.#records.values()].map(record => record.snapshot)),
 				};
 			}
 			case "logs":
@@ -973,11 +1012,13 @@ class DaemonBroker {
 					snapshot.state !== "stopping" &&
 					processRef?.status() === "running";
 				if (!detached) {
-					if (processRef) await processRef.terminate({ group: true, gracefulMs: 500, timeoutMs: 2_000 });
-					snapshot.pid = undefined;
-					snapshot.state = "exited";
-					snapshot.exitedAt = Date.now();
-					snapshot.exitReason = "previous broker exited";
+					// Reap only records that were still alive when the previous broker
+					// exited; already-terminal records keep their real exit time so
+					// `list` ranks exited history by true recency (issue #6517).
+					if (!terminalState(snapshot.state) && processRef) {
+						await processRef.terminate({ group: true, gracefulMs: 500, timeoutMs: 2_000 });
+					}
+					reapRecoveredSnapshot(snapshot, Date.now());
 				} else if (snapshot.state === "restarting") {
 					snapshot.state = spec.ready ? "starting" : "running";
 				}

package/src/modes/controllers/input-controller.ts

@@ -179,9 +179,9 @@ export class InputController {
 	// (>= LEFT_DOUBLE_TAP_MAX_GAP_MS) starts a fresh sequence. See
 	// #detectLeftDoubleTap.
 	#leftTapCount = 0;
-	// Sequential index for `local://attachment-N` references created by large-paste and
-	// pasted-file attachments. Seeded from 0 and bumped past existing attachment files.
-	#attachmentCounter = 0;
+	// Sequential index for `local://paste-N.md` references created by the large-paste
+	// flow. Seeded from 0 and bumped past existing paste files.
+	#pasteCounter = 0;
 
 	#showTinyTitleDownloadProgress(modelKey: string): void {
 		if (!isTinyTitleLocalModelKey(modelKey)) return;
@@ -1711,7 +1711,7 @@ export class InputController {
 				`Pasted ${lineCount} lines`,
 				[
 					{ label: WRAPPED_BLOCK, description: "Wrap the text in <attachment> tags, collapsed to a marker" },
-					{ label: LOCAL_FILE, description: "Save the text to a local://attachment file" },
+					{ label: LOCAL_FILE, description: "Save the text to a local://paste file" },
 					{ label: INLINE, description: "Collapse the text to an inline paste marker" },
 				],
 				{ helpText: "Esc to paste inline" },
@@ -1740,7 +1740,7 @@ export class InputController {
 	}
 
 	/**
-	 * Save a large paste to the session's `local://` store and insert a clean `local://attachment-N`
+	 * Save a large paste to the session's `local://` store and insert a clean `local://paste-N.md`
 	 * reference into the editor so the agent can `read` it on demand — instead of inlining the text or
 	 * leaking a raw temp path. Falls back to an inline paste marker when the write fails, so the
 	 * content is never lost.
@@ -1748,7 +1748,7 @@ export class InputController {
 	async #attachPasteAsFile(text: string, lineCount: number): Promise<void> {
 		try {
 			// Mirror the exact mapping the read tool's local:// resolver uses so a later
-			// `read local://attachment-N` lands on the file written here.
+			// `read local://paste-N.md` lands on the file written here.
 			const localRoot = resolveLocalRoot({
 				getArtifactsDir: () => this.ctx.sessionManager.getArtifactsDir(),
 				getSessionId: () => this.ctx.sessionManager.getSessionId(),
@@ -1756,8 +1756,8 @@ export class InputController {
 			let name: string;
 			let filePath: string;
 			do {
-				this.#attachmentCounter++;
-				name = `attachment-${this.#attachmentCounter}`;
+				this.#pasteCounter++;
+				name = `paste-${this.#pasteCounter}.md`;
 				filePath = path.join(localRoot, name);
 			} while (await Bun.file(filePath).exists());
 			await Bun.write(filePath, text);

package/src/modes/interactive-mode.ts

@@ -209,6 +209,7 @@ import type {
 	InteractiveModeContext,
 	InteractiveModeInitOptions,
 	InteractiveSelectorDialogOptions,
+	RenderSessionContextOptions,
 	SubmittedUserInput,
 	TodoItem,
 	TodoPhase,
@@ -1740,6 +1741,60 @@ export class InteractiveMode implements InteractiveModeContext {
 		const context = this.viewSession.buildTranscriptSessionContext({
 			collapseCompactedHistory: settings.get("display.collapseCompacted"),
 		});
+		const preservedLiveToolCallIds = new Set<string>();
+		// A preserved pending-tool component whose result has already landed in
+		// the replayed transcript is re-rendered by `renderSessionContext` itself
+		// (the toolResult message reconstructs the block with its output). Keeping
+		// it in the live set too re-appends a second identical block below the
+		// replayed one — the tool call renders twice (#6516). The preservation
+		// above assumes every pending-tool component is still dangling (its result
+		// lives outside `state.messages`), which stops holding the instant the
+		// result is persisted while the component lingers in `pendingTools` (a
+		// rebuild racing tool-completion, a background/displaceable snapshot).
+		// Drop the already-resolved ones and let the replay own them; only
+		// genuinely in-flight (dangling, replay-stripped) calls still need
+		// preserving.
+		for (const message of context.messages) {
+			if (message.role !== "toolResult") continue;
+			const resolved = livePendingTools.get(message.toolCallId);
+			if (!resolved) continue;
+			// A background task's initial `async.state === "running"` result is
+			// persisted while `EventController#handleToolExecutionEnd` deliberately
+			// keeps its component in `pendingTools` so a later
+			// `tool_execution_update`/`_end` settles it. Such a handle is still
+			// live — dropping it would strand those updates on the running snapshot
+			// — so keep it and let the live component retain ownership; only
+			// terminal results are owned by the replay. (Cast mirrors the async
+			// detail reads in tool-execution.ts / event-controller.ts.)
+			const details = message.details as { async?: { state?: string } } | undefined;
+			if (details?.async?.state === "running") {
+				preservedLiveToolCallIds.add(message.toolCallId);
+				continue;
+			}
+			livePendingTools.delete(message.toolCallId);
+			// A `ReadToolGroupComponent` is shared by every read id it renders
+			// (ui-helpers sets the same group for each collapsed read call). While a
+			// sibling read id still points at it the component must stay on screen
+			// and preserved — splicing it here would detach the pending read's
+			// display and strand its future result on an off-screen component.
+			// Splice only once no remaining pending id shares it.
+			let stillShared = false;
+			for (const other of livePendingTools.values()) {
+				if (other === resolved) {
+					stillShared = true;
+					break;
+				}
+			}
+			if (stillShared) {
+				// The shared component still owns this completed member as well as
+				// its pending sibling. Suppress the replay copy so the group remains
+				// a single on-screen block while future results keep routing to it.
+				preservedLiveToolCallIds.add(message.toolCallId);
+				continue;
+			}
+			const index = liveComponents.indexOf(resolved as unknown as Component);
+			if (index >= 0) liveComponents.splice(index, 1);
+		}
 		// Prune the settled-component cache to the messages this rebuild will
 		// actually render. Message objects stay strongly reachable through
 		// session entries for the whole session, so entries for compacted-away
@@ -1751,7 +1806,10 @@ export class InteractiveMode implements InteractiveModeContext {
 			if (component) retained.set(message, component);
 		}
 		this.transcriptMessageComponents = retained;
-		this.renderSessionContext(context, { reuseSettledComponents: options.reuseSettledComponents });
+		this.renderSessionContext(context, {
+			reuseSettledComponents: options.reuseSettledComponents,
+			preservedLiveToolCallIds,
+		});
 		for (const child of liveComponents) {
 			this.chatContainer.addChild(child);
 		}
@@ -4294,10 +4352,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#uiHelpers.addMessageToChat(message, options);
 	}
 
-	renderSessionContext(
-		sessionContext: SessionContext,
-		options?: { updateFooter?: boolean; populateHistory?: boolean; reuseSettledComponents?: boolean },
-	): void {
+	renderSessionContext(sessionContext: SessionContext, options?: RenderSessionContextOptions): void {
 		for (const message of sessionContext.messages) {
 			this.noteDisplayableThinkingContent(message);
 		}

package/src/modes/types.ts

@@ -92,6 +92,14 @@ export interface InteractiveModeInitOptions {
 
 export type InteractiveSelectorDialogOptions = ExtensionUIDialogOptions & Pick<HookSelectorOptions, "disabledIndices">;
 
+export interface RenderSessionContextOptions {
+	updateFooter?: boolean;
+	populateHistory?: boolean;
+	reuseSettledComponents?: boolean;
+	/** Tool calls whose existing live component remains the sole render owner across a rebuild. */
+	preservedLiveToolCallIds?: ReadonlySet<string>;
+}
+
 export interface InteractiveModeContext {
 	// UI access
 	ui: TUI;
@@ -310,10 +318,7 @@ export interface InteractiveModeContext {
 			reuseSettledComponent?: boolean;
 		},
 	): Component[];
-	renderSessionContext(
-		sessionContext: SessionContext,
-		options?: { updateFooter?: boolean; populateHistory?: boolean; reuseSettledComponents?: boolean },
-	): void;
+	renderSessionContext(sessionContext: SessionContext, options?: RenderSessionContextOptions): void;
 	renderInitialMessages(options?: { preserveExistingChat?: boolean; clearTerminalHistory?: boolean }): void;
 	getUserMessageText(message: Message): string;
 	findLastAssistantMessage(): AssistantMessage | undefined;

package/src/modes/utils/ui-helpers.ts

@@ -33,7 +33,7 @@ import { UserMessageComponent } from "../../modes/components/user-message";
 import { decodeStreamedToolArgs, streamingStringKeysForTool } from "../../modes/controllers/tool-args-reveal";
 import { materializeImageReferenceLinksSync } from "../../modes/image-references";
 import { theme } from "../../modes/theme/theme";
-import type { CompactionQueuedMessage, InteractiveModeContext } from "../../modes/types";
+import type { CompactionQueuedMessage, InteractiveModeContext, RenderSessionContextOptions } from "../../modes/types";
 import {
 	BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE,
 	type CustomMessage,
@@ -72,12 +72,6 @@ type AddMessageOptions = {
 	reuseSettledComponent?: boolean;
 };
 
-type RenderSessionContextOptions = {
-	updateFooter?: boolean;
-	populateHistory?: boolean;
-	reuseSettledComponents?: boolean;
-};
-
 function imageLinksForMessage(
 	message: Extract<AgentMessage, { role: "developer" | "user" }>,
 	putBlobSync: InteractiveModeContext["sessionManager"]["putBlobSync"],
@@ -422,8 +416,12 @@ export class UiHelpers {
 					if (content.type !== "toolCall") {
 						continue;
 					}
-					resolveWaitingPoll(content.name);
 					const afterToolSegment = timeline.afterToolCalls.get(content.id);
+					if (options.preservedLiveToolCallIds?.has(content.id)) {
+						appendAssistantSegment(afterToolSegment);
+						continue;
+					}
+					resolveWaitingPoll(content.name);
 
 					if (content.name === "read" && readArgsCollapseIntoGroup(content.arguments)) {
 						if (hasErrorStop && errorMessage) {
@@ -538,6 +536,7 @@ export class UiHelpers {
 				pendingUsageTtft = message.ttft;
 				pendingUsageTimestamp = message.timestamp;
 			} else if (message.role === "toolResult") {
+				if (options.preservedLiveToolCallIds?.has(message.toolCallId)) continue;
 				const pendingReadComponent = this.ctx.pendingTools.get(message.toolCallId);
 				const isReadGroupResult =
 					message.toolName === "read" &&

package/src/prompts/system/resolve-device-reminder.md

@@ -1,3 +1,3 @@
 <system-reminder>
-This is a preview. Finalize it now with the `write` tool: write a one-sentence reason as plain text to `xd://resolve` to APPLY it, or to `xd://reject` to DISCARD it.
+The `{{toolName}}` result above is a PREVIEW — no files were changed. Finalize it now with the `write` tool: write a one-sentence reason as plain text to `xd://resolve` to APPLY it, or to `xd://reject` to DISCARD it.
 </system-reminder>

package/src/prompts/system/workflow-notice.md

@@ -13,7 +13,7 @@ Worth it when the task benefits from decomposition + parallel coverage, or from
 <helpers>
 State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
 
-- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("scout", "reviewer", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes. Recursion follows `task.maxRecursionDepth` (default 2; a negative value disables the cap): main agent depth = 0, each `agent()` child increments depth by 1, and, when the cap is non-negative, a spawner may call `agent()` only while its current `taskDepth < cap`. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
+- `agent(prompt, *, agent="task", label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("scout", "reviewer", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes. Recursion follows `task.maxRecursionDepth` (default 2; a negative value disables the cap); deeper calls raise an error.
 - `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
 - `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
 - `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.

package/src/prompts/tools/ast-edit.md

@@ -1,4 +1,4 @@
-Structural AST-aware rewrites via ast-grep. Use for codemods where text replace is unsafe. Narrow each call to one language.
+Structural AST-aware rewrites via ast-grep. Use for codemods where text replace is unsafe. Mixed-language paths are fine: each file is parsed in its own language, and a pattern only rewrites files it parses in.
 
 - Metavariables in `pat` (`$A`, `$$$ARGS`) substitute into `out`.
 - **Patterns match AST structure, not text.** `$NAME` = one node; `$_` = unbound; `$$$NAME` = zero-or-more.
@@ -7,4 +7,5 @@ Structural AST-aware rewrites via ast-grep. Use for codemods where text replace
 - Rewrite patterns MUST parse as single AST node. Non-standalone → wrap: `class $_ { … }`.
 - TS: tolerate annotations — `async function $NAME($$$ARGS): $_ { $$$BODY }`. Delete with empty `out`: `{"pat":"console.log($$$)","out":""}`.
 - 1:1 substitution — no splitting/merging captures.
+- Matches are STAGED as a proposal, not applied: finalize by writing a one-sentence reason to `xd://resolve` (apply) or `xd://reject` (discard).
 - Parse issues → malformed rewrite, not clean no-op. For one-off text edits, prefer the Edit tool.

package/src/prompts/tools/bash.md

@@ -9,6 +9,7 @@ Use ONLY for: single binary call or short pipeline that COMPUTES a fact (`wc -l`
 - `pty: true` only for real terminal needs (`sudo`, `ssh`); default `false`.
 - Multiple calls run concurrently; NEVER split order-dependent commands — chain with `&&` in one call (`;` only to continue past failure).
 - Internal URIs (`skill://`, `agent://`, …) auto-resolve to FS paths.
+{{#if hasShellBuiltins}}- aux utils available: mkdir, head, tail, wc, sort, ls, find, grep, rg, fd, cat, uniq, base64, cmp, md5sum, sha{1,224,256,384,512}sum, b2sum, basename, dirname, readlink, realpath, touch, stat, date, mktemp, seq, yes, printenv, truncate, tac, nproc, uname, whoami, hostname, which, diff, cut, tee, tr, paste, comm, sed, xargs, jq, rm, mv, ln, ts, sponge, ifne, isutf8, combine{{#unless isWindows}}, errno{{/unless}}{{/if}}
 {{#if asyncEnabled}}- `async: true` defers reporting for finite commands needing no later input.{{/if}}
 </instruction>
 

package/src/prompts/tools/eval.md

@@ -20,9 +20,9 @@ tool.<name>(args) → unknown
     Invoke any session tool; `args` = its parameter object.
 completion(prompt, model?="default"|"smol"|"slow", system?=None, schema?=None) → str | dict
     Oneshot, stateless (no history/tools). `model`: "smol" fast | "default" session | "slow" most capable. `schema` (JSON-Schema) → parsed object.
-{{#if spawns}}agent(prompt, agent?="{{spawnDefaultAgent}}", model?=None, label?=None, schema?=None, schema{{#if js}}Mode{{else}}_mode{{/if}}?="permissive", isolated?=None, apply?=None, merge?=None, handle?=False) → str | dict
+{{#if spawns}}agent(prompt, agent?="{{spawnDefaultAgent}}", label?=None, schema?=None, schema{{#if js}}Mode{{else}}_mode{{/if}}?="permissive", isolated?=None, apply?=None, merge?=None, handle?=False) → str | dict
     Run a subagent → final output. `agent` selects a discovered agent; omit it to use `{{spawnDefaultAgent}}`.{{#if spawnAllowedAgentsText}} Allowed agents: {{spawnAllowedAgentsText}}.{{/if}} `schema` overrides agent/session schemas; `schemaMode`/`schema_mode`: "permissive" | "strict". Effective schemas return parsed data. `isolated` requests a worktree; `apply`/`merge` control its changes. Background via `local://` files named in the prompt. `handle` → { text, output, handle: "agent://<id>", id, agent }, parsed `data` when structured.
-{{#if js}}    JS: ONE trailing object — agent(prompt, { agent, model, label, schema, schemaMode, isolated, apply, merge, handle }).{{/if}}
+{{#if js}}    JS: ONE trailing object — agent(prompt, { agent, label, schema, schemaMode, isolated, apply, merge, handle }).{{/if}}
 {{/if}}
 parallel(thunks) → list     pipeline(items, ...stages) → list
 log(message) → None         phase(title) → None

package/src/prompts/tools/task.md

@@ -14,6 +14,9 @@ Agents marked BLOCKING run inline — results return in this call; non-blocking
 - **Agent typing:** Pick each item's `agent` type. Read-only research MUST use `agent: "scout"` (faster model). Use default worker only when no specialist fits.
 - **No overhead:** Each `task` MUST instruct its agent to skip formatters, linters, and project-wide test suites. Run those once at the end.
 - **One-pass:** Prefer agents that investigate AND edit in one pass; spin a read-only scout only when affected files are genuinely unknown.
+- **Overlap is safe:** Concurrent edits to the same files auto-resolve{{#if ircEnabled}}; worst case, agents coordinate directly over IRC{{/if}}. NEVER shrink or serialize a batch to avoid file overlap. Two prerequisites:
+  1. Every task MUST skip validation (build/lint/tests) — validating mid-flight blocks agents on each other's edits.
+  2. Decide cross-task contracts up front (e.g. the interface A implements and B consumes) and state them in the {{#if batchEnabled}}batch `context`{{else}}task{{/if}}, not left for agents to negotiate.
 
 # Inputs
 {{#if batchEnabled}}
@@ -22,7 +25,7 @@ Agents marked BLOCKING run inline — results return in this call; non-blocking
   - `name`: A stable CamelCase identifier (≤32 chars), used to address the agent (IRC, job ids). Generated automatically if omitted.
   - `agent`: The agent type running this item (e.g. `scout`, `reviewer`). Omitting it gives you the general-purpose worker (`{{defaultAgent}}`) — NEVER pass that name explicitly. Only omit it after checking the agent list below and finding no specialist that fits.{{#if allowedAgentsText}} Current spawn policy allows: {{allowedAgentsText}}.{{/if}}
   - `task`: Complete, self-contained instructions. One-liners or missing acceptance criteria are PROHIBITED.
-  - `model`: Explicit non-empty model selector or non-empty fallback chain for this spawn. A `:reasoning` suffix is preserved. Overrides agent-specific model settings.
+  - `effort`: Scale w/ complexity of this task: `"lo"`|`"med"`|`"hi"`
   - `outputSchema`: Invocation-specific JSON Schema. Overrides the selected agent and parent-session schemas.
   - `schemaMode`: `"permissive"` (default) accepts a retry-exhausted invalid result with a warning; `"strict"` fails it.
 {{#if isolationEnabled}}
@@ -36,7 +39,7 @@ Agents marked BLOCKING run inline — results return in this call; non-blocking
 - `name`: A stable CamelCase identifier (≤32 chars), used to address the agent (IRC, job ids). Generated automatically if omitted.
 - `agent`: The agent type to spawn (e.g. `scout`, `reviewer`). Omitting it gives you the general-purpose worker (`{{defaultAgent}}`) — NEVER pass that name explicitly. Only omit it after checking the agent list below and finding no specialist that fits.{{#if allowedAgentsText}} Current spawn policy allows: {{allowedAgentsText}}.{{/if}}
 - `task`: Complete, self-contained instructions. One-liners or missing acceptance criteria are PROHIBITED.
-- `model`: Explicit non-empty model selector or non-empty fallback chain for this spawn. A `:reasoning` suffix is preserved. Overrides agent-specific model settings.
+- `effort`: Scale w/ complexity of this task: `"lo"`|`"med"`|`"hi"`
 - `outputSchema`: Invocation-specific JSON Schema. Overrides the selected agent and parent-session schemas.
 - `schemaMode`: `"permissive"` (default) accepts a retry-exhausted invalid result with a warning; `"strict"` fails it.
 {{#if isolationEnabled}}

package/src/prompts/tools/web-search.md

@@ -3,4 +3,6 @@ Searches the web for up-to-date information beyond knowledge cutoff.
 <instruction>
 - You SHOULD prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
 - You MUST include links for cited sources in the final response
+- NEVER use for content that is programmatically accessible or whose URL you already know (GitHub repos/issues, a known arXiv paper, a Wikipedia page, official docs) — `read` the URL directly instead
+- `query` supports Google-style directives on every provider: `site:`/`-site:`, `after:`/`before:` (`YYYY-MM-DD`), `inurl:`, `intitle:`, `filetype:`, `"exact phrase"`, `-term`, `OR`. Constraints map to native provider filters where available; otherwise results are filtered leniently — a constraint matching nothing is relaxed and reported instead of returning zero results.
 </instruction>

package/src/sdk.ts

@@ -2594,9 +2594,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// ExtensionToolWrapper, so the registry holds them unwrapped. The normal
 		// `write xd://<tool>` path runs approval through the wrapped `write` tool's
 		// tier gate, but Cursor invokes advertised devices via `tool.execute()`
-		// directly — so wrap unwrapped devices here to keep the approval/deny/prompt
-		// gate. Dynamic mounts (custom/MCP) already come from the wrapped registry.
-		const resolveCursorDevice = (name: string): AgentTool | undefined => {
+		// directly, and the agent loop's fallback resolver executes mounted
+		// devices the model called by their top-level name — so wrap unwrapped
+		// devices here to keep the approval/deny/prompt gate. Dynamic mounts
+		// (custom/MCP) already come from the wrapped registry.
+		const resolveDeviceTool = (name: string): AgentTool | undefined => {
 			const device = toolSession.xdevRegistry?.get(name);
 			if (!device) return undefined;
 			return device instanceof ExtensionToolWrapper ? device : new ExtensionToolWrapper(device, extensionRunner);
@@ -2604,7 +2606,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const cursorExecHandlers = new CursorExecHandlers({
 			cwd,
 			tools: toolRegistry,
-			getTool: resolveCursorDevice,
+			getTool: resolveDeviceTool,
 			getToolContext: () => toolContextStore.getContext(),
 			emitEvent: event => cursorEventEmitter?.(event),
 		});
@@ -3012,6 +3014,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			cursorExecHandlers,
 			getCursorTools: () => [...(toolSession.xdevRegistry?.list() ?? [])],
 			transformToolCallArguments,
+			resolveFallbackTool: resolveDeviceTool,
 			intentTracing: !!intentField,
 			pruneToolDescriptions: inlineToolDescriptors,
 			dialect: resolveDialect(settings.get("tools.format"), model),
@@ -3360,6 +3363,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					getToolContext: toolCall => toolContextStore.getContext(toolCall),
 					streamFn: settingsAwareStreamFn,
 					transformToolCallArguments,
+					resolveFallbackTool: resolveDeviceTool,
 					intentTracing: !!intentField,
 					pruneToolDescriptions: inlineToolDescriptors,
 					dialect: resolveDialect(settings.get("tools.format"), captureModel),

package/src/session/agent-session.ts

@@ -2406,6 +2406,20 @@ export class AgentSession {
 						baseUrl: this.#modelRegistry.getProviderBaseUrl?.(assistantMsg.provider),
 					});
 				}
+				// Broker deployments: report this request's burn so the broker can
+				// attribute token usage per install. No-op with a local auth store.
+				this.#modelRegistry.authStorage.recordObservedUsage({
+					provider: assistantMsg.provider,
+					model: assistantMsg.model,
+					at: assistantMsg.timestamp,
+					usage: {
+						input: assistantMsg.usage.input,
+						output: assistantMsg.usage.output,
+						cacheRead: assistantMsg.usage.cacheRead,
+						cacheWrite: assistantMsg.usage.cacheWrite,
+					},
+					costUsd: assistantMsg.usage.cost.total,
+				});
 			}
 			if (event.message.role === "toolResult") {
 				const { toolName, toolCallId, isError, content } = event.message;

package/src/session/queued-messages.ts

@@ -44,7 +44,13 @@ export function isTerminalTextAssistantAnswer(message: AgentMessage | undefined)
 			if (part.text.trim().length > 0) hasText = true;
 			continue;
 		}
-		if (part.type === "thinking" || part.type === "redactedThinking" || part.type === "fallback") continue;
+		if (
+			part.type === "thinking" ||
+			part.type === "redactedThinking" ||
+			part.type === "fallback" ||
+			part.type === "anthropicServerTool"
+		)
+			continue;
 		return false;
 	}
 	return hasText;

package/src/session/stream-guards.ts

@@ -185,7 +185,7 @@ export class StreamingEditGuard {
 	#abortForAutoGeneratedPath(toolCall: ToolCall, filePath: string, resolvedPath: string): void {
 		if (this.#lastToolCallId === toolCall.id) return;
 		this.#lastToolCallId = toolCall.id;
-		void assertEditableFile(resolvedPath, filePath).catch(error => {
+		void assertEditableFile(resolvedPath, filePath, this.#host.settings).catch(error => {
 			if (!(error instanceof ToolError) || this.#lastToolCallId !== toolCall.id) return;
 			if (!this.#abortTriggered) {
 				this.#abortTriggered = true;

package/src/task/executor.ts

@@ -46,7 +46,7 @@ import type { AuthStorage } from "../session/auth-storage";
 import { SKILL_PROMPT_MESSAGE_TYPE, USER_INTERRUPT_LABEL } from "../session/messages";
 import { SessionManager } from "../session/session-manager";
 import { truncateTail } from "../session/streaming-output";
-import type { ConfiguredThinkingLevel } from "../thinking";
+import { type ConfiguredThinkingLevel, resolveTaskEffortLevel, type TaskEffort } from "../thinking";
 import type { ContextFileEntry, ToolSession } from "../tools";
 import { resolveEvalBackends } from "../tools/eval-backends";
 import { isIrcEnabled } from "../tools/hub";
@@ -323,6 +323,8 @@ export interface ExecutorOptions {
 	 */
 	parentActiveModelPattern?: string;
 	thinkingLevel?: ConfiguredThinkingLevel;
+	/** Caller-requested coarse effort (`lo`/`med`/`hi`); maps onto the resolved model's supported thinking range and wins over {@link thinkingLevel}. */
+	effort?: TaskEffort;
 	/** Schema used to validate the final structured completion. */
 	outputSchema?: unknown;
 	/** Enforcement policy for {@link outputSchema}; defaults to legacy permissive behavior. */
@@ -2644,16 +2646,22 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			if (model?.contextWindow && model.contextWindow > 0) {
 				progress.contextWindow = model.contextWindow;
 			}
+			// Caller-requested coarse effort maps onto the resolved model's
+			// supported range; undefined (no effort, or no controllable effort
+			// surface) falls through to the normal selectors below.
+			const effortLevel = options.effort !== undefined ? resolveTaskEffortLevel(model, options.effort) : undefined;
 			if (model) {
-				progress.resolvedModel = explicitThinkingLevel
-					? formatModelSelectorValue(formatModelStringWithRouting(model), resolvedThinkingLevel)
-					: formatModelStringWithRouting(model);
+				const displayLevel = effortLevel ?? (explicitThinkingLevel ? resolvedThinkingLevel : undefined);
+				progress.resolvedModel =
+					displayLevel !== undefined
+						? formatModelSelectorValue(formatModelStringWithRouting(model), displayLevel)
+						: formatModelStringWithRouting(model);
 			}
-			// Precedence: explicit `:level` suffix on the resolved model pattern >
-			// agent-definition default (e.g. task's `auto`) > pattern-derived level.
-			const effectiveThinkingLevel = explicitThinkingLevel
-				? resolvedThinkingLevel
-				: (thinkingLevel ?? resolvedThinkingLevel);
+			// Precedence: caller `effort` > explicit `:level` suffix on the resolved
+			// model pattern > agent-definition default (e.g. task's `auto`) >
+			// pattern-derived level.
+			const effectiveThinkingLevel =
+				effortLevel ?? (explicitThinkingLevel ? resolvedThinkingLevel : (thinkingLevel ?? resolvedThinkingLevel));
 			resolvedAt = performance.now();
 			// Per-agent prewalk: the agent definition's `prewalk` frontmatter or the
 			// `task.agentPrewalk` settings override hands the subagent off to a