@oh-my-pi/pi-coding-agent 17.2.13 → 17.2.15

package/src/prompts/tools/image-gen.md

@@ -1,7 +1,7 @@
-Generates or edits images.
+Generates/edits images.
 
 <instructions>
-- Provide a single detailed `subject` prompt for generation or editing.
-- When using multiple `input`, describe each image's role in `subject` (e.g. `Image 1` for composition, `Image 2` for lighting).
-- For text: add "sharp, legible, correctly spelled"; keep text short.
+- One detailed `subject` prompt: generation or editing.
+- Multiple `input`: describe each image's role in `subject` (e.g. `Image 1` for composition, `Image 2` for lighting).
+- Text: add "sharp, legible, correctly spelled"; keep short.
 </instructions>

package/src/prompts/tools/inspect-image-system.md

@@ -1,20 +1,20 @@
-You are an image-analysis assistant.
+Image-analysis assistant.
 
 Core behavior:
-- Be evidence-first: distinguish direct observations from inferences.
-- If something is unclear, say uncertain rather than guessing.
+- Evidence-first: direct observations and inferences distinct.
+- If unclear, say uncertain—not guess.
 - NEVER fabricate unreadable or occluded details.
-- Keep output compact and useful.
+- Output compact, useful.
 
-Default output format (unless the requested question asks for another format):
+Default format unless question requests another:
 1) Answer
 2) Key evidence
 3) Caveats / uncertainty
 
-For OCR-style requests:
+OCR-style requests:
 - Preserve exact visible text, including casing and punctuation.
-- If text is partially unreadable, mark the unreadable segments explicitly.
+- Partially unreadable text: explicitly mark unreadable segments.
 
-For UI/screenshot debugging requests:
-- Focus on visible states, labels, toggles, error messages, disabled controls, and relevant affordances.
-- Separate observed UI state from probable root cause.
+UI/screenshot debugging:
+- Focus: visible states, labels, toggles, error messages, disabled controls, relevant affordances.
+- Observed UI state and probable root cause separate.

package/src/prompts/tools/inspect-image.md

@@ -1,22 +1,19 @@
-Inspects an image file with a vision-capable model and returns compact text analysis.
+Inspects image files via a vision-capable model; returns compact text analysis.
 
 <instruction>
-- Use this for image understanding tasks (OCR, UI/screenshot debugging, scene/object questions)
-- Provide `path` as a local image file path, `Image #N` attachment label, or `attachment://N` URI
-- Write a specific `question`:
-  - what to inspect
-  - constraints (for example: "quote visible text verbatim", "only report confirmed findings")
-  - desired output format (bullets/table/JSON/short answer)
-- Keep `question` grounded in observable evidence and ask for uncertainty when details are unclear
-- Use this tool over `read` when the goal is image analysis
+- Use for image understanding: OCR, UI/screenshot debugging, scene/object questions.
+- `path`: local image-file path | `Image #N` attachment label | `attachment://N` URI.
+- `question` specific: inspection target; constraints (e.g. "quote visible text verbatim", "only report confirmed findings"); output format (bullets/table/JSON/short answer).
+- Ground `question` in observable evidence; request uncertainty for unclear details.
+- For image analysis, use over `read`.
 </instruction>
 
 <output>
-- Returns text-only analysis from the vision model
-- No image content blocks are returned in tool output
+- Vision-model text-only analysis.
+- Tool output: no image content blocks.
 </output>
 
 <critical>
-- If image submission is blocked by settings, the tool will fail with an actionable error
-- If configured model does not support image input, configure a vision-capable model role before retrying
+- Settings-blocked image submission → actionable error.
+- Configured model lacks image input → configure a vision-capable model role before retrying.
 </critical>

package/src/prompts/tools/learn.md

@@ -1,7 +1,7 @@
-Capture a reusable lesson into long-term memory, and optionally mint or enhance a managed skill in the same call.
+Capture reusable lessons in long-term memory; optionally mint/enhance a managed skill in the same call.
 
-Use after solving something whose insight will pay off again: a non-obvious fix, a project convention you had to discover, a workflow that worked.
+Use after solving insight likely to pay off again: a non-obvious fix, discovered project convention, or workflow that worked.
 
