@oh-my-pi/pi-coding-agent 13.9.2 → 13.9.4

package/src/modes/interactive-mode.ts

@@ -3,7 +3,7 @@
  * Handles TUI rendering and user interaction, delegating business logic to AgentSession.
  */
 import * as path from "node:path";
-import type { Agent, AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { type Agent, type AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Model, UsageReport } from "@oh-my-pi/pi-ai";
 import type { Component, Loader, SlashCommand } from "@oh-my-pi/pi-tui";
 import {
@@ -423,7 +423,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		} else if (this.isPythonMode) {
 			this.editor.borderColor = theme.getPythonModeBorderColor();
 		} else {
-			const level = this.session.thinkingLevel || "off";
+			const level = this.session.thinkingLevel ?? ThinkingLevel.Off;
 			this.editor.borderColor = theme.getThinkingBorderColor(level);
 		}
 		this.updateEditorTopBorder();

package/src/modes/rpc/rpc-client.ts

@@ -3,8 +3,8 @@
  *
  * Spawns the agent in RPC mode and provides a typed API for all operations.
  */
-import type { AgentEvent, AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { ImageContent, ThinkingLevel } from "@oh-my-pi/pi-ai";
+import type { AgentEvent, AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import { isRecord, ptree, readJsonl } from "@oh-my-pi/pi-utils";
 import type { BashResult } from "../../exec/bash-executor";
 import type { SessionStats } from "../../session/agent-session";
@@ -34,12 +34,7 @@ export interface RpcClientOptions {
 	args?: string[];
 }
 
-export interface ModelInfo {
-	provider: string;
-	id: string;
-	contextWindow: number;
-	reasoning: boolean;
-}
+export type ModelInfo = Pick<Model, "provider" | "id" | "contextWindow" | "reasoning" | "thinking">;
 
 export type RpcEventListener = (event: AgentEvent) => void;
 
@@ -284,7 +279,7 @@ export class RpcClient {
 	 */
 	async cycleModel(): Promise<{
 		model: { provider: string; id: string };
-		thinkingLevel: ThinkingLevel;
+		thinkingLevel: ThinkingLevel | undefined;
 		isScoped: boolean;
 	} | null> {
 		const response = await this.#send({ type: "cycle_model" });
@@ -309,7 +304,7 @@ export class RpcClient {
 	/**
 	 * Cycle thinking level.
 	 */
-	async cycleThinkingLevel(): Promise<{ level: ThinkingLevel } | null> {
+	async cycleThinkingLevel(): Promise<{ level: Effort } | null> {
 		const response = await this.#send({ type: "cycle_thinking_level" });
 		return this.#getData(response);
 	}

package/src/modes/rpc/rpc-types.ts

@@ -4,8 +4,8 @@
  * Commands are sent as JSON lines on stdin.
  * Responses and events are emitted as JSON lines on stdout.
  */
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { ImageContent, Model, ThinkingLevel } from "@oh-my-pi/pi-ai";
+import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { SessionStats } from "../../session/agent-session";
 import type { CompactionResult } from "../../session/compaction";
@@ -70,7 +70,7 @@ export type RpcCommand =
 
 export interface RpcSessionState {
 	model?: Model;
-	thinkingLevel: ThinkingLevel;
+	thinkingLevel: ThinkingLevel | undefined;
 	isStreaming: boolean;
 	isCompacting: boolean;
 	steeringMode: "all" | "one-at-a-time";
@@ -114,7 +114,7 @@ export type RpcResponse =
 			type: "response";
 			command: "cycle_model";
 			success: true;
-			data: { model: Model; thinkingLevel: ThinkingLevel; isScoped: boolean } | null;
+			data: { model: Model; thinkingLevel: ThinkingLevel | undefined; isScoped: boolean } | null;
 	  }
 	| {
 			id?: string;
@@ -131,7 +131,7 @@ export type RpcResponse =
 			type: "response";
 			command: "cycle_thinking_level";
 			success: true;
-			data: { level: ThinkingLevel } | null;
+			data: { level: Effort } | null;
 	  }
 
 	// Queue modes

package/src/modes/theme/theme.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ThinkingLevel } from "@oh-my-pi/pi-ai";
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Effort } from "@oh-my-pi/pi-ai";
 import {
 	detectMacOSAppearance,
 	type HighlightColors as NativeHighlightColors,
@@ -108,6 +109,7 @@ export type SymbolKey =
 	| "icon.warning"
 	| "icon.rewind"
 	| "icon.auto"
+	| "icon.fast"
 	| "icon.extensionSkill"
 	| "icon.extensionTool"
 	| "icon.extensionSlashCommand"
@@ -268,6 +270,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.warning": "⚠",
 	"icon.rewind": "↶",
 	"icon.auto": "⟲",
+	"icon.fast": "⚡",
 	"icon.extensionSkill": "✦",
 	"icon.extensionTool": "🛠",
 	"icon.extensionSlashCommand": "⌘",
@@ -499,7 +502,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.rewind": "\uf0e2",
 	// pick: 󰁨 | alt:   
 	"icon.auto": "\u{f0068}",
-	// pick:  | alt:  
+	"icon.fast": "\uf0e7",
 	"icon.extensionSkill": "\uf0eb",
 	// pick:  | alt:  
 	"icon.extensionTool": "\uf0ad",
@@ -680,6 +683,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.warning": "[!]",
 	"icon.rewind": "<-",
 	"icon.auto": "[A]",
+	"icon.fast": ">>",
 	"icon.extensionSkill": "SK",
 	"icon.extensionTool": "TL",
 	"icon.extensionSlashCommand": "/",
@@ -1220,7 +1224,7 @@ export class Theme {
 		return this.mode;
 	}
 
-	getThinkingBorderColor(level: ThinkingLevel): (str: string) => string {
+	getThinkingBorderColor(level: ThinkingLevel | Effort): (str: string) => string {
 		// Map thinking levels to dedicated theme colors
 		switch (level) {
 			case "off":
@@ -1381,6 +1385,7 @@ export class Theme {
 			warning: this.#symbols["icon.warning"],
 			rewind: this.#symbols["icon.rewind"],
 			auto: this.#symbols["icon.auto"],
+			fast: this.#symbols["icon.fast"],
 			extensionSkill: this.#symbols["icon.extensionSkill"],
 			extensionTool: this.#symbols["icon.extensionTool"],
 			extensionSlashCommand: this.#symbols["icon.extensionSlashCommand"],

package/src/priority.json

@@ -10,6 +10,7 @@
 		"mini"
 	],
 	"slow": [
+		"gpt-5.4",
 		"gpt-5.3-codex",
 		"gpt-5.3",
 		"gpt-5.2-codex",

package/src/prompts/system/auto-handoff-threshold-focus.md

@@ -0,0 +1 @@
+Threshold-triggered maintenance: preserve critical implementation state and immediate next actions.

package/src/prompts/system/system-prompt.md

@@ -186,7 +186,7 @@ Use the Task tool unless the change is:
 - A direct answer or explanation with no code changes
 - A command the user asked you to run yourself
 
-For everything else — multi-file changes, refactors, new features, test additions, investigations — break the work into tasks and delegate. Err on the side of delegating. You are an orchestrator first, a coder second.
+For everything else — multi-file changes, refactors, new features, test additions, investigations — break the work into tasks and delegate once the target design is settled. Err on the side of delegating after the architectural direction is fixed.
 </eager-tasks>
 {{/if}}
 
@@ -218,6 +218,18 @@ These are inviolable. Violation is system failure.
 6. You **MUST NOT** ask for information obtainable from tools, repo context, or files. File referenced → you **MUST** locate and read it. Path implied → you **MUST** resolve it.
 7. Full CUTOVER is **REQUIRED**. You **MUST** replace old usage everywhere you touch — no backwards-compat shims, no gradual migration, no "keeping both for now." The old way is dead; lingering instances **MUST** be treated as bugs.
 
+# Design Integrity
+- You **MUST** prefer a coherent final design over a minimally invasive patch.
+- You **MUST NOT** preserve obsolete abstractions to reduce edit scope.
+- Temporary bridges are **PROHIBITED** unless the user explicitly asks for a migration path.
+- If a refactor introduces a new canonical abstraction, you **MUST** migrate consumers to it instead of wrapping it in compatibility helpers.
+- Parallel APIs that express the same concept are a bug, not a convenience.
+- Boolean compatibility helpers that collapse richer capability models are **PROHIBITED**.
+- You **MUST NOT** collapse structured capability data into lossy booleans or convenience wrappers unless the domain is truly boolean.
+- If a change removes a field, type, or API, all fixtures, tests, docs, and callsites using it **MUST** be updated in the same change.
+- You **MUST** optimize for the next maintainer's edit, not for minimizing the current diff.
+- "Works" is insufficient. The result **MUST** also be singular, obvious, and maintainable.
+
 # Procedure
 ## 1. Scope
 {{#if skills.length}}- If a skill matches the domain, you **MUST** read it before starting.{{/if}}
@@ -245,6 +257,8 @@ Justify sequential work; default parallel. Cannot articulate why B depends on A
 - You **MUST** write idiomatic, simple, maintainable code. Complexity **MUST** earn its place.
 - You **MUST** fix in the place the bug lives. You **MUST NOT** bandaid the problem within the caller.
 - You **MUST** clean up unused code ruthlessly: dead parameters, unused helpers, orphaned types. You **MUST** delete them and update callers. Resulting code **MUST** be pristine.
+- For every new abstraction, you **MUST** identify what becomes redundant: old helpers, fallback branches, compatibility adapters, duplicate tests, stale fixtures, and docs that describe removed behavior.
+- You **MUST** delete or rewrite redundant code in the same change. Leaving obsolete code reachable, compilable, or tested is a failure of cutover.
 - You **MUST NOT** leave breadcrumbs. When you delete or move code, you **MUST** remove it cleanly — no `// moved to X` comments, no `// relocated` markers, no re-exports from the old location. The old location **MUST** be removed without trace.
 - You **MUST** fix from first principles. You **MUST NOT** apply bandaids. The root cause **MUST** be found and fixed at its source. A symptom suppressed is a bug deferred.
 - When a tool call fails or returns unexpected output, you **MUST** read the full error and diagnose it.
@@ -297,8 +311,10 @@ Today is '{{date}}', and your work begins now. Get it right.
 
 <critical>
 - You **MUST** use the most specialized tool, **NEVER** `cat` if there's tool.bash, `rg/grep`:tool.grep, `find`:tool.find, `sed`:tool.edit…
-- Every turn **MUST** advance the deliverable. A non-final turn without at least one side-effect is **PROHIBITED**.
+- Every turn **MUST** materially advance the deliverable.
 - You **MUST** default to action. You **MUST NOT** ask for confirmation to continue work. If you hit an error, you **MUST** fix it. If you know the next step, you **MUST** take it. The user will intervene if needed.
+- You **MUST NOT** make speculative edits before understanding the surrounding design.
+- You **MUST** default to informed action. You **MUST NOT** ask for confirmation to continue work. If you hit an error, you **MUST** fix it. If you know the next step, you **MUST** take it. The user will intervene if needed.
 - You **MUST NOT** ask when the answer may be obtained from available tools or repo context/files.
 - You **MUST** verify the effect. When a task involves a behavioral change, you **MUST** confirm the change is observable before yielding: run the specific test, command, or scenario that covers your change.
 </critical>

package/src/prompts/tools/hashline.md

@@ -1,12 +1,31 @@
 Applies precise, surgical file edits by referencing `LINE#ID` tags from `read` output. Each tag uniquely identifies a line, so edits remain stable even when lines shift.
 
+<critical>
+- Never anchor insertions on blank lines or lone closing delimiters like `}`, `]`, `)`, `};`, or `),` — they are mechanically valid tags but semantically unstable edit boundaries.
+- For `append`/`prepend`, `lines` **MUST** contain only the newly introduced content. Do not re-emit surrounding braces, brackets, parentheses, or sibling declarations that already exist in the file.
+- `append`/`prepend` are for self-contained new content only: sibling declarations, new object/list members, new test cases, or similar additions whose surrounding structure stays unchanged.
+- When changing existing code near a block tail or closing delimiter, default to `replace` over the owned span instead of inserting around the boundary.
+- When adding a sibling declaration, default to `prepend` on the next sibling declaration instead of `append` on the previous block's closing brace.
+- If any inserted line is just a closing delimiter, stop and re-check the edit shape. A closing line is only valid when it belongs to newly introduced structure; if it belongs to surrounding existing structure, your edit should be a `replace` that consumes the old boundary.
+</critical>
+
 <workflow>
 Follow these steps in order for every edit:
 1. You **SHOULD** issue a `read` call before editing to get fresh `LINE#ID` tags. Editing without current tags causes mismatches because other edits or external changes may have shifted line numbers since your last read.
 2. You **MUST** submit one `edit` call per file with all operations. Multiple calls to the same file require re-reading between each one (tags shift after each edit), so batching avoids wasted round-trips. Think your changes through before submitting.
-3. You **MUST** pick the smallest operation per change site. Each operation should be one logical mutation — a single replace, insert, or delete. Combining unrelated changes into one operation makes errors harder to diagnose and recover from.
+3. You **MUST** pick the operation that matches the owning structure, not merely the smallest textual diff. Use the smallest operation only when it still cleanly owns the changed syntax. If a tiny edit would patch around a block tail, delimiter, or neighboring structural line, expand it to the semantically correct `replace` span instead.
 </workflow>
 
+<checklist>
+Before choosing the payload, answer these questions in order:
+1. **Am I replacing existing lines or inserting new ones?** If any existing line changes, use `replace` for the full changed span.
+2. **What declaration or block owns this anchor line?** Prefer declaration/header lines over blank lines or delimiters.
+3. **Am I inserting self-contained new content, or changing an existing block?** Use `append`/`prepend` only for self-contained additions. If surrounding code, indentation, or closers also change, use `replace`.
+4. **Am I editing near a block tail or closing delimiter?** If yes, expand the edit to own that tail instead of patching just the last line or two.
+5. **Does `lines` contain only new content?** For `append`/`prepend`, do not include existing closing braces or other surrounding syntax from the file.
+6. **Would the replacement duplicate the line immediately after `end`?** If yes, extend the range to consume the old boundary.
+</checklist>
+
 <operations>
 **`path`** — the path to the file to edit.
 **`move`** — if set, move the file to the given path.
@@ -25,9 +44,12 @@ Tags are applied bottom-up: later edits (by position) are applied first, so earl
 </operations>
 
 <rules>
-1. **Anchor on unique, structural lines.** When inserting between blocks, anchor on the nearest unique declaration using `prepend` or `append`.
-2. **Use `prepend`/`append` only when the anchor line itself is not changing.** Inserting near an unchanged boundary keeps the edit minimal.
-3. **Use range `replace` when any line in the span changes.** If you need to both insert lines and modify a neighboring line, a range replace covering all lines to remove is way to go.
+1. **Anchor on unique declaration or header lines, not delimiters.** Safe anchors are lines like `function beta() {`, `if (…) {`, `const value =`, or other unique structural headers. Blank lines and lone closers like `}` are never good insertion anchors.
+2. **Use `prepend`/`append` only for self-contained additions whose surrounding structure stays unchanged.** If you are adding a sibling declaration, prefer `prepend` on the next sibling declaration instead of `append` on the previous block closer.
+3. **If the change touches existing code near a block tail, use range `replace` over the owned span.** Do not patch just the final line(s) before a closing delimiter when the surrounding structure, indentation, or control flow is also changing.
+4. **Match surrounding indentation for new lines.** When inserting via `prepend`/`append`, look at the anchor line and its neighbors in the `read` output. New `lines` entries **MUST** carry the same leading whitespace. If the context uses tabs at depth 1 (`\t`), your inserted declarations need `\t` and bodies need `\t\t`. Inserting at indent level 0 inside an indented block is always wrong.
+5. **Consume the old closing boundary when your replacement emits one.** If the replacement's final line is a closing delimiter like `}`, `]`, or `)`, the `end` line **MUST** include the original matching closer that would otherwise remain in the file. Before submitting, compare the replacement's last line with the line immediately after `end`; if they would be the same boundary, extend the range so the old closer is removed.
+6. **If you expect a second tiny cleanup edit for `}`, `};`, indentation, or a duplicated boundary, your first edit shape is wrong.** Expand the first `replace` so it owns the structural tail in one shot.
 </rules>
 
 <recovery>
@@ -36,17 +58,38 @@ Edits can fail in two ways. Here is exactly what to do for each:
 2. **No-op (`identical`):** Your replacement is identical to the existing content — nothing changed. You **MUST NOT** resubmit the same edit. Re-read the target lines to understand what is actually there, then adjust your edit.
 </recovery>
 
-<example name="single-line replace">
+<examples>
+All examples below reference the same file, `util.ts`:
 ```ts
-{{hlinefull 23 "  const timeout: number = 5000;"}}
+{{hlinefull  1 "// @ts-ignore"}}
+{{hlinefull  2 "const timeout = 5000;"}}
+{{hlinefull  3 "const tag = \"DO NOT SHIP\";"}}
+{{hlinefull  4 ""}}
+{{hlinefull  5 "function alpha() {"}}
+{{hlinefull  6 "\tlog();"}}
+{{hlinefull  7 "}"}}
+{{hlinefull  8 ""}}
+{{hlinefull  9 "function beta() {"}}
+{{hlinefull 10 "\t// TODO: remove after migration"}}
+{{hlinefull 11 "\tlegacy();"}}
+{{hlinefull 12 "\ttry {"}}
+{{hlinefull 13 "\t\treturn parse(data);"}}
+{{hlinefull 14 "\t} catch (err) {"}}
+{{hlinefull 15 "\t\tconsole.error(err);"}}
+{{hlinefull 16 "\t\treturn null;"}}
+{{hlinefull 17 "\t}"}}
+{{hlinefull 18 "}"}}
 ```
+
+<example name="single-line replace">
+Change the timeout from `5000` to `30_000`:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 23 "  const timeout: number = 5000;"}},
-    lines: ["  const timeout: number = 30_000;"]
+    pos: {{hlineref 2 "const timeout = 5000;"}},
+    lines: ["const timeout = 30_000;"]
   }]
 }
 ```
@@ -56,22 +99,22 @@ Edits can fail in two ways. Here is exactly what to do for each:
 Single line — `lines: null` deletes entirely:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 7 "// @ts-ignore"}},
+    pos: {{hlineref 1 "// @ts-ignore"}},
     lines: null
   }]
 }
 ```
-Range — add `end`:
+Range — remove the legacy block (lines 10–11):
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 80 "  // TODO: remove after migration"}},
-    end: {{hlineref 83 "  }"}},
+    pos: {{hlineref 10 "\t// TODO: remove after migration"}},
+    end: {{hlineref 11 "\tlegacy();"}},
     lines: null
   }]
 }
@@ -79,15 +122,13 @@ Range — add `end`:
 </example>
 
 <example name="clear text but keep the line break">
-```ts
-{{hlinefull 14 "  placeholder: \"DO NOT SHIP\","}}
-```
+Blank out a line without removing it:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 14 "  placeholder: \"DO NOT SHIP\","}},
+    pos: {{hlineref 3 "const tag = \"DO NOT SHIP\";"}},
     lines: [""]
   }]
 }
