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

package/src/prompts/tools/exit-plan-mode.md

@@ -19,15 +19,14 @@ Use when:
 Presents plan to user for approval. If approved, plan mode exits with full tool access restored and the plan is renamed to `local://<title>.md`.
 </output>
 
-<example name="ready">
+<examples>
+# Ready
 Plan complete at local://PLAN.md, no open questions.
 → Call `exit_plan_mode` with `{ "title": "WP_MIGRATION_PLAN" }`
-</example>
-
-<example name="unclear">
+# Unclear
 Unsure about auth method (OAuth vs JWT).
 → Use `ask` first to clarify, then call `exit_plan_mode`
-</example>
+</examples>
 
 <avoid>
 - **MUST NOT** call before plan is written to file

package/src/prompts/tools/find.md

@@ -8,14 +8,10 @@ Finds files using fast pattern matching that works with any codebase size.
 Matching file paths sorted by modification time (most recent first). Truncated at 1000 entries or 50KB (configurable via `limit`).
 </output>
 
-<example name="find files">
-```
-{
-  "pattern": "src/**/*.ts",
-  "limit": 1000
-}
-```
-</example>
+<examples>
+# Find files
+`{"pattern": "src/**/*.ts", "limit": 1000}`
+</examples>
 
 <avoid>
 For open-ended searches requiring multiple rounds of globbing and grepping, you **MUST** use Task tool instead.

package/src/prompts/tools/github.md

@@ -0,0 +1,18 @@
+GitHub CLI tool with a single op-based dispatch. Wraps `gh` for repository, issue, pull request, search, checkout, push, and Actions watch workflows.
+
+<instruction>
+Pick the operation via `op`. Each op uses a subset of the parameters:
+- `repo_view` — Read repository metadata. Optional `repo` (owner/repo) and `branch`. Falls back to the current checkout or default `gh` repo.
+- `issue_view` — Read an issue. Required `issue` (number or URL). Optional `repo`. Set `comments: false` to skip discussion.
+- `pr_view` — Read a pull request, including reviews and inline review comments. Optional `pr` (number, URL, or branch); omitting it targets the current branch's PR. Optional `repo`. Set `comments: false` for a lighter summary.
+- `pr_diff` — Read a pull request diff. Optional `pr`, `repo`. Set `nameOnly: true` for changed file names. Use `exclude` to drop generated paths from the diff.
+- `pr_checkout` — Check a pull request out into a dedicated git worktree. Optional `pr`, `repo`, `branch` (local), `worktree` (path), `force` (reset existing local branch).
+- `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout` (carries push metadata). Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
+- `search_issues` — Search issues using normal GitHub issue search syntax. Required `query`. Optional `repo`, `limit`.
+- `search_prs` — Search pull requests using normal GitHub PR search syntax. Required `query`. Optional `repo`, `limit`.
+- `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Streams snapshots, fast-fails on the first detected job failure (with a brief grace period to capture concurrent failures), then fetches tailed logs for the failed jobs. The full failed-job logs are saved as a session artifact for on-demand reads.
+</instruction>
+
+<output>
+Returns a concise readable summary tailored to the chosen op (repo/issue/PR metadata, diff text, search results, checkout info, push target, or workflow run snapshot). For `run_watch`, the full failed-job logs are saved as a session artifact when failures occur.
+</output>

package/src/prompts/tools/grep.md

@@ -2,21 +2,20 @@ Searches files using powerful regex matching.
 
 <instruction>
 - Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`); literal braces need escaping (`interface\\{\\}` for `interface{}` in Go)