-Provide the optional `skill` object when the lesson is a repeatable *procedure* worth codifying as a `SKILL.md` (not just a fact). Managed skills are written to an isolated directory (`~/.omp/agent/managed-skills`) and are surfaced like normal skills next session. They NEVER touch user-authored skills. Frontmatter is generated from `name` and `description`.
+`skill` optional; provide only for a repeatable procedure worth codifying as `SKILL.md`, not a fact. Managed skills: isolated `~/.omp/agent/managed-skills`; surfaced as normal skills next session; NEVER touch user-authored skills. Frontmatter: generated from `name` and `description`.
 
-Capture sparingly and specifically. One strong, reusable lesson beats several vague ones.
+Capture sparingly, specifically: one strong reusable lesson > several vague ones.

package/src/prompts/tools/manage-skill.md

@@ -1,9 +1,12 @@
-Create, update, or delete a managed skill — a `SKILL.md` written to an isolated directory (`~/.omp/agent/managed-skills`) and surfaced like a normal skill in future sessions.
+Managed skill: `SKILL.md` in isolated `~/.omp/agent/managed-skills`; surfaced as a normal skill in future sessions.
 
-Managed skills are for repeatable procedures worth codifying: a setup sequence, a debugging recipe, a project-specific workflow. They are kept separate from user-authored skills and this tool NEVER edits those.
+Use: repeatable procedures worth codifying — setup sequence, debugging recipe, project-specific workflow.
+User-authored skills separate; tool NEVER edits them.
 
-- `action: "create"` — fails if the skill already exists.
-- `action: "update"` — overwrites the body; fails if the skill does not exist.
-- `action: "delete"` — fails if the skill does not exist.
+- `action: "create"` — fails if skill exists.
+- `action: "update"` — overwrites body; fails if skill absent.
+- `action: "delete"` — fails if skill absent.
 
-`name` is kebab-case (lowercase letters, digits, hyphens). The `description` drives discovery, so make it specific. Do not include frontmatter in `body`; it is generated from `name` and `description`.
+`name`: kebab-case (lowercase letters, digits, hyphens).
+`description`: specific; drives discovery.
+No frontmatter in `body`; generated from `name` and `description`.

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

@@ -1,12 +1,12 @@
-Edit Mnemopi long-term memories by id.
+Edit Mnemopi long-term memories by id. Only ids returned by `recall`.
 
-Use only with ids returned by the `recall` tool. Operations:
-- `update`: replace content and/or importance for a working memory.
-- `forget`: permanently delete a working memory.
-- `invalidate`: softly supersede a working or episodic memory, optionally pointing at `replacement_id`.
+Operations:
+- `update`: working memory; replace content and/or importance.
+- `forget`: permanently delete working memory.
+- `invalidate`: softly supersede working or episodic memory; optional `replacement_id`.
 
-Fact ids (recall results marked `[facts]`) are read-only: inspect them with `read memory://<id>`; every edit op on a fact id returns `not_editable`.
+Fact ids — `recall` results marked `[facts]`: read-only. Inspect with `read memory://<id>`; any edit op → `not_editable`.
 
-Prefer `invalidate` when a memory became stale but its history may still be useful. Use `forget` only for content that should be hard-deleted.
+Prefer `invalidate` for stale memory whose history may still be useful. Use `forget` only for content requiring hard deletion.
 
-**Always read the full memory before `update`.** Recall results are clipped previews (the trailing `…` marks a truncation and `full_length` reports the original size); `update` replaces content wholesale, so overwriting the preview would delete the unseen tail. Fetch the row first with `read memory://<id>`, then pass the merged content in `content`.
+MUST read full memory before `update`. Recall previews clipped: trailing `…` marks truncation; `full_length` original size. `update` replaces content wholesale → updating a preview deletes its unseen tail. First `read memory://<id>`; pass merged content in `content`.

package/src/prompts/tools/recall.md

@@ -1,7 +1,7 @@
-Search long-term memory for relevant information. Returns raw matching entries ranked by relevance.
+Search long-term memory; return raw relevance-ranked matching entries.
 
-Use proactively — before answering questions about past conversations, user preferences, project decisions, or any topic where prior context would help accuracy. When in doubt, recall first.
+Use proactively before questions about past conversations, user preferences, project decisions, or topics where prior context improves accuracy. When in doubt, recall first.
 
-Prefer `recall` when you need specific facts or entries. Use `reflect` instead when you need a synthesized answer across many memories.
+`recall`: specific facts or entries. `reflect`: synthesized answer across many memories.
 
