@oh-my-pi/pi-coding-agent 15.10.0 → 15.10.2

package/src/modes/workflow.ts

@@ -3,25 +3,25 @@ import { createGradientHighlighter, type KeywordHighlighter } from "./gradient-h
 import { keywordInProse } from "./markdown-prose";
 
 /**
- * "workflow" keyword support.
+ * "workflowz" keyword support.
  *
  * Typing the standalone word in the input editor paints it with a warm
  * amber→green gradient ({@link highlightWorkflow}); submitting a message that
  * mentions it appends a hidden {@link WORKFLOW_NOTICE} that steers the model to
  * author a deterministic multi-subagent workflow in eval cells (agent/parallel/
  * pipeline). Matching is whitespace-delimited and case-sensitive (lowercase
- * only) — "workflow"/"workflows" trigger, but "workflowed", "Workflow", and
- * "workflow.ts" never do.
+ * only) — "workflowz" triggers, but "workflowzed", "Workflowz", and
+ * "workflowz.ts" never do.
  */
 
-// Detection: lowercase keyword (singular or plural) flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
-const WORKFLOW_WORD = /(?<!\S)workflows?(?!\S)/;
+// Detection: lowercase keyword flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
+const WORKFLOW_WORD = /(?<!\S)workflowz(?!\S)/;
 
-/** Hidden system notice appended after a user message that mentions "workflow". */
+/** Hidden system notice appended after a user message that mentions "workflowz". */
 export const WORKFLOW_NOTICE: string = workflowNotice.trim();
 
 /**
- * Whether `text` contains the standalone keyword "workflow"/"workflows"
+ * Whether `text` contains the standalone keyword "workflowz"
  * (lowercase, whitespace-delimited) in prose — never inside a code block, inline
  * code span, or XML/HTML section.
  */
@@ -30,13 +30,13 @@ export function containsWorkflow(text: string): boolean {
 }
 
 /**
- * Highlight every standalone "workflow"/"workflows" in `text` for editor display
+ * Highlight every standalone "workflowz" in `text` for editor display
  * with a warm amber→green gradient (hue 30..150), visually distinct from
  * ultrathink's rainbow and orchestrate's teal→violet.
  */
 export const highlightWorkflow: KeywordHighlighter = createGradientHighlighter({
-	probe: /workflow/,
-	highlight: /(?<!\S)workflows?(?!\S)/g,
+	probe: /workflowz/,
+	highlight: /(?<!\S)workflowz(?!\S)/g,
 	stops: 14,
 	hue: t => 30 + t * 120,
 });

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

@@ -1,15 +1,12 @@
-import * as fs from "node:fs/promises";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { resolveLocalUrlToPath } from "../internal-urls";
-import { normalizeLocalScheme } from "../tools/path-utils";
 import { ToolError } from "../tools/tool-errors";
 
 /** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
  *  approval popup. Populated by the standing handler that the resolve tool
- *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
 export interface PlanApprovalDetails {
 	planFilePath: string;
-	finalPlanFilePath: string;
 	title: string;
 	planExists: boolean;
 }
@@ -110,54 +107,80 @@ export function humanizePlanTitle(title: string): string {
 	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 
-interface RenameApprovedPlanFileOptions {
-	planFilePath: string;
-	finalPlanFilePath: string;
-	getArtifactsDir: () => string | null;
-	getSessionId: () => string | null;
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export function planFileUrlForSlug(slug: string): string {
+	return `local://${slug}-plan.md`;
 }
 
-function assertLocalUrl(path: string, label: "source" | "destination"): void {
-	if (!path.startsWith("local:/") && !path.startsWith("local://")) {
-		throw new Error(`Approved plan ${label} path must use local: scheme with / or // (received ${path}).`);
+/** Derive a `<slug>` from an agent-supplied `extra.title`, or `undefined` when
+ *  the title is missing/non-string/unsanitizable. A trailing `-plan` is stripped
+ *  so a supplied "auth-plan" maps to `auth-plan.md`, not `auth-plan-plan.md`. */
+function planSlugFromSupplied(suppliedTitle: unknown): string | undefined {
+	if (typeof suppliedTitle !== "string" || !suppliedTitle.trim()) return undefined;
+	try {
+		const { title } = normalizePlanTitle(suppliedTitle);
+		const slug = title.replace(/-plan$/i, "");
+		return slug || title;
+	} catch {
+		return undefined;
 	}
 }
 