-- `path` also accepts comma-separated path lists; pair with `glob` when you need a relative file filter in addition to `type`
-- For cross-line patterns like `struct \\{[\\s\\S]*?field`, set `multiline: true`
-- If the pattern contains a literal `\n`, `multiline` defaults to true automatically
+- `path` is required and accepts a file, directory, glob, comma-separated path list, or internal URL
+- Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
 </instruction>
 
 <output>
 {{#if IS_HASHLINE_MODE}}
-- Text output is CID prefixed: `LINE#ID:content`
+- Text output is anchor-prefixed: `123th:content` (match) or `123th-content` (context). The 2-letter ID is a content fingerprint.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Text output is line-number-prefixed
 {{/if}}
 {{/if}}
 {{#if IS_CHUNK_MODE}}
-- Text output is chunk-path-prefixed: `path:selector>LINE|content`
+- Text output is chunk-path-prefixed: `path:sel>123th:content`
 {{/if}}
 </output>
 

package/src/prompts/tools/hashline.md

@@ -1,22 +1,21 @@
-Applies precise file edits using `LINE#ID` anchors from `read` output.
+Applies precise file edits using full anchors from `read` output (for example `160sr`).
 
-Read the file first. Copy anchors exactly from the latest `read` output. After any successful edit, re-read before editing that file again.
+Read the file first. Copy the full anchors exactly as shown by `read`.
 
 <operations>
 **Top level**
 - `edits` — array of edit entries
+- `path` (optional) — default file path used when an entry omits its own `path`. Lets you share the path across many edits in one request.
 
-**Edit entry**: `{ path, loc, content }` or `{ path, delete: true }` or `{ path, move: "new/path" }`
-- `path` — file path
+**Edit entry**: `{ path?, loc, content }`
+- `path` — file path (omit to fall back to the request-level `path`)
 - `loc` — where to apply the edit (see below)
-- `content` — replacement/inserted lines (array of strings preferred, `null` to delete)
-- `delete` — delete the file
-- `move` — move/rename the file
+- `content` — replacement/inserted lines (`string[]`, one element per line; `null` to delete)
 
 **`loc` values**
 - `"append"` / `"prepend"` — insert at end/start of file
-- `{ append: "N#ID" }` / `{ prepend: "N#ID" }` — insert after/before anchored line
-- `{ range: { pos: "N#ID", end: "N#ID" } }` — replace inclusive range `pos..end` with new content (set `pos == end` for single-line replace)
+- `{ append: "123th" }` / `{ prepend: "123th" }` — insert after/before anchored line
+- `{ range: { pos: "123th", end: "123th" } }` — replace inclusive range `pos..end` with new content (set `pos == end` for single-line replace)
 </operations>
 
 <examples>
@@ -43,92 +42,26 @@ All examples below reference the same file:
 {{hline 18 "}"}}
 ```
 
-<example name="replace a block body">
+# Replace a block body
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 15 "\t\tconsole.error(err);"}}, end: {{href 16 "\t\treturn null;"}} } },
-    content: [
-      "\t\tif (isEnoent(err)) return null;",
-      "\t\tthrow err;"
-    ]
-  }]
-}
-```
-</example>
-
-<example name="replace whole block including closing brace">
-Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 6 "\tlog();"}}, end: {{href 7 "}"}} } },
-    content: [
-      "\tvalidate();",
-      "\tlog();",
-      "}"
-    ]
-  }]
-}
-```
-
-**Wrong**: `end: {{href 6 "\tlog();"}}` with the same content — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
-</example>
-
-<example name="replace one line">
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 15 "\t\tconsole.error(err);"}},end:{{href 16 "\t\treturn null;"}}}},content:["\t\tif (isEnoent(err)) return null;","\t\tthrow err;"]}]}`
+# Replace whole block including closing brace
+Replace `alpha`'s entire body including the closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 6 "\tlog();"}},end:{{href 7 "}"}}}},content:["\tvalidate();","\tlog();","}"]}]}`
+**Wrong**: `end: {{href 6 "\tlog();"}}` — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
+# Replace one line
 Single-line replace uses `pos == end`.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 2 "const timeout = 5000;"}}, end: {{href 2 "const timeout = 5000;"}} } },
-    content: ["const timeout = 30_000;"]
-  }]
-}
-```
-</example>
-
-<example name="delete a range">
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { range: { pos: {{href 10 "\t// TODO: remove after migration"}}, end: {{href 11 "\tlegacy();"}} } },
-    content: null
-  }]
-}
-```
-</example>
-
-<example name="insert before sibling">
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 2 "const timeout = 5000;"}},end:{{href 2 "const timeout = 5000;"}}}},content:["const timeout = 30_000;"]}]}`
+# Delete a range
+`{edits:[{path:"a.ts",loc:{range:{pos:{{href 10 "\t// TODO: remove after migration"}},end:{{href 11 "\tlegacy();"}}}},content:null}]}`
+# Insert before a sibling
 When adding a sibling declaration, prefer `prepend` on the next declaration.
-
-```
-{
-  edits: [{
-    path: "a.ts",
-    loc: { prepend: {{href 9 "function beta() {"}} },
-    content: [
-      "function gamma() {",
-      "\tvalidate();",
-      "}",
-      ""
-    ]
-  }]
-}
-```
-</example>
+`{edits:[{path:"a.ts",loc:{prepend:{{href 9 "function beta() {"}}},content:["function gamma() {","\tvalidate();","}",""]}]}`
 </examples>
 
 <critical>
-- Make the minimum exact edit. Do not rewrite nearby code unless the range requires it.
-- Copy anchors exactly as `N#ID` from the latest `read` output.
+- Make the minimum exact edit.
+- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
 - `range` requires both `pos` and `end`.
 - **Closing-delimiter check**: when your replacement `content` ends with a closing delimiter (`}`, `*/`, `)`, `]`), compare it against the line immediately after `end` in the file. If they match, extend `end` to include that line — otherwise the original delimiter survives and `content` adds a second copy.
 - For a range, replace only the body or the whole range — don't split range boundaries.