-Content in each result is a preview. A trailing `…` marks a truncation (`truncated: true`, `full_length` gives the original size). Fetch the full row with `read memory://<id>` — required before any `memory_edit update`.
+Results: content preview. Trailing `…`: truncation (`truncated: true`; `full_length`: original size). Before any `memory_edit update`, MUST fetch full row: `read memory://<id>`.

package/src/prompts/tools/reflect.md

@@ -1,5 +1,5 @@
-Generate a synthesized answer by reasoning over long-term memory. Unlike `recall`, `reflect` blends relevant memories into a coherent response.
+`reflect`: synthesizes a coherent response from relevant long-term memories; unlike `recall`, blends them.
 
 Use for open-ended questions spanning many stored facts: "What do you know about this user?", "Summarize project decisions.", "What are my preferences for X?"
 
-Optional `context` parameter focuses the synthesis on a specific angle or sub-topic.
+`context` optional; focuses synthesis on a specific angle or sub-topic.

package/src/prompts/tools/replace.md

@@ -1,30 +1,32 @@
-Performs a single string replacement in a file with fuzzy whitespace matching.
+Single file string replacement; fuzzy whitespace matching.
 
 <instruction>
-- You MUST use the smallest `old_string` that uniquely identifies the change
-- If `old_string` is not unique, you MUST expand it with more context or use `replace_all: true` to replace all occurrences
-- Use `replace_all: true` when renaming a string across the file
-- You SHOULD prefer editing existing files over creating new ones
+- MUST use smallest `old_string` uniquely identifying change.
+- Nonunique `old_string` → MUST add context or use `replace_all: true` for all occurrences.
+- Rename a string across file → use `replace_all: true`.
+- SHOULD edit existing files, not create new.
 </instruction>
 
 <output>
-Returns success/failure status. On success, file modified in place with replacement applied. On failure (e.g., `old_string` not found or matches multiple locations without `replace_all: true`), returns error describing issue.
+Success/failure status.
+Success: file modified in place; replacement applied.
+Failure — e.g., `old_string` absent or multiple matches without `replace_all: true`: error describes issue.
 </output>
 
 <critical>
-- You MUST read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
+- MUST read file at least once in conversation before editing. Tool errors on edit before read.
 </critical>
 
 <bash-alternatives>
-Replace is content-addressed — you identify *what* to change by its text.
+Replace content-addressed — identify change by text.
 
-For pattern-addressed bulk changes, bash is more efficient:
+Pattern-addressed bulk changes: bash more efficient:
 
 |Operation|Command|
 |---|---|
 |Regex replace|`sd 'pattern' 'replacement' file`|
 |Bulk replace across files|`sd 'pattern' 'replacement' **/*.ts`|
 
-Use Replace when _content itself_ identifies location; use `ast_edit` for structure-aware codemods.
-For in-place edits prefer this tool or `write` — you get a diff preview and fuzzy matching.
+Use Replace when content identifies location; `ast_edit` for structure-aware codemods.
+For in-place edits prefer Replace or `write` — diff preview and fuzzy matching.
 </bash-alternatives>

package/src/prompts/tools/retain.md

@@ -1,6 +1,5 @@
-Store one or more facts in long-term memory for future sessions.
+Store ≥1 fact in long-term memory for future sessions.
 
-Use for durable, reusable knowledge: user preferences, project decisions, architectural choices, anything that improves future responses.
-Ephemeral task state does not belong here.
+Use: durable, reusable knowledge—user preferences, project decisions, architectural choices; anything improving future responses. No ephemeral task state.
 
-Each item MUST be specific and self-contained — include who, what, when, and why. Batch related facts in a single call; they are deduplicated and consolidated.
+Each item MUST be specific, self-contained: who, what, when, why. Batch related facts per call; deduplicated and consolidated.

package/src/prompts/tools/rewind.md

@@ -1,14 +1,13 @@
-End an active checkpoint. Rewind context to it, replacing intermediate exploration with your report.
+End active checkpoint; rewind context to it, replacing intermediate exploration with your report.
 
-Call immediately after `checkpoint`-started investigative work.
+Call immediately after investigative work started by `checkpoint`.
 
 Requirements:
-- `report` MUST be concise, factual, and actionable.
-- Include key findings, decisions, and any unresolved risks.
+- `report` MUST be concise, factual, actionable; include key findings, decisions, unresolved risks.
 - AVOID raw scratch logs unless essential.
