pantheon-opencode 1.3.2 → 1.3.3

package/src/pantheon/dispatch-guard.ts

@@ -0,0 +1,102 @@
+/**
+ * Dispatch Guard (Wave 4, PR #46) — auto-retry-on-empty for background
+ * delegations. Classifies a dispatch result and redispatch once when it
+ * came back empty.
+ *
+ * Failure signature classification:
+ *   - 'content'     — text content present, nothing to do.
+ *   - 'empty-mode1' — NO content AND NO tokens: the dispatch returned
+ *                     nothing at all (no reply / early abort).
+ *   - 'empty-mode2' — no text part but tokens present: reasoning happened
+ *                     but the text part was lost — the themis Wave-2
+ *                     failure signature that triggered this guard.
+ *
+ * Retry cap is HARD at 1 (never 2x). The guard is stateful per instance:
+ * one retry budget total. It is a PURE library — it does NOT intercept
+ * task() (opencode 1.18.x cannot intercept task completion via hooks, so
+ * integration is manual-orchestration; see zeus.md "Empty-Result Retry").
+ *
+ * @module dispatch-guard
+ */
+
+/** A dispatch result — the minimal shape needed to classify emptiness. */
+export interface DispatchResultLike {
+  /** Text content of the result (task_result / report markdown). */
+  content?: string | null
+  /** Input tokens (present when the model actually reasoned). */
+  tokensInput?: number
+  /** Output tokens (present when the model actually reasoned). */
+  tokensOutput?: number
+}
+
+/** Classification of a dispatch result. */
+export type DispatchClassification = 'content' | 'empty-mode1' | 'empty-mode2'
+
+export interface DispatchGuardOptions {
+  /** Enable auto-retry on empty results. Default: true. */
+  retryOnEmpty?: boolean
+  /** Injectable logger (defaults to console.warn with a prefix). */
+  logger?: { warn: (message: string) => void }
+}
+
+export interface DispatchGuard {
+  /** Classify a result: content, empty-mode1 (nothing), empty-mode2 (reasoning, no text). */
+  classifyResult(result: DispatchResultLike): DispatchClassification
+  /**
+   * Redispatch ONCE when the result is empty and retryOnEmpty is enabled.
+   * A retried result that is STILL empty is returned as-is — the cap of 1
+   * is never exceeded. Never throws.
+   */
+  maybeRetry(
+    result: DispatchResultLike,
+    redispatch: () => Promise<DispatchResultLike>,
+  ): Promise<{
+    classification: DispatchClassification
+    retried: boolean
+    result: DispatchResultLike
+  }>
+}
+
+/** 1-based retry budget — the hard cap. Never 2x. */
+const MAX_RETRIES = 1
+
+/** Whether a result carries any text content (whitespace-only counts as empty). */
+function hasContent(result: DispatchResultLike): boolean {
+  return typeof result.content === 'string' && result.content.trim() !== ''
+}
+
+/** Whether the result carries any token counts (i.e. the model actually ran). */
+function hasTokens(result: DispatchResultLike): boolean {
+  return (result.tokensInput ?? 0) > 0 || (result.tokensOutput ?? 0) > 0
+}
+
+export function createDispatchGuard(options?: DispatchGuardOptions): DispatchGuard {
+  const retryOnEmpty = options?.retryOnEmpty ?? true
+  const warn =
+    options?.logger?.warn ??
+    ((message: string) => console.warn(`[pantheon-dispatch-guard] ${message}`))
+  // Per-instance retry budget — the "cap 1" enforcement point.
+  let retriesUsed = 0
+
+  return {
+    classifyResult(result: DispatchResultLike): DispatchClassification {
+      if (hasContent(result)) return 'content'
+      return hasTokens(result) ? 'empty-mode2' : 'empty-mode1'
+    },
+
+    async maybeRetry(result, redispatch) {
+      const classification = this.classifyResult(result)
+      if (!retryOnEmpty || classification === 'content' || retriesUsed >= MAX_RETRIES) {
+        return { classification, retried: false, result }
+      }
+      retriesUsed += 1
+      warn(`dispatch returned ${classification}; retrying once (cap ${MAX_RETRIES})`)
+      const retriedResult = await redispatch()
+      return {
+        classification: this.classifyResult(retriedResult),
+        retried: true,
+        result: retriedResult,
+      }
+    },
+  }
+}

