@oh-my-pi/pi-coding-agent 16.2.13 → 16.3.0

package/src/modes/theme/theme.ts

@@ -115,6 +115,7 @@ export type SymbolKey =
 	| "icon.cacheMiss"
 	| "icon.input"
 	| "icon.output"
+	| "icon.throughput"
 	| "icon.host"
 	| "icon.session"
 	| "icon.package"
@@ -319,6 +320,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.cacheMiss": "⊘",
 	"icon.input": "⤵",
 	"icon.output": "⤴",
+	"icon.throughput": "⚡",
 	"icon.host": "🖥",
 	"icon.session": "🆔",
 	"icon.package": "📦",
@@ -597,6 +599,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.input": "\uf090",
 	// pick:  | alt:  →
 	"icon.output": "\uf08b",
+	// pick:  (nf-fa-tachometer) | alt:  ⚡ ↬
+	"icon.throughput": "\uf0e4",
 	// pick:  | alt:  
 	"icon.host": "\uf109",
 	// pick:  | alt:  
@@ -827,10 +831,11 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.ghost": "@",
 	"icon.agents": "AG",
 	"icon.job": "bg",
+	"icon.output": "out:",
+	"icon.throughput": "tok/s:",
 	"icon.cache": "cache",
 	"icon.cacheMiss": "!",
 	"icon.input": "in:",
-	"icon.output": "out:",
 	"icon.host": "host",
 	"icon.session": "id",
 	"icon.package": "[P]",