-- You MUST call this before yielding if a checkpoint is active.
+- MUST call before yielding if checkpoint active.
 
 Behavior:
-- 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.
+- No active checkpoint → error. Checkpoint already rewound → continue from retained report; NEVER retry.
+- Success → session rewinds, retains your report as context, closes checkpoint.
+- Successful rewind final for that checkpoint; repeat calls error.

package/src/prompts/tools/rewrite.md

@@ -0,0 +1,12 @@
+Submit compressed source draft + every drop.
+
+- `text`: complete, verbatim, ready-to-ship compressed output; NEVER diff, summary, or edit description.
+- `losses`: one entry per omitted claim, qualifier, default, bound, example, or exact string; quote/name it and why omission remains correct. Empty array: no losses.
+
+Each call: review turn → reply with draft, measured size, declared losses; ask verdict. `rewrite` replaces draft; `approve` accepts.
+
+<critical>
+- Declare losses honestly: declared losses auditable; undeclared loss: silent regression.
+- `text` MUST stand alone: reader without source can execute it.
+- New draft supersedes earlier approval.
+</critical>

package/src/prompts/tools/security-publish.md

@@ -1 +1,5 @@
-Publish the canonical result of the current OMP-native security scan. Call this exactly once after every in-scope file and candidate has a final disposition. Supply only evidence grounded in repository files inspected during this scan. This tool validates, fingerprints, assigns OMP-owned IDs, writes the canonical security store, and creates SARIF. Do not invent IDs or edit the store directly.
+Publish current OMP-native security scan's canonical result.
+Call exactly once after every in-scope file and candidate reaches final disposition.
+Evidence: only repository files inspected during this scan.
+Tool: validates, fingerprints, assigns OMP-owned IDs, writes canonical security store, creates SARIF.
+NEVER invent IDs or edit store directly.

package/src/prompts/tools/security-scan.md

@@ -1 +1,10 @@
-Plan, start, inspect, cancel, and validate OMP-native repository security scans. `preflight` creates an immutable plan pinned to the repository snapshot, model, and exact OAuth credential. `start` runs the plan as a background OMP job. `status` and `cancel` use the returned operation ID. `cloud_scans` lists Codex Security cloud configurations for the exact selected ChatGPT OAuth account. `cloud_start` creates and enables a cloud scan configuration using `repository_id`, `repository_url`, and `environment_id`; this consumes the account's separate Codex Security cloud allowance and is never a fallback from a native scan. `cloud_status` reads cloud progress. `cloud_pull` imports cloud findings into the canonical OMP security store, where they are available through `security://`. Cloud actions use `cloud_configuration_id` and may use `credential_id` to pin an account. Security must be enabled in settings.
+OMP-native repository security scans: plan, start, inspect, cancel, validate.
+`preflight`: immutable plan pinned to repository snapshot, model, exact OAuth credential.
+`start`: plan → background OMP job.
+`status`, `cancel`: returned operation ID.
+`cloud_scans`: Codex Security cloud configurations for exact selected ChatGPT OAuth account.
+`cloud_start`: creates/enables configuration using `repository_id`, `repository_url`, `environment_id`; consumes account's separate Codex Security cloud allowance; NEVER native-scan fallback.
+`cloud_status`: cloud progress.
+`cloud_pull`: cloud findings → canonical OMP security store, available through `security://`.
+Cloud actions: `cloud_configuration_id` required; `credential_id` MAY pin account.
+Security MUST be enabled in settings.

package/src/prompts/tools/task-async-contract.md

@@ -1 +1,7 @@
-No polling is needed. Inspecting a settled job with `hub jobs` or `hub wait` makes that snapshot its delivery, so no duplicate `async-result` follows. Job IDs live in process memory for roughly five minutes after settlement; afterward, use the agent ID with `hub send`, `agent://<id>`, or `history://<id>`. `completed` means the subagent yielded successfully, not that claimed artifacts were verified.
+No polling needed.
+
+Settled-job inspection: `hub jobs` | `hub wait` delivers its snapshot → no duplicate `async-result`.
+
+Job IDs: process memory ~5min after settlement; afterward use agent ID: `hub send`, `agent://<id>`, `history://<id>`.
+
+`completed`: subagent yielded successfully; claimed artifacts unverified.

package/src/prompts/tools/todo.md

