smcreader 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "smcreader",
+  "description": "SMC Reader (Save My Context Reader) for Claude Code",
+  "owner": { "name": "bulatko" },
+  "plugins": [
+    {
+      "name": "smcreader",
+      "description": "Large tool outputs go to disk behind a short pointer; the model pulls only the lines it needs.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "smcreader",
+  "version": "0.1.1",
+  "description": "SMC Reader (Save My Context Reader): large tool outputs are spilled to disk and replaced by a short pointer; the model pulls only the lines it needs via reader_ask / reader_peek.",
+  "author": { "name": "bulatko" },
+  "homepage": "https://github.com/bulatko/SMCReader",
+  "repository": "https://github.com/bulatko/SMCReader",
+  "license": "MIT",
+  "keywords": ["context", "mcp", "hooks", "tool-output"]
+}

package/.mcp.json

@@ -0,0 +1,7 @@
+{
+  "smcreader": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "--omit=optional", "--package=smcreader@0.1.1", "smcreader-mcp"]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bulatko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# SMC Reader
+
+**Save My Context Reader** — keep large tool outputs out of your agent's context window.
+
+[![CI](https://github.com/bulatko/SMCReader/actions/workflows/ci.yml/badge.svg)](https://github.com/bulatko/SMCReader/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node ≥ 20](https://img.shields.io/badge/node-%E2%89%A5%2020-339933?logo=node.js&logoColor=white)
+![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)
+
+<img src="docs/hero.svg" alt="Without SMC Reader a 13.9 KB command output stays in the model context; with SMC Reader a hook spills it to disk and the model gets a ~1 KB pointer and pulls only the lines it needs" width="880">
+
+</div>
+
+A big `Bash` or `WebFetch` output does not have to land in the model's context.
+SMC Reader's hook catches it **before the model sees it**, spills it to disk and hands the model a
+short pointer. The model then pulls only what it needs — exact lines, or an answer to a question.
+
+## Quick start
+
+In Claude Code (Node.js ≥ 20 on `PATH`):
+
+```
+/plugin marketplace add bulatko/SMCReader
+/plugin install smcreader@smcreader
+```
+
+That's it — no `settings.json` or `--mcp-config` edits. Run something noisy and the model gets this
+instead of 3000 lines:
+
+```
+[READER ctx_b4c9b23c] Bash output intercepted: 13893 bytes, 3001 lines (>2048 chars).
+1
+2
+...
+... (2989 lines omitted — in the reader) ...
+2999
+3000
+Full output is in reader ctx_b4c9b23c: mcp__plugin_smcreader_smcreader__reader_ask(id, question) to analyze, mcp__plugin_smcreader_smcreader__reader_peek(id, start_line, end_line) for exact lines, mcp__plugin_smcreader_smcreader__reader_close(id) when done.
+```
+
+## Why
+
+Agents run commands whose output is mostly noise for the task at hand: test logs, build output,
+`grep -r`, `git log`, fetched pages. Every byte of it stays in the context for the rest of the
+session, pushes out what matters and makes every following turn more expensive.
+Truncating is not a fix — the one line the agent needs may be in the middle.
+
+Measured on our own agent transcripts over 5 days (19–23 Oct 2026): **472 interceptions, 2.88 MB**
+of tool output.
+
+| what the agent did with the intercepted output | share |
+|---|---:|
+| nothing — the head and tail in the pointer were enough | **48%** |
+| asked a question (`reader_ask`) | 11% |
+| pulled a part of it (`reader_peek`) | 14% |
+| pulled almost everything back | 27% |
+
+**54% of the intercepted bytes (1.55 MB) never entered the context.** On outputs of 16 KB and more
+the saving is about **21 KB per interception**.
+
+## How it works
+
+<p align="center">
+<img src="docs/analogy.svg" alt="Three steps: 1) Opus runs npm test; the SMC Reader hook catches the 3,000-line output before it reaches Opus and saves it to disk; 2) Opus gets a short note instead, saying what was caught and how to read it with reader_ask or reader_peek; 3) Opus asks Haiku which test failed, Haiku reads all of it and returns just the two lines that matter" width="880">
+</p>
+
+The main model (Opus, Fable) runs a command as usual — but the output never reaches it. SMC Reader's
+hook catches it on the way, saves it to disk and gives the model a short note instead: what was caught
+and how to read it. When the model needs something, it asks a cheap model (Haiku) with `reader_ask`;
+Haiku reads the whole output and returns only the lines that answer the question, verbatim.
+Exact lines by number (`reader_peek`) come straight from disk, with no model at all.
+
+Under the hood:
+
+1. Claude Code runs a tool and passes the result to the `PostToolUse` command hook.
+2. If the output is large (≥ 2048 chars by default), the hook writes it to
+   `~/.cache/smcreader/ctx_<id>.txt` and replaces it with a pointer **in the same shape as the
+   original output** — the engine silently ignores a replacement of a different shape.
+3. The model sees the pointer: id, size, head and tail of the output.
+4. It pulls what it needs through the `smcreader` MCP server:
+
+| tool | what it does |
+|---|---|
+| `reader_peek(id, start_line, end_line)` | exact numbered lines from disk, no LLM |
+| `reader_ask(id, question)` | a small Haiku session reads the document and returns the relevant lines verbatim with a short note |
+| `reader_open({path \| text, briefing})` | open any file or text explicitly |
+| `reader_list()` / `reader_close(id)` | what is open / delete a document |
+
+The hook and the MCP server are separate processes sharing one directory; the directory is the
+source of truth (open-document limit, LRU eviction, 48 h expiry since last use).
+
+## Install
+
+**As a plugin (recommended)** — see [Quick start](#quick-start); the repository is its own plugin
+marketplace. The hook has no dependencies and runs from the plugin directory. The MCP server is
+started with `npx -y --omit=optional --package=smcreader@<plugin version> smcreader-mcp`: the first
+start downloads the npm package once (~40 MB with dependencies, ~60 MB on disk). `--omit=optional`
+skips the Agent SDK's bundled Claude Code binaries (~280 MB per platform variant); `reader_ask` runs your own `claude`
+from `PATH` instead (or `READER_CLAUDE_EXECUTABLE`). Loaded as a plugin, the tools are named
+`mcp__plugin_smcreader_smcreader__reader_*`, and the hook writes these names into the pointer.
+
+For a one-off session from a checkout: `git clone https://github.com/bulatko/SMCReader ~/smcreader`
+and `claude --plugin-dir ~/smcreader`.
+
+<details>
+<summary><b>Manual setup</b> (hook in <code>settings.json</code> + <code>claude mcp add</code>)</summary>
+
+```sh
+npm install -g smcreader        # or: git clone … && npm install --omit=dev
+```
+
+1. Hook — add to `~/.claude/settings.json` (or a project's `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      { "matcher": "Bash|WebFetch",
+        "hooks": [{ "type": "command", "command": "READER_TOOL_PREFIX=mcp__smcreader__ smcreader-hook" }] }
+    ]
+  }
+}
+```
+
+2. MCP server:
+
+```sh
+claude mcp add smcreader -- smcreader-mcp
+```
+
+With a git checkout instead of a global install use `node /ABSOLUTE/PATH/bin/smcreader-hook` and
+`node /ABSOLUTE/PATH/bin/smcreader-mcp`. The old binary names `reader-hook` / `reader-mcp` remain
+as aliases.
+
+Both processes read the same environment; if you set `READER_DIR`, set it for both
+(`claude mcp add smcreader -e READER_DIR=/path -- smcreader-mcp`).
+
+**Intercepting an MCP tool.** Add it to the hook's `matcher` **and** to `READER_ALLOWLIST`, e.g.
+matcher `Bash|WebFetch|mcp__mesh__execute` and command
+`READER_ALLOWLIST=Bash,WebFetch,mcp__mesh__execute smcreader-hook`. Never allowlist SMC Reader's
+own tools.
+
+**Read guard (optional).** `PreToolUse`, matcher `Read`, same command with
+`READER_READ_GUARD=32768`: a full `Read` of a file above the threshold is denied with working
+alternatives (`Read` with offset/limit, Grep, `reader_open`, sed/head/tail). The plugin does not
+enable it.
+
+</details>
+
+<details>
+<summary><b>Configuration</b> (environment variables)</summary>
+
+| variable | default | used by | meaning |
+|---|---|---|---|
+| `READER_DIR` | `$XDG_CACHE_HOME/smcreader` or `~/.cache/smcreader` | both | shared document directory |
+| `READER_THRESHOLD` | `2048` | hook | intercept outputs of at least this many characters |
+| `READER_ALLOWLIST` | `Bash,WebFetch` | hook | comma-separated tool names to intercept |
+| `READER_TOOL_PREFIX` | — | hook | tool-name prefix written into the pointer, e.g. `mcp__smcreader__` |
+| `READER_READ_GUARD` | `0` (off) | hook | bytes; deny a full `Read` of bigger files (`PreToolUse`) |
+| `READER_LOG` | — | hook | append a log line per interception / error to this file |
+| `READER_OWNER` | — | server (hook: fallback) | owner the server acts as; unset = sees all documents |
+| `READER_ASK_FORMAT` | `lines` | server | default `reader_ask` format: `lines` (verbatim lines + short note) or `prose` |
+| `READER_WORK_DIR` | `$TMPDIR/reader-work` | server | cwd of the Haiku reader sessions (their transcripts land there) |
+| `READER_CLAUDE_EXECUTABLE` | the Agent SDK's bundled binary if installed, else `claude` on `PATH` | server | Claude Code binary that runs the Haiku reader |
+
+**Owners.** The hook stamps each document with the `session_id` from its input (a subagent's
+document gets `<session>/agent:<agent_id>`). The open-document limit (10) and LRU eviction are per
+owner; `reader_close` refuses another owner's document when the server has `READER_OWNER`;
+reading by id is never restricted.
+
+</details>
+
+<details>
+<summary><b>Development</b> (layout, tests)</summary>
+
+| path | role |
+|---|---|
+| `lib/reader-store.js` | document store over a directory (`ctx_<8hex>.txt` + `.meta.json`), owners, LRU limit, TTL sweep |
+| `lib/reader-model.js` | Haiku reader via Agent SDK `query()`; answer formats `prose` / `lines`; `createRunQuery({cwd, settings, cleanupPeriodDays, executable})` for embedding hosts |
+| `lib/reader-tools.js` | transport-free tool definitions `reader_open/ask/peek/close/list` |
+| `lib/intercept-hook.js` | interception: extract text, mirror the tool's output shape, build the pointer |
+| `lib/read-guard.js` | optional `PreToolUse` guard for big `Read`s |
+| `lib/stdio-mcp.js`, `bin/smcreader-mcp` | stdio MCP server (`@modelcontextprotocol/sdk`) |
+| `lib/reader-mcp.js` | in-process MCP factory for the Agent SDK (`createSdkMcpServer`) — same tools |
+| `lib/hook-command.js`, `bin/smcreader-hook` | the command hook (stdin JSON → stdout JSON) |
+| `.claude-plugin/`, `hooks/hooks.json`, `.mcp.json` | Claude Code plugin + marketplace manifests |
+| `e2e/claude-code.sh`, `e2e/plugin.sh` | end-to-end tests in a real Claude Code CLI |
+
+```sh
+npm test                                         # unit + cross-process (spawns the real bin/ scripts)
+sh e2e/claude-code.sh                            # real Claude Code: hook via --settings, server via --mcp-config
+READER_E2E_NO_HOOK=1 sh e2e/claude-code.sh       # negative control: no hook — must fail
+sh e2e/plugin.sh                                 # real Claude Code, everything from the plugin
+READER_E2E_NO_PLUGIN=1 sh e2e/plugin.sh          # negative control: no --plugin-dir — must fail
+READER_E2E_PACKAGE=registry sh e2e/plugin.sh     # the published npm version instead of `npm pack`
+```
+
+`e2e/plugin.sh` loads a copy of the tracked files without `node_modules` (what a marketplace
+install gets) and points its `.mcp.json` at `npm pack` of the working tree.
+
+**Releasing.** A marketplace install takes the plugin from the default branch, and its `.mcp.json`
+pins `smcreader@<version>` — so publish that version to npm *before* pushing the version bump.
+
+The e2e verdict comes from `--output-format stream-json`, i.e. from what the model actually
+received, not from what it said: (1) the Bash `tool_result` contains `[READER ctx_` and not
+`1500` (from `seq 1 3000`); (2) a reader tool call with that id returned `2999`. One run takes
+~10–20 s and ~$0.03 on Haiku. CI runs only `npm test`: e2e needs a logged-in Claude Code.
+
+</details>
+
+## Limitations
+
+- Needs a Claude Code version that applies `hookSpecificOutput.updatedToolOutput` from command
+  hooks (verified on 2.1.282). Older versions call the hook but keep the original output.
+- Supported output shapes: string, `{stdout,…}` (Bash), `{content:[…]}` (MCP), `{output}`,
+  `{file:{content}}` (Read), arrays of content blocks. Unknown shape → passed through untouched.
+- `Read` is not intercepted by default — `Edit` needs exact bytes. Use the read guard instead.
+- `reader_ask` needs Claude Code credentials and a `claude` binary (Agent SDK, model Haiku);
+  `reader_open` / `reader_peek` / `reader_list` work without them. Documents above 700 KB can
+  only be peeked; above 5 MB `reader_open` refuses them.
+- The plugin's hook sets an environment variable inline (`VAR=… node …`), which needs a POSIX
+  shell; Windows is not tested.
+- The server does not know the Claude Code session by itself (it outlives `/clear` and resumes);
+  set `READER_OWNER` if you need per-session isolation in a shared `READER_DIR`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/reader-hook

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Alias kept for existing installs: same as bin/smcreader-hook.
+require('./smcreader-hook');

package/bin/reader-mcp

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Alias kept for existing installs: same as bin/smcreader-mcp.
+require('./smcreader-mcp');

package/bin/smcreader-hook

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Claude Code command hook (PostToolUse; PreToolUse — Read guard). Fail-open: always exits 0.
+'use strict';
+let main;
+try { ({ main } = require('../lib/hook-command')); } catch (_) { process.exit(0); }
+main().then(() => process.exit(0), () => process.exit(0));

package/bin/smcreader-mcp

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Reader stdio MCP server. stdout carries the protocol, so all logging goes to stderr.
+'use strict';
+const { createReaderStore } = require('../lib/reader-store');
+const { runStdio } = require('../lib/stdio-mcp');
+const { loadConfig } = require('../lib/config');
+
+const cfg = loadConfig();
+const log = (msg) => { try { process.stderr.write(`${msg}\n`); } catch (_) { /* */ } };
+const store = createReaderStore({ dir: cfg.dir, log });
+runStdio({ store, owner: cfg.owner, askFormat: cfg.askFormat }).catch((e) => {
+  log(`[smcreader-mcp] fatal: ${e && e.stack || e}`);
+  process.exit(1);
+});

package/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "description": "SMC Reader: replace large Bash/WebFetch outputs with a [READER ctx_...] pointer",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash|WebFetch",
+        "hooks": [
+          { "type": "command", "command": "READER_TOOL_PREFIX=mcp__plugin_smcreader_smcreader__ node \"${CLAUDE_PLUGIN_ROOT}/bin/smcreader-hook\"" }
+        ]
+      }
+    ]
+  }
+}

package/lib/config.js

@@ -0,0 +1,33 @@
+/**
+ * config — settings from the environment. The hook and the server are separate processes, so
+ * the only shared channel between them is the $READER_DIR directory and the same variables.
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { DEFAULT_ALLOWLIST, DEFAULT_THRESHOLD } = require('./intercept-hook');
+
+const int = (v, dflt) => {
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n >= 0 ? n : dflt;
+};
+const list = (v, dflt) => (v && v.trim() ? v.split(',').map((x) => x.trim()).filter(Boolean) : dflt);
+
+function loadConfig(env = process.env) {
+  return {
+    dir: env.READER_DIR || path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'smcreader'),
+    threshold: int(env.READER_THRESHOLD, DEFAULT_THRESHOLD),
+    allowlist: list(env.READER_ALLOWLIST, DEFAULT_ALLOWLIST),
+    owner: env.READER_OWNER || undefined,
+    askFormat: env.READER_ASK_FORMAT === 'prose' ? 'prose' : 'lines',
+    readGuard: int(env.READER_READ_GUARD, 0),   // bytes; 0 — Read guard disabled
+    logFile: env.READER_LOG || '',
+    // Prefix of reader tool names in the pointer hint: depends on how the server is connected
+    // (claude mcp add smcreader → mcp__smcreader__, plugin → mcp__plugin_smcreader_smcreader__).
+    toolPrefix: env.READER_TOOL_PREFIX && /^[A-Za-z0-9_-]+$/.test(env.READER_TOOL_PREFIX) ? env.READER_TOOL_PREFIX : '',
+  };
+}
+
+module.exports = { loadConfig };

package/lib/hook-command.js

@@ -0,0 +1,80 @@
+/**
+ * hook-command — body of bin/reader-hook, a Claude Code command hook.
+ *
+ * PostToolUse: large output from an allowlisted tool goes into the store ($READER_DIR); the
+ * response is hookSpecificOutput.updatedToolOutput in the same shape as tool_response, holding
+ * the pointer "[READER ctx_…] <tool> output intercepted: N bytes, L lines …" plus head/tail.
+ * PreToolUse (only when $READER_READ_GUARD > 0): a full Read of a file above the threshold is
+ * denied with working alternatives (lib/read-guard.js).
+ *
+ * The document owner is the session_id from stdin (a subagent gets `<session>/agent:<id>`).
+ * Fail-open: any error → empty response, the output passes through unchanged, exit 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { createReaderStore } = require('./reader-store');
+const { createInterceptHook, extractText } = require('./intercept-hook');
+const { createReadGuardHook } = require('./read-guard');
+const { loadConfig } = require('./config');
+
+function makeLog(cfg) {
+  if (!cfg.logFile) return () => {};
+  return (msg) => {
+    try { fs.appendFileSync(cfg.logFile, `${new Date().toISOString()} ${msg}\n`); } catch (_) { /* logging never breaks the hook */ }
+  };
+}
+
+/**
+ * @param {object} input  JSON from the hook's stdin
+ * @param {object} [env]
+ * @returns {Promise<object>} hook response ({} means change nothing)
+ */
+async function handleHookInput(input, env = process.env) {
+  const cfg = loadConfig(env);
+  const log = makeLog(cfg);
+  try {
+    if (!input || typeof input !== 'object') return {};
+    const event = input.hook_event_name;
+
+    if (event === 'PreToolUse') {
+      if (!cfg.readGuard) return {};
+      return await createReadGuardHook({ threshold: cfg.readGuard, hasReader: true, log })(input);
+    }
+    if (event !== undefined && event !== 'PostToolUse') return {};
+
+    // Cheap prefilter BEFORE creating the store: the hook runs on every tool call, and the
+    // store reads its directory on creation (sweep). Small output costs zero file operations.
+    if (!cfg.allowlist.includes(input.tool_name)) return {};
+    const { text } = extractText(input.tool_response);
+    if (!text || text.length < cfg.threshold) return {};
+
+    const store = createReaderStore({ dir: cfg.dir, log });
+    const owner = typeof input.session_id === 'string' && input.session_id ? input.session_id : cfg.owner;
+    const P = cfg.toolPrefix;
+    const askHint = P ? (id) => `Full output is in reader ${id}: ${P}reader_ask(id, question) to analyze, ${P}reader_peek(id, start_line, end_line) for exact lines, ${P}reader_close(id) when done.` : undefined;
+    const hook = createInterceptHook({ store, threshold: cfg.threshold, allowlist: cfg.allowlist, log, owner, askHint });
+    return await hook(input);
+  } catch (e) {
+    log(`[reader-hook] error (passing output through): ${e.message}`);
+    return {};
+  }
+}
+
+/** Read all of stdin, handle it, print the response. Never throws. */
+async function main({ stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
+  let raw = '';
+  try {
+    stdin.setEncoding('utf8');
+    for await (const chunk of stdin) raw += chunk;
+  } catch (_) { return 0; }
+  let out = {};
+  try { out = await handleHookInput(JSON.parse(raw), env); } catch (_) { out = {}; }
+  if (out && Object.keys(out).length) {
+    try { stdout.write(JSON.stringify(out)); } catch (_) { /* fail-open */ }
+  }
+  return 0;
+}
+
+module.exports = { handleHookInput, main };

package/lib/index.js

@@ -0,0 +1,17 @@
+'use strict';
+// Public package entry point: core (store, reader model, tools) and adapters.
+const { createReaderStore } = require('./reader-store');
+const readerModel = require('./reader-model');
+const { createReaderTools, READER_TOOL_NAMES } = require('./reader-tools');
+const { createInterceptHook, extractText, buildReplacement, headTail, DEFAULT_ALLOWLIST, DEFAULT_THRESHOLD } = require('./intercept-hook');
+const { createReadGuardHook } = require('./read-guard');
+const { loadConfig } = require('./config');
+
+module.exports = {
+  createReaderStore, readerModel, createReaderTools, READER_TOOL_NAMES,
+  createInterceptHook, extractText, buildReplacement, headTail, DEFAULT_ALLOWLIST, DEFAULT_THRESHOLD,
+  createReadGuardHook, loadConfig,
+  // adapters are loaded lazily: each pulls in its own SDK
+  createReaderMcpServer: (...a) => require('./reader-mcp').createReaderMcpServer(...a),
+  buildMcpServer: (...a) => require('./stdio-mcp').buildMcpServer(...a),
+};

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 };