@oh-my-pi/pi-coding-agent 12.13.0 → 12.14.0

package/src/prompts/tools/bash.md

@@ -8,7 +8,7 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - `skill://` URIs are auto-resolved to filesystem paths before execution
 	- `python skill://my-skill/scripts/init.py` runs the script from the skill directory
 	- `skill://<name>/<relative-path>` resolves within the skill's base directory
-- `agent://`, `artifact://`, `plan://`, `memory://`, and `rule://` URIs are also auto-resolved to filesystem paths before execution
+- `agent://`, `artifact://`, `plan://`, `memory://`, `rule://`, and `docs://` URIs are also auto-resolved to filesystem paths before execution
 </instruction>
 
 <output>

package/src/prompts/tools/grep.md

@@ -13,7 +13,7 @@ Powerful search tool built on ripgrep.
 <output>
 - Results are always content mode.
 {{#if IS_HASHLINE_MODE}}
-- Text output is CID prefixed: `LINE#ID|content`
+- Text output is CID prefixed: `LINE#ID:content`
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Text output is line-number-prefixed

package/src/prompts/tools/hashline.md

@@ -1,31 +1,34 @@
-# Edit (Hash Anchored)
+# Edit
 
-Apply precise file edits using `LINE#ID` anchors from `read` output.
-**CRITICAL:** anchors are `LINE#ID` only. Copy verbatim from the prefix (example: `{{hlineref 42 "const x = 1"}}`). Never include `|content`.
+Apply precise file edits using `LINE#ID` tags, anchoring to the file content.
 
 <workflow>
-1. `read` the target range to capture current `LINE#ID` anchors.
-2. Pick the smallest operation per change site (`set`/`set_range`/`insert`/`replace`).
-3. Direction-lock every edit: exact current text -> intended text.
+1. `read` the target range to capture current `LINE#ID` tags.
+2. Pick the smallest operation per change site (line/range/insert/content-replace).
+3. Direction-lock every edit: exact current text → intended text.
 4. Submit one `edit` call per file containing all operations.
 5. If another edit is needed in that file, re-read first (hashes changed).
 6. Output tool calls only; no prose.
 </workflow>
 
 <operations>
-- **`set`** (single line replace/delete)
-  - `{ set: { ref: "LINE#ID", body: ["..."] } }`
-  - `body: []` deletes the line; `body: [""]` keeps a blank line.
-- **`set_range`** (contiguous multi-line replace/delete)
-  - `{ set_range: { beg: "LINE#ID", end: "LINE#ID", body: ["..."] } }`
-  - Use for swaps, block rewrites, or deleting a full span (`body: []`).
-- **`insert`** (new content)
-  - `{ insert: { before: "LINE#ID", body: ["..."] } }`
-  - `{ insert: { after: "LINE#ID", body: ["..."] } }`
-  - `{ insert: { after: "LINE#ID", before: "LINE#ID", body: ["..."] } }` (between adjacent anchors; safest for blocks)
-  - `{ insert: { body: ["..."] } }` (append EOF only when intentional)
-- **`replace`** (fuzzy text fallback when anchors unavailable)
-  - `{ replace: { old_text: "...", new_text: "...", all?: boolean } }`
+- **Single line replace/delete**
+  - `{ op: "set", tag: "N#ID", content: […] }`
+  - `content: null` deletes the line; `content: [""]` keeps a blank line.
+- **Range replace/delete**
+  - `{ op: "replace", first: "N#ID", last: "N#ID", content: […] }`
+  - Use for swaps, block rewrites, or deleting a full span (`content: null`).
+- **Insert** (new content)
+  - `{ op: "prepend", before: "N#ID", content: […] }` or `{ op: "prepend", content: […] }` (no `before` = insert at beginning of file)
+  - `{ op: "append", after: "N#ID", content: […] }` or `{ op: "append", content: […] }` (no `after` = insert at end of file)
+  - `{ op: "insert", after: "N#ID", before: "N#ID", content: […] }` (between adjacent anchors; safest for blocks)
+{{#if allowReplaceText}}
+- **Content replace**
+  - `{ op: "replaceText", old_text: "…", new_text: "…", all?: boolean }`
+{{/if}}
+- **File-level controls**
+  - `{ delete: true, edits: [] }` deletes the file (cannot be combined with `rename`).
+  - `{ rename: "new/path.ts", edits: […] }` writes result to new path and removes old path.
 **Atomicity:** all ops validate against the same pre-edit file snapshot; refs are interpreted against last `read`; applicator applies bottom-up.
 </operations>
 
@@ -33,98 +36,197 @@ Apply precise file edits using `LINE#ID` anchors from `read` output.
 1. **Minimize scope:** one logical mutation site per operation.
 2. **Preserve formatting:** keep indentation, punctuation, line breaks, trailing commas, brace style.
 3. **Prefer insertion over neighbor rewrites:** anchor on structural boundaries (`}`, `]`, `},`) not interior property lines.
-4. **No no-ops:** replacement body must differ from current content.
+4. **No no-ops:** replacement content must differ from current content.
 5. **Touch only requested code:** avoid incidental edits.
-6. **Use exact current tokens:** never "rewrite approximately"; mutate the token that exists now.
-7. **For swaps/moves:** prefer one `set_range` over multiple conflicting `set`s.
+6. **Use exact current tokens:** never rewrite approximately; mutate the token that exists now.
+7. **For swaps/moves:** prefer one range operation over multiple single-line operations.
 </rules>
 
-<selection_heuristics>
-- One wrong line -> `set`
-- Adjacent block changed -> `set_range`
-- Missing line/block -> `insert`
-- Cannot trust line anchors (generated/unknown offsets) -> `replace` (last resort)
-</selection_heuristics>
-
-<anchor_hygiene>
-- Copy anchor IDs exactly from `read` or error output.
-- Never handcraft hashes.
-- For inserts, prefer `after+before` dual anchors when both boundaries are known.
+<op_choice>
+- One wrong line → `set`
+- Adjacent block changed → `insert`
+- Missing line/block → insert with `append`/`prepend`
+</op_choice>
+
+<tag_choice>
+- Copy tags exactly from the prefix of the `read` or error output.
+- Never guess tags.
+- For inserts, prefer `insert` > `append`/`prepend` when both boundaries are known.
 - Re-read after each successful edit call before issuing another on same file.
-</anchor_hygiene>
+</tag_choice>
 
 <recovery>
-**Hash mismatch (`>>>`)**
-- Retry with the updated anchors shown in error output.
-- Re-read only if required anchors are missing from error snippet.
+**Tag mismatch (`>>>`)**
+- Retry with the updated tags shown in error output.
+- Re-read only if required tags are missing from error snippet.
 - If mismatch repeats, stop and re-read the exact block.
-**No-op / identical content**
-- Re-read immediately; target is stale or replacement equals current text.
-- After two no-ops on same area, re-read the full function/block before retry.
 </recovery>
 
-<examples>
-<example name="single-line token fix (set)">
-Read:
-{{hlinefull 41 "  return record != null && record.status === 'fulfilled';"}}
-Edit:
-set: { ref: "{{hlineref 41 "  return record != null && record.status === 'fulfilled';"}}", body: ["  return record != null && record?.status === 'fulfilled';"] }
+<example name="fix a value or type">
+```ts
+{{hlinefull 23 "  const timeout: number = 5000;"}}
+```
+```
+op: "set"
+tag: "{{hlineref 23 "  const timeout: number = 5000;"}}"
+content: ["  const timeout: number = 30_000;"]
+```
+</example>
+
+<example name="remove a line entirely">
+```ts
+{{hlinefull 7 "// @ts-ignore"}}
+{{hlinefull 8 "const data = fetchSync(url);"}}
+```
+```
+op: "set"
+tag: "{{hlineref 7 "// @ts-ignore"}}"
+content: null
+```
+</example>
+
+<example name="clear content but keep the line break">
+```ts
+{{hlinefull 14 "  placeholder: \"DO NOT SHIP\","}}
+```
+```
+op: "set"
+tag: "{{hlineref 14 "  placeholder: \"DO NOT SHIP\","}}"
+content: [""]
+```
+</example>
+
+<example name="rewrite a block of logic">
+```ts
+{{hlinefull 60 "    } catch (err) {"}}
+{{hlinefull 61 "      console.error(err);"}}
+{{hlinefull 62 "      return null;"}}
+{{hlinefull 63 "    }"}}
+```
+```
+op: "replace"
+first: "{{hlineref 60 "    } catch (err) {"}}"
+last: "{{hlineref 63 "    }"}}"
+content: ["    } catch (err) {", "      if (isEnoent(err)) return null;", "      throw err;", "    }"]
+```
 </example>
 
-<example name="restore missing declaration (insert before)">
-Read:
-{{hlinefull 15 "export function useX(...): boolean {"}}
-{{hlinefull 16 "  useEffect(() => {"}}
-Edit:
-insert: { before: "{{hlineref 16 "  useEffect(() => {"}}", body: ["  const [isVisible, setIsVisible] = useState(true);"] }
+<example name="remove a full block">
+```ts
+{{hlinefull 80 "  // TODO: remove after migration"}}
+{{hlinefull 81 "  if (legacy) {"}}
+{{hlinefull 82 "    legacyHandler(req);"}}
+{{hlinefull 83 "  }"}}
+```
+```
+op: "replace"
+first: "{{hlineref 80 "  // TODO: remove after migration"}}"
+last: "{{hlineref 83 "  }"}}"
+content: null
+```
 </example>
 
-<example name="insert between siblings (after+before)">
-Read:
-{{hlinefull 120 "      doFirst();"}}
-{{hlinefull 121 "      doThird();"}}
-Edit:
-insert: { after: "{{hlineref 120 "      doFirst();"}}", before: "{{hlineref 121 "      doThird();"}}", body: ["      doSecond();"] }
+<example name="add an import above the first import">
+```ts
+{{hlinefull 1 "import * as fs from \"node:fs/promises\";"}}
+{{hlinefull 2 "import * as path from \"node:path\";"}}
+```
+```
+op: "prepend"
+before: "{{hlineref 1 "import * as fs from \"node:fs/promises\";"}}"
+content: ["import * as os from \"node:os\";"]
+```
+Use `before` for anchored insertion before a specific line. Omit `before` to prepend at BOF.
 </example>
 
-<example name="swap adjacent lines atomically (set_range)">
-Read:
-{{hlinefull 190 "      thenable.then(resolve, ignoreReject);"}}
-{{hlinefull 191 "      chunkCache.set(chunkId, thenable);"}}
-Edit:
-set_range: { beg: "{{hlineref 190 "      thenable.then(resolve, ignoreReject);"}}", end: "{{hlineref 191 "      chunkCache.set(chunkId, thenable);"}}", body: ["      chunkCache.set(chunkId, thenable);", "      thenable.then(resolve, ignoreReject);"] }
+<example name="append at end of file">
+```ts
+{{hlinefull 260 "export { serialize, deserialize };"}}
+```
+```
+op: "append"
+after: "{{hlineref 260 "export { serialize, deserialize };"}}"
+content: ["export { validate };"]
+```
+Use `after` for anchored insertion after a specific line. Omit `after` to append at EOF.
 </example>
 
-<example name="insert guard before comment">
-Read:
-{{hlinefull 188 ""}}
-{{hlinefull 189 "          // If we don't find a Fiber on the comment..."}}
-Edit:
-insert: { after: "{{hlineref 188 ""}}", body: ["          if (targetFiber) {", "            targetInst = targetFiber;", "          }"] }
+<example name="add an entry between known siblings">
+```ts
+{{hlinefull 44 "  \"build\": \"bun run compile\","}}
+{{hlinefull 45 "  \"test\": \"bun test\""}}
+```
+```
+op: "insert"
+after: "{{hlineref 44 "  \"build\": \"bun run compile\","}}"
+before: "{{hlineref 45 "  \"test\": \"bun test\""}}"
+content: ["  \"lint\": \"biome check\","]
+```
+Dual anchors pin the insert to exactly one gap, preventing drift from edits elsewhere in the file. **Always prefer dual anchors when both boundaries are content lines.**
 </example>
 
-<example name="anti-pattern: interior anchor vs boundary anchor">
-Bad:
-insert: { after: "195#d3", body: ["  { id: \"nanogpt\", available: true },"] }
-Good:
-insert: { after: "196#f6", before: "197#fc", body: [" { id: \"nanogpt\", available: true },"] }
+<example name="insert a function before another function">
+```ts
+{{hlinefull 100 "  return buf.toString(\"hex\");"}}
+{{hlinefull 101 "}"}}
+{{hlinefull 102 ""}}
+{{hlinefull 103 "export function serialize(data: unknown): string {"}}
+```
+```
+op: "insert"
+before: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
+content: ["function validate(data: unknown): boolean {", "  return data != null && typeof data === \"object\";", "}", ""]
+```
+The trailing `""` in `content` preserves the blank-line separator. **Anchor to the structural line (`export function ...`), not the blank line above it** — blank lines are ambiguous and may be added or removed by other edits.
 </example>
 
-<example name="explicit EOF append">
-insert: { body: ["// end marker"] }
+{{#if allowReplaceText}}
+<example name="content replace (rare)">
+```
+op: "replaceText"
+old_text: "x = 42"
+new_text: "x = 99"
+```
+
+Use only when line anchors aren't available. `old_text` must match exactly one location in the file (or set `"all": true` for all occurrences).
 </example>
+{{/if}}
 
-<example name="replace fallback only">
-replace: { old_text: "x = 42", new_text: "x = 99" }
+<example name="file delete">
+```
+path: "src/deprecated/legacy.ts"
+delete: true
+```
 </example>
-</examples>
-
-<validation>
-- [ ] Payload shape is `{ "path": string, "edits": [operation, ...] }` and `edits` is non-empty
-- [ ] Every operation has exactly one variant key: `set` | `set_range` | `insert` | `replace`
-- [ ] Every anchor is copied exactly as `LINE#ID` (no spaces, no `|content`)
-- [ ] `body` lines are raw content only (no diff markers, no anchor prefixes)
-- [ ] Every replacement is meaningfully different from current content
-- [ ] Scope is minimal and formatting is preserved except targeted token changes
-</validation>
-**Final reminder:** anchors are immutable references to the last read snapshot. Re-read when state changes, then edit.
+
+<example name="file rename with edits">
+```
+path: "src/utils.ts"
+rename: "src/helpers/utils.ts"
+edits: […]
+```
+</example>
+
+<example name="anti-pattern: anchoring to whitespace">
+Bad — tags to a blank line; fragile if blank lines shift:
+```
+after: "{{hlineref 102 ""}}"
+content: ["function validate() {", …, "}"]
+```
+
+Good — anchors to the structural target:
+
+```
+before: "{{hlineref 103 "export function serialize(data: unknown): string {"}}"
+content: ["function validate() {", …, "}"]
+```
+</example>
+
+<critical>
+Ensure:
+- Payload shape is `{ "path": string, "edits": [operation, …], "delete"?: boolean, "rename"?: string }`
+- Every edit matches exactly one variant
+- Every tag has been copied EXACTLY from a tool result as `N#ID`
+- Scope is minimal and formatting is preserved except targeted token changes
+</critical>
+**Final reminder:** tags are immutable references to the last read snapshot. Re-read when state changes, then edit.

package/src/prompts/tools/read.md

@@ -6,7 +6,7 @@ Reads files from local filesystem or internal URLs.
 - Reads up to {{DEFAULT_MAX_LINES}} lines default
 - Use `offset` and `limit` for large files
 {{#if IS_HASHLINE_MODE}}
-- Text output is CID prefixed: `LINE#ID|content`
+- Text output is CID prefixed: `LINE#ID:content`
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Text output is line-number-prefixed
@@ -23,6 +23,8 @@ Reads files from local filesystem or internal URLs.
   - `memory://root/<path>` - read relative path within project memory root
   - `agent://<id>` - read agent output artifact
   - `agent://<id>/<path>` or `agent://<id>?q=<query>` - extract JSON from agent output
+  - `docs://` - list available pi documentation files
+  - `docs://<file>.md` - read a specific pi documentation file
 </instruction>
 
 <output>

package/src/sdk.ts

@@ -19,6 +19,7 @@ import {
 	type CustomCommandsLoadResult,
 	loadCustomCommands as loadCustomCommandsInternal,
 } from "./extensibility/custom-commands";
+import { discoverAndLoadCustomTools } from "./extensibility/custom-tools";
 import type { CustomTool, CustomToolContext, CustomToolSessionEvent } from "./extensibility/custom-tools/types";
 import { CustomToolAdapter } from "./extensibility/custom-tools/wrapper";
 import {
@@ -39,6 +40,7 @@ import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal }
 import {
 	AgentProtocolHandler,
 	ArtifactProtocolHandler,
+	DocsProtocolHandler,
 	InternalUrlRouter,
 	MemoryProtocolHandler,
 	PlanProtocolHandler,
@@ -770,6 +772,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getRules: () => rulebookRules,
 		}),
 	);
+	internalRouter.register(new DocsProtocolHandler());
 	toolSession.internalRouter = internalRouter;
 	toolSession.getArtifactsDir = getArtifactsDir;
 	toolSession.agentOutputManager = new AgentOutputManager(
@@ -848,6 +851,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		time("getSearchTools");
 	}
 
+	debugStartup("sdk:discoverCustomTools:start");
+	// Discover and load custom tools from .omp/tools/, .claude/tools/, etc.
+	const builtInToolNames = builtinTools.map(t => t.name);
+	const discoveredCustomTools = await discoverAndLoadCustomTools([], cwd, builtInToolNames);
+	for (const { path, error } of discoveredCustomTools.errors) {
+		logger.error("Custom tool load failed", { path, error });
+	}
+	if (discoveredCustomTools.tools.length > 0) {
+		customTools.push(...discoveredCustomTools.tools.map(loaded => loaded.tool));
+	}
+	time("discoverAndLoadCustomTools");
+	debugStartup("sdk:discoverCustomTools:done");
+
 	const inlineExtensions: ExtensionFactory[] = options.extensions ? [...options.extensions] : [];
 	if (customTools.length > 0) {
 		inlineExtensions.push(createCustomToolsExtension(customTools));
@@ -1207,6 +1223,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		},
 		cursorExecHandlers,
 		transformToolCallArguments: obfuscator?.hasSecrets() ? args => obfuscator!.deobfuscateObject(args) : undefined,
+		intentTracing: settings.get("tools.intentTracing") || $env.PI_INTENT_TRACING === "1",
 	});
 	cursorEventEmitter = event => agent.emitExternalEvent(event);
 	debugStartup("sdk:createAgent");

package/src/session/agent-session.ts

@@ -1140,6 +1140,7 @@ export class AgentSession {
 				toolCallId: event.toolCallId,
 				toolName: event.toolName,
 				args: event.args,
+				intent: event.intent,
 			};
 			await this.#extensionRunner.emit(extensionEvent);
 		} else if (event.type === "tool_execution_update") {

package/src/tools/fetch.ts

@@ -966,11 +966,12 @@ function countNonEmptyLines(text: string): number {
 
 /** Render fetch call (URL preview) */
 export function renderFetchCall(
-	args: { url: string; timeout?: number; raw?: boolean },
+	args: { url?: string; timeout?: number; raw?: boolean },
 	uiTheme: Theme = theme,
 ): Component {
-	const domain = getDomain(args.url);
-	const path = truncate(args.url.replace(/^https?:\/\/[^/]+/, ""), 50, "…");
+	const url = args.url ?? "";
+	const domain = getDomain(url);
+	const path = truncate(url.replace(/^https?:\/\/[^/]+/, ""), 50, "\u2026");
 	const description = `${domain}${path ? ` ${path}` : ""}`.trim();
 	const meta: string[] = [];
 	if (args.raw) meta.push("raw");

package/src/tools/grep.ts

@@ -104,7 +104,17 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 			const effectiveMultiline = multiline ?? patternHasNewline;
 
 			const useHashLines = resolveFileDisplayMode(this.session).hashLines;
-			const searchPath = resolveToCwd(searchDir || ".", this.session.cwd);
+			let searchPath: string;
+			const internalRouter = this.session.internalRouter;
+			if (searchDir && internalRouter?.canHandle(searchDir)) {
+				const resource = await internalRouter.resolve(searchDir);
+				if (!resource.sourcePath) {
+					throw new ToolError(`Cannot grep internal URL without a backing file: ${searchDir}`);
+				}
+				searchPath = resource.sourcePath;
+			} else {
+				searchPath = resolveToCwd(searchDir || ".", this.session.cwd);
+			}
 			const scopePath = (() => {
 				const relative = path.relative(this.session.cwd, searchPath).replace(/\\/g, "/");
 				return relative.length === 0 ? "." : relative;
@@ -210,10 +220,10 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				const formatLine = (lineNumber: number, line: string, isMatch: boolean): string => {
 					if (useHashLines) {
 						const ref = `${lineNumber}#${computeLineHash(lineNumber, line)}`;
-						return isMatch ? `>>${ref}|${line}` : `  ${ref}|${line}`;
+						return isMatch ? `>>${ref}:${line}` : `  ${ref}:${line}`;
 					}
 					const padded = lineNumber.toString().padStart(lineWidth, " ");
-					return isMatch ? `>>${padded}|${line}` : `  ${padded}|${line}`;
+					return isMatch ? `>>${padded}:${line}` : `  ${padded}:${line}`;
 				};
 
 				// Add context before

package/src/tools/read.ts

@@ -772,7 +772,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const prependHashLines = (text: string, startNum: number): string => {
 				const textLines = text.split("\n");
 				return textLines
-					.map((line, i) => `${startNum + i}#${computeLineHash(startNum + i, line)}|${line}`)
+					.map((line, i) => `${startNum + i}#${computeLineHash(startNum + i, line)}:${line}`)
 					.join("\n");
 			};
 			const formatText = (text: string, startNum: number): string => {
@@ -929,7 +929,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		};
 		const prependHashLines = (text: string, startNum: number): string => {
 			const textLines = text.split("\n");
-			return textLines.map((line, i) => `${startNum + i}#${computeLineHash(startNum + i, line)}|${line}`).join("\n");
+			return textLines.map((line, i) => `${startNum + i}#${computeLineHash(startNum + i, line)}:${line}`).join("\n");
 		};
 		const formatText = (text: string, startNum: number): string => {
 			if (shouldAddHashLines) return prependHashLines(text, startNum);

package/src/web/search/render.ts

@@ -282,11 +282,11 @@ export function renderSearchResult(
 
 /** Render web search call (query preview) */
 export function renderSearchCall(
-	args: { query: string; provider?: string; [key: string]: unknown },
+	args: { query?: string; provider?: string; [key: string]: unknown },
 	theme: Theme,
 ): Component {
 	const provider = args.provider ?? "auto";
-	const query = truncateToWidth(args.query, 80);
+	const query = truncateToWidth(args.query ?? "", 80);
 	const text = renderStatusLine({ icon: "pending", title: "Web Search", description: query, meta: [provider] }, theme);
 	return new Text(text, 0, 0);
 }