@@ -1,42 +1,44 @@
-**Tasks referenced by verbatim content string, NEVER an auto-generated ID — no "task-1"/"task-N" exists. Pass the content text in the `task` field.**
+**Tasks: verbatim content strings, NEVER auto-generated IDs; no "task-1"/"task-N". Pass content in `task`.**
 
-On each completion the earliest still-open task (in phase order) auto-promotes to `in_progress`.
-Completing tasks out of phase order can move this pointer **back** to an earlier phase — expected; completed tasks are never reverted.
+Each completion: earliest still-open task (phase order) auto-promotes to `in_progress`. Out-of-order completion may move pointer back to an earlier phase—expected; completed tasks NEVER revert.
 
 ## Operations
 
-|`op`|Required fields|Effect|
+|`op`|Fields|Effect|
 |---|---|---|
-|`init`|`list: [{phase, items: string[]}]`|Initialize full list (replaces existing)|
+|`init`|`list: [{phase, items: string[]}]`|Initialize full list; replaces existing|
 |`init`|`items: string[]`|Flattened single-phase init|
 |`start`|`task`|Mark in progress|
 |`done`|`task` or `phase`|Mark completed|
 |`drop`|`task` or `phase`|Mark abandoned|
-|`block`|`task` or `phase`, optional `reason`|Mark **blocked** — open but waiting on external input; excluded from the stop-time incomplete-todo reminder|
-|`unblock`|`task` or `phase`|Return a blocked task to `pending`|
-|`rm`|`task` or `phase` (optional)|Remove task or phase; omit both to clear|
-|`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
-|`view`|—|Read-only: echo list|
+|`block`|`task` or `phase`; optional `reason`|Mark blocked: open, awaiting external input; excluded from stop-time incomplete-todo reminder|
+|`unblock`|`task` or `phase`|Blocked task → `pending`|
+|`rm`|optional `task` or `phase`|Remove task/phase; omit both → clear|
+|`append`|`phase`; `items: string[]`|Append tasks to phase; lazily creates phase|
+|`view`|—|Read-only; echo list|
 
 ## Anatomy
-- **Task content**: 5–10 words; what, not how. Unique identifier.
-- **Phase name**: short noun phrase (e.g. `Foundation`, `Auth`, `Verification`). Unique identifier. NEVER prefix `1.`, `A)`, `Phase 1:`.
+
+- Task content: 5–10 words; what, not how; unique identifier.
+- Phase name: short noun phrase (e.g. `Foundation`, `Auth`, `Verification`); unique identifier. NEVER prefix `1.`, `A)`, `Phase 1:`.
 
 ## Rules
-- Mark tasks done immediately after finishing. Complete phases in order.
-- NEVER make a todo call your turn's only tool call — batch it with the real work: `init` with the first reads/edits, each `done`/`start` with the next action. Solo todo turns waste a round trip.
-- Waiting on something you can't act on (a user decision, another agent, an external service)? `block` the task (optional `reason`) — it stays in the tracker but won't trip the stop reminder; `unblock` when it's actionable again. If the blocker is itself agent-actionable, `append` an unblocking task instead.
-- Keep `task`/`phase` strings stable once introduced.
-- Lost the exact task text? `view` echoes the list — NEVER guess from memory.
-
-## When to create a list
-- Task requires 3+ distinct steps
-- User explicitly requests one
-- User provides a set of tasks
-- New instructions arrive mid-task — capture before proceeding
+
+- Mark tasks done immediately after finishing; complete phases in order.
+- NEVER make a todo call the turn's only tool call. Batch with real work: `init` with first reads/edits; each `done`/`start` with next action. Solo todo turns waste a round trip.
+- Waiting on something you can't act on—a user decision, another agent, external service: `block` task (optional `reason`); remains tracked but avoids stop reminder. `unblock` when actionable. If blocker agent-actionable, `append` an unblocking task instead.
+- Keep introduced `task`/`phase` strings stable.
+- Lost exact task text: `view` echoes list; NEVER guess from memory.
+
+## Create a list
+
+- Task requires 3+ distinct steps.
+- User explicitly requests one.
+- User provides a set of tasks.
+- New instructions arrive mid-task: capture before proceeding.
 
 <critical>
-User hands you a multi-step plan — phased todo, numbered/bulleted checklist, or "N bugs/items/tasks":
-- You MUST `init` the list with EVERY item as its own task before working.
+User gives multi-step plan—phased todo, numbered/bulleted checklist, or "N bugs/items/tasks":
+- MUST `init` every item as its own task before working.
 - Enumerate all; NEVER summarize into fewer tasks, sample "the important ones", drop items, or track the rest from memory.
 </critical>

package/src/prompts/tools/vibe-kill.md

@@ -1,3 +1,3 @@
-Terminates a worker session: aborts its in-flight turn (if any) and discards the session. Its conversation cannot be continued afterwards — the transcript stays readable at `history://<id>`.
+Terminates worker session: aborts in-flight turn, if any; discards session. Conversation cannot continue; transcript remains readable at `history://<id>`.
 
