@oh-my-pi/pi-coding-agent 14.2.1 → 14.3.0

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

@@ -1,13 +1,14 @@
-Edits files via syntax-aware chunks. Run `read(path="file.ts")` first.
+Edits files via syntax-aware chunks. Use `read(path="file.ts")` to read and discover chunks before editing.
+- `read` is the canonical read path for chunk source and `sel="?"` tree listings.
 - `write` rewrites the entire targeted region — best for most edits.
-- `replace` does surgical find-and-replace within a chunk — use when making small changes to a large chunk, or batching multiple substitutions.
 - `insert` adds content before/after a chunk.
+- `delete` deletes a targeted chunk and must be explicit.
 
 Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
 
 <rules>
-- **MUST** `read` first. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
-- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#ABCD~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `put`/`find`+`replace`/`delete`.
+- **MUST** inspect first with `read`. Never invent chunk paths or IDs. Copy them from the latest `read` output or edit response.
+- `path` format: `file:selector` — e.g. `src/app.ts:fn_foo#ABCD~`. Append `~` for body, `^` for head, or nothing for the whole chunk. Include `#ID` for `write`/`delete`.
 - If the exact chunk path is unclear, run `read(path="file", sel="?")` and copy a selector from that listing.
 {{#if chunkAutoIndent}}
 - Use `\t` for indentation in `content`. Write content at indent-level 0 — the tool re-indents it to match the chunk's position in the file. For example, to replace `~` of a method, write the body starting at column 0:
@@ -16,6 +17,8 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   ```
   The tool adds the correct base indent automatically. Never manually pad with the chunk's own indentation.
   Multiple sibling body lines at the same level all start at column 0: `"print(a)\nprint(b)\nprint(c)\n"`. Only use `\t` when nesting deeper (e.g. `"if cond:\n\tinner\nouter\n"`).
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0 and use one `\t` per relative nesting level.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
   **Common mistake** when replacing `~` of a function body: do NOT include the function's own indentation.
   Wrong: `"if b == 0:\n\t\treturn None\n\treturn a / b\n"` — adds the function's base `\t` to every line.
   Correct: `"if b == 0:\n\treturn None\nreturn a / b\n"` — `if` and `return a / b` at column 0, only `return None` gets `\t` for nesting.
@@ -26,10 +29,15 @@ Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
   content: "if (x) {\n  return true;\n}"
   ```
   The tool adds the correct base indent automatically, then preserves the tabs/spaces you used inside the snippet. Never manually pad with the chunk's own indentation.
+  Before applying the target's base indent, the tool strips any common leading whitespace shared by all non-empty `write` lines as a safety net. Do not rely on that cleanup for mixed indentation; write `~` bodies at column 0.
+  Multi-line replacements use the same relative-indentation model: the replacement text is dedented, then re-indented to the matched source line. Do not include the chunk's base indentation in replacement text.
 {{/if}}
-- Region suffixes only apply to container chunks (classes, functions, impl blocks, sections). On leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` silently fall back to whole-chunk replacement — prefer the unsuffixed form and always supply the complete replacement (condition + body, not just the body) to avoid dropping structural parts.
-- `put`, `find`+`replace`, and `delete` require the current ID. `prepend`/`append` do not.
+- Region suffixes only apply to chunks with a real head/body boundary (classes, functions, impl blocks, and similar containers). On code leaf chunks (enum variants, fields, single statements, and compound statements like `if`/`for`/`while`/`match`/`try`), `~` and `^` are rejected. Use the unsuffixed selector and supply the complete replacement content, or edit the parent container's `~` body.
+- Unsuffixed `write` on a leaf chunk uses your content verbatim after normal replacement; it is not a body-region rewrite. Include the exact indentation and punctuation the leaf needs in the file.
+- `^` head writes and `~` body writes use the same base-indent model: write content at column 0 relative to the target region, and the tool applies the chunk's file indentation.
+- `write` and `delete` require the current ID. `prepend`/`append` do not.
 - **IDs change after every edit.** The edit response always carries the new IDs — use those for the next call or run `read(path="file", sel="?")` to refresh. Never reuse an ID from before the latest edit.
+- Same-file edit batches are transactional: if any operation in that file fails, no changes from that file's batch are saved. Multi-file edit calls run per file, so a later file error does not roll back earlier files that already succeeded.
 </rules>
 
 <critical>
@@ -42,24 +50,25 @@ You **MUST** use the narrowest region that covers your change. Putting without a
 
 <regions>
 In `read` output, lines marked `^` between the line number and `|` are **head** lines (doc comments, attributes/decorators, signature). Lines without `^` are **body** lines. Use this to decide which region to target:
-- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On leaf chunks, falls back to whole chunk.
+- `fn_foo#ID~` — **body only (the default choice for most edits).** Head lines (`^`) are preserved automatically — doc comments, attributes, and signature stay untouched. On code leaf chunks, this is rejected because there is no safe body boundary.
 - `fn_foo#ID^` — head only (decorators, attributes, doc comments, signature, opening delimiter). Body stays untouched.
 - `fn_foo#ID` — entire chunk including leading trivia. **You must include doc comments and attributes in `content`; omitting them deletes them.**
-- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*.
+- `chunk~` + `append`/`prepend` inserts *inside* the container. `chunk` + `append`/`prepend` inserts *outside*. Appending to a container without `~` emits a warning because it lands after the closing delimiter, not before it.
 
-**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. If you need to rewrite a decorator, check the `?` listing for a sibling `chunk#ID` directly above your target.
+**Note on leading trivia:** whether a decorator/doc comment belongs to `^` depends on the parser. In Rust and Python, attributes and decorators are attached to the function chunk, so `^` covers them. In TypeScript/JavaScript, a `@decorator` + `/** jsdoc */` block immediately above a method often surfaces as a **separate sibling chunk** (shown as `chunk#ID` in the `?` listing) rather than as part of the function's `^`. JSDoc directly above a plain function is more likely to be absorbed into that function's `^`. If you need to rewrite a decorated member, run `read(path="file", sel="?")` and check for a sibling `chunk#ID` directly above your target.
 
-**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, fenced code blocks, frontmatter), `^` and `~` fall back to the whole chunk. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), always use unsuffixed whole-chunk replace — `^` and `~` on section containers also fall back to whole-chunk replace. When editing fenced code blocks in markdown, use the exact whitespace from the file (read with `raw` first) — the tool preserves literal indentation inside fenced blocks, but any content you supply is written verbatim. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
+**Python notes:** Python docstrings are body lines, not head lines. A `~` body write on a function that has a docstring deletes the docstring unless you include the docstring in `content`. Python enum members and nested functions/closures are often opaque inside their parent chunk and may not appear as addressable child chunks; rewrite the parent container body. Python decorated class/function `^` writes and Python `^` deletes are rejected because indentation-sensitive bodies can become attached to the wrong block while still parsing.
+
+**Note on non-code formats:** for prose and data formats (markdown, YAML, JSON, frontmatter), unsupported `^` and `~` suffixes warn and fall back to whole-chunk editing. Always replace the entire chunk and include any delimiter syntax (fence backticks, `---` frontmatter markers, list markers, table rows, headings) in your `content` — omitting them deletes them. For markdown sections (`sect_*`), prefer unsuffixed whole-chunk replace because `^`/`~` on prose sections can replace the heading and child content too; if you only need the heading, target the heading child chunk shown in `sel="?"`. Fenced code blocks with a declared language are parsed again and can expose inner chunks such as `code_py#ID.fn_gre#ID`; target those inner chunks when available. Markdown root writes preserve fenced code indentation verbatim. Recognized pipe tables expose `row_N` children for row-level edits; table cells and list items are not independently addressable, so rewrite the whole list/table chunk for those structural changes. Appending a table-row-shaped string (`| value |`) to a table chunk inserts it before the trailing blank-line separator so it remains part of the table. Otherwise read with `raw` first and preserve the exact whitespace inside fences. To insert content after a markdown section heading, use `after` on the heading chunk (`sect_*.chunk` or `sect_*.chunk_1`) — not `before`/`prepend` on the section itself, which lands physically before the heading and gets absorbed by the preceding section on reparse.
 </regions>
 
 <ops>
-Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `replace`, or `insert`. Never set more than one on the same entry.
+Each edit entry has `path` (`file:selector`) plus **exactly one** operation field — `write`, `insert`, or `delete`. Never set more than one on the same entry. `write:null`, `write:""`, and bare `{path}` entries are rejected; they do not delete.
 
 |fields|path (selector part)|effect|
 |---|---|---|
 |`write: "content"`|`file:chunk#ID`, `file:chunk#ID~`, or `file:chunk#ID^`|write complete new content to the region|
-|`write: null`|`file:chunk#ID`|delete the chunk|
-|`replace: {old, new}`|`file:chunk#ID`|find a literal substring in the chunk and replace it|
+|`delete: true`|`file:chunk#ID`|delete the chunk explicitly|
 |`insert: {loc, body}`|`file:chunk` or `file:chunk~`|insert before/after the chunk (`loc`: `"prepend"` or `"append"`)|
 </ops>
 
@@ -185,12 +194,6 @@ Result — the head (all `^` lines + opening brace) changes, body untouched:
     }
 ```
 
-**Find and replace** (surgical edit within a chunk):
-```
-{ "path": "counter.rs:impl_Counte.fn_increm#MNHV", "replace": { "old": "self.value += 1;", "new": "self.value = (self.value + 1).min(self.max);" } }
-```
-Result — only the matched substring changes, everything else is preserved.
-
 **Insert before a chunk** (`prepend`):
 ```
 { "path": "counter.rs:impl_Counte.fn_get", "insert": { "loc": "prepend", "body": "/// Resets the counter to zero.\npub fn reset(&mut self) {\n\tself.value = 0;\n}\n\n" } }