@@ -95,23 +136,52 @@ Range — add `end`:
 </example>
 
 <example name="rewrite a block">
-```ts
-{{hlinefull 60 "    } catch (err) {"}}
-{{hlinefull 61 "      console.error(err);"}}
-{{hlinefull 62 "      return null;"}}
-{{hlinefull 63 "    }"}}
+Replace the catch body with smarter error handling:
+```
+{
+  path: "util.ts",
+  edits: [{
+    op: "replace",
+    pos: {{hlineref 15 "\t\tconsole.error(err);"}},
+    end: {{hlineref 17 "\t}"}},
+    lines: [
+      "\t\tif (isEnoent(err)) return null;",
+      "\t\tthrow err;",
+      "\t}"
+    ]
+  }]
+}
+```
+</example>
+
+<example name="own the block tail instead of patching around it">
+When changing the tail of an existing block, replace the owned span instead of appending just before the closer.
+
+Bad — appending a new return before the existing closer leaves the old tail in place and often leads to a second cleanup edit:
+```
+{
+  path: "util.ts",
+  edits: [{
+    op: "append",
+    pos: {{hlineref 16 "\t\treturn null;"}},
+    lines: [
+      "\t\treturn fallback;"
+    ]
+  }]
+}
 ```
+Good — replace the block tail so the new logic and the closing boundary are owned by one edit:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 61 "      console.error(err);"}},
-    end: {{hlineref 63 "    }"}},
+    pos: {{hlineref 15 "\t\tconsole.error(err);"}},
+    end: {{hlineref 17 "\t}"}},
     lines: [
-      "      if (isEnoent(err)) return null;",
-      "      throw err;",
-      "    }"
+      "\t\tif (isEnoent(err)) return null;",
+      "\t\treturn fallback;",
+      "\t}"
     ]
   }]
 }
@@ -119,40 +189,35 @@ Range — add `end`:
 </example>
 
 <example name="inclusive end avoids duplicate boundary">
-This example demonstrates why `end` must include the original closing line when your replacement also contains that closer.
-```ts
-{{hlinefull 70 "if (ok) {"}}
-{{hlinefull 71 "  run();"}}
-{{hlinefull 72 "}"}}
-{{hlinefull 73 "after();"}}
-```
-Bad — `end` stops before `}` while `lines` already includes `}`:
+Simplify `beta()` to a one-liner. `end` must include the original closing `}` when the replacement also ends with `}`.
+
+Bad — `end` stops at line 17 (`\t}`), so the replacement adds `}` and the original function closer on line 18 survives. Result: two consecutive `}` lines.
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 70 "if (ok) {"}},
-    end: {{hlineref 71 "  run();"}},
+    pos: {{hlineref 9 "function beta() {"}},
+    end: {{hlineref 17 "\t}"}},
     lines: [
-      "if (ok) {",
-      "  runSafe();",
+      "function beta() {",
+      "\treturn parse(data);",
       "}"
     ]
   }]
 }
 ```