package/src/pantheon/file-persistence.ts

@@ -23,8 +23,9 @@ const DEFAULT_STATE_PATH = '.pantheon/board/state.json'
  * Writes are atomic: content is written to a `.tmp` file, then renamed.
  *
  * The board's in-memory `this.jobs` Map is the source of truth —
- * this file is a crash-recovery snapshot only. `deleteJob()` is a no-op
- * because stale entries are harmless and overwritten on the next `saveJob()`.
+ * this file is a crash-recovery snapshot. `deleteJob()` removes the
+ * record from the snapshot so pruned/reconciled jobs don't resurface
+ * after a restart.
  */
 export class FilePersistenceAdapter implements PersistenceAdapter {
   private readonly statePath: string
@@ -87,9 +88,12 @@ export class FilePersistenceAdapter implements PersistenceAdapter {
     return (await this.readState()) ?? []
   }
 
-  async deleteJob(_taskID: string): Promise<void> {
-    // No-op: the board's in-memory Map is the source of truth.
-    // The file is a crash-recovery snapshot; stale entries are harmless
-    // and will be overwritten on the next saveJob().
+  async deleteJob(taskID: string): Promise<void> {
+    const records = await this.readState()
+    if (!records) return
+    const idx = records.findIndex(r => r.taskID === taskID)
+    if (idx < 0) return
+    records.splice(idx, 1)
+    await this.writeState(records)
   }
 }

package/src/pantheon/goal-loop.ts

@@ -0,0 +1,297 @@
+/**
+ * Full-auto Goal Loop (Wave 3, PR #46) — one active goal per session,
+ * continued automatically while idle. `pantheon_goal_create` starts a goal;
+ * `pantheon_goal_update` moves it pending → in_progress → done; while
+ * active, `GoalLoop.onIdle` re-injects the continuation prompt (objective
+ * restated from the store) until marked done. Council-approved cut: NO LLM
+ * completion-audit prompt — the state machine is the source of truth.
+ *
+ * Persistence: FILE-based GoalStore (`.pantheon/goals/<sessionID>.json`,
+ * atomic tmp+rename). Opt-in `full_auto.enabled: false` default. Guards:
+ * board-running skip, in-flight Set, cooldown, max_continuations cap (25).
+ * Injectable now() clock. Pure TypeScript — zero runtime deps.
+ *
+ * @module goal-loop
+ */
+
+import { z } from 'zod'
+
+import type { BackgroundJobBoard } from './background-job-board.ts'
+import type { ToolContextLike } from './delegation.ts'
+import { GoalStore } from './goal-store.ts'
+import type { TodoEnforcerMessage } from './todo-enforcer.ts'
+
+export type { Goal, GoalStatus } from './goal-store.ts'
+export { GoalStore }
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** Continuation text injected into idle sessions. `{objective}` is substituted. */
+export const GOAL_CONTINUATION_PROMPT =
+  "Active goal: {objective}. Continue working toward it. Do not stop until you update the goal to done. If you believe it's complete, call pantheon_goal_update with status done."
+
+/** Defaults matching routing.yml `full_auto`. */
+export const GOAL_LOOP_DEFAULTS = {
+  enabled: false,
+  cooldownMs: 5000,
+  maxContinuations: 25,
+} as const
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Structural client surface — the subset of the SDK the loop uses. */
+export interface GoalLoopClient {
+  session: {
+    messages(input: { path: { id: string } }): Promise<TodoEnforcerMessage[]>
+    promptAsync(input: {
+      path: { id: string }
+      body: {
+        agent?: string
+        model?: { providerID: string; modelID: string }
+        parts: Array<{ type: 'text'; text: string }>
+      }
+    }): Promise<unknown>
+  }
+}
+
+/** Tunables (all optional — see GOAL_LOOP_DEFAULTS). */
+export interface GoalLoopOptions {
+  enabled?: boolean
+  /** Minimum gap between continuations (ms). */
+  cooldownMs?: number
+  /** Hard cap on continuations per goal — after this the loop halts. */
+  maxContinuations?: number
+  /** Injectable clock (testable), defaults to `Date.now`. */
+  now?: () => number
+}
+
+/** Dependencies threaded to the loop (structural board — list only). */
+export interface GoalLoopDeps {
+  store: GoalStore
+  client: GoalLoopClient
+  board: Pick<BackgroundJobBoard, 'list'>
+  options?: GoalLoopOptions
+  logger?: { warn: (message: string) => void }
+}
+
+type InheritedContext = {
+  agent?: string
+  model?: { providerID: string; modelID: string }
+}
+
+/** Render a tool failure as error text (tools return errors as TEXT). */
+function toolFailure(prefix: string, err: unknown): string {
+  const reason = err instanceof Error ? err.message : String(err)
+  return `${prefix} failed: ${reason}`
+}
+
+// ─── Args schemas ──────────────────────────────────────────────────────
+
+const goalCreateArgs = {
+  objective: z.string().min(1).describe('The goal objective the session keeps working toward.'),
+} satisfies z.ZodRawShape
+
+const goalUpdateArgs = {
+  status: z.enum(['pending', 'in_progress', 'done']).optional().describe('New goal status.'),
+  objective: z.string().min(1).optional().describe('New goal objective.'),
+} satisfies z.ZodRawShape
+
+const goalGetArgs = {} satisfies z.ZodRawShape
+
+/** One structural goal tool: description + zod args shape + execute (delegation.ts shape). */
+export type GoalTool<Args extends z.ZodRawShape> = {
+  description: string
+  args: Args
+  execute(args: z.infer<z.ZodObject<Args>>, ctx: ToolContextLike): Promise<string>
+}
+
+/** The three goal tools. */
+export interface GoalToolset {
+  pantheon_goal_create: GoalTool<typeof goalCreateArgs>
+  pantheon_goal_update: GoalTool<typeof goalUpdateArgs>
+  pantheon_goal_get: GoalTool<typeof goalGetArgs>
+}
+
+// ─── GoalLoop ──────────────────────────────────────────────────────────
+
+/**
+ * Re-inject a continuation prompt into idle sessions with an active goal.
+ * Per-session state: last-continuation timestamp (cooldown) and an in-flight
+ * set (never concurrent). `onIdle` never throws — the event hook can never
+ * break the session.
+ */
+export class GoalLoop {
+  private readonly store: GoalStore
+  private readonly client: GoalLoopClient
+  private readonly board: Pick<BackgroundJobBoard, 'list'>
+  private readonly options: Required<GoalLoopOptions>
+  private readonly warn: (message: string) => void
+
+  private readonly inFlight = new Set<string>()
+  private readonly lastContinuationAt = new Map<string, number>()
+
+  constructor(deps: GoalLoopDeps) {
+    this.store = deps.store
+    this.client = deps.client
+    this.board = deps.board
+    const opts = deps.options ?? {}
+    this.options = {
+      enabled: opts.enabled ?? GOAL_LOOP_DEFAULTS.enabled,
+      cooldownMs: opts.cooldownMs ?? GOAL_LOOP_DEFAULTS.cooldownMs,
+      maxContinuations: opts.maxContinuations ?? GOAL_LOOP_DEFAULTS.maxContinuations,
+      now: opts.now ?? Date.now,
+    }
+    this.warn =
+      deps.logger?.warn ?? ((message: string) => console.warn(`[pantheon-goal] ${message}`))
+  }
+
+  /** True when the session has an active (non-done) goal. Used by the idle dispatcher. */
+  async hasActiveGoal(sessionID: string): Promise<boolean> {
+    return this.store.hasActive(sessionID)
+  }
+
+  /** Handle a `session.idle` event for a session with an active goal. Never throws. */
+  async onIdle(sessionID: string): Promise<void> {
+    if (!this.options.enabled) return
+    if (this.inFlight.has(sessionID)) return
+    this.inFlight.add(sessionID)
+    try {
+      await this.handleIdle(sessionID)
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`goal continuation failed for session ${sessionID}: ${reason}`)
+    } finally {
+      this.inFlight.delete(sessionID)
+    }
+  }
+
+  private async handleIdle(sessionID: string): Promise<void> {
+    const goal = await this.store.load(sessionID)
+    // DONE (or absent) goal → nothing to continue.
+    if (goal === undefined || goal.status === 'done') return
+
+    // A session with a running background job is busy — skip.
+    if (this.board.list(sessionID).some((job) => job.state === 'running')) return
+
+    // Hard cap: stop the loop once the cap is reached.
+    if (goal.continuationCount >= this.options.maxContinuations) return
+
+    const now = this.options.now()
+    const last = this.lastContinuationAt.get(sessionID)
+    if (last !== undefined && now - last < this.options.cooldownMs) return
+
+    // Timestamp BEFORE the call — a failed injection still applies the
+    // cooldown (no hot retry loop).
+    this.lastContinuationAt.set(sessionID, now)
+    const inherited = await this.inheritAgentOrModel(sessionID)
+    const prompt = GOAL_CONTINUATION_PROMPT.replace('{objective}', goal.objective)
+    await this.client.session.promptAsync({
+      path: { id: sessionID },
+      body: {
+        ...(inherited.agent !== undefined ? { agent: inherited.agent } : {}),
+        ...(inherited.model !== undefined ? { model: inherited.model } : {}),
+        parts: [{ type: 'text', text: prompt }],
+      },
+    })
+    goal.continuationCount += 1
+    goal.updatedAt = now
+    await this.store.save(goal)
+  }
+
+  /**
+   * Inherit the agent (or model) from the LAST assistant message so the
+   * continuation runs in the same context as the session's last turn.
+   */
+  private async inheritAgentOrModel(sessionID: string): Promise<InheritedContext> {
+    const messages = await this.client.session.messages({ path: { id: sessionID } })
+    for (const msg of [...messages].reverse()) {
+      const info = msg.info
+      if (info === undefined || info.role !== 'assistant') continue
+      if (typeof info.agent === 'string' && info.agent !== '') {
+        return { agent: info.agent }
+      }
+      const providerID = info.model?.providerID ?? info.providerID
+      const modelID = info.model?.modelID ?? info.modelID
+      if (
+        typeof providerID === 'string' &&
+        providerID !== '' &&
+        typeof modelID === 'string' &&
+        modelID !== ''
+      ) {
+        return { model: { providerID, modelID } }
+      }
+    }
+    return {}
+  }
+
+  /** Build the three structural goal tools (single active goal per session). */
+  tools(): GoalToolset {
+    return {
+      pantheon_goal_create: {
+        description:
+          'Create the single active goal for this session. The goal loop then continues the session automatically on idle until the goal is marked done.',
+        args: goalCreateArgs,
+        execute: async (args, ctx) => {
+          try {
+            this.store.sanitizeSessionID(ctx.sessionID)
+            const existing = await this.store.load(ctx.sessionID)
+            if (existing !== undefined && existing.status !== 'done') {
+              return `pantheon_goal_create failed: session ${ctx.sessionID} already has an active goal`
+            }
+            const now = this.options.now()
+            await this.store.save({
+              id: ctx.sessionID,
+              sessionID: ctx.sessionID,
+              objective: args.objective,
+              status: 'pending',
+              createdAt: now,
+              updatedAt: now,
+              continuationCount: 0,
+            })
+            return `Goal created (${ctx.sessionID}): ${args.objective}`
+          } catch (err: unknown) {
+            return toolFailure('pantheon_goal_create', err)
+          }
+        },
+      },
+      pantheon_goal_update: {
+        description:
+          'Update the active goal: set status (pending/in_progress/done) and/or rewrite the objective. Setting status to done stops all further continuations.',
+        args: goalUpdateArgs,
+        execute: async (args, ctx) => {
+          try {
+            const goal = await this.store.load(ctx.sessionID)
+            if (goal === undefined) {
+              return `pantheon_goal_update failed: no active goal for session ${ctx.sessionID}`
+            }
+            if (args.status === undefined && args.objective === undefined) {
+              return 'pantheon_goal_update failed: provide status and/or objective'
+            }
+            if (args.objective !== undefined) goal.objective = args.objective
+            if (args.status !== undefined) goal.status = args.status
+            goal.updatedAt = this.options.now()
+            await this.store.save(goal)
+            return `Goal updated: status=${goal.status}, objective=${goal.objective}`
+          } catch (err: unknown) {
+            return toolFailure('pantheon_goal_update', err)
+          }
+        },
+      },
+      pantheon_goal_get: {
+        description: 'Return the active goal for this session (status, objective, continuations).',
+        args: goalGetArgs,
+        execute: async (_args, ctx) => {
+          try {
+            const goal = await this.store.load(ctx.sessionID)
+            if (goal === undefined) {
+              return `No active goal for session ${ctx.sessionID}`
+            }
+            return `Goal (${goal.id}): status=${goal.status}, objective=${goal.objective}, continuations=${goal.continuationCount}`
+          } catch (err: unknown) {
+            return toolFailure('pantheon_goal_get', err)
+          }
+        },
+      },
+    }
+  }
+}