-Kill sessions that are stuck, looping, or whose workstream is complete. Freeing dead weight keeps the roster legible.
+Kill stuck, looping, or completed-workstream sessions. Free dead weight → legible roster.

package/src/prompts/tools/vibe-list.md

@@ -1,3 +1,3 @@
-Shows your worker-session roster: id, CLI flavor (`fast`/`good`), state (`starting`/`running`/`idle`/`dead`), model, turn count, queued messages, and a one-line gist of each session's latest activity.
+Worker-session roster: id, CLI flavor (`fast`/`good`), state (`starting`/`running`/`idle`/`dead`), model, turn count, queued messages, one-line gist of latest activity.
 
-Use it to reorient: which sessions exist, who is busy, who is idle and ready for the next instruction.
+Use to reorient: existing sessions, busy workers, idle workers ready for next instruction.

package/src/prompts/tools/vibe-send.md

@@ -1,9 +1,8 @@
-Sends a message to one of your worker sessions (by id from `vibe_spawn` / `vibe_list`). The session keeps its full conversation history — refer to earlier work naturally ("now do the same for the other module").
+Send a worker session message by id from `vibe_spawn`/`vibe_list`. Session retains full conversation history; refer naturally ("now do the same for the other module").
 
-Returns immediately with an ack telling you how the message landed:
+Returns immediately with an ack:
+- `turn`: worker idle → new turn; result self-delivers when done.
+- `steered`: worker mid-turn → message injected into the running turn as live steering.
+- `queued`: worker mid-turn and not currently steerable → message runs automatically as next turn.
 
-- `turn` — the worker was idle; a new turn started. Its result self-delivers when done.
-- `steered` — the worker was mid-turn; your message was injected into the running turn as live steering.
-- `queued` — the worker was mid-turn and not steerable right now; your message runs as the next turn automatically.
-
-Use it for follow-ups, corrections, scope changes, and review requests. Never re-explain prior context — the session already has it.
+Use for follow-ups, corrections, scope changes, review requests. NEVER re-explain prior context; session already has it.

package/src/prompts/tools/vibe-spawn.md

@@ -1,10 +1,12 @@
-Starts a persistent worker session — a full coding agent (edit, bash, grep, everything) that you drive by conversation. Pick the CLI flavor per task:
+Starts persistent conversational coding-agent worker session (edit, bash, grep, everything).
 
-- `fast`: low-latency model for mechanical, well-specified work (renames, boilerplate, running tests, data collection).
-- `good`: strong model for hard work (design, debugging, multi-file changes, judgment calls).
+CLI flavor by task:
+- `fast`: low-latency model; mechanical, well-specified work (renames, boilerplate, running tests, data collection).
+- `good`: strong model; hard work (design, debugging, multi-file changes, judgment calls).
 
-`prompt` is the session's first instruction. The worker starts with NO context beyond it — include files, constraints, and acceptance criteria. `name` (optional) labels the session; otherwise one is generated.
+`prompt`: first session instruction. Worker starts with NO context beyond it; include files, constraints, acceptance criteria.
+`name`: optional session label; otherwise generated.
 
-Returns immediately with the session id; the turn's result (activity trace + the worker's response) is delivered to you automatically when the worker finishes. Do not wait unless you are blocked — keep directing other sessions.
+Returns session id immediately. On worker completion, turn result—activity trace + worker response—delivered automatically. Do not wait unless blocked; direct other sessions.
 
-The session persists after the turn: it remembers the whole conversation. Continue it with `vibe_send`; never spawn a second session for a follow-up on the same workstream.
+Session persists after turn; remembers whole conversation. Same-workstream follow-up: `vibe_send`; NEVER spawn second session.

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

