@oh-my-pi/pi-coding-agent 14.0.5 → 14.1.1

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

@@ -1,11 +1,13 @@
-Edits files via syntax-aware chunks. Run `read(path="file.ts")` first. The edit selector is a chunk path, optionally qualified with a region.
+Edits files via syntax-aware chunks. Run `read(path="file.ts")` first.
+- `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.
+
+Call format: `{"edits": [{"path": "file:chunk#ID~", "write": "new body"}, …]}`
 
 <rules>
-- **MUST** `read` first. Never invent chunk paths or CRCs. Copy them from the latest `read` output or edit response.
-- `sel` format:
-  - insertions: `chunk`, `chunk~`, or `chunk^`
-  - replacements: `chunk#CRC`, `chunk#CRC~`, or `chunk#CRC^`
-- Without a suffix it defaults to the entire chunk including leading trivia. `~` targets the body, `^` targets the head.
+- **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`.
 - 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:
@@ -13,6 +15,10 @@ Edits files via syntax-aware chunks. Run `read(path="file.ts")` first. The edit
   content: "if (x) {\n\treturn true;\n}"
   ```
   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"`).
+  **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.
 {{else}}
 - Match the file's literal tabs/spaces in `content`. Do not convert indentation to canonical `\t`.
 - Write content at indent-level 0 relative to the target region. For example, to replace `~` of a method, write:
@@ -22,217 +28,239 @@ Edits files via syntax-aware chunks. Run `read(path="file.ts")` first. The edit
   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.
 {{/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.
-- `replace` requires the current CRC. Insertions do not.
-- **CRCs change after every edit.** The edit response always carries the new CRCs — use those for the next call or run `read(path="file", sel="?")` to refresh. Never reuse a CRC from before the latest edit.
+- `put`, `find`+`replace`, 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.
 </rules>
 
 <critical>
-You **MUST** use the narrowest region that covers your change. Replacing without a region replaces the **entire chunk including leading comments, decorators, and attributes** — omitting them from `content` deletes them.
+You **MUST** use the narrowest region that covers your change. Putting without a region overwrites the **entire chunk including leading comments, decorators, and attributes** — omitting them from `content` deletes them.
 
-**`replace` is total, not surgical.** The `content` you supply becomes the *complete* new content for the targeted region. Everything in the original region that you omit from `content` is deleted. Before replacing `~` on any chunk, verify the chunk does not contain children you intend to keep. If a chunk spans hundreds of lines and your change touches only a few, target a specific child chunk — not the parent.
+**`put` is total, not surgical.** The `content` you supply becomes the *complete* new content for the targeted region. Everything in the original region that you omit from `content` is deleted. Before using `put` on any chunk's `~`, verify the chunk does not contain children you intend to keep. If a chunk spans hundreds of lines and your change touches only a few, target a specific child chunk — not the parent.
 
-**Group chunks (`stmts_*`, `imports_*`, `decls_*`) are containers.** They hold many sibling items (test functions, import statements, declarations). Replacing `~` on a group chunk replaces **all** of its children. To edit one item inside a group, target that item's own chunk path. If no child chunk exists, use the specific child's chunk selector from `read` output — do not replace the parent group.
+**Group chunks (`stmts_*`, `imports_*`, `decls_*`) are containers.** They hold many sibling items (test functions, import statements, declarations). `put` on a group chunk's `~` overwrites **all** of its children. To edit one item inside a group, target that item's own chunk path. If no child chunk exists, use the specific child's chunk selector from `read` output — do not `put` the parent group.
 </critical>
 
 <regions>
-Given a chunk like:
-```
-/// doc comment      <-- leading trivia
-#[attr]              <-- leading trivia
-fn foo(x: i32) {     <-- signature + opening delimiter
-    body();          <-- body
-}                    <-- closing delimiter
-```
-
-Append `~` to target the body, `^` to target the head (trivia + signature), or nothing for the whole chunk:
-- `fn_foo#CRC~` — body only. **Use for most edits.** On leaf chunks, falls back to whole chunk.
-- `fn_foo#CRC^` — head (decorators, attributes, doc comments, signature, opening delimiter).
-- `fn_foo#CRC` — entire chunk including leading trivia.
+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^` — 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*.
 
-**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#CRC` 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#CRC` 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 `^`. If you need to rewrite a decorator, check the `?` listing 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.
 </regions>
 
 <ops>
-|op|sel|effect|
+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.
+
+|fields|path (selector part)|effect|
 |---|---|---|
-|`replace`|`chunk#CRC`, `chunk#CRC~`, or `chunk#CRC^`|rewrite the addressed region|
-|`before`|`chunk`, `chunk~`, or `chunk^`|insert before the region span|
-|`after`|`chunk`, `chunk~`, or `chunk^`|insert after the region span|
-|`prepend`|`chunk`, `chunk~`, or `chunk^`|insert at the start inside the region|
-|`append`|`chunk`, `chunk~`, or `chunk^`|insert at the end inside the region|
+|`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|
+|`insert: {loc, body}`|`file:chunk` or `file:chunk~`|insert before/after the chunk (`loc`: `"prepend"` or `"append"`)|
 </ops>
 
 <examples>
-Given this `read` output for `example.ts`:
-```
-  | example.ts·34L·ts·#QBMH
-  |
-  | [<interface_Config#BWTR>]
- 1| interface Config {
-  | 	[<interface_Config.field_host#TTMN>]
- 2| 	host: string;
-  | 	[<interface_Config.field_port#QSMH>]
- 3| 	port: number;
-  | 	[<interface_Config.field_debug#JPRR>]
- 4| 	debug: boolean;
- 5| }
-  |
-  | [<class_Counter#HZHY>]
- 7| class Counter {
-  | 	[<class_Counter.field_value#QJBY>]
- 8| 	value: number = 0;
- 9|
-  | 	[<class_Counter.fn_increment#NQWY>]
-10| 	increment(): void {
-11| 		this.value += 1;
-12| 	}
-13|
-  | 	[<class_Counter.fn_decrement#PMBP>]
-14| 	decrement(): void {
-15| 		this.value -= 1;
-16| 	}
-17|
-  | 	[<class_Counter.fn_toString#ZQZP>]
-18| 	toString(): string {
-19| 		return `Counter(${this.value})`;
-20| 	}
-21| }
-  |
-  | [<enum_Status#HYQJ>]
-23| enum Status {
-  | 	[<enum_Status.variant_Active#PQNS>]
-24| 	Active = "ACTIVE",
-  | 	[<enum_Status.variant_Paused#HHNM>]
-25| 	Paused = "PAUSED",
-  | 	[<enum_Status.variant_Stopped#NHTY>]
-26| 	Stopped = "STOPPED",
-27| }
-  |
-  | [<fn_createCounter#PQQY>]
-29| function createCounter(initial: number): Counter {
-30| 	const counter = new Counter();
-31| 	counter.value = initial;
-32| 	return counter;
-33| }
-```
-
-**Replace a whole chunk** (rename a function):
-~~~json
-{{#if chunkAutoIndent}}
-{ "sel": "fn_createCounter#PQQY", "op": "replace", "content": "function makeCounter(start: number): Counter {\n\tconst c = new Counter();\n\tc.value = start;\n\treturn c;\n}\n" }
-{{else}}
-{ "sel": "fn_createCounter#PQQY", "op": "replace", "content": "function makeCounter(start: number): Counter {\n  const c = new Counter();\n  c.value = start;\n  return c;\n}\n" }
-{{/if}}
-~~~
-Result — the entire chunk is rewritten:
+Given this `read` output for `counter.rs`:
 ```
-function makeCounter(start: number): Counter {
-  const c = new Counter();
-  c.value = start;
-  return c;
-}
+   | counter.rs·62L·rust·#ZRPW
+   |
+@imp#MNHH
+ 1 |use std::fmt;
+   |
+@struct_Counte#QTSX
+ 3^|/// A simple counter that tracks a value and its history.
+ 4^|#[derive(Debug, Clone)]
+ 5^|pub struct Counter {
+-@struct_Counte.field_value#MQTW
+ 6 |	/// The current value.
+ 7 |	value: i32,
+-@struct_Counte.field_max#HJMQ
+ 8 |	/// Maximum allowed value.
+ 9 |	max: i32,
+10 |}
+   |
+@impl_Counte#VNPP
+12^|impl Counter {
+-@impl_Counte.fn_new#RWZV
+13^|	/// Creates a new counter starting at zero.
+14^|	pub fn new(max: i32) -> Self {
+15 |		Self { value: 0, max }
+16 |	}
+17 |
+-@impl_Counte.fn_increm#MNHV
+18^|	/// Increments the counter by one, clamping at max.
+19^|	pub fn increment(&mut self) {
+20 |		if self.value < self.max {
+21 |			self.value += 1;
+22 |		}
+23 |	}
+24 |
+-@impl_Counte.fn_decrem#TTWB
+25^|	/// Decrements the counter by one, clamping at zero.
+26^|	pub fn decrement(&mut self) {
+27 |		if self.value > 0 {
+28 |			self.value -= 1;
+29 |		}
+30 |	}
+31 |
+-@impl_Counte.fn_get#PTNT
+32^|	/// Returns the current value.
+33^|	pub fn get(&self) -> i32 {
+34 |		self.value
+35 |	}
+36 |}
+   |
+@impl_Displa#BNJH
+38^|impl fmt::Display for Counter {
+-@impl_Displa.fn_fmt#NKRN
+39^|	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+40 |		write!(f, "Counter({}/{})", self.value, self.max)
+41 |	}
+42 |}
+   |
+@mod_tests#YWXM
+44^|#[cfg(test)]
+45^|mod tests {
+-@mod_tests.chunk#VSMY
+46 |	use super::*;
+47 |
+-@mod_tests.fn_test_i#YXQZ
+48^|	#[test]
+49^|	fn test_increment() {
+50 |		let mut c = Counter::new(10);
+51 |		c.increment();
+52 |		assert_eq!(c.get(), 1);
+53 |	}
+54 |
+-@mod_tests.fn_test_d#XPBQ
+55^|	#[test]
+56^|	fn test_decrement_at_zero() {
+57 |		let mut c = Counter::new(10);
+58 |		c.decrement();
+59 |		assert_eq!(c.get(), 0);
+60 |	}
+61 |}
 ```
 
-**Replace a method body** (`~`):
+**Understanding `^` markers in `read` output:** Lines marked with `^` between the line number and `|` (e.g. ` 3^|`) are **head** lines — doc comments, attributes, and the signature. Lines without `^` (e.g. ` 7 |`) are **body** lines. `~` replaces body lines only, keeping head lines intact.
+
+**Put body** (`~` — the common case):
 ```
-{ "sel": "class_Counter.fn_increment#NQWY~", "op": "replace", "content": "this.value += 1;\nconsole.log('incremented to', this.value);\n" }
+{ "path": "counter.rs:impl_Counte.fn_increm#MNHV~", "write": "self.value = (self.value + 1).min(self.max);\n" }
 ```
-Result — only the body changes, signature and braces are kept:
+Result — only the body (non-`^` lines) changes; the doc comment, signature, and closing `}` are all preserved:
 ```
-  increment(): void {
-    this.value += 1;
-    console.log('incremented to', this.value);
-  }
+    /// Increments the counter by one, clamping at max.
+    pub fn increment(&mut self) {
+        self.value = (self.value + 1).min(self.max);
+    }
 ```
 
-**Replace a function header** (`^` — signature and doc comment):
+**Write whole chunk** (rewrite signature + doc comment + body):
 ```
-{ "sel": "fn_createCounter#PQQY^", "op": "replace", "content": "/** Creates a counter with the given start value. */\nfunction createCounter(initial: number, label?: string): Counter {\n" }
+{ "path": "counter.rs:impl_Counte.fn_increm#MNHV", "write": "/// Increments by the given step, clamping at max.\npub fn increment(&mut self, step: i32) {\n\tself.value = (self.value + step).min(self.max);\n}\n" }
 ```
-Result — adds a doc comment and updates the signature, body untouched:
+Result — **everything** including the doc comment and signature is rewritten. You must include them; omitting them deletes them:
 ```
-/** Creates a counter with the given start value. */
-function createCounter(initial: number, label?: string): Counter {
-  const counter = new Counter();
-  counter.value = initial;
-  return counter;
-}
+    /// Increments by the given step, clamping at max.
+    pub fn increment(&mut self, step: i32) {
+        self.value = (self.value + step).min(self.max);
+    }
 ```
 
-**Insert before a chunk** (`before`):
+**Write head** (`^` — attributes, doc comments, signature):
+```
+{ "path": "counter.rs:impl_Counte.fn_get#PTNT^", "write": "/// Returns the current counter value.\n#[inline]\npub fn get(&self) -> i32 {\n" }
 ```
-{ "sel": "fn_createCounter", "op": "before", "content": "/** Factory function below. */\n" }
+Result — the head (all `^` lines + opening brace) changes, body untouched:
 ```
-Result — a comment is inserted before the function:
+    /// Returns the current counter value.
+    #[inline]
+    pub fn get(&self) -> i32 {
+        self.value
+    }
 ```
-/** Factory function below. */
 
-function createCounter(initial: number): Counter {
+**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 after a chunk** (`after`):
-~~~json
-{{#if chunkAutoIndent}}
-{ "sel": "enum_Status", "op": "after", "content": "\nfunction isActive(s: Status): boolean {\n\treturn s === Status.Active;\n}\n" }
-{{else}}
-{ "sel": "enum_Status", "op": "after", "content": "\nfunction isActive(s: Status): boolean {\n  return s === Status.Active;\n}\n" }
-{{/if}}
-~~~
-Result — a new function appears after the enum:
+**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" } }
+```
+Result — a new method is inserted before `fn get`:
+```
+    /// Resets the counter to zero.
+    pub fn reset(&mut self) {
+        self.value = 0;
+    }
+
+    /// Returns the current value.
+    pub fn get(&self) -> i32 {
+```
+
+**Insert after a chunk** (`append`):
+```
+{ "path": "counter.rs:struct_Counte", "insert": { "loc": "append", "body": "\nimpl Default for Counter {\n\tfn default() -> Self {\n\t\tSelf { value: 0, max: 100 }\n\t}\n}\n" } }
+```
+Result — a new impl block appears after the struct:
 ```
-enum Status {
-  Active = "ACTIVE",
-  Paused = "PAUSED",
-  Stopped = "STOPPED",
 }
 
-function isActive(s: Status): boolean {
-  return s === Status.Active;
+impl Default for Counter {
+    fn default() -> Self {
+        Self { value: 0, max: 100 }
+    }
 }
 
-function createCounter(initial: number): Counter {
+impl Counter {
 ```
 
-**Prepend inside a container** (`~` + `prepend`):
+**Insert at start of container body** (`~` + `prepend`):
 ```
-{ "sel": "class_Counter~", "op": "prepend", "content": "label: string = 'default';\n\n" }
+{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "prepend", "body": "/// Creates a counter starting at the given value.\npub fn with_value(value: i32, max: i32) -> Self {\n\tSelf { value: value.min(max), max }\n}\n\n" } }
 ```
-Result — a new field is added at the top of the class body, before existing members:
+Result — a new method is added at the top of the impl body, before existing methods:
 ```
-class Counter {
-  label: string = 'default';
+impl Counter {
+    /// Creates a counter starting at the given value.
+    pub fn with_value(value: i32, max: i32) -> Self {
+        Self { value: value.min(max), max }
+    }
 
-  value: number = 0;
+    /// Creates a new counter starting at zero.
+    pub fn new(max: i32) -> Self {
 ```
 
-**Append inside a container** (`~` + `append`):
-~~~json
-{{#if chunkAutoIndent}}
-{ "sel": "class_Counter~", "op": "append", "content": "\nreset(): void {\n\tthis.value = 0;\n}\n" }
-{{else}}
-{ "sel": "class_Counter~", "op": "append", "content": "\nreset(): void {\n  this.value = 0;\n}\n" }
-{{/if}}
-~~~
-Result — a new method is added at the end of the class body, before the closing `}`:
+**Insert at end of container body** (`~` + `append`):
+```
+{ "path": "counter.rs:impl_Counte~", "insert": { "loc": "append", "body": "\n/// Returns true if the counter is at its maximum.\npub fn is_maxed(&self) -> bool {\n\tself.value >= self.max\n}\n" } }
+```
+Result — a new method is added at the end of the impl body, before the closing `}`:
 ```
-  toString(): string {
-    return `Counter(${this.value})`;
-  }
+    pub fn get(&self) -> i32 {
+        self.value
+    }
 
-  reset(): void {
-    this.value = 0;
-  }
+    /// Returns true if the counter is at its maximum.
+    pub fn is_maxed(&self) -> bool {
+        self.value >= self.max
+    }
 }
 ```
 
-**Delete a chunk** (`replace` with empty content):
+**Delete a chunk**:
 ```
-{ "sel": "class_Counter.fn_toString#ZQZP", "op": "replace", "content": "" }
+{ "path": "counter.rs:impl_Counte.fn_decrem#TTWB", "write": null }
 ```
-Result — the method is removed from the class.
+Result — the method (including its doc comment and signature) is removed.
 - Indentation rules (important):
 {{#if chunkAutoIndent}}
   - Use `\t` for each indent level. The tool converts tabs to the file's actual style (2-space, 4-space, etc.).
@@ -240,12 +268,12 @@ Result — the method is removed from the class.
   - 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 `~` of a function: write at column 0, and use `\t` for *relative* nesting. Flat body: `"return x;\n"`. Nested body: `"if (cond) {\n\treturn x;\n}\n"` — the `if` is at column 0, the `return` is one tab in, and the tool adds the method's base indent to both.
-  - For `^`: write at the chunk's own depth. A class member's head uses `"/** doc */\nstart(): void {"`.
+  - 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() {"`.
 {{#if chunkAutoIndent}}
-  - For a top-level item: start at zero indent. Write `"function foo() {\n\treturn 1;\n}\n"`.
+  - 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 `"function foo() {\n  return 1;\n}\n"`.
+  - 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/hashline.md

@@ -1,17 +1,17 @@
 Applies precise file edits using `LINE#ID` anchors from `read` output.
 
-Read the file first. Copy anchors exactly from the latest `read` output. In one `edit` call, batch all edits for one file. After any successful edit, re-read before editing that file again.
+Read the file first. Copy anchors exactly from the latest `read` output. After any successful edit, re-read before editing that file again.
 
 <operations>
 **Top level**
-- `path` — file path
-- `move` — optional rename target
-- `delete` — optional whole-file delete
-- `edits` — array of `{ loc, content }` entries
+- `edits` — array of edit entries
 
-**Edit entry**: `{ loc, content }`
+**Edit entry**: `{ path, loc, content }` or `{ path, delete: true }` or `{ path, move: "new/path" }`
+- `path` — file 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
 
 **`loc` values**
 - `"append"` / `"prepend"` — insert at end/start of file
@@ -46,8 +46,8 @@ All examples below reference the same file:
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
 ```
 {
-  path: "a.ts",
   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;",
@@ -62,8 +62,8 @@ Replace only the catch body. Do not target the shared boundary line `} catch (er
 Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
 ```
 {
-  path: "a.ts",
   edits: [{
+    path: "a.ts",
     loc: { range: { pos: {{href 6 "\tlog();"}}, end: {{href 7 "}"}} } },
     content: [
       "\tvalidate();",
@@ -79,8 +79,8 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 <example name="replace one line">
 ```
 {
-  path: "a.ts",
   edits: [{
+    path: "a.ts",
     loc: { range: { pos: {{href 2 "const timeout = 5000;"}}, end: {{href 2 "const timeout = 5000;"}} } },
     content: ["const timeout = 30_000;"]
   }]
@@ -91,8 +91,8 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 <example name="delete a range">
 ```
 {
-  path: "a.ts",
   edits: [{
+    path: "a.ts",
     loc: { range: { pos: {{href 10 "\t// TODO: remove after migration"}}, end: {{href 11 "\tlegacy();"}} } },
     content: null
   }]
@@ -104,8 +104,8 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 When adding a sibling declaration, prefer `prepend` on the next declaration.
 ```
 {
-  path: "a.ts",
   edits: [{
+    path: "a.ts",
     loc: { prepend: {{href 9 "function beta() {"}} },
     content: [
       "function gamma() {",

package/src/prompts/tools/patch.md

@@ -18,7 +18,8 @@ When editing structured blocks (nested braces, tags, indented regions), include
 
 <parameters>
 ```ts
-type T =
+// Input is { edits: Entry[] } where Entry is one of:
+type Entry =
    // Diff is one or more hunks in the same file.
    // - Each hunk begins with "@@" (anchor optional).
    // - Each hunk body only has lines starting with ' ' | '+' | '-'.
@@ -50,19 +51,23 @@ Returns success/failure; on failure, error message indicates:
 </critical>
 
 <example name="create">
-edit {"path":"hello.txt","op":"create","diff":"Hello\n"}
+edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}
 </example>
 
 <example name="update">
-edit {"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}
+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 {"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}
+edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}
 </example>
 
 <example name="delete">
-edit {"path":"obsolete.txt","op":"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>
 
 <avoid>

package/src/prompts/tools/{await.md → poll.md}

@@ -1,5 +1,5 @@
 Blocks until one or more background jobs complete, fail, or are cancelled.
 
-You **MUST** use this instead of polling `read jobs://` in a loop when you need to wait for background task or bash results before continuing.
+You **MUST** use the `poll` tool instead of polling `read jobs://` in a loop when you need to wait for background task or bash results before continuing.
 
 Returns the status and results of all watched jobs once at least one finishes.

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

@@ -5,8 +5,8 @@ Reads files using syntax-aware chunks.
 - `sel` — optional selector: `class_Foo`, `class_Foo.fn_bar#ABCD~`, `?`, `L50`, `L50-L120`, or `raw`
 - `timeout` — seconds, for URLs only
 
-Each opening anchor `[< full.chunk.path#CCCC ]` in the default 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 CRCs.
+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.
 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.
@@ -18,9 +18,18 @@ Chunk reads preserve literal leading tabs/spaces from the file. When editing, ke
 {{/if}}
 
 Chunk trees: JS, TS, TSX, Python, Rust, Go. Others use blank-line fallback.
+
+# SQLite Databases
+When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), returns structured database content.
+- `file.db` — list tables with row counts
+- `file.db:table` — table schema + sample rows
+- `file.db:table:key` — single row by primary key
+- `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
 </instruction>
 
 <critical>
-- **MUST** `read` before editing — never invent chunk names or CRCs.
+- **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.
 </critical>

package/src/prompts/tools/read.md

@@ -38,6 +38,15 @@ When used against a directory, or an archive root, the tool will return a list o
 - Formats: `.tar`, `.tar.gz`, `.tgz`, and `.zip`.
 - Use `archive.ext:path/inside/archive` to read or list archive contents
 
+# SQLite Databases
+When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), returns structured database content.
+- `file.db` — list tables with row counts
+- `file.db:table` — table schema + sample rows
+- `file.db:table:key` — single row by primary key
+- `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
 - Extract information from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs, RSS/Atom feeds, JSON endpoints
 - `sel="raw"` for untouched HTML or debugging

package/src/prompts/tools/task.md

@@ -2,7 +2,7 @@ Launches subagents to parallelize workflows.
 
 {{#if asyncEnabled}}
 - Use `read jobs://` to inspect state; `read jobs://<job_id>` for detail.
-- Use the `await` tool to wait until completion. You **MUST NOT** poll `read jobs://` in a loop.
+- Use the `poll` tool to wait until completion. You **MUST NOT** poll `read jobs://` in a loop.
 {{/if}}
 
 Subagents lack your conversation history. Every decision, file content, and user requirement they need **MUST** be explicit in `context` or `assignment`.
@@ -13,7 +13,7 @@ Subagents lack your conversation history. Every decision, file content, and user
   - `.description`: UI display only — subagent never sees it
   - `.assignment`: Complete self-contained instructions. One-liners PROHIBITED; missing acceptance criteria = too vague.
 - `context`: Shared background prepended to every assignment. Session-specific info only.
-- `schema`: JTD schema for expected output. Format lives here — **MUST NOT** be duplicated in assignments.
+- `schema`: JSON-encoded JTD schema for expected output. Format lives here — **MUST NOT** be duplicated in assignments.
 - `tasks`: Tasks to execute in parallel.
 - `isolated`: Run in isolated environment; returns patches. Use when tasks edit overlapping files.
 </parameters>