package/src/pantheon/goal-store.ts

@@ -0,0 +1,97 @@
+/**
+ * File-based goal persistence for the full-auto Goal Loop (Wave 3, PR #46).
+ *
+ * One JSON file per session (`.pantheon/goals/<sessionID>.json`), written
+ * atomically (tmp + rename) so a crash never leaves a partial goal. The
+ * plugin layer cannot reach MCP KV servers, so goals live on disk.
+ * Session IDs are sanitized before path construction (path-traversal guard,
+ * same pattern as assertSafeParentSessionID).
+ *
+ * Pure TypeScript — zero runtime deps beyond node:fs.
+ *
+ * @module goal-store
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { assertSafeParentSessionID } from './delegation-finalize.ts'
+
+export type GoalStatus = 'pending' | 'in_progress' | 'done'
+
+/** One goal persisted at `.pantheon/goals/<sessionID>.json`. */
+export interface Goal {
+  id: string
+  sessionID: string
+  objective: string
+  status: GoalStatus
+  createdAt: number
+  updatedAt: number
+  continuationCount: number
+}
+
+const DEFAULT_GOAL_DIR = '.pantheon/goals'
+
+/**
+ * File-based goal persistence. `save` writes atomically (tmp + rename);
+ * `load` returns undefined when no goal exists yet.
+ */
+export class GoalStore {
+  private readonly dir: string
+
+  constructor(opts: { dir?: string } = {}) {
+    this.dir = opts.dir ?? DEFAULT_GOAL_DIR
+  }
+
+  /**
+   * Path-traversal guard for session IDs embedded in file paths (same
+   * pattern as assertSafeParentSessionID). Throws on `..`, `/`, `\`.
+   */
+  sanitizeSessionID(sessionID: string): string {
+    assertSafeParentSessionID(sessionID)
+    return sessionID
+  }
+
+  private pathFor(sessionID: string): string {
+    return join(this.dir, `${this.sanitizeSessionID(sessionID)}.json`)
+  }
+
+  /** Load the session's goal; undefined when none exists yet. */
+  async load(sessionID: string): Promise<Goal | undefined> {
+    const path = this.pathFor(sessionID)
+    try {
+      const content = await readFile(path, 'utf-8')
+      return JSON.parse(content) as Goal
+    } catch (err: unknown) {
+      if (
+        err instanceof Error &&
+        'code' in err &&
+        (err as NodeJS.ErrnoException).code === 'ENOENT'
+      ) {
+        return undefined
+      }
+      throw err
+    }
+  }
+
+  /** Persist a goal atomically (tmp + rename). */
+  async save(goal: Goal): Promise<void> {
+    const path = this.pathFor(goal.sessionID)
+    const tmpPath = `${path}.tmp`
+    await mkdir(this.dir, { recursive: true })
+    await writeFile(tmpPath, JSON.stringify(goal, null, 2), 'utf-8')
+    await rename(tmpPath, path)
+  }
+
+  /** True when the session has a goal that is not `done`. */
+  async hasActive(sessionID: string): Promise<boolean> {
+    const goal = await this.load(sessionID)
+    return goal !== undefined && goal.status !== 'done'
+  }
+
+  /** List the session's goals — at most one (YAGNI: single active goal). */
+  async list(sessionID: string): Promise<Goal[]> {
+    const goal = await this.load(sessionID)
+    return goal === undefined ? [] : [goal]
+  }
+}