@@ -1,8 +1,8 @@
-Searches the web for up-to-date information beyond knowledge cutoff.
+Web search: current 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.
+- SHOULD prefer primary sources (papers, official docs); corroborate key claims with multiple sources.
+- MUST link cited sources in final response.
+- NEVER use for programmatically accessible content or known URLs (GitHub repos/issues, known arXiv papers, Wikipedia pages, official docs) — `read` URL directly.
+- `query`: every provider supports Google-style `site:`/`-site:`, `after:`/`before:` (`YYYY-MM-DD`), `inurl:`, `intitle:`, `filetype:`, `"exact phrase"`, `-term`, `OR`. Map constraints to native filters when available; otherwise filter results leniently. If a constraint matches nothing, relax and report it; do not return zero results.
 </instruction>

package/src/sdk.ts

@@ -201,6 +201,7 @@ import {
 	ReadTool,
 	releaseComputerSessionsForOwner,
 	resolveMountedXdevExecutable,
+	supportsExternalThinking,
 	type Tool,
 	type ToolSession,
 	WebSearchTool,
@@ -3237,7 +3238,14 @@ async function createAgentSessionScoped(options: CreateAgentSessionOptions): Pro
 						});
 					}
 				}
-				return settingsAwareStreamFn(streamModel, context, streamOptions);
+				const externalThinking =
+					settings.get("externalThinking") &&
+					agent.state.tools.some(tool => tool.name === "think") &&
+					supportsExternalThinking(streamModel);
+				return settingsAwareStreamFn(streamModel, context, {
+					...streamOptions,
+					forceReasoningOff: externalThinking || streamOptions?.forceReasoningOff,
+				});
 			},
 			cursorExecHandlers,
 			getCursorTools: () => (toolSession.xdev ? listXdevTools(toolSession.xdev) : []),
@@ -3393,6 +3401,7 @@ async function createAgentSessionScoped(options: CreateAgentSessionOptions): Pro
 			createComputerTool: restrictToolNames
 				? undefined
 				: async () => (await BUILTIN_TOOLS.computer(toolSession)) ?? null,
+			createThinkTool: async () => (await HIDDEN_TOOLS.think(toolSession)) ?? null,
 			createInspectImageTool: restrictToolNames
 				? undefined
 				: async () => (await BUILTIN_TOOLS.inspect_image(toolSession)) ?? null,

package/src/session/agent-session-types.ts

