smcreader 0.0.0-stage → 0.1.2

package/lib/intercept-hook.js

@@ -0,0 +1,190 @@
+/**
+ * intercept-hook — PostToolUse hook that intercepts LARGE tool outputs before
+ * they reach the main agent's context and replaces them with a "lazy pointer":
+ * a compact header + head/tail + reader_id.
+ *
+ * Haiku is NOT called at interception time (zero latency, zero cost) — the
+ * actual reading happens lazily, when the agent calls reader_ask with a
+ * question it already has (pull model).
+ *
+ * Fail-safe: any failure inside the hook → return {} (output passes through as is).
+ * Losing compression is cheap; blinding the agent is expensive.
+ */
+
+const DEFAULT_THRESHOLD = 2048; // chars; ~500 tokens
+const HEAD_LINES = 8;
+const TAIL_LINES = 4;
+const POINTER_BODY_CAP = 900; // chars for head+tail in the pointer
+
+/** Tools whose outputs are intercepted by default. Deliberately NOT: Read (exact bytes
+ *  for Edit), Agent/Task (already summaries), mcp__reader__* (recursion). MCP tools —
+ *  only via an explicit allowlist ($READER_ALLOWLIST): each has its own output shape. */
+const DEFAULT_ALLOWLIST = ['Bash', 'WebFetch'];
+
+/**
+ * Extract text from tool_response + classify its SHAPE. The shape is critical:
+ * the engine applies updatedToolOutput only if the replacement structurally matches
+ * what the tool returned (otherwise "does not match output shape" → original is kept).
+ * shape ∈ {string, stdout, content, output, array, file} — supported for replacement;
+ * 'unknown' → skip interception (fail-open).
+ */
+function extractText(toolResponse) {
+  if (typeof toolResponse === 'string') return { text: toolResponse, shape: 'string' };
+  if (toolResponse == null) return { text: '', shape: 'unknown' };
+  if (typeof toolResponse === 'object') {
+    if (typeof toolResponse.stdout === 'string') { // Bash: {stdout,stderr,interrupted,isImage,...}
+      const err = typeof toolResponse.stderr === 'string' && toolResponse.stderr.trim()
+        ? `\n--- stderr ---\n${toolResponse.stderr}` : '';
+      return { text: toolResponse.stdout + err, shape: 'stdout' };
+    }
+    if (Array.isArray(toolResponse.content)) { // MCP: {content:[{type:'text',text}]}
+      const text = toolResponse.content
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text).join('\n');
+      if (text) return { text, shape: 'content' };
+    }
+    if (typeof toolResponse.output === 'string') return { text: toolResponse.output, shape: 'output' };
+    // Read: {type:'text', file:{filePath, content, numLines, startLine, totalLines}}.
+    // Without this shape, interception silently failed open on EVERY Read, and large
+    // file contents went into the context in full.
+    if (toolResponse.file && typeof toolResponse.file.content === 'string') {
+      return { text: toolResponse.file.content, shape: 'file' };
+    }
+    // MCP output as a bare array of content blocks: [{type:'text',text}, ...]
+    // (some MCP servers return this; Object.keys of the array = ['0','1',...]).
+    if (Array.isArray(toolResponse)) {
+      const text = toolResponse
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text).join('\n');
+      if (text) return { text, shape: 'array' };
+    }
+  }
+  return { text: '', shape: 'unknown' }; // can't mirror this shape — don't intercept
+}
+
+/**
+ * Build the replacement in the SAME shape the tool returned, substituting the pointer.
+ * Other fields (interrupted, isImage, ...) are preserved; stderr is cleared.
+ */
+function buildReplacement(toolResponse, shape, pointer) {
+  switch (shape) {
+    case 'string': return pointer;
+    case 'stdout': return { ...toolResponse, stdout: pointer, stderr: '' };
+    case 'content': return { ...toolResponse, content: [{ type: 'text', text: pointer }] };
+    case 'output': return { ...toolResponse, output: pointer };
+    // Other file fields (filePath/numLines/…) are kept: the engine checks the shape,
+    // and the agent benefits from seeing WHAT was moved to the reader.
+    case 'file': return { ...toolResponse, file: { ...toolResponse.file, content: pointer } };
+    case 'array': return [{ type: 'text', text: pointer }]; // array of content blocks — mirror as an array
+    default: return null;
+  }
+}
+
+function headTail(text) {
+  const lines = text.split('\n');
+  if (lines.length <= HEAD_LINES + TAIL_LINES) {
+    // Few lines, but the text may be huge (minified JSON, single-line log):
+    // use character head+tail so the tail (exit code, last error) is not lost.
+    if (text.length <= POINTER_BODY_CAP) return text;
+    const headChars = Math.floor(POINTER_BODY_CAP * 0.7);
+    const tailChars = POINTER_BODY_CAP - headChars;
+    return `${text.slice(0, headChars)}\n... (${text.length - headChars - tailChars} chars omitted — in the reader) ...\n${text.slice(-tailChars)}`;
+  }
+  const head = lines.slice(0, HEAD_LINES).join('\n');
+  const tail = lines.slice(-TAIL_LINES).join('\n');
+  let body = `${head}\n... (${lines.length - HEAD_LINES - TAIL_LINES} lines omitted — in the reader) ...\n${tail}`;
+  if (body.length > POINTER_BODY_CAP) body = body.slice(0, POINTER_BODY_CAP) + '…';
+  return body;
+}
+
+function describeInput(toolName, toolInput) {
+  try {
+    if (toolName === 'Bash' && toolInput?.command) return toolInput.command.slice(0, 200);
+    if (toolName === 'WebFetch' && toolInput?.url) return toolInput.url.slice(0, 200);
+    if (toolInput?.command) return String(toolInput.command).slice(0, 200);
+    return JSON.stringify(toolInput).slice(0, 200);
+  } catch (_) { return '(unprintable input)'; }
+}
+
+/**
+ * Factory for the PostToolUse callback.
+ * @param {object} opts
+ * @param {object} opts.store      ReaderStore
+ * @param {number} [opts.threshold]
+ * @param {string[]} [opts.allowlist]
+ * @param {Function} [opts.log]
+ */
+// owner — id of the session that owns intercepted documents (shared store of the main agent).
+// taskContext() — the agent's task, used in the reader briefing.
+// askHint(id) — last line of the pointer: how to work with the reader.
+function createInterceptHook({ store, threshold = DEFAULT_THRESHOLD, allowlist = DEFAULT_ALLOWLIST, log = console.log, owner,
+  taskContext = null, askHint = null } = {}) {
+  if (!store) throw new Error('createInterceptHook requires {store}');
+  const allowed = new Set(allowlist);
+
+  return async function postToolUseIntercept(input /*, toolUseID, { signal } */) {
+    try {
+      const toolName = input?.tool_name;
+      if (!toolName || !allowed.has(toolName)) return {};
+
+      const { text, shape } = extractText(input.tool_response);
+      if (!text || text.length < threshold) return {};
+      if (shape === 'unknown') return {}; // shape can't be mirrored → skip (the engine would reject the replacement)
+
+      const inputDesc = describeInput(toolName, input.tool_input);
+      let task = null;
+      try { task = typeof taskContext === 'function' ? taskContext() : null; } catch (_) { task = null; }
+      const why = input.tool_input && typeof input.tool_input.description === 'string' ? input.tool_input.description.trim() : '';
+      // The task and the call description give the reader a goal: without them the briefing
+      // is a generic "look for errors" template, and the reader has nothing to judge
+      // "what matters here" against.
+      const briefing = `Intercepted output of ${toolName} (${inputDesc}).`
+        + (task ? ` The agent's task: ${String(task).slice(0, 600)}.` : '')
+        + (why ? ` Its own description of this call: ${why.slice(0, 300)}.` : '')
+        + ` The main agent saw only a head/tail pointer and will ask about specifics. Watch for: errors, warnings, anomalies, unexpected values${task ? ', and whatever matters for the task' : ''}.`;
+      // The hook also fires for subagent tools (Agent/Task) — the SDK sets agent_id for them.
+      // Under the session owner, their outputs would consume the session's reader limit and
+      // evict its documents. A subagent gets its own child owner: its own limit and LRU;
+      // the session can still close them.
+      const docOwner = input.agent_id
+        ? `${owner !== undefined ? `${owner}/` : ''}agent:${input.agent_id}`
+        : owner;
+      const r = store.open({ text }, briefing, {
+        tool_name: toolName,
+        tool_input: inputDesc,
+        ...(docOwner !== undefined ? { owner: docOwner } : {}),
+      });
+
+      // Eviction MUST be visible right here: the pointer is the only thing the agent
+      // reads. It doesn't see the store's server log, and a silently lost document
+      // looks to it like "the reader lied".
+      const cap = store.limits && store.limits.MAX_OPEN;
+      const evictedNote = r.evicted
+        ? `\n(evicted ${r.evicted}${cap ? ` — ${cap}/${cap} open` : ' — reader limit reached'}; close with mcp__reader__reader_close)`
+        : '';
+      const pointer =
+        `[READER ${r.id}] ${toolName} output intercepted: ${r.size} bytes, ${r.lines} lines (>${threshold} chars).${evictedNote}\n` +
+        `${headTail(text)}\n` +
+        (typeof askHint === 'function' ? askHint(r.id)
+          : `Full output is in reader ${r.id}: mcp__reader__reader_ask(id, question) to analyze, reader_peek(id, start_line, end_line) for exact lines, reader_close(id) when done.`);
+
+      // The replacement MUST match the tool's shape — otherwise the engine silently keeps the original.
+      const replacement = buildReplacement(input.tool_response, shape, pointer);
+      if (replacement === null) return {}; // safety net
+
+      log(`[reader-hook] intercepted ${toolName} output: ${text.length} chars (shape=${shape}) -> ${r.id}`);
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          updatedToolOutput: replacement,
+        },
+      };
+    } catch (e) {
+      // fail-open: never break output delivery
+      try { log(`[reader-hook] error (passing output through): ${e.message}`); } catch (_) {}
+      return {};
+    }
+  };
+}
+
+module.exports = { createInterceptHook, extractText, buildReplacement, headTail, DEFAULT_ALLOWLIST, DEFAULT_THRESHOLD };