package/src/pantheon/hashline/core.ts

@@ -0,0 +1,91 @@
+/**
+ * Hashline core (Wave 2, PR #46) — tagged-line formatting, ref parsing, and
+ * mismatch diagnostics shared by the read enhancer and the hashline_edit tool.
+ *
+ * A "ref" is the stable anchor used by hashline_edit: `{line}#{tag}` where
+ * the tag is the 2-char sha256 hash of the line content. Ref format:
+ *   ^([0-9]+)#([ZPMQVRWSNKTXJBYH]{2})$
+ *
+ * @module hashline/core
+ */
+
+import { HASHLINE_DICT, hashTag } from './xxhash.ts'
+
+/** A ref string: line number + 2-char tag (e.g. "12#XJ"). */
+export const HASHLINE_REF_RE = /^([0-9]+)#([ZPMQVRWSNKTXJBYH]{2})$/
+
+/** Matches an already-tagged line (`12#XJ|content`) — idempotency guard. */
+const TAGGED_LINE_RE = new RegExp(`^\\s*[0-9]+#[${HASHLINE_DICT}]{2}\\|`)
+
+/** A resolved line match used in mismatch diagnostics. */
+export interface LineMatch {
+  /** 1-based line number. */
+  line: number
+  /** The tag ACTUALLY computed for the line content. */
+  tag: string
+  /** The raw line content (for the excerpt). */
+  content?: string | undefined
+}
+
+/**
+ * Format a line as a hashline-tagged line: `{lineNo}#{tag}|{content}`.
+ * This is the format the read enhancer emits and the edit tool consumes.
+ */
+export function formatTaggedLine(lineNo: number, content: string): string {
+  return `${lineNo}#${hashTag(content, lineNo)}|${content}`
+}
+
+/**
+ * Whether a line is already hashline-tagged (idempotency check). Used by the
+ * read enhancer to avoid re-tagging and by tests to verify the format.
+ */
+export function isTaggedLine(line: string): boolean {
+  return TAGGED_LINE_RE.test(line)
+}
+
+/**
+ * Build the "Did you mean" suggestion for a mismatched ref: the corrected
+ * ref is the ACTUAL line number + ACTUAL tag, e.g. `Did you mean "12#XJ"?`.
+ */
+export function suggestLineForHash(lineNo: number, tag: string): string {
+  return `Did you mean "${lineNo}#${tag}"?`
+}
+
+/**
+ * Build the full mismatch error text for the hashline_edit tool (returned
+ * as error-as-text, never thrown, never partially written):
+ *
+ *   hashline_edit: ref "12#QQ" does not match /path/file at line 12 (tag "XJ")
+ *
+ *   >>>12#XJ|actual line content
+ *    ...   13#AB|next line
+ *
+ *   Did you mean "12#XJ"?
+ *
+ * The excerpt is a RE-TAGGED view of the original `lines` around the target
+ * line (±2 lines of context), with the mismatched line marked `>>>` and
+ * carrying its ACTUAL tag.
+ */
+export function buildMismatchError(
+  file: string,
+  ref: string,
+  actual: LineMatch,
+  lines: readonly string[],
+): string {
+  const start = Math.max(1, actual.line - 2)
+  const end = Math.min(lines.length, actual.line + 2)
+  const excerpt: string[] = []
+  for (let i = start; i <= end; i++) {
+    const content = lines[i - 1] ?? ''
+    const tag = i === actual.line ? actual.tag : hashTag(content, i)
+    const marker = i === actual.line ? '>>>' : '   '
+    excerpt.push(`${marker}${i}#${tag}|${content}`)
+  }
+  return [
+    `hashline_edit: ref "${ref}" does not match ${file} at line ${actual.line} (tag "${actual.tag}")`,
+    '',
+    excerpt.join('\n'),
+    '',
+    suggestLineForHash(actual.line, actual.tag),
+  ].join('\n')
+}