@@ -164,6 +164,8 @@ export interface AgentSessionConfig {
 	createMemoryTools?: () => Promise<AgentTool[]>;
 	/** Creates the built-in `computer` tool for session-scoped runtime enablement (see {@link AgentSession.setComputerToolEnabled}). */
 	createComputerTool?: () => Promise<AgentTool | null>;
+	/** Creates the private `think` scratchpad tool for runtime setting changes. */
+	createThinkTool?: () => Promise<AgentTool | null>;
 	/** Creates the built-in `inspect_image` tool for session-scoped runtime enablement (see {@link AgentSession.setInspectImageMode}). */
 	createInspectImageTool?: () => Promise<AgentTool | null>;
 	/** Model registry for API key resolution and model discovery. */

package/src/session/agent-session.ts

@@ -199,6 +199,7 @@ import {
 	PROPOSE_DEVICE_NAME,
 	writeDeviceDispatch,
 } from "../tools/resolve";
+import { supportsExternalThinking } from "../tools/think";
 import type { TodoPhase } from "../tools/todo";
 import { ToolError } from "../tools/tool-errors";
 import { parseCommandArgs } from "../utils/command-args";
@@ -1241,6 +1242,7 @@ export class AgentSession {
 			toolRegistry: config.toolRegistry,
 			createVibeTools: config.createVibeTools,
 			createComputerTool: config.createComputerTool,
+			createThinkTool: config.createThinkTool,
 			createInspectImageTool: config.createInspectImageTool,
 			builtInToolNames: config.builtInToolNames,
 			mcpManagerToolNames: config.mcpManagerToolNames,
@@ -4419,6 +4421,11 @@ export class AgentSession {
 		return this.#tools.setComputerToolEnabled(enabled);
 	}
 
+	/** Applies the external-thinking setting to the private scratchpad tool immediately. */
+	setThinkToolEnabled(enabled: boolean): Promise<boolean> {
+		return this.#tools.setThinkToolEnabled(enabled);
+	}
+
 	/**
 	 * Session-scoped inspect_image mode (`/vision`). `auto` clears the override
 	 * and returns to the persisted `inspect_image.mode` setting; `on`/`off`
@@ -5176,6 +5183,15 @@ export class AgentSession {
 
 		// Skip eager preludes when the user has already queued a directive
 		const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
+		const activeModel = this.agent.state.model;
+		const externalThinkingToolChoice =
+			!options?.synthetic &&
+			!hasPendingUserDirective &&
+			this.settings.get("externalThinking") &&
+			this.getEnabledToolNames().includes("think") &&
+			supportsExternalThinking(activeModel)
+				? buildNamedToolChoice("think", activeModel)
+				: undefined;
 		const eagerTodoPrelude =
 			!options?.synthetic && !hasPendingUserDirective ? this.#todo.createEagerTodoPrelude(expandedText) : undefined;
 		const eagerTaskPrelude =
@@ -5193,6 +5209,12 @@ export class AgentSession {
 			: undefined;
 
 		const promptAttribution = options?.attribution ?? (options?.synthetic ? "agent" : "user");
+		if (externalThinkingToolChoice) {
+			this.#toolChoiceQueue.pushOnce(externalThinkingToolChoice, {
+				label: "external-thinking",
+				now: true,
+			});
+		}
 		const message = options?.synthetic
 			? { role: "developer" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() }
 			: { role: "user" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() };
@@ -5223,6 +5245,7 @@ export class AgentSession {
 			// Clean up residual eager-todo directive if the prompt never consumed it
 			// (e.g., compaction aborted, validation failed).
 			this.#toolChoiceQueue.removeByLabel("eager-todo");
+			this.#toolChoiceQueue.removeByLabel("external-thinking");
 		}
 		return true;
 	}
@@ -7043,6 +7066,11 @@ export class AgentSession {
 		} catch (error) {
 			logger.warn("inspect_image reconcile after model change failed", { error: String(error) });
 		}
+		try {
+			await this.#tools.reconcileThinkTool();
+		} catch (error) {
+			logger.warn("think tool reconcile after model change failed", { error: String(error) });
+		}
 	}
 
 	#closeCodexProviderSessionsForHistoryRewrite(): void {

package/src/session/session-handoff.ts

@@ -14,6 +14,7 @@ import { logger, Snowflake } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../config/model-registry";
 import type { Settings } from "../config/settings";
 import type { ExtensionRunner, SessionBeforeSwitchResult } from "../extensibility/extensions";
+import { copyLocalArtifacts, resolveLocalUrlToPath } from "../internal-urls";
 import { obfuscateProviderContext } from "../secrets/message-transform";
 import type { SecretObfuscator } from "../secrets/obfuscator";
 import type { HandoffResult, SessionHandoffOptions } from "./agent-session-types";
@@ -255,6 +256,15 @@ export class SessionHandoff {
 			// Stop and settle in-flight advisors while the old-session feeds can still
 			// observe message_end, then mute before opening the replacement session.
 			await this.#host.drainAndDetachAdvisorRecorders();
+			// Snapshot the outgoing session's local:// root BEFORE newSession() mints a
+			// fresh session id (and therefore a fresh, empty local root). The handoff
+			// document routinely references plans/scratch files under local://, so those
+			// artifacts must follow the session switch or every reference dangles.
+			const localProtocolOptions = {
+				getArtifactsDir: () => this.#host.sessionManager.getArtifactsDir(),
+				getSessionId: () => this.#host.sessionManager.getSessionId(),
+			};
+			const previousLocalRoot = resolveLocalUrlToPath("local://", localProtocolOptions);
 			const bashTransition = this.#host.beginBashSessionTransition();
 			this.#host.cancelOwnAsyncJobs();
 			try {
@@ -292,6 +302,17 @@ export class SessionHandoff {
 			this.#host.clearPendingNextTurnMessages();
 			this.#host.resetTodoCycle();
 
+			// Carry local:// artifacts into the replacement session (best-effort: the
+			// switch is already committed, so a copy failure must not fail the handoff).
+			try {
+				const newLocalRoot = resolveLocalUrlToPath("local://", localProtocolOptions);
+				await copyLocalArtifacts(previousLocalRoot, newLocalRoot);
+			} catch (error) {
+				logger.warn("Failed to copy local artifacts into handoff session", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+
 			// Inject the handoff document as a custom message
 			const handoffContent = createHandoffContext(handoffText);
 			this.#host.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");