package/src/prompts/tools/{gemini-image.md → image-gen.md}

@@ -1,4 +1,4 @@
-Generates or edits images using Gemini image models.
+Generates or edits images using the configured image provider.
 
 <instructions>
 - You **MUST** provide a single detailed `subject` prompt for image generation or editing.

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

@@ -12,12 +12,12 @@ Inspects an image file with a vision-capable model and returns compact text anal
 </instruction>
 
 <examples>
-- OCR with strict formatting:
-  - `{"path":"screenshots/error.png","question":"Extract all visible text verbatim. Return as bullet list in reading order."}`
-- Screenshot debugging:
-  - `{"path":"screenshots/settings.png","question":"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence."}`
-- Scene/object question:
-  - `{"path":"photos/shelf.jpg","question":"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable."}`
+# OCR with strict formatting
+`{"path":"screenshots/error.png","question":"Extract all visible text verbatim. Return as bullet list in reading order."}`
+# Screenshot debugging
+`{"path":"screenshots/settings.png","question":"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence."}`
+# Scene/object question
+`{"path":"photos/shelf.jpg","question":"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable."}`
 </examples>
 
 <output>

package/src/prompts/tools/lsp.md

@@ -36,4 +36,4 @@ Interacts with Language Server Protocol servers for code intelligence.
 - 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>
+</critical>

package/src/prompts/tools/patch.md

@@ -50,25 +50,18 @@ Returns success/failure; on failure, error message indicates:
 - **NEVER** use edit to fix indentation, whitespace, or reformat code. Formatting is a single command run once at the end (`bun fmt`, `cargo fmt`, `prettier —write`, etc.)—not N individual edits. If you see inconsistent indentation after an edit, leave it; the formatter will fix all of it in one pass.
 </critical>
 