@@ -258,7 +261,7 @@ Result — a new method is added at the end of the impl body, before the closing
 
 **Delete a chunk**:
 ```
-{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "write": null }
+{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "delete": true }
 ```
 Result — the method (including its doc comment and signature) is removed.
 - Indentation rules (important):
@@ -268,12 +271,12 @@ Result — the method (including its doc comment and signature) is removed.
   - Match the file's real indentation characters in your snippet. The tool preserves your literal tabs/spaces after adding the target region's base indent.
 {{/if}}
   - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
+  - For `write`, the tool strips common leading whitespace shared by all non-empty lines, then adds the target region's base indent. If lines have mixed relative indentation, write them at column 0 so the common-margin cleanup cannot change the structure.
   - For `~` of a function: write at column 0, and use `\t` for *relative* nesting. Flat body: `"return x;\n"`. Multiple sibling lines: `"print(a)\nprint(b)\nprint(c)\n"` — all at column 0, the tool adds the function's base indent. Nested body: `"if (cond) {\n\treturn x;\n}\n"` — the `if` is at column 0, the `return` is one tab in. Python example — to replace `~` of `def divide(a, b):`, write: `"if b == 0:\n\treturn None\nreturn a / b\n"` — the `if` and `return a / b` are at column 0, `return None` is one `\t` in.
