pi-fff: emit hashline [path#TAG] headers so ffgrep output is directly editable in omp

[jms830]

Summary

ffgrep / fffind output carries no hashline [path#TAG] header, so in oh-my-pi (omp) every fff hit needs a follow-up native read before edit can anchor. That follow-up round trip spends most of the token saving fff just earned.

The fix needs no session access — omp's hashline tag is derived from file bytes alone. pi-fff can mint it locally.

Why this is cheap

Tag recipe (@oh-my-pi/hashline/src/format.ts:108-121):

const norm = text.replace(/[ \t\r]+(?=\n|$)/g, "");
const tag = (Bun.hash.xxHash32(norm, 0) & 0xffff).toString(16).padStart(4, "0").toUpperCase();

Apply gate consults no snapshot store (@oh-my-pi/hashline/src/patcher.ts:688,728):

const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
if (expected === undefined || liveMatches) { /* applyEdits */ }

Verified empirically 2026-08-17 on omp 0.10.5-era build: hand-computed a tag (DD92) in a REPL for a file the agent had never read, issued [path#DD92] PUT 2.=2: and the edit applied, returning a fresh tag. So emitting [relpath#TAG] plus N: text rows from the bytes fff already has in hand makes fff output directly editable.

Proposed change

When the host is omp (or unconditionally, behind a flag), prefix each file's match group in ffgrep output with [<relpath>#<TAG>] and format rows as N: text, matching omp's native grep/read shape (src/tools/grep.ts:1466 mints the same header).

Caveat worth encoding

If edit.enforceSeenLines is true (default false, settings-schema.ts:3239-3241), the stricter guard additionally wants seen-line provenance via recordSeenLinesFromBody (src/edit/file-snapshot-store.ts:141). That lives on AgentSession.fileSnapshotStore, and ExtensionContext exposes sessionManager, modelRegistry, cwd, ui, model, models — never the session (extensibility/extensions/runner.ts:1045-1081). So an extension cannot register provenance.

Fallback for that configuration only: register under the builtin name (override mode) and delegate to the native implementation via ctx.invokeTool, which is wired only when the extension tool name shadows a builtin (extensibility/extensions/types.ts:497-509, wrapper.ts:69-86). Note override mode is currently affected by #792.

Prior art

Searched both dmtrKovalenko/fff and can1357/oh-my-pi — 0 hits for the tag gap. Related but distinct: #737 / PR #741 (dynamic ${toolNames.grep} in promptGuidelines), #792 / PR #793 (tools registered before startup mode known).

[gustav-fff]

[triage-bot] FEATURE REQUEST: premise checks out, not shipping it blind. Two decisions are yours, not the extension's.

Verified locally against installed @oh-my-pi/hashline@17.3.4 + @oh-my-pi/pi-coding-agent:

• Tag recipe is exactly as reported (hashline/src/format.ts:117-121).
• edit.enforceSeenLines default is false (config/settings-schema.ts:3238-3240), so the gate at patcher.ts:688 accepts a bytes-only tag.
• Cost is a non-issue: read + normalize + xxHash32 over 20 chromium .cc/.h files (340 KiB) = 2.2 ms warm, 8.8 ms cold. Nothing next to the 10 s grep budget (packages/pi-fff/src/index.ts:44).

Blockers:

1. Extension cannot know hashline output is wanted. Native grep gates the header on resolveFileDisplayMode(session).hashLines, i.e. edit.mode === "hashline" && hasEditTool (utils/file-display-mode.ts:39). ExtensionContext exposes no settings and no session (extensibility/extensions/types.ts:440-494). Emitting [path#TAG] unconditionally poisons every ffgrep result on plain pi and in non-hashline omp edit modes. Sniffing ctx.getSystemPrompt() for hashline syntax works but is a hack fff should not carry.

2. ffgrep rows are not byte-faithful. truncateLine() does line.trim() and caps at 500 chars (packages/pi-fff/src/index.ts:125-128, used at 180/183/187). Native omp pushes match.line raw (tools/grep.ts:1494). A hashline header over trimmed rows advertises editable output while hiding indentation — model then issues PUT with guessed leading whitespace. Doing it right means untrimming grep rows, which changes tuned output for every host, not only omp.

Also: native grep does recordFileSnapshot (tools/grep.ts:1466) and recordSeenLinesFromBody (:1514). A bytes-only tag skips both, so anyone flipping edit.enforceSeenLines on silently loses ffgrep-anchored edits — that failure mode needs a note in the tool output, not silence.

No duplicates found.

@dmtrKovalenko your call: (a) opt-in hashlineHeaders in pi-fff.json, untrimmed rows only when on, accepting that fff hardcodes omp's private hash recipe; or (b) wait for omp to expose display mode + snapshot registration to extensions. Not opening a speculative PR.

Honk-Honk 🪿

[FelikZ]

Would be nice to have it, could be an optional setting / env that enables this.