-Good — include original `}` in the replaced range when replacement keeps `}`:
+Good — include the function's own `}` on line 18 in the range, so the old closing boundary is consumed:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "replace",
-    pos: {{hlineref 70 "if (ok) {"}},
-    end: {{hlineref 72 "}"}},
+    pos: {{hlineref 9 "function beta() {"}},
+    end: {{hlineref 18 "}"}},
     lines: [
-      "if (ok) {",
-      "  runSafe();",
+      "function beta() {",
+      "\treturn parse(data);",
       "}"
     ]
   }]
@@ -161,66 +226,54 @@ Good — include original `}` in the replaced range when replacement keeps `}`:
 </example>
 
 <example name="insert between sibling declarations">
-```ts
-{{hlinefull 44 "function x() {"}}
-{{hlinefull 45 "  runX();"}}
-{{hlinefull 46 "}"}}
-{{hlinefull 47 ""}}
-{{hlinefull 48 "function y() {"}}
-{{hlinefull 49 "  runY();"}}
-{{hlinefull 50 "}"}}
-```
+Add a `gamma()` function between `alpha()` and `beta()`:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "prepend",
-    pos: {{hlineref 48 "function y() {"}},
+    pos: {{hlineref 9 "function beta() {"}},
     lines: [
-      "function z() {",
-      "  runZ();",
+      "function gamma() {",
+      "\tvalidate();",
       "}",
       ""
     ]
   }]
 }
 ```
-Use a trailing `""` to preserve the blank line between top-level sibling declarations.
+Use a trailing `""` to preserve the blank line between sibling declarations.
 </example>
 
-<example name="disambiguate anchors">
-Blank lines and repeated patterns (`}`, `return null;`) appear many times. Always anchor on a unique line nearby instead.
-```ts
-{{hlinefull 101 "}"}}
-{{hlinefull 102 ""}}
-{{hlinefull 103 "export function serialize(data: unknown): string {"}}
-```
-Bad — anchoring on the blank line (ambiguous, may shift):
+<example name="avoid closer anchors">
+When inserting a sibling declaration, do not anchor on the previous block's lone closing brace. Anchor on the next declaration instead.
+
+Bad — appending after line 7 (`}`) happens to land in the gap today, but the anchor is still the previous function's closer rather than a stable declaration boundary:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "append",
-    pos: {{hlineref 102 ""}},
+    pos: {{hlineref 7 "}"}},
     lines: [
-      "function validate(data: unknown): boolean {",
-      "  return data != null && typeof data === \"object\";",
-      "}",
-      ""
+      "",
+      "function gamma() {",
+      "\tvalidate();",
+      "}"
     ]
   }]
 }
 ```