-export async function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void> {
-	const { planFilePath, finalPlanFilePath, getArtifactsDir, getSessionId } = options;
-	assertLocalUrl(planFilePath, "source");
-	assertLocalUrl(finalPlanFilePath, "destination");
+export interface ResolveApprovedPlanInput {
+	/** The agent's `extra.title` from the `resolve` call, if any. */
+	suppliedTitle?: unknown;
+	/** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+	statePlanFilePath: string;
+	/** Read a plan `local://` URL, returning null when the file does not exist. */
+	readPlan: (planUrl: string) => Promise<string | null>;
+	/** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+	 *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+	 *  still found. */
+	listPlanFiles?: () => Promise<string[]>;
+}
+
+export interface ResolvedApprovedPlan {
+	planFilePath: string;
+	planContent: string;
+	title: string;
+}
 
-	const resolveOptions = {
-		getArtifactsDir: () => getArtifactsDir(),
-		getSessionId: () => getSessionId(),
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export async function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan> {
+	const ordered: string[] = [];
+	const consider = (url: string | undefined): void => {
+		if (url && !ordered.includes(url)) ordered.push(url);
 	};
-	const resolvedSource = resolveLocalUrlToPath(normalizeLocalScheme(planFilePath), resolveOptions);
-	const resolvedDestination = resolveLocalUrlToPath(normalizeLocalScheme(finalPlanFilePath), resolveOptions);
 
-	if (resolvedSource === resolvedDestination) {
-		return;
+	const slug = planSlugFromSupplied(input.suppliedTitle);
+	consider(slug ? planFileUrlForSlug(slug) : undefined);
+	consider(input.statePlanFilePath);
+
+	for (const url of ordered) {
+		const content = await input.readPlan(url);
+		if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 	}
 
-	try {
-		const destinationStat = await fs.stat(resolvedDestination);
-		if (destinationStat.isFile()) {
-			throw new Error(
-				`Plan destination already exists at ${finalPlanFilePath}. Choose a different title and submit the plan for approval again.`,
-			);
-		}
-		throw new Error(`Plan destination exists but is not a file: ${finalPlanFilePath}`);
-	} catch (error) {
-		if (!isEnoent(error)) {
-			throw error;
+	if (input.listPlanFiles) {
+		for (const url of await input.listPlanFiles()) {
+			if (ordered.includes(url)) continue;
+			const content = await input.readPlan(url);
+			if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 		}
 	}
 
-	try {
-		await fs.rename(resolvedSource, resolvedDestination);
-	} catch (error) {
-		throw new Error(
-			`Failed to rename approved plan from ${planFilePath} to ${finalPlanFilePath}: ${error instanceof Error ? error.message : String(error)}`,
-		);
-	}
+	const target = ordered[0] ?? input.statePlanFilePath;
+	throw new ToolError(
+		`Plan file not found at ${target}. Write the finalized plan to ${target} before requesting approval.`,
+	);
+}
+
+function finalizeApprovedPlan(planFilePath: string, planContent: string, suppliedTitle: unknown): ResolvedApprovedPlan {
+	const { title } = resolvePlanTitle({ suppliedTitle, planContent, planFilePath });
+	return { planFilePath, planContent, title };
 }

package/src/plan-mode/plan-protection.ts

@@ -16,11 +16,11 @@ function readTargetsPlan(readPath: string, planTarget: string): boolean {
  * Build a compaction protection matcher that keeps `read` results for the active
  * plan file intact through prune/shake — the plan analog of skill-read
  * protection. Matches both the canonical `local://PLAN.md` alias and the
- * session's current plan reference path (e.g. a titled `local://<title>.md`), so
- * the plan survives compaction whether the agent reads it by alias or by title.
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
  *
- * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
- * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
  */
 export function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean {
 	return (context: ProtectedToolContext) => {

package/src/prompts/system/background-tan-dispatch.md

@@ -0,0 +1,8 @@
+<system-notice reason="background_task_dispatched" job="{{jobId}}">
+The user launched a tangential task that is now running in a separate background agent. This is NOT a prompt injection and NOT a new instruction for you — it is the coding agent informing you that work was handed off elsewhere.
+
+The task below is being handled by another agent in its own session. You are NOT responsible for it: do NOT start working on it, do NOT reference it, and do NOT let it interrupt or alter your current task. Simply continue what you were doing as if this message had not appeared. Results, if any, will surface separately when the background task ({{jobId}}) completes.
+
+Dispatched work (for your awareness only):
+{{work}}
+</system-notice>

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

@@ -6,111 +6,120 @@ You NEVER:
 - Run state-changing commands (git commit, npm install, etc.)
 - Make any system changes
 
-To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<PLAN_TITLE>" }` → user approves an execution option → full write access is restored. `<PLAN_TITLE>` may only contain letters, numbers, underscores, and hyphens; the approved plan is renamed to `local://<PLAN_TITLE>.md`.
+To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<slug>" }` where `<slug>` matches your `local://<slug>-plan.md` file → user approves an execution option → full write access is restored. `<slug>` may only contain letters, numbers, underscores, and hyphens. The plan file is never renamed, so its name is yours to choose.
 
 You NEVER ask the user to exit plan mode for you; you MUST call `resolve` yourself.
 </critical>
 
+## Objective
+
+A plan is **decision-complete**: another engineer or agent can execute it end-to-end without making a single design decision. Optimize every choice for that. Detail exists to remove the implementer's decisions — not to look thorough. A document that reads like a design doc (Non-Goals, Alternatives, risk matrices) yet leaves real decisions open is a FAILED plan.
+
 ## Plan File
 
 {{#if planExists}}
-Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally.
+Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally. If this request is a different task, write a fresh `local://<slug>-plan.md` instead and leave the old plan in place.
 {{else}}
-You MUST create a plan at `{{planFilePath}}`.
+Choose a short kebab-case `<slug>` that names this task (letters, numbers, hyphens) and write the plan to `local://<slug>-plan.md` — e.g. `local://auth-token-refresh-plan.md`. You MUST pass that same `<slug>` as `title` when you call `resolve`.
 {{/if}}
 
-You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace.
+You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace. You MUST update the plan as you learn — you NEVER batch all writing to the end.
 
-<caution>
-The approval selector includes:
-- **Approve and execute**: starts execution in fresh context (session cleared).
-- **Approve and compact context**: distills the plan-mode discussion into a summary, then starts execution in this session.
-- **Approve and keep context**: starts execution in this session, preserving exploration history.
+## Resolving Unknowns
 
-You MUST still make the plan file self-contained: include requirements, decisions, key findings, and remaining todos.
-</caution>
+You MUST eliminate unknowns by discovering facts, not by asking. Before asking the user anything, perform at least one targeted exploration pass.
+
+Two kinds of unknowns, treated differently:
+- **Discoverable facts** — repo/system truth: file locations, current behavior, existing patterns, types, configs. You MUST explore first (`find`, `search`, `read`, parallel explore subagents). You NEVER ask what the codebase can answer (e.g. "where is this defined?"). Ask only when several plausible candidates remain or a required identifier is genuinely absent — and then present the candidates with a recommendation.
+- **Preferences and tradeoffs** — intent, UX, scope boundaries, performance-vs-simplicity: not derivable from code. You MUST surface these early via `{{askToolName}}` with 2–4 mutually exclusive options and a recommended default. If left unanswered, proceed with the default and record it under Assumptions.
+
+Every question MUST materially change the plan, confirm a load-bearing assumption, or choose between real tradeoffs. You MUST batch questions. You NEVER ask filler questions or offer obviously-wrong options.
 
 {{#if reentry}}
 ## Re-entry
 
 <procedure>
-1. Read existing plan
-2. Evaluate request against it
+1. Read the existing plan.
+2. Evaluate the new request against it.
 3. Decide:
-   - **Different task** → Overwrite plan
-   - **Same task, continuing** → Update and clean outdated sections
-4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete
+   - **Different task** → overwrite the plan.
+   - **Same task, continuing** → update and delete outdated sections.
+4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete.
 </procedure>
 {{/if}}
 
 {{#if iterative}}
-## Iterative Planning
+## Workflow — Iterative
 
 <procedure>
 ### 1. Explore
-You MUST use `find`, `search`, `read` to understand the codebase.
+You MUST use `find`, `search`, `read` to ground yourself in the actual code. Hunt for existing functions, utilities, and conventions to reuse before proposing anything new.
 
 ### 2. Interview
-You MUST use `{{askToolName}}` to clarify:
-- Ambiguous requirements
-- Technical decisions and tradeoffs
-- Preferences: UI/UX, performance, edge cases
+You MUST use `{{askToolName}}` to resolve preferences and tradeoffs (see Resolving Unknowns). Batch questions; never ask what exploration answers.
 
-You MUST batch questions. You NEVER ask what you can answer by exploring.
-
-### 3. Update Incrementally
-You MUST use `{{editToolName}}` to update plan file as you learn; NEVER wait until end.
+### 3. Update incrementally
+You MUST use `{{editToolName}}` to revise the plan file as you learn.
 
 ### 4. Calibrate
-- Large unspecified task → multiple interview rounds
-- Smaller task → fewer or no questions
+- Large, unspecified task → multiple interview rounds.
+- Small, well-specified task → few or no questions.
 </procedure>
-
-<caution>
-### Plan Structure
-
-You MUST use clear markdown headers; include:
-- Recommended approach (not alternatives)
-- Paths of critical files to modify
-- Verification: how to test end-to-end
-
-The plan MUST be scannable yet detailed enough to execute.
-</caution>
-
 {{else}}
-## Planning Workflow
+## Workflow — Parallel
 
 <procedure>
-### Phase 1: Understand
-You MUST focus on the request and associated code. You SHOULD launch parallel explore agents when scope spans multiple areas.
+### Phase 1 — Understand
+You MUST focus on the request and the code behind it. You SHOULD launch parallel `explore` subagents (via `task`) when scope spans multiple areas — give each a distinct focus (existing implementations, related components, test patterns). Actively hunt for reusable functions, utilities, and conventions; avoid proposing new code when a suitable implementation already exists.
 
-### Phase 2: Design
-You MUST draft an approach based on exploration. You MUST consider trade-offs briefly, then choose.
+### Phase 2 — Design
+You MUST draft an approach from your exploration, weigh trade-offs briefly, then commit to one. For large or cross-cutting changes you MAY spawn a planning/critique subagent to pressure-test the approach before you commit.
 
-### Phase 3: Review
-You MUST read critical files. You MUST verify plan matches original request. You SHOULD use `{{askToolName}}` to clarify remaining questions.
+### Phase 3 — Review
+You MUST read the critical files you intend to touch to confirm the approach holds against the real code. You MUST verify the plan still matches the original request. You SHOULD use `{{askToolName}}` to close remaining preference questions.
 
-### Phase 4: Update Plan
-You MUST update `{{planFilePath}}` (`{{editToolName}}` for changes, `{{writeToolName}}` only if creating from scratch):
-- Recommended approach only
-- Paths of critical files to modify
-- Verification section
+### Phase 4 — Write the plan
+You MUST write the plan file (see **Plan File** above) per **The Plan** below.
 </procedure>
+{{/if}}
+
+## The Plan
+
+The plan MUST be self-contained: approval may clear or compact this conversation, so the file alone must carry everything needed to execute.
 
 <caution>
-You MUST ask questions throughout. You NEVER make large assumptions about user intent.
+Write 3–5 short, scannable markdown sections. The usual shape:
+- **Context** — why this change: the problem or need, what prompted it, the intended outcome. 2–4 sentences.
+- **Approach** — the recommended approach only. Group bullets by subsystem or behavior, NOT file-by-file. Name existing functions/utilities to reuse, with their paths. Describe a repeated pattern once with a few representative paths — you NEVER enumerate every file or line.
+- **Critical files** — the ≤5 files that disambiguate non-obvious changes, each with a one-line reason. Skip files whose change is already obvious from the Approach.
+- **Verification** — how to test end-to-end: exact commands, tests to run or add, manual steps.
+- **Assumptions** — only the decisions you made that the user might want to override.
+
+Prefer the minimum detail needed for safe implementation, not exhaustive coverage. Compress related changes into high-signal bullets; omit branch-by-branch logic, restated invariants, and lists of unaffected behavior. Behavior-level descriptions beat symbol-by-symbol removal lists.
 </caution>
-{{/if}}
 
 <directives>
-- You MUST use `{{askToolName}}` only for clarifying requirements or choosing approaches
+- You NEVER include sections that decide nothing: Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work. Omit them entirely.
+- You NEVER invent schema, validation, precedence, or fallback policy the request did not establish, unless it is required to prevent a concrete implementation mistake.
+- You NEVER present alternatives in the final plan — choose. Record a discarded option only when it is a live tradeoff the user should confirm, and put it under Assumptions.
 </directives>
 
+<caution>
+The approval selector offers:
+- **Approve and execute** — execution starts in fresh context (session cleared).
+- **Approve and compact context** — distills this discussion into a summary, then executes in this session.
+- **Approve and keep context** — executes in this session, preserving exploration history.
+
+All three rely on the plan file being self-contained.
+</caution>
+
 <critical>
+You MUST use `{{askToolName}}` only to clarify requirements or choose between approaches.
+
 Your turn ends ONLY by:
 1. Using `{{askToolName}}` to gather information, OR
-2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<PLAN_TITLE>" }` when ready — this triggers user approval, then implementation with full tool access
+2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<slug>" }` (the slug of your `local://<slug>-plan.md`) when ready — this triggers user approval, then implementation with full tool access.
 
-You NEVER ask plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
-You MUST keep going until complete.
+You NEVER ask for plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
+You MUST keep going until the plan is decision-complete.
 </critical>

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

@@ -16,7 +16,7 @@ The plan path is for subagent handoff only. You already have the plan; NEVER rea
 
 The full plan is injected below. You MUST execute it now:
 
-<plan path="{{finalPlanFilePath}}">
+<plan path="{{planFilePath}}">
 {{planContent}}
 </plan>
 

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

@@ -1,5 +1,5 @@
 <system-notice>
-The user's message above contains the **workflow** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration as Python in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
+The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration as Python in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
 
 <when>
 Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline FIRST (list the files, scope the diff, find the call sites) to discover the work-list, then fan out over it — you don't need to know the shape before the *task*, only before the *fan-out*. Common shapes, each a well-scoped `eval` call you can chain across turns:

package/src/prompts/tools/bash.md

@@ -31,6 +31,15 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
 - For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
 {{/if}}
+{{#if autoBackgroundEnabled}}
+
+## Auto-background
+
+- A foreground (non-`async`) call that has not completed within **{{autoBackgroundThresholdSeconds}}s** is automatically converted into a background job and returns a `Background job <id> started: …` notice with the buffered output so far. The command keeps running; the final result is delivered as a follow-up tool call when it completes.
+- This is NOT a failure or a re-queue. Treat the notice as "still running, will report back" — do not retry the same command, and do not wait synchronously for it.
+- Auto-backgrounding does NOT extend `timeout`: the job is still killed at the original deadline.
+- If you need the result inline (e.g. piping into another command), raise `timeout` above the expected duration so it finishes before the threshold matters{{#if asyncEnabled}}, or set `async: true` up front so the contract is explicit{{/if}}.
+{{/if}}
 
 # Output minimizer
 

package/src/prompts/tools/browser.md

@@ -26,7 +26,7 @@ Drives real Chromium tab; full puppeteer access via JS execution.
   - `tab.waitForResponse(pattern, { timeout? })` — pattern substring, `RegExp`, or `(response) => boolean`. Returns raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
   - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
   - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — captures screenshot and **auto-attaches to tool output for you to view** (unless `silent: true`). `save` is **strictly optional**: OMIT when you just want to look at page — downscaled image shown regardless, full-res capture written to temp file automatically. Pass `save` (a path) ONLY when deliberately need to keep full-res copy on disk for later use; `browser.screenshotDir` does same for every shot. NEVER invent `save` path for throwaway/temporal screenshot.
-  - `tab.extract(format = "markdown")` — Readability-extracted page content.
+  - `tab.extract(format = "markdown")` — returns Readability-extracted page content as a string (`"markdown"` or `"text"`). Throws if the page yields no readable content.
 - Selectors accept CSS plus puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…` normalized.
 - Default `tab.observe()` over `tab.screenshot()` for page state. Screenshot only when visual appearance matters.
 </instruction>

package/src/prompts/tools/eval.md

@@ -46,8 +46,9 @@ tool.<name>(args) → unknown
     Invoke any session tool by name. `args` is the tool's parameter object.
 llm(prompt, model?="default", system?=None, schema?=None) → str | dict
     Oneshot, stateless LLM call (no history, no tools). `model` picks a tier: "smol" (fast), "default" (this session's model), "slow" (most capable). Pass `system` for a system prompt. Pass a JSON-Schema `schema` to force structured output and get the parsed object back; otherwise returns the completion text.
-agent(prompt, agent_type?="task", model?=None, context?=None, label?=None, schema?=None) → str | dict
+{{#if spawns}}agent(prompt, agent_type?="task", model?=None, context?=None, label?=None, schema?=None) → str | dict
     Run a subagent and return its final output. Defaults to the bundled "task" agent; pass `agent_type`/`agentType` for another discovered agent. Pass a JSON-Schema `schema` to force structured output and get the parsed object back.
+{{/if}}
 parallel(thunks) → list
     Run thunks (callables) through a bounded pool, preserving input order. The pool is as wide as a `task` tool batch (tracks the `task.maxConcurrency` setting), so fan out as wide as the work divides — don't pre-shrink it. Barrier: returns once all finish; a thunk that throws propagates.
 pipeline(items, ...stages) → list

package/src/prompts/tools/read.md

@@ -18,8 +18,8 @@ Append `:<sel>` to `path`. The bare path falls back to the default mode.
 - `:50` / `:50-` — read from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
 - `:50+150` — 150 lines starting at line 50.
-- `:20+1` — exactly one line.
-- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).
+- `:20+1` — anchor on line 20 (single-range reads expand by ≤1 leading and ≤3 trailing context lines).
+- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged). Multi-range mode returns exact bounds with no context padding.
 - `:raw` — verbatim text; no anchors, no summary, no line prefixes.
 - `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.
 - `:conflicts` — one-line-per-block index of every unresolved git merge conflict.

package/src/sdk.ts

@@ -10,7 +10,6 @@ import {
 } from "@oh-my-pi/pi-agent-core";
 import {
 	type CredentialDisabledEvent,
-	isUsageLimitError,
 	type Message,
 	type Model,
 	type SimpleStreamOptions,
@@ -24,7 +23,6 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import {
 	$env,
 	$flag,
-	extractRetryHint,
 	getAgentDbPath,
 	getAgentDir,
 	getAuthBrokerSnapshotCachePath,
@@ -39,10 +37,13 @@ import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from ".
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
+import { createApiKeyResolver } from "./config/api-key-resolver";
 import { shouldEnableAppendOnlyContext } from "./config/append-only-context-mode";
 import { ModelRegistry } from "./config/model-registry";
 import {
+	defaultModelPerProvider,
 	formatModelString,
+	getModelMatchPreferences,
 	parseModelPattern,
 	parseModelString,
 	resolveAllowedModels,
@@ -280,6 +281,8 @@ export interface CreateAgentSessionOptions {
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
+	/** Optional provider-facing prompt cache key, distinct from request lineage. */
+	providerPromptCacheKey?: string;
 
 	/** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
 	customTools?: (CustomTool | ToolDefinition)[];
@@ -708,6 +711,7 @@ function customToolToDefinition(tool: CustomTool): ToolDefinition {
 		parameters: tool.parameters,
 		hidden: tool.hidden,
 		deferrable: tool.deferrable,
+		approval: typeof tool.approval === "function" ? tool.approval.bind(tool) : tool.approval,
 		mcpServerName: tool.mcpServerName,
 		mcpToolName: tool.mcpToolName,
 		execute: (toolCallId, params, signal, onUpdate, ctx) =>
@@ -1029,9 +1033,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const hasServiceTierEntry = existingBranch.some(entry => entry.type === "service_tier_change");
 
 	const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
-	const modelMatchPreferences = {
-		usageOrder: settings.getStorage()?.getModelUsageOrder(),
-	};
+	const modelMatchPreferences = getModelMatchPreferences(settings);
 	const allowedModels = await logger.time("resolveAllowedModels", () =>
 		resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
 	);
@@ -1552,9 +1554,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Resolve deferred --model pattern now that extension models are registered.
 		if (!model && options.modelPattern) {
 			const availableModels = modelRegistry.getAll();
-			const matchPreferences = {
-				usageOrder: settings.getStorage()?.getModelUsageOrder(),
-			};
+			const matchPreferences = getModelMatchPreferences(settings);
 			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
 				modelRegistry,
 			});
@@ -1573,12 +1573,30 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// Re-resolve the allowed set: extension factories above may have
 			// registered providers/models that weren't visible at startup.
 			const fallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
-			for (const candidate of fallbackCandidates) {
-				if (await hasModelApiKey(candidate)) {
-					model = candidate;
+			// Prefer each provider's configured default model
+			// (DEFAULT_MODEL_PER_PROVIDER) over raw catalog order. Without this the
+			// first-run fallback picks whatever model sorts first in models.json for
+			// the winning provider (e.g. anthropic's claude-3-5-sonnet-20240620)
+			// instead of the intended provider default (claude-sonnet-4-6). Mirrors
+			// findInitialModel's precedence.
+			for (const [provider, defaultId] of Object.entries(defaultModelPerProvider)) {
+				const preferred = fallbackCandidates.find(
+					candidate => candidate.provider === provider && candidate.id === defaultId,
+				);
+				if (preferred && (await hasModelApiKey(preferred))) {
+					model = preferred;
 					break;
 				}
 			}
+			// Otherwise, first available model with a valid API key.
+			if (!model) {
+				for (const candidate of fallbackCandidates) {
+					if (await hasModelApiKey(candidate)) {
+						model = candidate;
+						break;
+					}
+				}
+			}
 			if (model) {
 				if (modelFallbackMessage) {
 					modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
@@ -2001,6 +2019,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			onPayload,
 			onResponse,
 			sessionId: providerSessionId,
+			promptCacheKey: options.providerPromptCacheKey,
 			transformContext,
 			steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
 			followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
@@ -2017,9 +2036,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
-			getApiKey: async provider => {
+			getApiKey: async (provider, ctx) => {
 				// Read agent.sessionId at call time so credential selection stays aligned
 				// with metadataResolver after /new, fork, resume, or branch switches.
+				// Retry steps (ctx carries an auth error) drive the central a/b/c
+				// policy — force-refresh the same account, then rotate to a sibling —
+				// and may legitimately yield no key when every account is exhausted.
+				if (ctx?.error !== undefined) {
+					return createApiKeyResolver(modelRegistry, provider, { sessionId: agent.sessionId })(ctx);
+				}
 				const key = await modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
 				if (!key) {
 					throw new Error(`No API key found for provider "${provider}"`);
@@ -2033,40 +2058,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return streamSimple(streamModel, context, {
 					...streamOptions,
 					openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
-					onAuthError: async (provider, oldKey, error) => {
-						const message = error instanceof Error ? error.message : String(error);
-						// streamSimple invokes this for both 401 auth failures AND
-						// rotatable usage-limit errors (Codex usage_limit_reached,
-						// Anthropic usage_limit_reached, etc.). The two need
-						// different storage actions: a real 401 means the credential
-						// is bad and should be marked suspect; a usage limit just
-						// means this account is parked until reset and should be
-						// temporarily blocked so a sibling can pick the request up.
-						if (isUsageLimitError(message)) {
-							const retryAfterMs = extractRetryHint(undefined, message);
-							const switched = await modelRegistry.authStorage.markUsageLimitReached(provider, agent.sessionId, {
-								retryAfterMs,
-								signal: streamOptions?.signal,
-							});
-							logger.debug("Retrying provider request after usage-limit block", {
-								provider,
-								switched,
-								retryAfterMs,
-								error: message,
-							});
-							if (!switched) return undefined;
-							return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-						}
-						await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
-							signal: streamOptions?.signal,
-							sessionId: agent.sessionId,
-						});
-						logger.debug("Retrying provider request after credential invalidation", {
-							provider,
-							error: message,
-						});
-						return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-					},
 				});
 			},
 			cursorExecHandlers,