package/src/pantheon/hashline/read-enhancer.ts

@@ -0,0 +1,66 @@
+/**
+ * Read enhancer (Wave 2, PR #46) — augments the `read` tool output with
+ * per-line hashline tags so the model can anchor hashline_edit refs.
+ *
+ * Wired as the plugin's `tool.execute.after` hook (purely additive — the
+ * plugin has no `tool.execute.after` yet; pantheon-hooks.ts is a SEPARATE
+ * plugin instance, so no key collision). Only `input.tool === 'read'` is
+ * touched; every other tool passes through byte-for-byte.
+ *
+ * Transform: lines matching `^\s*(\d+): ?(.*)$` or `^\s*(\d+)\| ?(.*)$` are
+ * rewritten as `{line}#{tag}|{content}`. Already-tagged lines are skipped
+ * (idempotent — safe across multiple hook invocations). Lines that do not
+ * carry a line-number prefix (truncation markers like `... 500 more lines`,
+ * bare text) are left untouched.
+ *
+ * @module hashline/read-enhancer
+ */
+
+import { isTaggedLine } from './core.ts'
+import { hashTag } from './xxhash.ts'
+
+/** Input shape of the opencode `tool.execute.after` hook. */
+export interface ToolExecuteAfterInput {
+  tool: string
+  sessionID: string
+  callID: string
+  args: unknown
+}
+
+/** Output shape of the opencode `tool.execute.after` hook (mutable). */
+export interface ToolExecuteAfterOutput {
+  title?: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+/** The `tool.execute.after` handler shape. */
+export type ToolExecuteAfterHandler = (
+  input: ToolExecuteAfterInput,
+  output: ToolExecuteAfterOutput,
+) => Promise<void>
+
+/** Read-output line prefixes: `N: content`, `N| content`, `N|content`. */
+const LINE_PREFIX_RE = /^\s*([0-9]+): ?(.*)$|^\s*([0-9]+)\| ?(.*)$/
+
+/**
+ * Build the read enhancer handler. Throws nothing — any unexpected state is
+ * a no-op so the hook can never break the tool result.
+ */
+export function createReadEnhancer(): ToolExecuteAfterHandler {
+  return async (input: ToolExecuteAfterInput, output: ToolExecuteAfterOutput): Promise<void> => {
+    if (input.tool !== 'read') return
+    if (typeof output.output !== 'string') return
+
+    const tagged = output.output.split('\n').map((line: string) => {
+      if (isTaggedLine(line)) return line
+      const m = LINE_PREFIX_RE.exec(line)
+      if (!m) return line
+      const lineNo = Number(m[1] ?? m[3])
+      const content = m[2] ?? m[4] ?? ''
+      return `${lineNo}#${hashTag(content, lineNo)}|${content}`
+    })
+
+    output.output = tagged.join('\n')
+  }
+}