pi-hashline-edit-pro 4.5.0 → 4.5.1

package/README.md

@@ -41,7 +41,7 @@ the result is the post-edit diff with fresh anchors, so the next edit needs no r
 - [Configuration](#configuration)
 - [Limits](#limits)
 - [Tool result details](#tool-result-details)
-- [Error and warning codes](#error-and-warning-codes)
+- [Error, warning, and hint codes](#error-warning-and-hint-codes)
 - [Troubleshooting](#troubleshooting)
 - [Privacy and on-disk state](#privacy-and-on-disk-state)
 - [How anchors work](#how-anchors-work)
@@ -390,16 +390,16 @@ All seven tools return machine-readable metadata in `details` alongside the mode
 | Tool | `details` |
 | --- | --- |
 | `read` | `truncation` (set when output was truncated), `snapshotId` (a `v2\|path\|ino\|mtime\|ctime\|size` fingerprint), `nextOffset` (use as the next `offset`), and `metrics` with `truncated` and `next_offset`. |
-| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+anchor│` and ` anchor│` rows; a same-message batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut or skipped for a pair over 1MB and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-message batch membership; earlier members also carry `aborted: true` and `abortMessage` after a batch abort), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
+| `replace`, `insert` | `diff` (post-edit diff, capped, with current anchors on `+anchor│` and ` anchor│` rows; a same-message batch reports the combined diff on its last call and an empty diff on earlier calls), `patch` (a standard unified patch for external tools, capped like the diff), `patchTruncated` (true when the patch was cut or skipped for a pair over 1MB and can no longer be applied as-is), `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when nothing changed), `batch` (`{ id, size, last, total }` marking same-message batch membership; earlier members also carry `aborted: true` and `abortMessage` after a batch abort), `hints` (informative `[H_*]` notices, for example literal escaped text written as sent), and `metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`. |
 | `copy`, `move` | Same shape as `replace`: `diff` (post-edit diff with current anchors), `patch`, `patchTruncated`, `firstChangedLine`, `snapshotId`, `classification` (`"noop"` when a move changes nothing), and `metrics` with the same counters. |
 | `undo_last_change` | `diff` (the undo diff with restored anchors), `patch`, `patchTruncated`, and `metrics` in the same shape as `replace`. |
 | `anchor_grep` | `metrics` with `matches` (capped at `limit`), `files`, and `truncated`; `truncation` (the standard pi truncation report) when output was cut; and `linesTruncated` (true when long lines were shown as fragments). |
 
-`snapshotId`, `firstChangedLine`, and `metrics.warnings` are the three fields external consumers most often read; `snapshotId` is a string fingerprint, `firstChangedLine` is a 1-based line number on the result file, and `metrics.warnings` counts the `[W_*]` notices in `details.warnings`.
+`snapshotId`, `firstChangedLine`, and `metrics.warnings` are the three fields external consumers most often read; `snapshotId` is a string fingerprint, `firstChangedLine` is a 1-based line number on the result file, and `metrics.warnings` counts the `[W_*]` notices in `details.warnings`; hint `[H_*]` notices live in `details.hints` and are not counted.
 
-## Error and warning codes
+## Error, warning, and hint codes
 
-Codes starting with `E_` are errors: nothing was written, with one exception. `File was written; anchor finalization failed` means the file was written and one undo reverts it. Codes starting with `W_` are warnings: the call succeeded with an auto-fix notice or an anchor-reclaim notice; check `classification` (`applied` vs `noop`) in `details.metrics` to tell whether bytes changed. `[E_AUTO_READ_ALL]` is informational rather than a failure: the `read` was refused because the file is unchanged since the start-of-session auto-read, so the attached content is still exact.
+Codes starting with `E_` are errors: nothing was written, with one exception. `File was written; anchor finalization failed` means the file was written and one undo reverts it. Codes starting with `W_` are warnings: the call succeeded with an auto-fix notice or an anchor-reclaim notice; check `classification` (`applied` vs `noop`) in `details.metrics` to tell whether bytes changed. Codes starting with `H_` are hints: the call succeeded and the file holds exactly what was requested, so the notice is informational, never blocks an edit (not even in strict-input mode), and is reported in `details.hints` instead of `details.warnings`. `[E_AUTO_READ_ALL]` is informational rather than a failure: the `read` was refused because the file is unchanged since the start-of-session auto-read, so the attached content is still exact.
 
 Most common, with the fix:
 
@@ -422,8 +422,8 @@ Full reference:
 | `[E_STALE_ANCHOR]` | An anchor is not owned in this session (it was never shown to you, or its line was edited or the file was rewritten); call `read` for fresh anchors. |
 | `[W_INVALID_PATCH]` | A `replacement_lines` element is a diff-preview row (`+anchor│`, `-anchor│`, `-    │`). The marker is stripped automatically with a warning. |
 | `[W_BARE_HASH_PREFIX]` | A `replacement_lines` element starts with an `anchor│` prefix. The prefix is stripped automatically with a warning. |
-| `[W_LITERAL_ESCAPE]` | `lines` or `replacement_lines` contains literal escape text such as `\u200b` or `\n`; the file receives those characters as written. Decode the escapes first if the text came from a quoted prompt. |
 | `[W_ANCHOR_RECLAIMED]` | The session's anchor quota was exhausted, so all anchors of the listed files (the least recently read or edited) were freed to make room. Read those files again before editing them. |
+| `[H_LITERAL_ESCAPE]` | `lines` or `replacement_lines` contains the literal escaped text such as `\u200b` or `\n`; the file receives those characters as written. Decode the escapes first if the text came from a quoted prompt. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. A cross-file `move` may empty its source file. |
 | `[E_NOT_FOUND]` | The path does not exist. |
 | `[E_ACCESS]` | The file is not readable or writable. |

package/index.ts

@@ -11,7 +11,7 @@ import { buildAutoReadAllInjection, autoReadAllBudget } from "./src/auto-read-al
 import { clearAutoReadAllComplete } from "./src/auto-read-all-state";
 import type { RMetrics } from "./src/replace-response";
 import type { ReplaceDetails } from "./src/replace";
-import { extractWarnings } from "./src/replace-render";
+import { extractHints, extractWarnings } from "./src/replace-render";
 import { MAX_HASH_LINES } from "./src/hashline";
 import type { AutoReadAllMode } from "./src/config";
 import {
@@ -266,6 +266,7 @@ export default function (pi: ExtensionAPI): void {
     const toolDetails = event.details as ReplaceDetails | undefined;
     const diff = toolDetails?.diff;
     const detailWarnings = Array.isArray(toolDetails?.warnings) ? toolDetails.warnings.filter((w): w is string => typeof w === "string") : [];
+    const detailHints = Array.isArray(toolDetails?.hints) ? toolDetails.hints.filter((h): h is string => typeof h === "string") : [];
     if (typeof diff !== "string") return;
     const hasDiff = diff.length > 0;
 
@@ -277,12 +278,14 @@ export default function (pi: ExtensionAPI): void {
       .map((entry) => entry.text)
       .join("\n");
     const warnings = detailWarnings.length ? `Warnings:\n${detailWarnings.join("\n")}` : extractWarnings(rendered);
-    const hint = hasDiff ? (warnings ? `${diff}\n\n${warnings}` : diff) : warnings ? `[post-edit] applied successfully; the diff is empty (whitespace-only change).\n\n${warnings}` : "[post-edit] applied successfully; the diff is empty (whitespace-only change).";
+    const hints = detailHints.length ? `Hints:\n${detailHints.join("\n")}` : extractHints(rendered);
+    const notices = [warnings, hints].filter((part): part is string => part !== undefined).join("\n\n");
+    const noticeText = hasDiff ? (notices ? `${diff}\n\n${notices}` : diff) : notices ? `[post-edit] applied successfully; the diff is empty (whitespace-only change).\n\n${notices}` : "[post-edit] applied successfully; the diff is empty (whitespace-only change).";
     return {
       content: [
         {
           type: "text",
-          text: hint,
+          text: noticeText,
         },
       ],
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/prompts/insert.md

@@ -1,3 +1,3 @@
-Insert lines after or before one existing line in a text file, addressed by a bare anchor from any served anchor│content row. The anchor line is preserved: `lines` go after it with `direction: "after"` or before it with `direction: "before"`, one string per line, no anchor prefixes. An element is one line: a real line-break character (`\n`, `\r\n`, or `\r`) splits it and sets that line's ending; escape sequences such as `\n` or `\u200b` are not decoded. Inserted lines are written exactly as given; nothing else in the file changes.
+Insert lines after or before one existing line in a text file, addressed by a bare anchor from any served anchor│content row. The anchor line is preserved: `lines` go after it with `direction: "after"` or before it with `direction: "before"`, one string per line, no anchor prefixes. An element is one line: a real line-break character (`\n`, `\r\n`, or `\r`) splits it and sets that line's ending. Inserted lines are written exactly as given; nothing else in the file changes.
 
 Same-file calls in one message batch: earlier calls reply `In batch N` and the last call shows the combined diff, with one undo for the whole batch.

package/prompts/replace.md

@@ -1,4 +1,4 @@
-Replace a range of lines (or a single line) in a text file, targeted by 4-character anchors from any served anchor│content row. Give `remove_from` and `remove_to` as bare anchors marking the first and last line to remove, and `replacement_lines` as one string per new line with no anchor prefixes. An element is one line: a real line-break character (`\n`, `\r\n`, or `\r`) splits it and sets that line's ending; escape sequences such as `\n` or `\u200b` are not decoded. `[]` deletes the range.
+Replace a range of lines (or a single line) in a text file, targeted by 4-character anchors from any served anchor│content row. Give `remove_from` and `remove_to` as bare anchors marking the first and last line to remove, and `replacement_lines` as one string per new line with no anchor prefixes. An element is one line: a real line-break character (`\n`, `\r\n`, or `\r`) splits it and sets that line's ending. `[]` deletes the range.
 
 Same-file calls in one message batch: earlier calls reply `In batch N` and the last call shows the combined diff, with one undo for the whole batch.
 

package/src/insert.ts

@@ -11,7 +11,7 @@ import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuide } from "./prompts";
 import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
-import { decodeStringArray, isRec, literalEscapeWarning, splitLines } from "./utils";
+import { decodeStringArray, isRec, literalEscapeHint, splitLines } from "./utils";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
 export { assertInsertReq, type InsertReq };
@@ -28,7 +28,7 @@ const insertDirectionSchema = Type.Union(
 
 const insertLinesSchema = Type.Array(
   Type.String({
-    description: "One line to insert. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings; escape sequences are not decoded.",
+    description: "One line to insert. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings.",
   }),
   {
     description: 'One string per line; [""] is a blank line; never include the anchor line.',
@@ -192,7 +192,7 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
         }
         assertInsertReq(canonical);
         const req = canonical;
-        const literalEscape = literalEscapeWarning(req.lines, "lines");
+        const literalEscape = literalEscapeHint(req.lines, "lines");
         if (literalEscape !== undefined) insertWarnings.push(literalEscape);
         const targetPath = await resolveEditTargetWithRequirement({
           anchor: req.anchor,

package/src/payload-contract.ts

@@ -4,7 +4,7 @@ import { isRec, normalizeRequest, rejectUnknownFields, assertNoNul } from "./uti
 const replacementLinesSchema = Type.Array(
   Type.String({
     description:
-      "One replacement line. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings; escape sequences are not decoded.",
+      "One replacement line. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings.",
   }),
   {
     description:

package/src/replace-render.ts

@@ -126,7 +126,13 @@ export function getResultText(result: {
 export function extractWarnings(
 	text: string | undefined,
 ): string | undefined {
-	return text?.match(/(?:^|\n)Warnings:\n[\s\S]*$/)?.[0]?.trimStart();
+	return text?.match(/(?:^|\n)Warnings:\n[\s\S]*?(?=\n\nHints:\n|$)/)?.[0]?.trimStart();
+}
+
+export function extractHints(
+	text: string | undefined,
+): string | undefined {
+	return text?.match(/(?:^|\n)Hints:\n[\s\S]*$/)?.[0]?.trimStart();
 }
 
 export function isApplied(
@@ -153,8 +159,8 @@ export function expandHint(): string {
 function extractSummary(text: string | undefined): string | undefined {
 	if (!text) return undefined;
 	if (text.includes("│")) return undefined;
-	const warningsIdx = text.indexOf("\n\nWarnings:");
-	const summary = warningsIdx >= 0 ? text.slice(0, warningsIdx) : text;
+	const noticesIdx = text.search(/\n\n(?:Warnings|Hints):\n/);
+	const summary = noticesIdx >= 0 ? text.slice(0, noticesIdx) : text;
 	return summary.length > 0 ? summary : undefined;
 }
 
@@ -190,6 +196,8 @@ export function buildAppliedText(
 	}
 	const warnings = details?.warnings?.length ? `Warnings:\n${details.warnings.join("\n")}` : extractWarnings(text);
 	if (warnings) sections.push(warnings);
+	const hints = details?.hints?.length ? `Hints:\n${details.hints.join("\n")}` : extractHints(text);
+	if (hints) sections.push(hints);
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
 

package/src/replace-response.ts

@@ -85,6 +85,17 @@ function warnBlock(warnings: string[] | undefined): string {
 	return warnings?.length ? `\n\nWarnings:\n${warnings.join("\n")}` : "";
 }
 
+function hintBlock(hints: string[] | undefined): string {
+	return hints?.length ? `\n\nHints:\n${hints.join("\n")}` : "";
+}
+
+function splitNotices(notices: string[] | undefined): { warnings: string[]; hints: string[] } {
+	const warnings: string[] = [];
+	const hints: string[] = [];
+	for (const notice of notices ?? []) (notice.startsWith("[H_") ? hints : warnings).push(notice);
+	return { warnings, hints };
+}
+
 export function buildNoop(input: NoopInput, noopNoun = "Replacement"): TResult {
 	const {
 		path,
@@ -97,13 +108,14 @@ export function buildNoop(input: NoopInput, noopNoun = "Replacement"): TResult {
 	const noopDetailsText = noopEdit
 		? `${noopNoun} for ${noopEdit.loc} is identical to current content:\n  ${noopEdit.loc}: ${clipLine(noopEdit.currentContent)}`
 		: "The edit produced identical content.";
-	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(warnings)}`;
+	const { warnings: noticeWarnings, hints } = splitNotices(warnings);
+	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(noticeWarnings)}${hintBlock(hints)}`;
 
 	const metrics = buildMetrics({
 		classification: "noop",
 		editsAttempted: editMeta.editsAttempted,
 		noopEditsCount: editMeta.noopEditsCount,
-		warningsCount: warnings?.length ?? 0,
+		warningsCount: noticeWarnings.length,
 	});
 
 	return {
@@ -115,7 +127,8 @@ export function buildNoop(input: NoopInput, noopNoun = "Replacement"): TResult {
 			snapshotId,
 			classification: "noop" as const,
       metrics,
-      ...(warnings?.length ? { warnings: [...warnings] } : {}),
+      ...(noticeWarnings.length ? { warnings: [...noticeWarnings] } : {}),
+      ...(hints.length ? { hints: [...hints] } : {}),
 		},
 	};
 }
@@ -126,22 +139,23 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
   const diffResult = genDiff(originalNormalized, result, diffContextLines, resultHashes, originalHashes, undefined, spans);
   const addedLines = editMeta.addedLines;
   const removedLines = editMeta.removedLines;
-  const warningsBlock = warnBlock(warnings);
+  const { warnings: noticeWarnings, hints } = splitNotices(warnings);
+  const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(hints)}`;
   const successPrefix = `Successfully ${verb} in ${path}.`;
   const lineSummary = addedLines > 0 || removedLines > 0
     ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
     : "";
   const text = resultLines.length === 0
     ? "File is empty. Use replace to insert content."
-    : warningsBlock
-      ? `${successPrefix}${lineSummary}${warningsBlock}`
+    : noticesBlock
+      ? `${successPrefix}${lineSummary}${noticesBlock}`
       : `${successPrefix}${lineSummary}`;
 
   const metrics = buildMetrics({
     classification: "applied",
     editsAttempted: editMeta.editsAttempted,
     noopEditsCount: editMeta.noopEditsCount,
-    warningsCount: warnings?.length ?? 0,
+    warningsCount: noticeWarnings.length,
     firstChangedLine: editMeta.firstChangedLine,
     lastChangedLine: editMeta.lastChangedLine,
     addedLines,
@@ -160,7 +174,8 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
       snapshotId,
       metrics,
       diffLineNumbers: diffResult.lineNumbers.map((line) => line ?? null),
-      ...(warnings?.length ? { warnings: [...warnings] } : {}),
+      ...(noticeWarnings.length ? { warnings: [...noticeWarnings] } : {}),
+      ...(hints.length ? { hints: [...hints] } : {}),
     },
   };
 }

package/src/replace.ts

@@ -10,7 +10,7 @@ import {
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, buildEditToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
-import { literalEscapeWarning, splitLines } from "./utils";
+import { literalEscapeHint, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
 import { applyEdit,
@@ -48,6 +48,7 @@ export type ReplaceDetails = {
   metrics?: RMetrics;
   diffLineNumbers?: (number | null)[];
   warnings?: string[];
+  hints?: string[];
   batch?: { id: number; size: number; last: boolean; total: number; aborted?: boolean; abortMessage?: string };
 };
 
@@ -273,7 +274,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
         const canonical = normReq(params);
         assertReq(canonical);
         const normalizedParams = canonical;
-        const literalEscape = literalEscapeWarning(normalizedParams.replacement_lines, "replacement_lines");
+        const literalEscape = literalEscapeHint(normalizedParams.replacement_lines, "replacement_lines");
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: normalizedParams.remove_from,
           removeTo: normalizedParams.remove_to,

package/src/utils.ts

@@ -384,7 +384,7 @@ function isSurrogateEscapePair(line: string, index: number, hex: string): boolea
 	return false;
 }
 
-export function literalEscapeWarning(lines: string[], label: string): string | undefined {
+export function literalEscapeHint(lines: string[], label: string): string | undefined {
 	for (const line of lines) {
 		if (!line.includes("\\")) continue;
 		const hasRealBreak = REAL_LINE_BREAK_RE.test(line);
@@ -396,7 +396,7 @@ export function literalEscapeWarning(lines: string[], label: string): string | u
 				if (hex.toLowerCase() === "dddd") continue;
 				if (isSurrogateEscapePair(line, match.index, hex)) continue;
 			}
-			return `[W_LITERAL_ESCAPE] "${label}" contains the literal escape text "${match[0]}"`;
+			return `[H_LITERAL_ESCAPE] "${label}" contains the literal escaped text "${match[0]}"`;
 		}
 	}
 	return undefined;