-<example name="create">
-edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}
-</example>
-
-<example name="update">
-edit {"edits":[{"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}
-</example>
-
-<example name="rename">
-edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}
-</example>
-
-<example name="delete">
-edit {"edits":[{"path":"obsolete.txt","op":"delete"}]}
-</example>
-
-<example name="multi-file">
-edit {"edits":[{"path":"src/types.ts","op":"update","diff":"@@\n-old\n+new\n"},{"path":"src/index.ts","op":"update","diff":"@@\n-old\n+new\n"}]}
-</example>
+<examples>
+# Create
+`edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}`
+# Update
+`edit {"edits":[{"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}`
+# Rename
+`edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}`
+# Delete
+`edit {"edits":[{"path":"obsolete.txt","op":"delete"}]}`
+# Multi-file
+`edit {"edits":[{"path":"src/types.ts","op":"update","diff":"@@\n-old\n+new\n"},{"path":"src/index.ts","op":"update","diff":"@@\n-old\n+new\n"}]}`
+</examples>
 
 <avoid>
 - Generic anchors: `import`, `export`, `describe`, `function`, `const`

package/src/prompts/tools/python.md

@@ -44,7 +44,8 @@ User sees output like Jupyter notebook; rich displays render fully:
 - You **MUST** use `run()` for shell commands; you **MUST NOT** use raw `subprocess`
 </critical>
 
-<example name="multiple small cells">
+<examples>
+# Multiple small cells
 ```python
 cells: [
     {"title": "imports", "code": "import json\nfrom pathlib import Path"},
@@ -53,4 +54,4 @@ cells: [
     {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
 ]
 ```
-</example>
+</examples>

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

@@ -2,7 +2,6 @@ Reads files using syntax-aware chunks. Also inspects directories, archives, SQLi
 
 <instruction>
 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.
 
@@ -17,7 +16,7 @@ The chunk-aware `read` variant returns AST-scoped chunks with current checksum I
 |---|---|
 |*(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|
+|`class_Foo.fn_bar#thth~`|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|
@@ -27,7 +26,7 @@ The chunk-aware `read` variant returns AST-scoped chunks with current checksum I
 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.
+Each anchor `@full.chunk.path#thth` (with `-` prefixes for nesting depth) in the output identifies a chunk. Use `full.chunk.path#thth` 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 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.
 

package/src/prompts/tools/read.md

@@ -18,13 +18,13 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 |`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)|
+|`raw`|Skip line-numbering / hashline / chunking; return file content as plain text. For URLs: untouched HTML.|
 
 Max {{DEFAULT_MAX_LINES}} lines per call.
 
 # Filesystem
 {{#if IS_HASHLINE_MODE}}
-- Reading from FS returns lines prefixed with anchors: `41#ZZ:def alpha():`
+- Reading from FS returns lines prefixed with anchors: `41th:def alpha():` (line number, 2-letter ID, colon, then content)
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Reading from FS returns lines prefixed with line numbers: `41:def alpha():`

package/src/prompts/tools/ssh.md

@@ -25,20 +25,11 @@ You **MUST** build commands from the reference below
 You **MUST** verify the shell type from "Available hosts" and use matching commands.
 </critical>
 
-<example name="linux">
-Task: List /home/user files on "server1"
-Host: server1 (10.0.0.1) | linux/bash
-Command: `ls -la /home/user`
-</example>
-
-<example name="windows-cmd">
-Task: Show running processes on "winbox"
-Host: winbox (192.168.1.5) | windows/cmd
-Command: `tasklist /v`
-</example>
-
-<example name="macos">
-Task: Get system info on "macbook"
-Host: macbook (10.0.0.20) | macos/zsh
-Command: `uname -a && sw_vers`
-</example>
+<examples>
+# List files: Linux
+Host: server1 (10.0.0.1) | linux/bash. Command: `ls -la /home/user`
+# Show running processes: Windows cmd
+Host: winbox (192.168.1.5) | windows/cmd. Command: `tasklist /v`
+# Get system info: macOS
+Host: macbook (10.0.0.20) | macos/zsh. Command: `uname -a && sw_vers`
+</examples>

package/src/prompts/tools/todo-write.md

@@ -1,28 +1,53 @@
-Manages a phased task list. Each field is a verb — set the ones you need in a single call.
+Manages a phased task list through an `ops` array of flat operations.
 The next pending task is auto-promoted to `in_progress` after completing the current one.
 
 <protocol>
-## Fields
+## Shape
+
+Pass an object with an `ops` array:
+
+```ts
+{
+  ops: [
+    { op: "replace", phases: [...] },
+    { op: "start", task: "task-3" },
+    { op: "done", phase: "Implementation" },
+    { op: "rm" },
+    { op: "drop", task: "task-9" },
+    { op: "append", phase: "Implementation", items: [{ id: "task-10", label: "Run tests" }] },
+  ],
+}
+```
+
+## Operation fields
 
 |Field|Type|When to use|
 |---|---|---|
-|`phases`|Phase[]|Initial setup, or full restructure when the plan changes significantly|
-|`complete`|string[]|Mark tasks done|
-|`start`|string|Jump to a specific task out of order|
-|`abandon`|string[]|Drop tasks intentionally|
-|`remove`|string[]|Remove tasks that are no longer relevant|
-|`add_notes`|{id, notes}[]|Append runtime observations to tasks|
-|`add_tasks`|{phase, content, details?}[]|Add tasks to a phase (by name or ID)|
-|`add_phase`|{name, tasks?}|Add a new phase of work discovered mid-task|
+|`op`|string|Required. One of `replace`, `start`, `done`, `rm`, `drop`, `append`|
+|`task`|string|Task id for `start`, or a task target for `done` / `rm` / `drop`|
+|`phase`|string|Phase target for `done` / `rm` / `drop`, or append destination for `append`|
+|`items`|{id, label}[]|Required for `append`. If the phase does not exist, it is created at the end|
+|`phases`|Phase[]|Only for `replace`. Keeps initial phased setup available for harness bootstrap and full restructures|
+
+## Semantics
+- `start`: requires `task`; sets that task to `in_progress`
+- `done`: marks one task, one phase, or all tasks completed
+- `rm`: removes one task, one phase's tasks, or all tasks
+- `drop`: marks one task, one phase, or all tasks abandoned
+- `append`: appends `items` to `phase`; creates the phase if missing
+- `replace`: replaces the full todo list
+
+If `done`, `rm`, or `drop` omits both `task` and `phase`, it applies to all tasks.
 
 ## Task Anatomy
-- `content`: Short label (5-10 words). What is being done, not how.
-- `details`: File paths, implementation steps, edge cases. Shown only when the task is active.
+- `label`: Short label (5-10 words). What is being done, not how.
+- `replace` task `content` should stay short and specific.
 
 ## Rules
-- Mark tasks completed immediately after finishing — never defer
-- Complete phases in order — do not skip ahead while earlier ones are pending
-- On blockers: add a new task describing the blocker
+- Mark tasks done immediately after finishing — never defer.
+- Complete phases in order — do not skip ahead while earlier ones are pending.
+- On blockers, append a new task to the active phase.
+- Keep ids stable once introduced.
 </protocol>
 
 <conditions>
@@ -33,32 +58,20 @@ Create a todo list when:
 4. New instructions arrive mid-task — capture before proceeding
 </conditions>
 
-<example name="initial-setup">
-{phases: [
-  {name: "Investigation", tasks: [{content: "Read source"}, {content: "Map callsites"}]},
-  {name: "Implementation", tasks: [{content: "Apply fix", details: "Update parser.ts to handle edge case in line 42"}, {content: "Run tests"}]}
-]}
-</example>
-
-<example name="complete">
-{complete: ["task-2", "task-3"]}
-</example>
-
-<example name="add-notes">
-{add_notes: [{id: "task-3", notes: "Found edge case in parser — needs null check"}]}
-</example>
-
-<example name="add-task">
-{add_tasks: [{phase: "Implementation", content: "Handle retries", details: "Cap exponential backoff in retry.ts"}]}
-</example>
-
-<example name="add-phase">
-{add_phase: {name: "Cleanup", tasks: [{content: "Remove dead code"}]}}
-</example>
-
-<example name="combined">
-{complete: ["task-2"], add_notes: [{id: "task-3", notes: "Needs extra validation"}]}
-</example>
+<examples>
+# Initial setup
+`{"ops":[{"op":"replace","phases":[{"name":"Investigation","tasks":[{"content":"Read source"},{"content":"Map callsites"}]},{"name":"Implementation","tasks":[{"content":"Apply fix"},{"content":"Run tests"}]}]}]}`
+# Complete one task
+`{"ops":[{"op":"done","task":"task-2"}]}`
+# Complete a whole phase
+`{"ops":[{"op":"done","phase":"Implementation"}]}`
+# Remove all tasks
+`{"ops":[{"op":"rm"}]}`
+# Drop one task
+`{"ops":[{"op":"drop","task":"task-7"}]}`
+# Append tasks to a phase
+`{"ops":[{"op":"append","phase":"Implementation","items":[{"id":"task-8","label":"Handle retries"},{"id":"task-9","label":"Run tests"}]}]}`
+</examples>
 
 <avoid>
 - Single-step tasks — act directly

package/src/sdk.ts

@@ -128,7 +128,7 @@ import {
 	warmupLspServers,
 } from "./tools";
 import { ToolContextStore } from "./tools/context";
-import { getGeminiImageTools } from "./tools/gemini-image";
+import { getImageGenTools } from "./tools/image-gen";
 import { wrapToolWithMetaNotice } from "./tools/output-meta";
 import { queueResolveHandler } from "./tools/resolve";
 import { EventBus } from "./utils/event-bus";
@@ -209,8 +209,8 @@ export interface CreateAgentSessionOptions {
 
 	/** Output schema for structured completion (subagents) */
 	outputSchema?: unknown;
-	/** Whether to include the submit_result tool by default */
-	requireSubmitResultTool?: boolean;
+	/** Whether to include the yield tool by default */
+	requireYieldTool?: boolean;
 	/** Task recursion depth (for subagent sessions). Default: 0 */
 	taskDepth?: number;
 	/** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
@@ -673,7 +673,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	}
 
 	const imageProvider = settings.get("providers.image");
-	if (imageProvider === "auto" || imageProvider === "gemini" || imageProvider === "openrouter") {
+	if (
+		imageProvider === "auto" ||
+		imageProvider === "openai" ||
+		imageProvider === "gemini" ||
+		imageProvider === "openrouter"
+	) {
 		setPreferredImageProvider(imageProvider);
 	}
 
@@ -916,7 +921,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			skills,
 			eventBus,
 			outputSchema: options.outputSchema,
-			requireSubmitResultTool: options.requireSubmitResultTool,
+			requireYieldTool: options.requireYieldTool,
 			taskDepth: options.taskDepth ?? 0,
 			getSessionFile: () => sessionManager.getSessionFile() ?? null,
 			getPythonKernelOwnerId: () => pythonKernelOwnerId,
@@ -1047,10 +1052,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		toolSession.mcpManager = mcpManager;
 
-		// Add Gemini image tools if GEMINI_API_KEY (or GOOGLE_API_KEY) is available
-		const geminiImageTools = await logger.time("getGeminiImageTools", getGeminiImageTools);
-		if (geminiImageTools.length > 0) {
-			customTools.push(...(geminiImageTools as unknown as CustomTool[]));
+		// Add image tools when the active model or configured image providers can generate images.
+		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, model));
+		if (imageGenTools.length > 0) {
+			customTools.push(...(imageGenTools as unknown as CustomTool[]));
 		}
 
 		// Add web search tools

package/src/session/agent-session.ts

@@ -525,6 +525,7 @@ export class AgentSession {
 	#obfuscator: SecretObfuscator | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
 	#pendingRewindReport: string | undefined = undefined;
+	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
 	#providerSessionState = new Map<string, ProviderSessionState>();
 
@@ -789,6 +790,9 @@ export class AgentSession {
 				this.#toolChoiceQueue.resolve();
 			}
 		}
+		if (event.type === "tool_execution_end" && event.toolName === "yield" && !event.isError) {
+			this.#lastSuccessfulYieldToolCallId = event.toolCallId;
+		}
 		if (event.type === "turn_end" && this.#pendingRewindReport) {
 			const report = this.#pendingRewindReport;
 			this.#pendingRewindReport = undefined;
@@ -1026,7 +1030,10 @@ export class AgentSession {
 				.find((message): message is AssistantMessage => message.role === "assistant");
 			const msg = this.#lastAssistantMessage ?? fallbackAssistant;
 			this.#lastAssistantMessage = undefined;
-			if (!msg) return;
+			if (!msg) {
+				this.#lastSuccessfulYieldToolCallId = undefined;
+				return;
+			}
 
 			// Invalidate GitHub Copilot credentials on auth failure so stale tokens
 			// aren't reused on the next request
@@ -1040,8 +1047,15 @@ export class AgentSession {
 
 			if (this.#skipPostTurnMaintenanceAssistantTimestamp === msg.timestamp) {
 				this.#skipPostTurnMaintenanceAssistantTimestamp = undefined;
+				this.#lastSuccessfulYieldToolCallId = undefined;
+				return;
+			}
+
+			if (this.#assistantEndedWithSuccessfulYield(msg)) {
+				this.#lastSuccessfulYieldToolCallId = undefined;
 				return;
 			}
+			this.#lastSuccessfulYieldToolCallId = undefined;
 
 			// Check for retryable errors first (overloaded, rate limit, server errors)
 			if (this.#isRetryableError(msg)) {
@@ -3227,7 +3241,6 @@ export class AgentSession {
 				id: task.id,
 				content: task.content,
 				status: task.status,
-				notes: task.notes,
 			})),
 		}));
 	}
@@ -4230,6 +4243,16 @@ export class AgentSession {
 			}
 		}
 	}
+	#assistantEndedWithSuccessfulYield(assistantMessage: AssistantMessage): boolean {
+		const toolCallId = this.#lastSuccessfulYieldToolCallId;
+		if (!toolCallId) return false;
+		const lastToolCall = assistantMessage.content
+			.slice()
+			.reverse()
+			.find((content): content is ToolCall => content.type === "toolCall");
+		return lastToolCall?.name === "yield" && lastToolCall.id === toolCallId;
+	}
+
 	#enforceRewindBeforeYield(): boolean {
 		if (!this.#checkpointState || this.#pendingRewindReport) {
 			return false;