package/lib/read-guard.js

@@ -0,0 +1,128 @@
+/**
+ * read-guard — PreToolUse guard for large Reads: a full Read of a large file is
+ * not let into the context window, only a targeted one (limit/offset) or navigation.
+ *
+ * A factory (rather than a ready-made hook), because the threshold and the set of
+ * alternatives depend on the agent's profile (whether it has a reader, whether Read
+ * output is intercepted). A denial MUST lead to a working path: an agent told "no"
+ * without "but you can do this" simply loses access to the information.
+ *
+ * Fail-open on anything unclear (no file_path, stat failed, binary file) —
+ * let Read return its own error; blinding the agent costs more than not compressing.
+ */
+
+const fs = require('fs');
+
+const DEFAULT_THRESHOLD = 32 * 1024;
+// Binary formats are not guarded — they can't be read by line ranges.
+const BINARY_EXT = /\.(png|jpe?g|gif|webp|bmp|ico|pdf|ipynb)$/i;
+// How much of the file to measure: sources and logs being edited are hundreds of KB; the tail
+// of a giant log (beyond 4 MB) won't refine the chunk size, and the hook blocks every Read.
+const MEASURE_BYTES = 4 * 1024 * 1024;
+const CHUNK_FIT_SHARE = 0.95;
+
+/**
+ * Chunk size for a targeted Read that will get past output interception. For a subagent there
+ * is a second guard behind this one — Read output larger than outputCap goes to the reader
+ * (Read interception, intercept-hook). Given a bare "Read with limit" hint, an agent would pick
+ * e.g. limit 200 on a 17 KB file and get a reader pointer instead of the text. Average line
+ * length doesn't work — on an uneven file a chunk based on the average still ends up in the
+ * reader, while a worst-case guarantee chops the file into tiny pieces. We take the largest N
+ * such that 95% of all windows of N consecutive lines are shorter than the cap, whatever line
+ * you start from; the hint itself covers the dense spots.
+ * Measured in characters, like the interception itself (file.content without line numbers).
+ * @returns {{per: number, total: number}|null} lines per read and lines in the file; null — don't chunk
+ */
+function chunkLines(file, size, outputCap) {
+  const fd = fs.openSync(file, 'r');
+  let text;
+  try {
+    const buf = Buffer.alloc(Math.min(size, MEASURE_BYTES));
+    text = buf.subarray(0, fs.readSync(fd, buf, 0, buf.length, 0)).toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+  const parts = text.split('\n');
+  if (parts.length > 1 && parts[parts.length - 1] === '') parts.pop();   // trailing newline is not a line
+  const lens = parts.map(l => l.length + 1);
+  const pre = [0];
+  for (const l of lens) pre.push(pre[pre.length - 1] + l);
+  const fits = (n) => {
+    let bad = 0;
+    for (let i = n; i < pre.length; i++) if (pre[i] - pre[i - n] >= outputCap) bad++;
+    return bad <= (pre.length - n) * (1 - CHUNK_FIT_SHARE);
+  };
+  if (!fits(1)) return null;                                   // lines longer than the cap — can't chunk by lines
+  let lo = 1, hi = lens.length;
+  while (lo < hi) { const mid = Math.ceil((lo + hi) / 2); if (fits(mid)) lo = mid; else hi = mid - 1; }
+  const per = lo >= 100 ? lo - lo % 10 : lo;
+  const total = size <= MEASURE_BYTES ? lens.length : Math.round(lens.length * size / text.length);
+  return { per, total };
+}
+
+/**
+ * Denial text. Every item is an executable command, not advice like "read less".
+ * @param {number} kb file size
+ * @param {number} thresholdKb threshold
+ * @param {boolean} hasReader whether mcp__reader__* is available to the agent (without it, the reader item is a trap)
+ * @param {{capKb: number, per?: number, total?: number}} [cap] the agent's Read output interception
+ */
+function denyReason(kb, thresholdKb, hasReader, cap) {
+  const chunk = !cap ? ''
+    : cap.per
+      ? `, but output over ${cap.capKb}KB goes to the reader — read ${cap.per} lines at a time (file has ~${cap.total}): offset 1, ${cap.per + 1}, ${2 * cap.per + 1}…; if a chunk went to the reader (dense section), retry with half the limit`
+      : `, but output over ${cap.capKb}KB goes to the reader — read chunks smaller than ${cap.capKb}KB`;
+  const ways = [
+    `Read(file_path, offset, limit) — targeted read; Read with limit/offset is ALWAYS allowed${chunk}`,
+    'Grep(pattern, path, -n) — returns line numbers, then do a targeted Read at them',
+    ...(hasReader
+      ? ['mcp__reader__reader_open({path, briefing}) + mcp__reader__reader_ask(id, question) — the file goes to a separate reader, only the answers enter your context; mcp__reader__reader_peek(id, start_line, end_line) gives a verbatim slice']
+      : []),
+    "Bash: sed -n '120,180p' file / head -80 / tail -80 / grep -n",
+  ];
+  // Without the last line, an agent that read the file via the reader would pull a separate
+  // full copy for Edit: Edit requires a Read, and a targeted one is enough for the whole file.
+  return `File is ${kb}KB (threshold ${thresholdKb}KB): a full Read would bloat your context. ` +
+    `Read it this way instead:\n` + ways.map((w, i) => `${i + 1}) ${w}`).join('\n') +
+    `\nEdit does not need a full Read: after a targeted Read (offset/limit), Edit works on the whole file.`;
+}
+
+/**
+ * @param {object} opts
+ * @param {number} [opts.threshold] bytes; larger — deny Read without limit/offset
+ * @param {boolean} [opts.hasReader] whether the agent has mcp__reader__*
+ * @param {number} [opts.outputCap] chars; larger Read output is intercepted into the reader (8 KB for subagents)
+ * @param {Function} [opts.log]
+ * @returns {Function} PreToolUse callback (matcher 'Read')
+ */
+function createReadGuardHook({ threshold = DEFAULT_THRESHOLD, hasReader = false, outputCap = 0, log = console.log } = {}) {
+  const thresholdKb = Math.round(threshold / 1024);
+  return async function preToolUseReadGuard(input /*, toolUseID, { signal } */) {
+    try {
+      if (!input || input.tool_name !== 'Read') return {};
+      const ti = input.tool_input || {};
+      if (ti.limit || ti.offset) return {};                       // targeted read — always allowed
+      if (!ti.file_path || BINARY_EXT.test(ti.file_path)) return {};
+      const size = fs.statSync(ti.file_path).size;
+      if (size <= threshold) return {};
+      const kb = Math.round(size / 1024);
+      try { log(`[read-guard] deny: ${ti.file_path} (${kb}KB)`); } catch (_) {}
+      let cap = null;
+      if (outputCap) {
+        cap = { capKb: Math.round(outputCap / 1024) };
+        try { Object.assign(cap, chunkLines(ti.file_path, size, outputCap)); } catch (_) { /* no numbers — generic hint */ }
+      }
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: denyReason(kb, thresholdKb, hasReader, cap),
+        },
+      };
+    } catch (_) {
+      return {}; // no file / stat failed — let Read return its own error
+    }
+  };
+}
+
+module.exports = { createReadGuardHook, denyReason, chunkLines, DEFAULT_THRESHOLD, BINARY_EXT };