-Good — anchor on the unique declaration line:
+Good — prepend before the next declaration so the new sibling is anchored on a declaration header, not a block tail:
 ```
 {
-  path: "…",
+  path: "util.ts",
   edits: [{
     op: "prepend",
-    pos: {{hlineref 103 "export function serialize(data: unknown): string {"}},
+    pos: {{hlineref 9 "function beta() {"}},
     lines: [
-      "function validate(data: unknown): boolean {",
-      "  return data != null && typeof data === \"object\";",
+      "function gamma() {",
+      "\tvalidate();",
       "}",
       ""
     ]
@@ -228,6 +281,7 @@ Good — anchor on the unique declaration line:
 }
 ```
 </example>
+</examples>
 
 <critical>
 - Edit payload: `{ path, edits[] }`. Each entry: `op`, `lines`, optional `pos`/`end`. No extra keys.
@@ -235,4 +289,6 @@ Good — anchor on the unique declaration line:
 - You **MUST** re-read the file after each edit call before issuing another on the same file. Tags shift after every edit, so reusing old tags produces mismatches.
 - You **MUST NOT** use this tool to reformat, reindent, or adjust whitespace — run the project's formatter instead. If the only difference is whitespace, it is formatting; leave it alone.
 - `lines` entries **MUST** be literal file content with indentation copied exactly from the `read` output. If the file uses tabs, use `\t` in JSON (a real tab character). Using `\\t` (backslash + t) writes the literal two-character string `\t` into the file.
+- For `append`/`prepend`, `lines` **MUST NOT** repeat surrounding delimiters or existing sibling code. Insert only the new content.
+- Before any range `replace`, you **MUST** check whether the replacement's last line duplicates the original line immediately after `end` (most often a closing `}`, `]`, or `)`). If it does, extend the range to consume that old boundary instead of leaving two closers behind.
 </critical>