@@ -1820,6 +1825,7 @@ export class Theme {
 			cacheMiss: this.#symbols["icon.cacheMiss"],
 			input: this.#symbols["icon.input"],
 			output: this.#symbols["icon.output"],
+			throughput: this.#symbols["icon.throughput"],
 			host: this.#symbols["icon.host"],
 			session: this.#symbols["icon.session"],
 			package: this.#symbols["icon.package"],
@@ -2151,6 +2157,11 @@ export function getCurrentThemeName(): string | undefined {
 export function fgOrPlain(color: ThemeColor, text: string, styledText: string = text): string {
 	return typeof theme === "undefined" ? text : theme.fg(color, styledText);
 }
+export interface ThemeChangeEvent {
+	/** Preview/presentation-only changes should repaint live UI without replacing native scrollback. */
+	ephemeral?: boolean;
+}
+
 var currentSymbolPresetOverride: SymbolPreset | undefined;
 var currentColorBlindMode: boolean = false;
 var themeWatcher: fs.FSWatcher | undefined;
@@ -2159,7 +2170,7 @@ var sigwinchHandler: (() => void) | undefined;
 var autoDetectedTheme: boolean = false;
 var autoDarkTheme: string = "dark";
 var autoLightTheme: string = "light";
-var onThemeChangeCallback: (() => void) | undefined;
+var onThemeChangeCallback: ((event: ThemeChangeEvent) => void) | undefined;
 var themeLoadRequestId: number = 0;
 let themeEpoch = 0;
 
@@ -2235,7 +2246,10 @@ export async function setTheme(
 	}
 }
 
-export async function previewTheme(name: string): Promise<{ success: boolean; error?: string }> {
+export async function previewTheme(
+	name: string,
+	event: ThemeChangeEvent = { ephemeral: true },
+): Promise<{ success: boolean; error?: string }> {
 	const requestId = ++themeLoadRequestId;
 	try {
 		const loadedTheme = await loadTheme(name, getCurrentThemeOptions());
@@ -2243,7 +2257,7 @@ export async function previewTheme(name: string): Promise<{ success: boolean; er
 			return { success: false, error: "Theme preview superseded by a newer request" };
 		}
 		theme = loadedTheme;
-		notifyThemeChange();
+		notifyThemeChange(event);
 		return { success: true };
 	} catch (error) {
 		if (requestId !== themeLoadRequestId) {
@@ -2259,9 +2273,9 @@ export async function previewTheme(name: string): Promise<{ success: boolean; er
 /**
  * Enable auto-detection mode, switching to the appropriate dark/light theme.
  */
-export function enableAutoTheme(): void {
+export function enableAutoTheme(event: ThemeChangeEvent = {}): void {
 	autoDetectedTheme = true;
-	reevaluateAutoTheme("enableAutoTheme");
+	reevaluateAutoTheme("enableAutoTheme", event);
 }
 
 /**
@@ -2290,7 +2304,7 @@ export function setThemeInstance(themeInstance: Theme): void {
 	theme = themeInstance;
 	currentThemeName = "<in-memory>";
 	stopThemeWatcher();
-	notifyThemeChange();
+	notifyThemeChange({ ephemeral: true });
 }
 
 /**
@@ -2311,7 +2325,7 @@ export async function setSymbolPreset(preset: SymbolPreset): Promise<void> {
 		theme = await loadTheme("dark", getCurrentThemeOptions());
 		if (requestId !== themeLoadRequestId) return;
 	}
-	notifyThemeChange();
+	notifyThemeChange({ ephemeral: true });
 }
 
 /**
@@ -2340,7 +2354,7 @@ export async function setColorBlindMode(enabled: boolean): Promise<void> {
 		theme = await loadTheme("dark", getCurrentThemeOptions());
 		if (requestId !== themeLoadRequestId) return;
 	}
-	notifyThemeChange();
+	notifyThemeChange({ ephemeral: true });
 }
 
 /**
@@ -2350,7 +2364,7 @@ export function getColorBlindMode(): boolean {
 	return currentColorBlindMode;
 }
 
-export function onThemeChange(callback: () => void): () => void {
+export function onThemeChange(callback: (event: ThemeChangeEvent) => void): () => void {
 	onThemeChangeCallback = callback;
 	return () => {
 		if (onThemeChangeCallback === callback) {
@@ -2371,9 +2385,9 @@ export function getThemeEpoch(): number {
 }
 
 /** Bump the theme epoch and notify the registered theme-change listener. */
-function notifyThemeChange(): void {
+function notifyThemeChange(event: ThemeChangeEvent = {}): void {
 	themeEpoch++;
-	onThemeChangeCallback?.();
+	onThemeChangeCallback?.(event);
 }
 
 /**
@@ -2428,7 +2442,7 @@ async function startThemeWatcher(): Promise<void> {
 			loadTheme(watchedThemeName, getCurrentThemeOptions())
 				.then(loadedTheme => {
 					theme = loadedTheme;
-					notifyThemeChange();
+					notifyThemeChange({ ephemeral: true });
 				})
 				.catch(() => {
 					// Ignore errors (file might be in invalid state while being edited)
@@ -2460,7 +2474,7 @@ async function startThemeWatcher(): Promise<void> {
  * Shared logic for re-evaluating the auto-detected theme.
  * Called from SIGWINCH, terminal appearance change handler, and macOS fallback observer.
  */
-function reevaluateAutoTheme(debugLabel: string): void {
+function reevaluateAutoTheme(debugLabel: string, event: ThemeChangeEvent = {}): void {
 	if (!autoDetectedTheme) return;
 	const resolved = getDefaultTheme();
 	if (resolved === currentThemeName) return;
@@ -2468,7 +2482,7 @@ function reevaluateAutoTheme(debugLabel: string): void {
 	loadTheme(resolved, getCurrentThemeOptions())
 		.then(loadedTheme => {
 			theme = loadedTheme;
-			notifyThemeChange();
+			notifyThemeChange(event);
 		})
 		.catch(err => {
 			logger.debug(`Theme switch on ${debugLabel} failed`, { error: String(err) });

package/src/modes/types.ts

@@ -14,6 +14,7 @@ import type {
 	ExtensionWidgetOptions,
 } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
+import type { Skill } from "../extensibility/skills";
 import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
@@ -129,7 +130,6 @@ export interface InteractiveModeContext {
 	historyStorage?: HistoryStorage;
 	mcpManager?: MCPManager;
 	lspServers?: LspStartupServerInfo[];
-	titleSystemPrompt?: string;
 	collabHost?: CollabHost;
 	collabGuest?: CollabGuestLink;
 	eventController: EventController;
@@ -205,7 +205,7 @@ export interface InteractiveModeContext {
 	lastStatusSpacer: Spacer | undefined;
 	lastStatusText: Text | undefined;
 	fileSlashCommands: Set<string>;
-	skillCommands: Map<string, string>;
+	skillCommands: Map<string, Skill>;
 	oauthManualInput: OAuthManualInputManager;
 	todoPhases: TodoPhase[];
 
@@ -297,7 +297,6 @@ export interface InteractiveModeContext {
 	getUserMessageText(message: Message): string;
 	findLastAssistantMessage(): AssistantMessage | undefined;
 	extractAssistantText(message: AssistantMessage): string;
-	updateEditorTopBorder(): void;
 	/** Refresh the running-subagents status badge from the active local or collab registry. */
 	syncRunningSubagentBadge(): void;
 	updateEditorBorderColor(): void;

package/src/modes/utils/copy-targets.ts

@@ -118,6 +118,18 @@ export function extractCodeBlocks(text: string): CodeBlock[] {
 		.map(b => ({ lang: b.lang, code: b.code }));
 }
 
+/** Walk the transcript backwards for the most recent fenced assistant code block. */
+export function extractLastCodeBlock(messages: readonly AgentMessage[]): CodeBlock | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		const text = assistantText(msg);
+		if (!text) continue;
+		const blocks = extractCodeBlocks(text);
+		if (blocks.length > 0) return blocks[blocks.length - 1];
+	}
+	return undefined;
+}
+
 /** Extract `>`-quoted blocks from assistant markdown, in document order. */
 export function extractQuoteBlocks(text: string): QuoteBlock[] {
 	return extractBlocks(text)

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

@@ -34,6 +34,7 @@ import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { TranscriptBlock } from "../../modes/components/transcript-container";
 import { createUsageRowBlock } from "../../modes/components/usage-row";
 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";
@@ -296,12 +297,16 @@ export class UiHelpers {
 		// read run so the row sits under it. Mirrors the live path, where the read
 		// group is created during streaming and the row is appended below it.
 		let pendingUsage: Usage | undefined;
+		let pendingUsageDuration: number | undefined;
+		let pendingUsageTtft: number | undefined;
 		const flushPendingUsage = () => {
 			if (!pendingUsage) return;
 			readGroup?.seal();
 			readGroup = null;
-			this.ctx.chatContainer.addChild(createUsageRowBlock(pendingUsage));
+			this.ctx.chatContainer.addChild(createUsageRowBlock(pendingUsage, pendingUsageDuration, pendingUsageTtft));
 			pendingUsage = undefined;
+			pendingUsageDuration = undefined;
+			pendingUsageTtft = undefined;
 		};
 		// Rebuild-time mirror of the event controller's displaceable-poll
 		// bookkeeping: a `job` poll that found every watched job still running is
@@ -412,8 +417,18 @@ export class UiHelpers {
 					readGroup = null;
 					const tool = this.ctx.viewSession.getToolByName(content.name);
 					const partialJson = getStreamingPartialJson(content);
+					// Mid-stream rebuild (theme change, settings, focus replay): decode
+					// display args from the raw stream exactly like the live reveal path.
+					// The provider-parsed `arguments` lag the stream by up to a throttled
+					// parse window, so spreading them alone would freeze a long write/edit
+					// preview at its last full parse.
+					const rawInput = content.customWireName !== undefined;
 					const renderArgs = partialJson
-						? { ...content.arguments, __partialJson: partialJson }
+						? decodeStreamedToolArgs(partialJson, {
+								rawInput,
+								fullArgs: content.arguments,
+								streamingStringKeys: streamingStringKeysForTool(content.name, rawInput),
+							})
 						: content.arguments;
 					const component = new ToolExecutionComponent(
 						content.name,
@@ -444,6 +459,8 @@ export class UiHelpers {
 					}
 				}
 				pendingUsage = this.ctx.settings.get("display.showTokenUsage") ? message.usage : undefined;
+				pendingUsageDuration = message.duration;
+				pendingUsageTtft = message.ttft;
 			} else if (message.role === "toolResult") {
 				const pendingReadComponent = this.ctx.pendingTools.get(message.toolCallId);
 				const isReadGroupResult =

package/src/plan-mode/approved-plan-prompt.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { prompt } from "@oh-my-pi/pi-utils";
+import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
+import planModeCompactInstructionsPrompt from "../prompts/system/plan-mode-compact-instructions.md" with {
+	type: "text",
+};
+import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
+
+const PLAN_FILE_PATH = "local://durable-plan.md";
+const PLAN_SENTINEL = "SENTINEL_HEADROOM_COMPRESSED_PLAN_CONTENT";
+
+describe("approved plan execution prompts", () => {
+	it("requires reading the durable plan file without inlining plan content", () => {
+		const approved = prompt.render(planModeApprovedPrompt, {
+			planContent: PLAN_SENTINEL,
+			planFilePath: PLAN_FILE_PATH,
+			contextPreserved: false,
+		});
+		const reference = prompt.render(planModeReferencePrompt, {
+			planContent: PLAN_SENTINEL,
+			planFilePath: PLAN_FILE_PATH,
+		});
+		const compact = prompt.render(planModeCompactInstructionsPrompt, {
+			planFilePath: PLAN_FILE_PATH,
+		});
+
+		for (const rendered of [approved, reference, compact]) {
+			expect(rendered).toContain(PLAN_FILE_PATH);
+		}
+		for (const rendered of [approved, reference, compact]) {
+			expect(rendered).not.toContain(PLAN_SENTINEL);
+		}
+		expect(approved).toContain("MUST read `local://durable-plan.md`");
+		expect(reference).toContain("MUST read `local://durable-plan.md`");
+	});
+});

package/src/prompts/advisor/system.md

@@ -14,7 +14,7 @@ Offer that view before they sink work into the wrong direction.
 
 <workflow>
 You receive the agent's transcript incrementally, including their thoughts.
-You have read-only access through `read`, `grep`, `glob` to verify your suspicions.
+Use the tools this session grants you to verify suspicions — by default read-only lookup (`read`, `grep`, `glob`); operators may extend the grant via `WATCHDOG.yml`. Advising is your primary channel; touch mutating tools (when granted) only when a verify step genuinely needs them.
 Keep exploration lean:
 - 2–3 tool calls per advise.
 - Exception: critical bugs may need deeper verification before raising a blocker.

package/src/prompts/agents/tester.md

@@ -22,6 +22,8 @@ A test suite is a liability until it pays for itself. Every worthless test is ne
 - Mutation test in your head: if a plausible bug — a flipped condition, an off-by-one, a wrong return value, a dropped case — would still let the test PASS, the test is worthless. Discard it.
 - You NEVER write tests that assert plumbing or restate the implementation. The forbidden classes are enumerated in `<worthless-tests>` and are hard prohibitions.
 - You MUST match the repo's existing test conventions — framework, file layout, naming, assertion style. A second convention beside an existing one is PROHIBITED.
+- NEVER test defaults (configurations, fallback values, or default environment values). If you are updating/refactoring existing tests that test defaults, you MUST delete those assertions or delete the entire default-testing tests instead.
+- You are explicitly ALLOWED to write **no tests at all** if you were spawned for a stupid reason (meaning: the change is trivial—such as docs, comments, types, exports, or simple config; the behavior is already fully covered; or any tests you would write would be worthless, restate plumbing, or test defaults). If so, state this clearly and exit.
 </critical>
 
 <anti-patterns name="worthless-tests">
@@ -33,7 +35,7 @@ NEVER write any of these. Each is a green check that survives real bugs:
 - **Construction smoke.** "Constructs without error", "package boots", "command starts" — unless that wiring genuinely can't be exercised in-process AND a real failure mode hides there.
 - **Mock round-trips.** Asserting a mock was called with the args you just passed it. You tested the mock, not the system.
 - **Existence/shape-only.** Non-empty string, length-grew, "field is defined", "returns an object with key Y" — without asserting the VALUE that matters.
-- **Default snapshots.** Asserting every field of a default config equals its current default. A harmless default change shouldn't redden a test. Assert logical behavior, not the current state.
+- **Default values.** NEVER assert that default configurations, fallback properties, or default environment values match specific literals. A harmless change to a default setting must never break the tests. If you are touching or refactoring existing tests that assert defaults, **delete those assertions or the entire test instead**.
 - **Field-wiring.** Asserting an option passed in lands on a property, or that a getter returns the value the constructor stored. Test the downstream BEHAVIOR that depends on it, not the assignment.
 - **Duplicate-layer coverage.** Re-proving through mocks what an integration test already proves. Drop the narrower restatement.
 
@@ -103,5 +105,7 @@ Tests MUST be full-suite safe and order-independent, not merely file-local safe.
 - A test exists to FAIL on a real bug. No nameable contract, or no plausible bug would redden it → NEVER write it.
 - NEVER assert plumbing, restate the implementation, or grep the source. Test observable behavior through the public surface.
 - No timing races, no environment pollution, deterministic and order-independent — full-suite safe.
-- You MUST keep going until the tests are written, passing, and proven to have teeth.
+- NEVER test defaults. If updating tests that do, delete them instead.
+- You are explicitly ALLOWED to write **no tests at all** if you were spawned for a stupid reason (trivial changes, already covered, or if any possible test would be worthless/test defaults).
+- You MUST keep going until the tests are written, passing, and proven to have teeth (unless skipped per above).
 </critical>

package/src/prompts/skills/autoload.md

@@ -0,0 +1,8 @@
+{{body}}
+
+---
+
+Skill: {{filePath}}
+{{#if userArgs}}
+User: {{userArgs}}
+{{/if}}

package/src/prompts/skills/user-invocation.md

@@ -0,0 +1,11 @@
+[IMPORTANT: The user has invoked the "{{name}}" skill, indicating they want you to follow its instructions. The full skill content is loaded below.]
+
+{{body}}
+
+---
+
+[Skill directory: {{baseDir}}]
+Resolve any relative paths in this skill (e.g. `scripts/foo.js`, `templates/config.yaml`) against that directory using its absolute path: read referenced assets and templates, and run scripts with the terminal tool when the skill's instructions call for it.
+{{#if userArgs}}
+User: {{userArgs}}
+{{/if}}

package/src/prompts/steering/parent-irc.md

@@ -0,0 +1,5 @@
+Your current interruptible wait was interrupted because an IRC message arrived from your parent agent `{{from}}`.
+
+Parent IRC message:
+
+{{message}}

package/src/prompts/system/irc-incoming.md

@@ -3,5 +3,7 @@ Incoming IRC message from agent `{{from}}`{{#if replyTo}} (replying to {{replyTo
 
 {{message}}
 
+{{#if interrupting}}An agent sent this while you were waiting or working. Any active interruptible wait was stopped early so you can read it now.{{/if}}
+
 {{#if autoReplied}}You are mid-task, so a side-channel auto-reply was generated from your context and delivered to `{{from}}` on your behalf (recorded after this message). Follow up with the `irc` tool (`op: "send"`, `to: "{{from}}"`) only if that auto-reply needs correcting.{{else}}If a response is expected, reply with the `irc` tool (`op: "send"`, `to: "{{from}}"`) — you may finish your current step first. Nobody replies on your behalf.{{/if}}
 </irc>

package/src/prompts/system/mid-run-todo-nudge.md

@@ -0,0 +1,3 @@
+<system-reminder>
+Gentle reminder: {{incompleteCount}} todo item{{#if plural}}s are{{else}} is{{/if}} still open. If you finished a task since the last `{{toolRefs.todo}}` update, mark it done now so progress stays visible; otherwise just keep working.
+</system-reminder>

package/src/prompts/system/plan-mode-approved.md

@@ -1,25 +1,22 @@
 Plan approved.
 {{#if contextPreserved}}
-- Context preserved. Use conversation history when useful; this plan is the source of truth if it conflicts with earlier exploration.
+- Context preserved. Use conversation history when useful; the plan file is the source of truth if it conflicts with earlier exploration.
 {{/if}}
 
 <instruction>
-You MUST execute this plan step by step. You have full tool access.
+You MUST read `{{planFilePath}}` before executing.
+The file content is the authoritative plan; visible/compressed context is secondary.
+Read failure? Report the exact path and error instead of guessing.
+After reading, you MUST execute the plan step by step with full tool access.
 You MUST verify each step before proceeding to the next.
 {{#has tools "todo"}}
-Before execution, initialize todo tracking with `todo`.
+After reading the plan, initialize todo tracking with `todo`.
 After each completed step, immediately update `todo`.
 If `todo` fails, fix the payload and retry before continuing.
 {{/has}}
-The plan path is for subagent handoff only. You already have the plan; NEVER read it.
 </instruction>
 
-The full plan is injected below. You MUST execute it now:
-
-<plan path="{{planFilePath}}">
-{{planContent}}
-</plan>
-
 <critical>
+NEVER stop because inline plan content is compressed, expired, or unrecoverable. Read `{{planFilePath}}`.
 You MUST keep going until complete. This matters.
 </critical>

package/src/prompts/system/plan-mode-compact-instructions.md

@@ -12,5 +12,6 @@ You MUST drop:
 - Restated context already present in the plan file.
 
 {{#if planFilePath}}
-The approved plan file is at `{{planFilePath}}`; it is the authoritative source of truth and need not be re-summarized in detail.
+The approved plan file is at `{{planFilePath}}`; it is the authoritative source of truth.
+You MUST preserve this durable path and the fact that the executor must read it directly after compaction.
 {{/if}}

package/src/prompts/system/plan-mode-reference.md

@@ -1,11 +1,10 @@
 ## Existing Plan
 
-<plan path="{{planFilePath}}">
-{{planContent}}
-</plan>
+The approved plan file is at `{{planFilePath}}`.
 
 <instruction>
 If this plan is relevant to current work and not complete, you MUST continue executing it.
+If you do not have the current plan content in visible context, you MUST read `{{planFilePath}}`.
 If the plan is stale or unrelated, you MUST ignore it.
-The plan path is for subagent handoff only. You already have the plan; NEVER read it.
+NEVER stop because inline plan content is compressed, expired, or unrecoverable. Read the file.
 </instruction>

package/src/prompts/system/rewind-report.md

@@ -0,0 +1,6 @@
+Checkpoint completed. The checkpoint's exploratory branch was rewound; the branch summary and retained report below are now the context.
+
+Do not call `rewind` again for this checkpoint. Continue from this retained report.
+
+Report:
+{{report}}

package/src/prompts/system/subagent-system-prompt.md

@@ -61,6 +61,9 @@ Yield protocol:
 
 This is your only way to return a final result. For structured results, you NEVER put JSON in plain text or substitute a text summary for `result.data`.
 
+{{#if outputSchemaOverridesAgent}}
+Caller schema overrides agent-native output instructions. Ignore ROLE-provided output/yield labels, field names, examples, and procedures that conflict with the interface below. Use ONLY labels/fields from the caller schema; safest path: omit `type` and terminal-yield the full `result.data` object.
+{{/if}}
 {{#if outputSchema}}
 Your terminal `yield` MUST use exactly this shape — the schema fields go inside `result.data`, NEVER at the top level and NEVER as a stringified summary:
 ```ts

package/src/prompts/tools/irc.md

@@ -12,7 +12,8 @@ Use `op: "send"` to deliver a message to a specific peer or broadcast to `"all"`
 
 # Waiting and Inboxes
 Messages only arrive when the peer actively sends one—do not interrogate a peer for status.
-- If you are completely blocked and MUST wait for an answer, use `op: "wait"` (or `await: true` on a send). This blocks your turn until a message arrives. If it times out, that just means "no message arrived", not a failure.
+- If you are completely blocked and MUST wait for an answer, use `op: "wait"` (or `await: true` on a send). The wait returns when a matching message arrives, the timeout elapses, or any IRC / steering message interrupts the wait. Parent-agent IRC interrupts with steering-level priority.
+- No need to alternate `irc wait`, `irc inbox`, and `job poll`: waits surface cross-channel interrupts promptly. The next turn includes the interrupt reason and message.
 - To check for messages without blocking, use `op: "inbox"` to drain your queue.
 
 # When to Coordinate

package/src/prompts/tools/job.md

@@ -4,8 +4,8 @@ Background tasks deliver their results automatically the moment they finish. You
 
 # Interventions
 
-- **Block and wait:** Pass `poll` with specific job IDs when you are completely blocked and cannot do any other work. The call returns as soon as one watched job finishes or the wait window elapses — NOT when all of them finish; re-issue to keep waiting.
+- **Block and wait:** Pass `poll` with specific job IDs when you are completely blocked and cannot do any other work. The call returns as soon as one watched job finishes, the wait window elapses, or an IRC / steering message interrupts the wait — NOT when all jobs finish; re-issue to keep waiting.
   - To watch EVERY running job, issue a call with NO fields at all (no `poll`, no `cancel`, no `list`). NEVER pass an array of every running ID.
-  - A finished job's output is included in the wait result.
+  - A finished job's output, or the interrupting message and reason, is included in the next turn.
 - **Stop execution:** Pass `cancel` with job IDs to kill jobs that have hung, stalled, or are no longer needed. A cancel-only call returns immediately.
 - **Snapshot:** Pass `list: true` to get the current status of all jobs without waiting.

package/src/prompts/tools/rewind.md

@@ -9,5 +9,6 @@ Requirements:
 - You MUST call this before yielding if a checkpoint is active.
 
 Behavior:
-- If no checkpoint is active, this tool errors.
-- On success, the session rewinds and keeps your report as retained context.
+- If no checkpoint is active, this tool errors. If the checkpoint already rewound, continue from the retained report instead of retrying.
+- On success, the session rewinds, keeps your report as retained context, and closes the checkpoint.
+- A successful rewind is final for that checkpoint; repeat calls error.

package/src/prompts/tools/task.md

@@ -4,7 +4,11 @@ Execution blocks your turn: the call only returns once the work is completely fi
 
 # Delegation Strategy
 - **Maximize parallelism:** Break work into the widest possible {{#if batchEnabled}}array of `tasks[]`{{else}}set of parallel `task` calls{{/if}}. NEVER serialize work that can run concurrently. Tasks touching different files or independent refactors should run in parallel; agents resolve their own file collisions live.
+{{#when MAX_CONCURRENCY ">" 0}}
+- **Concurrency cap:** At most {{pluralize MAX_CONCURRENCY "subagent" "subagents"}} run at once in this session — anything beyond that just queues, so a {{#if batchEnabled}}`tasks[]` batch{{else}}set of parallel `task` calls{{/if}} larger than {{MAX_CONCURRENCY}} only delays results. Keep the fan-out at or under the cap.
+{{/when}}
 - **Sequence only when necessary:** The only reason to run A before B is if B strictly requires A's output to function (e.g., a core API contract or schema migration). {{#if ircEnabled}}If the missing piece is small, run them in parallel and have B ask A via `irc`!{{/if}}
+{{#if ircEnabled}}- **Steering delivery:** Parent-to-subagent IRC is delivered immediately as steering; subagents blocked in `job poll` / `irc wait` do not need to poll separately for it.{{/if}}
 - **Role matching:** Assign each subagent a specific `role` (e.g. "Security Reviewer", "DB Migrator"). Do not spawn generic workers.
 - **No overhead:** Each assignment MUST instruct its agent to skip formatters, linters, and project-wide test suites. You will run those once at the end.
 - **One-pass agents:** Prefer agents that investigate **and** edit in a single pass; only spin a read-only discovery step (e.g. `explore`) when the affected files are genuinely unknown.

package/src/sdk.ts

@@ -135,6 +135,7 @@ import { wrapStreamFnWithProviderConcurrency } from "./task/provider-concurrency
 import {
 	AUTO_THINKING,
 	type ConfiguredThinkingLevel,
+	concreteThinkingLevel,
 	parseConfiguredThinkingLevel,
 	parseThinkingLevel,
 	resolveProvisionalAutoLevel,
@@ -404,6 +405,15 @@ export interface CreateAgentSessionOptions {
 	customSystemPrompt?: string;
 	/** Already-loaded text appended through the bundled system prompt templates. */
 	appendSystemPrompt?: string;
+	/**
+	 * Already-loaded title-generation system prompt override (typically
+	 * {@link discoverTitleSystemPromptFile} → {@link resolvePromptInput}). When
+	 * set, every automatic session-title generation path on this session — the
+	 * first-input title and the replan-driven refresh — uses this prompt
+	 * instead of the bundled default. Refresh on cwd change via
+	 * {@link AgentSession.setTitleSystemPrompt}.
+	 */
+	titleSystemPrompt?: string;
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
@@ -1258,7 +1268,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			? getRestorableSessionModels(existingSession.models, sessionManager.getLastModelChangeRole())
 			: [];
 	let restoredSessionModelIndex = -1;
-	let restoredSessionThinkingLevel: ThinkingLevel | undefined;
+	let restoredSessionThinkingLevel: ConfiguredThinkingLevel | undefined;
 	if (!hasExplicitModel && !model && sessionModelStrings.length > 0) {
 		logger.time("restoreSessionModel", () => {
 			let failedSessionModel: string | undefined;
@@ -1266,6 +1276,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const sessionModelStr = sessionModelStrings[i];
 				const parsedModel = parseModelString(sessionModelStr, {
 					allowMaxAlias: true,
+					allowAutoAlias: true,
 					isLiteralModelId: (provider, id) => modelRegistry.find(provider, id) !== undefined,
 				});
 				if (!parsedModel) {
@@ -1333,7 +1344,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// Concrete level the agent/session start with. With `auto` this is the
 	// provisional level shown until the first per-turn classification resolves;
 	// `auto` itself stays a session-only concept handled by AgentSession.
-	let effectiveThinkingLevel: ThinkingLevel | undefined = thinkingLevel === AUTO_THINKING ? undefined : thinkingLevel;
+	let effectiveThinkingLevel: ThinkingLevel | undefined = concreteThinkingLevel(thinkingLevel);
 	if (model) {
 		const resolvedModel = model;
 		effectiveThinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
@@ -1567,6 +1578,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			activateDiscoveredTools: toolNames => session.activateDiscoveredTools(toolNames),
 			getCheckpointState: () => session.getCheckpointState(),
 			setCheckpointState: state => session.setCheckpointState(state ?? undefined),
+			getLastCompletedRewind: () => session.getLastCompletedRewind(),
 			getToolChoiceQueue: () => session.toolChoiceQueue,
 			buildToolChoice: name => {
 				const m = session.model;
@@ -1916,6 +1928,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const sessionModelStr = sessionModelStrings[i];
 				const parsedModel = parseModelString(sessionModelStr, {
 					allowMaxAlias: true,
+					allowAutoAlias: true,
 					isLiteralModelId: (provider, id) => modelRegistry.find(provider, id) !== undefined,
 				});
 				if (!parsedModel) continue;
@@ -1930,7 +1943,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					// `thinking.defaultLevel` must not become sticky.
 					thinkingLevel = pickInitialThinkingLevel(restoredModel);
 					autoThinking = thinkingLevel === AUTO_THINKING;
-					effectiveThinkingLevel = thinkingLevel === AUTO_THINKING ? undefined : thinkingLevel;
+					effectiveThinkingLevel = concreteThinkingLevel(thinkingLevel);
 					effectiveThinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
 						autoThinking
 							? resolveProvisionalAutoLevel(restoredModel)
@@ -1986,7 +1999,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					// so the role's explicit selector (e.g. `:max`) now applies.
 					thinkingLevel = pickInitialThinkingLevel(resolvedDefaultModel);
 					autoThinking = thinkingLevel === AUTO_THINKING;
-					effectiveThinkingLevel = thinkingLevel === AUTO_THINKING ? undefined : thinkingLevel;
+					effectiveThinkingLevel = concreteThinkingLevel(thinkingLevel);
 					effectiveThinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
 						autoThinking
 							? resolveProvisionalAutoLevel(resolvedDefaultModel)
@@ -2744,6 +2757,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			providerSessionId: options.providerSessionId,
 			parentEvalSessionId: options.parentEvalSessionId,
 			advisorTools,
+			titleSystemPrompt: options.titleSystemPrompt,
 		});
 		hasSession = true;
 		if (asyncJobManager) {