package/lib/reader-mcp.js

@@ -0,0 +1,32 @@
+/**
+ * reader-mcp — factory for the in-process "reader" MCP server for the Agent SDK
+ * (createSdkMcpServer → options.mcpServers). Same tools as the stdio server,
+ * from the same core (lib/reader-tools.js).
+ *
+ * In-process: the SDK keeps the instance in a per-query map and connects it on every query(),
+ * so do NOT reuse one object across calls — call the factory on every turn.
+ * The SDK is required LAZILY: it is ESM, and a static require breaks jest's parsing of
+ * modules that import this one.
+ */
+
+'use strict';
+
+const { createReaderTools, READER_TOOL_NAMES } = require('./reader-tools');
+
+/**
+ * @param {object} opts — same as createReaderTools, plus
+ * @param {boolean} [opts.alwaysLoad] tools are in the prompt right away, without ToolSearch
+ * @returns {object} McpSdkServerConfigWithInstance
+ */
+function createReaderMcpServer({ alwaysLoad = false, ...opts } = {}) {
+  if (!opts.store) throw new Error('createReaderMcpServer requires {store}');
+  const { createSdkMcpServer, tool } = require('@anthropic-ai/claude-agent-sdk');
+  return createSdkMcpServer({
+    name: 'reader',
+    version: '1.0.0',
+    ...(alwaysLoad ? { alwaysLoad: true } : {}),
+    tools: createReaderTools(opts).map((t) => tool(t.name, t.description, t.schema, t.handler)),
+  });
+}
+
+module.exports = { createReaderMcpServer, READER_TOOL_NAMES };