-  - For `^`: write at the chunk's own depth. A class member's head uses `"/// doc\n#[attr]\npub fn start() {"`.
+  - For `^`: write at column 0 relative to the head region, just like `~`. A class member's head uses `"/// doc\n#[attr]\npub fn start() {"` — do not include the class/member base indentation.
 {{#if chunkAutoIndent}}
   - For a top-level item: start at zero indent. Write `"fn foo() {\n\treturn 1;\n}\n"`.
 {{else}}
   - For a top-level item: start at zero indent. Write `"fn foo() {\n  return 1;\n}\n"`.
 {{/if}}
-  - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
 </examples>

package/src/prompts/tools/gh-pr-push.md

@@ -2,7 +2,8 @@ Pushes a checked-out pull request branch back to its source branch through local
 
 <instruction>
 - Defaults to the current checked-out git branch
-- Uses branch metadata recorded by `gh_pr_checkout` to push back to the contributor fork and PR head branch
+- Requires branch metadata recorded by `gh_pr_checkout`; fail instead of pushing if the branch was not checked out with `gh_pr_checkout`
+- Pushes back to the contributor fork and PR head branch recorded in that metadata
 - Use `forceWithLease` only when rewriting the branch intentionally
 </instruction>
 

package/src/prompts/tools/grep.md

@@ -21,7 +21,8 @@ Searches files using powerful regex matching.
 </output>
 
 <critical>
-- You **MUST** use Grep when searching for content.
-- You **MUST NOT** invoke `grep` or `rg` via Bash.
-- If the search is open-ended, requiring multiple rounds, you **MUST** use Task tool with explore subagent instead.
+- You **MUST** use the built-in Grep tool for any content search. Do **NOT** shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- Bash `grep`/`rg` returns raw text without chunk paths, loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The Grep tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
+- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the search through the Grep tool instead.
+- If the search is open-ended, requiring multiple rounds, you **MUST** use the Task tool with the explore subagent instead of chaining Grep calls yourself.
 </critical>

package/src/prompts/tools/lsp.md

@@ -31,3 +31,9 @@ Interacts with Language Server Protocol servers for code intelligence.
 - Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
 - When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `occurrence` values return an explicit error instead of silently falling back
 </caution>
+
+<critical>
+- You **MUST** use `lsp` for symbol-aware operations (rename, find references, go to definition/implementation, code actions) whenever a language server is available — it is safer and more accurate than text-based alternatives.
+- You **MUST NOT** perform cross-file renames with `ast_edit`, `sed`, `rsed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
+- Prefer `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
+</critical>

package/src/prompts/tools/read-chunk.md

@@ -1,23 +1,54 @@
-Reads files using syntax-aware chunks.
+Reads files using syntax-aware chunks. Also inspects directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
 
 <instruction>
-- `path` — file path or URL; may include `:selector` suffix
-- `sel` — optional selector: `class_Foo`, `class_Foo.fn_bar#ABCD~`, `?`, `L50`, `L50-L120`, or `raw`
+The chunk-aware `read` variant returns AST-scoped chunks with current checksum IDs for structural editing, and otherwise behaves like `open` for non-code content.
+
+- You **MUST** parallelize calls when exploring related files
+- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You **SHOULD** reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
+
+## Parameters
+- `path` — file path or URL; may include `:selector` suffix (required)
+- `sel` — optional selector for chunks, line ranges, listing, or raw mode
 - `timeout` — seconds, for URLs only
 
+## Selectors
+
+|`sel` value|Behavior|
+|---|---|
+|*(omitted)*|Read full file as chunks (up to {{DEFAULT_LIMIT}} lines)|
+|`class_Foo`|Read a specific chunk|
+|`class_Foo.fn_bar#ABCD~`|Read a chunk region (body `~` / head `^`) by ID|
+|`?`|List all chunk paths with IDs|
+|`L50`|Read from line 50 onward (shorthand for L50 to EOF)|
+|`L50-L120`|Read lines 50 through 120|
+|`L20-L20`|Read exactly one line|
+|`raw`|Raw content without transformations (for URLs: untouched HTML)|
+
+Max {{DEFAULT_MAX_LINES}} lines per call.
+
+# Chunks
 Each anchor `@full.chunk.path#CCCC` (with `-` prefixes for nesting depth) in the output identifies a chunk. Use `full.chunk.path#CCCC` as-is to read truncated chunks.
-If you need a canonical target list, run `read(path="file", sel="?")`. That listing shows chunk paths with IDs.
+If you need a canonical target list, run `read(path="file", sel="?")`. That listing shows chunk paths with IDs and is the safest structural discovery mode. Summary lines in this listing are orientation hints; follow a selector with `read(path="file", sel="chunk#ID")` or use `raw` when you need exact source.
 Line numbers in the gutter are absolute file line numbers.
 
-`L20` (single line, no explicit end) is shorthand for `L20` to end-of-file. Use `L20-L20` for a one-line window.
-
 {{#if chunkAutoIndent}}
 Chunk reads normalize leading indentation so copied content round-trips cleanly into chunk edits.
 {{else}}
 Chunk reads preserve literal leading tabs/spaces from the file. When editing, keep the same whitespace characters you see here.
 {{/if}}
+`raw` shows the file's literal whitespace. Structured chunk views may normalize or display indentation for edit round-tripping, so use `raw` when exact tabs/spaces matter, especially inside markdown fenced code blocks.
+
+IDs change after every edit. Use the new IDs from the edit response or refresh with `sel="?"` before the next `write`/`delete`. `insert` selectors may omit IDs, but still prefer fresh paths after structural edits.
+
+Parser boundaries vary by language: TypeScript/JavaScript decorators and JSDoc above decorated methods may appear as sibling `chunk#ID` entries, Python decorators are part of the function/class head, Python docstrings are body lines, and Python enum members or nested closures may remain opaque inside their parent chunk. Decorated Python `^` writes and Python `^` deletes are rejected for safety.
+Markdown sections, lists, and tables are structural chunks. Recognized pipe tables expose `row_N` children for row-level edits; list items and table cells are not independently addressable. Fenced code blocks with a declared language are parsed again when possible, so functions inside a markdown fence can appear as addressable nested chunks.
 
 Chunk trees: JS, TS, TSX, Python, Rust, Go. Others use blank-line fallback.
+# Inspection
+Extracts text from PDF, Word, PowerPoint, Excel, RTF, EPUB, and Jupyter notebook files. Can inspect images.
+
+# Directories & Archives
+Directories and archive roots return a list of entries. Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read contents.
 
 # SQLite Databases
 When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), returns structured database content.
@@ -27,9 +58,17 @@ When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), retu
 - `file.db:table?limit=50&offset=100` — paginated rows
 - `file.db:table?where=status='active'&order=created:desc` — filtered rows
 - `file.db?q=SELECT …` — read-only SELECT query
+
+# URLs
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout. You **SHOULD** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser when the page requires JS execution, authentication, or interactive actions (clicks, forms, scrolling).
 </instruction>
 
 <critical>
-- **MUST** `read` before editing — never invent chunk names or IDs.
+- You **MUST** `read` before editing — never invent chunk names or IDs.
     - Chunk names are truncated (e.g., `handleRequest` becomes `fn_handleRequ`). Always copy chunk paths from `read` or `?` output — never construct them from source identifiers.
+- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`/`curl`/`wget`) for all file, directory, archive, and URL reads.
+- You **MUST NOT** reach for a browser/puppeteer tool to fetch static web content — `read` handles HTML, PDFs, JSON, feeds, and docs directly. Reserve browser tools for JS-heavy pages or interactive flows.
+- You **MUST** always include the `path` parameter; never call with `{}`.
+- For specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` — not `cat -n file | sed`.
+- You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.
 </critical>

package/src/prompts/tools/read.md

@@ -1,8 +1,9 @@
 Reads the content at the specified path or URL.
 
 <instruction>
-The `read` tool is multi-purpose — inspects files, directories, archives, SQLite databases, and URLs.
+The `read` tool is multi-purpose and more capable than it looks — inspects files, directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
 - You **MUST** parallelize reads when exploring related files
+- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You **SHOULD** reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
 
 ## Parameters
 - `path` — file path or URL (required)
@@ -14,8 +15,9 @@ The `read` tool is multi-purpose — inspects files, directories, archives, SQLi
 |`sel` value|Behavior|
 |---|---|
 |*(omitted)*|Read full file (up to {{DEFAULT_LIMIT}} lines)|
-|`L50`|Read from line 50 onward|
+|`L50`|Read from line 50 onward (shorthand for L50 to EOF)|
 |`L50-L120`|Read lines 50 through 120|
+|`L20-L20`|Read exactly one line|
 |`raw`|Raw content without transformations (for URLs: untouched HTML)|
 
 Max {{DEFAULT_MAX_LINES}} lines per call.
@@ -45,11 +47,12 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db?q=SELECT …` — read-only SELECT query
 
 # URLs
-Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, and similar text-based resources. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout.
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout. You **SHOULD** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser when the page requires JS execution, authentication, or interactive actions (clicks, forms, scrolling).
 </instruction>
 
 <critical>
-- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`) for all file, directory, and archive reads.
+- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`/`curl`/`wget`) for all file, directory, archive, and URL reads.
+- You **MUST NOT** reach for a browser/puppeteer tool to fetch static web content — `read` handles HTML, PDFs, JSON, feeds, and docs directly. Reserve browser tools for JS-heavy pages or interactive flows.
 - You **MUST** always include the `path` parameter; never call with `{}`.
 - For specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` — not `cat -n file | sed`.
 - You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.

package/src/sdk.ts

@@ -194,6 +194,8 @@ export interface CreateAgentSessionOptions {
 
 	/** Enable MCP server discovery from .mcp.json files. Default: true */
 	enableMCP?: boolean;
+	/** Existing MCP manager to reuse (skips discovery, propagates to toolSession). */
+	mcpManager?: MCPManager;
 
 	/** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
 	enableLsp?: boolean;
@@ -1005,10 +1007,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const builtinTools = await logger.time("createAllTools", createTools, toolSession, options.toolNames);
 
 		// Discover MCP tools from .mcp.json files
-		let mcpManager: MCPManager | undefined;
+		let mcpManager: MCPManager | undefined = options.mcpManager;
 		const enableMCP = options.enableMCP ?? true;
 		const customTools: CustomTool[] = [];
-		if (enableMCP) {
+		if (enableMCP && !mcpManager) {
 			const mcpResult = await logger.time("discoverAndLoadMCPTools", discoverAndLoadMCPTools, cwd, {
 				onConnecting: serverNames => {
 					if (options.hasUI && serverNames.length > 0) {
@@ -1024,7 +1026,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				authStorage,
 			});
 			mcpManager = mcpResult.manager;
-			toolSession.mcpManager = mcpManager;
 
 			if (settings.get("mcp.notifications")) {
 				mcpManager.setNotificationsEnabled(true);
@@ -1044,6 +1045,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
 			}
 		}
+		toolSession.mcpManager = mcpManager;
 
 		// Add Gemini image tools if GEMINI_API_KEY (or GOOGLE_API_KEY) is available
 		const geminiImageTools = await logger.time("getGeminiImageTools", getGeminiImageTools);
@@ -1663,8 +1665,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}),
 		);
 
-		// Wire MCP manager callbacks to session for reactive tool updates
-		if (mcpManager) {
+		// Wire MCP manager callbacks to session for reactive tool updates.
+		// Skip when reusing a parent's manager — the parent owns the callbacks.
+		if (mcpManager && !options.mcpManager) {
 			mcpManager.setOnToolsChanged(tools => {
 				void session.refreshMCPTools(tools);
 			});

package/src/session/agent-session.ts

@@ -1179,6 +1179,29 @@ export class AgentSession {
 		);
 	}
 
+	#scheduleAutoContinuePrompt(generation: number): void {
+		const continuePrompt = async () => {
+			await this.#promptWithMessage(
+				{
+					role: "developer",
+					content: [{ type: "text", text: "Continue if you have next steps." }],
+					attribution: "agent",
+					timestamp: Date.now(),
+				},
+				"Continue if you have next steps.",
+				{ skipPostPromptRecoveryWait: true },
+			);
+		};
+		this.#schedulePostPromptTask(
+			async signal => {
+				await Promise.resolve();
+				if (signal.aborted) return;
+				await continuePrompt();
+			},
+			{ generation },
+		);
+	}
+
 	#cancelPostPromptTasks(): void {
 		this.#postPromptTasksAbortController.abort();
 		this.#postPromptTasksAbortController = new AbortController();
@@ -4813,6 +4836,9 @@ export class AgentSession {
 						aborted: false,
 						willRetry: false,
 					});
+					if (!autoCompactionSignal.aborted && reason !== "idle" && compactionSettings.autoContinue !== false) {
+						this.#scheduleAutoContinuePrompt(generation);
+					}
 					return;
 				}
 			}
@@ -5064,26 +5090,7 @@ export class AgentSession {
 			await this.#emitSessionEvent({ type: "auto_compaction_end", action, result, aborted: false, willRetry });
 
 			if (!willRetry && reason !== "idle" && compactionSettings.autoContinue !== false) {
-				const continuePrompt = async () => {
-					await this.#promptWithMessage(
-						{
-							role: "developer",
-							content: [{ type: "text", text: "Continue if you have next steps." }],
-							attribution: "agent",
-							timestamp: Date.now(),
-						},
-						"Continue if you have next steps.",
-						{ skipPostPromptRecoveryWait: true },
-					);
-				};
-				this.#schedulePostPromptTask(
-					async signal => {
-						await Promise.resolve();
-						if (signal.aborted) return;
-						await continuePrompt();
-					},
-					{ generation },
-				);
+				this.#scheduleAutoContinuePrompt(generation);
 			}
 
 			if (willRetry) {
@@ -5604,6 +5611,14 @@ export class AgentSession {
 	// Bash Execution
 	// =========================================================================
 
+	async #saveBashOriginalArtifact(originalText: string): Promise<string | undefined> {
+		try {
+			return await this.sessionManager.saveArtifact(originalText, "bash-original");
+		} catch {
+			return undefined;
+		}
+	}
+
 	/**
 	 * Execute a bash command.
 	 * Adds result to agent context and session.
@@ -5640,6 +5655,7 @@ export class AgentSession {
 				signal: this.#bashAbortController.signal,
 				sessionKey: this.sessionId,
 				timeout: clampTimeout("bash") * 1000,
+				onMinimizedSave: originalText => this.#saveBashOriginalArtifact(originalText),
 			});
 
 			this.recordBashResult(command, result, options);