package/lib/reader-model.js

@@ -0,0 +1,230 @@
+/**
+ * reader-haiku — the dialog layer of the reader MCP: a Haiku reader that holds
+ * the document in its context and answers questions from the main agent.
+ *
+ * Transport: query({model:'haiku'}) from claude-agent-sdk (Claude Code OAuth,
+ * or ANTHROPIC_API_KEY — same as Claude Code itself). The first ask creates a
+ * Haiku session with framing + briefing + numbered document; subsequent asks
+ * resume the same session (the document stays in its context, questions are cheap).
+ * The transport can be swapped inside ask() without changing the store or tools.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// cwd for Haiku sessions: their transcripts go to a separate Claude Code project, not the agent's project.
+// The directory is created on the first question, not at module load (the hook and tests don't need it).
+const workDir = () => process.env.READER_WORK_DIR || path.join(os.tmpdir(), 'reader-work');
+
+// Claude Code binary for the Haiku sessions. The SDK ships its own as an optional per-platform package
+// (~280 MB); the plugin starts the server via `npx --omit=optional` and reuses the user's `claude`.
+// Order: $READER_CLAUDE_EXECUTABLE → the SDK's bundled binary, if installed → `claude` on PATH.
+function bundledBinaryInstalled() {
+  const base = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`;
+  for (const name of [base, `${base}-musl`]) {
+    try { require.resolve(`${name}/package.json`); return true; } catch (_) { /* not installed */ }
+  }
+  return false;
+}
+
+function findOnPath(cmd, env = process.env) {
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const p = path.join(dir, cmd + ext);
+      try { fs.accessSync(p, fs.constants.X_OK); if (fs.statSync(p).isFile()) return p; } catch (_) { /* next */ }
+    }
+  }
+  return null;
+}
+
+/** @returns {string|undefined} path for options.pathToClaudeCodeExecutable; undefined = the SDK's bundled binary */
+function resolveClaudeExecutable({ env = process.env, bundled = bundledBinaryInstalled } = {}) {
+  if (env.READER_CLAUDE_EXECUTABLE) return env.READER_CLAUDE_EXECUTABLE;
+  if (bundled()) return undefined;
+  const found = findOnPath('claude', env);
+  if (!found) {
+    throw new Error('reader_ask needs Claude Code: put `claude` on PATH or set READER_CLAUDE_EXECUTABLE '
+      + '(the Agent SDK\'s bundled binary is not installed)');
+  }
+  return found;
+}
+
+const READER_FRAMING = `You are a document reader serving a main AI agent. Below is a document with line numbers ("N<TAB>text") and a BRIEFING explaining why the agent opened it.
+
+RULES (strict, apply to every answer in this conversation):
+1. ANSWER concisely and densely. Every factual claim cites line numbers: (L120) or (L120-134). If the answer is not in the document, say "not in document" — NEVER invent or fill gaps from general knowledge.
+2. VERBATIM PRESERVATION: reproduce numbers, file paths, identifiers, versions, URLs and error-message text EXACTLY as written, character for character. Never round numbers, never paraphrase error text.
+3. End EVERY response with a "NOTICED:" section — important things the agent did NOT ask about: errors, warnings, anomalies, contradictions, secrets/keys, TODOs/FIXMEs, deprecations, suspicious values. One line each with citations. Do not repeat items already reported earlier in this conversation. If nothing new: exactly "NOTICED: nothing new".
+4. If a question is ambiguous, answer the most likely reading and flag the ambiguity in one line.
+Keep answers under ~400 words unless enumeration is demanded.`;
+
+/**
+ * Question transport: a single-turn Haiku call via agent-sdk; resume continues the dialog.
+ * @param {object} [o]
+ * @param {string} [o.cwd]       cwd for Haiku sessions (default $READER_WORK_DIR or $TMPDIR/reader-work); created on call
+ * @param {object} [o.settings]  settings for query (e.g. {cleanupPeriodDays: 365} — transcript retention period)
+ * @param {number} [o.cleanupPeriodDays] shorthand for settings.cleanupPeriodDays
+ * @param {string} [o.executable] Claude Code binary (default: resolveClaudeExecutable() on each call)
+ * @returns {Function} (prompt, resumeSid, {fork}) → {out, sid}
+ */
+function createRunQuery({ cwd: cwdOpt, settings, cleanupPeriodDays, executable } = {}) {
+  const merged = { ...(settings || {}), ...(cleanupPeriodDays !== undefined ? { cleanupPeriodDays } : {}) };
+  const hasSettings = Object.keys(merged).length > 0;
+  // fork — branch off the resumeSid session (parallel question to the same document): the base is unchanged.
+  return async function runQuery(prompt, resumeSid, { fork = false } = {}) {
+    const { query } = require('@anthropic-ai/claude-agent-sdk');
+    const cwd = cwdOpt || workDir();
+    const exe = executable || resolveClaudeExecutable();
+    fs.mkdirSync(cwd, { recursive: true });
+    let out = '';
+    let sid = resumeSid || null;
+    const q = query({
+      prompt,
+      options: {
+        cwd,
+        // Do not inherit the user's settings.json: their hooks (including the reader hook itself
+        // and Stop hooks that replace the result) must not affect the reader session.
+        settingSources: [],
+        ...(hasSettings ? { settings: merged } : {}),
+        tools: { type: 'preset', preset: 'claude_code' },
+        permissionMode: 'default',
+        canUseTool: async (n, i) => ({ behavior: 'deny', message: 'reader is read-only' }),
+        model: 'haiku',
+        allowedTools: [],
+        maxTurns: 10,
+        ...(exe ? { pathToClaudeCodeExecutable: exe } : {}),
+        ...(resumeSid ? { resume: resumeSid } : {}),
+        ...(resumeSid && fork ? { forkSession: true } : {}),
+      },
+    });
+    for await (const m of q) {
+      if (m.session_id) sid = m.session_id;
+      if (m.type === 'result') out = m.result || '';
+    }
+    return { out, sid };
+  };
+}
+
+const defaultRunQuery = createRunQuery();
+
+// ---- "lines" answer format ----
+// Most of the answer latency is generating a long answer (<=400 words + NOTICED), not the prompt
+// or tools. An answer of "line ranges + a note of <=40 words" takes ~5–7 s, and the ranges are
+// accurate. The line text is filled in by the SERVER from the file (store.peek), so it is verbatim
+// by construction: Haiku does not retype or distort code.
+const LINES_CAP = 160;   // lines shown verbatim in one answer; the rest are listed as ranges for reader_peek
+
+// NOTICED is not requested in lines mode: scanning the whole document for "anything else suspicious"
+// made the first answer take 12–16 s versus 7–9 s without it, while subagents typically ask a document
+// a single question right after opening it. Suspicious items can be requested with a separate question.
+function linesInstruction() {
+  return '\n\nANSWER FORMAT for this question (overrides rule 1 prose and rule 3 — NO NOTICED section in this answer): ONLY one JSON object, no other text:\n'
+    + '{"ranges":[[from,to],...],"note":"the direct answer in <=40 words; numbers, identifiers, paths verbatim"}\n'
+    + 'ranges = the fewest document lines that answer the question; the agent will see exactly these lines verbatim. '
+    + 'If the answer is not in the document: "ranges":[] and say so in note.';
+}
+
+// First parseable JSON object in the answer (Haiku sometimes appends text after it).
+function extractJson(raw) {
+  const s = String(raw || '');
+  const start = s.indexOf('{');
+  if (start === -1) return null;
+  for (let end = s.lastIndexOf('}'); end > start; end = s.lastIndexOf('}', end - 1)) {
+    try { return JSON.parse(s.slice(start, end + 1)); } catch (_) { /* try shorter */ }
+  }
+  return null;
+}
+
+function renderLines(store, entry, raw) {
+  const j = extractJson(raw);
+  if (!j || !Array.isArray(j.ranges)) return `(answer not in lines format — shown as is)\n${raw}`;
+  const total = entry.meta.lines;
+  const rs = j.ranges
+    .map(r => (Array.isArray(r) ? r : [r, r]))
+    .map(([a, b]) => [Math.max(1, Math.floor(Number(a))), Math.min(total, Math.floor(Number(b ?? a)))])
+    .filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b) && a <= b)
+    .sort((x, y) => x[0] - y[0]);
+  const merged = [];
+  for (const r of rs) {
+    const last = merged[merged.length - 1];
+    if (last && r[0] <= last[1] + 1) last[1] = Math.max(last[1], r[1]); else merged.push([...r]);
+  }
+  let budget = LINES_CAP;
+  const parts = [];
+  const cut = [];
+  for (const [a, b] of merged) {
+    if (budget <= 0) { cut.push(`${a}-${b}`); continue; }
+    const e = Math.min(b, a + budget - 1);
+    parts.push(store.peek(entry.id, a, e));
+    budget -= e - a + 1;
+    if (e < b) cut.push(`${e + 1}-${b}`);
+  }
+  let out = j.note ? String(j.note).trim() : '';
+  out += parts.length ? `\n\n${parts.join('\n…\n')}` : '\n\n(no lines given — not in document)';
+  if (cut.length) out += `\n\n(not shown due to the ${LINES_CAP}-line limit: ${cut.join(', ')} — use reader_peek)`;
+  if (Array.isArray(j.noticed)) {
+    out += j.noticed.length ? `\n\nNOTICED:\n${j.noticed.map(x => `- ${x}`).join('\n')}` : '\n\nNOTICED: nothing new';
+  }
+  return out.trim();
+}
+
+function numberLines(text) {
+  return text.split('\n').map((l, i) => `${i + 1}\t${l}`).join('\n');
+}
+
+/**
+ * Ask the reader a question.
+ * A single question continues the dialog (entry.lock; the haikuSid session remembers earlier questions).
+ * A question that arrives while another one to the same document is in flight runs IN PARALLEL, without
+ * queueing: as a fork of the existing session (forkSession) or, if there is no session yet, in its own
+ * session with the document. Agents often ask questions in a batch, and queueing them would add up
+ * their latencies (e.g. 16 + 6.5 + 8.6 = 31 s).
+ * A parallel question does not see its siblings (they were written without each other's answers); the
+ * dialog base is changed only by a sequential question — or by a parallel one if there is no base yet.
+ * @param {object} store   ReaderStore (for readRaw)
+ * @param {object} entry   entry from store.get()
+ * @param {string} question
+ * @param {Function} [runQuery] transport injection for tests: (prompt, resumeSid, {fork}) → {out, sid}
+ * @param {object} [opts] format: 'prose' (connected answer with NOTICED) | 'lines' (verbatim lines + note)
+ * @returns {Promise<string>}
+ */
+async function ask(store, entry, question, runQuery = defaultRunQuery, opts = {}) {
+  const lines = opts.format === 'lines';
+  const gate = store.canAsk(entry);
+  if (!gate.ok) throw new Error(gate.reason);
+
+  const parallel = (entry.inFlight || 0) > 0;
+  entry.inFlight = (entry.inFlight || 0) + 1;
+  const exec = async () => {
+    const base = entry.haikuSid;
+    const q = lines ? question + linesInstruction() : question;
+    let prompt;
+    if (!base) {
+      const doc = numberLines(store.readRaw(entry.id));
+      const note = entry.rehydrated ? '\n(Note: a previous dialog about this document was reset by a server restart.)' : '';
+      prompt = `${READER_FRAMING}\n\nBRIEFING from the main agent: ${entry.meta.briefing}${note}\n\n--- DOCUMENT ${entry.id} (${entry.meta.lines} lines, ${entry.meta.size} bytes, source: ${entry.meta.source.path || 'inline text'}) ---\n${doc}\n--- END DOCUMENT ---\n\nFirst question: ${q}`;
+    } else {
+      prompt = q;
+    }
+    const { out, sid } = await runQuery(prompt, base, { fork: parallel && !!base });
+    if (!out) throw new Error('haiku returned an empty answer (transport problem?)');
+    // save the session ONLY on success — otherwise the dialog is not "corrupted"
+    if (!parallel || !entry.haikuSid) entry.haikuSid = sid;
+    entry.rehydrated = false;
+    entry.asks++;
+    return lines ? renderLines(store, entry, out) : out;
+  };
+  let run;
+  if (parallel) run = exec();
+  else {
+    run = entry.lock.then(exec);
+    // even on error the lock chain must not break for subsequent asks
+    entry.lock = run.catch(() => {});
+  }
+  return run.finally(() => { entry.inFlight--; });
+}
+
+module.exports = { ask, createRunQuery, defaultRunQuery, resolveClaudeExecutable, READER_FRAMING, numberLines, renderLines, extractJson, LINES_CAP };