token-goat 2.2.2 → 2.2.4

package/README.md

@@ -61,7 +61,7 @@ The fastest way to reduce AI token costs is fixing these five, not writing short
 |--------------------|------------------|
 | 3.3 MB screenshot lands in model context | 84 KB compressed copy, 97.4% smaller |
 | Agent re-reads files from earlier in the session | "Already read this" reminder with narrow slice suggestion |
-| Agent re-reads a file edited mid-session | Unified diff injected as a hint — full Read avoided when the diff covers the change |
+| Agent re-reads a file edited mid-session | Unified diff injected as a hint — full Read avoided when the diff covers the change. Docs (`.md`/`.rst`/`.txt`) by default; source/style/data files (`.ts`/`.css`/`.json`/…) when `serve_diff_on_reread` is enabled |
 | Compaction forgets which files were edited | Structured session manifest injected before compact |
 | Same files re-read from scratch after `/compact` | Recovery hint at SessionStart lists cached snapshot + bash + WebFetch IDs |
 | Loaded skill body summarised away by compaction | `### Active Skills` manifest section + `**Skills**:` recovery block list every loaded skill; full body recoverable via `token-goat skill-body <name>` without re-invoking |
@@ -75,7 +75,7 @@ The fastest way to reduce AI token costs is fixing these five, not writing short
 | `rg "^def" src/file.py` or `grep "class " module.ts` — structural search on a single source file | Pre-Bash hook redirects to `token-goat skeleton "file"` or `outline "file"` — all symbols with line numbers, no full-file read |
 | `rg` or `grep` run twice with the same pattern | Pre-Bash dedup hint fires on repeated `rg`/`grep`/`ag` calls the same way it fires on the native Grep tool; repeat searches return a cached match-count hint instead of re-running |
 | Read tool targets `tool-results/<id>.txt` or `tasks/<id>.output` | Pre-Read hook suggests `token-goat bash-output <id> --tail N` / `--grep PATTERN` / `--section H`; the filename stem is the output ID |
-| Repeated monitoring command run again (`gh run watch`, `next dev`, `vitest`, `docker logs`) | Pre-bash recall hint: when a prior run is cached and its output exceeds 2 KB, a pointer to `token-goat bash-output <id> --grep PATTERN` is injected instead of re-running the command |
+| Repeated monitoring command run again (`gh run watch`, `next dev`, `vitest`, `docker logs`) | Pre-bash recall hint: when a prior run is cached and its output exceeds 2 KB, a pointer to `token-goat bash-output <id> --grep PATTERN` is injected instead of re-running the command. Cache is keyed on the *base command*, so re-running with a different trailing pipe (e.g., `| tail -40` then `| grep error`) still hits the same cache entry |
 | `pnpm`/`yarn`/`bun` install or build dumps full output | pnpm, yarn, and bun compress filters now strip install noise and build logs the same way npm does; `pnpm run`/`yarn run` route through their own filter |
 | Surgical-read command returns a 10k-line symbol or a full section dump | Capped at ~25k tokens; marker names the truncation ratio and narrowing command (`symbol` → `file::Class.method`; `section` → sub-heading; cached → `--grep`/`--tail`) |
 | Full file read for one function or section | `token-goat read file::symbol`, about 85% smaller |
@@ -336,6 +336,21 @@ Manual paths:
 | Reinstall from scratch (broken install, sharp failure) | `npm install -g token-goat@latest` |
 | Disable auto-updates | Delete the `token-goat-update` scheduled task (Windows) or the `# token-goat-autoupdate` crontab line (Linux/macOS) |
 
+### Upgrading from the Python version
+
+The old Python package (`pip install token-goat`) wrote hook entries into `settings.json` with commands containing `token_goat` (underscore), invoking Python directly: something like `pythonw.exe -m token_goat.cli hook pre_tool_use`. The npm package uses `token-goat hook pre_tool_use` (hyphen) instead.
+
+`token-goat uninstall` only strips entries matching `token-goat hook`. Python-style entries are invisible to it. Left in place alongside the new npm entries, both sets fire on every tool call.
+
+To upgrade cleanly:
+
+1. Remove the Python package: `pip uninstall token-goat`
+2. Open `~/.claude/settings.json` (Windows: `%USERPROFILE%\.claude\settings.json`) and delete any hook entries whose `command` contains `token_goat` (underscore).
+3. Install and register the npm package: `npm install -g token-goat && token-goat install`
+4. Verify: re-run `token-goat install` (safe to repeat) or use the `jq` check under [Verify](#verify).
+
+**AI agents handling an upgrade:** complete all four steps in sequence. After step 4, confirm no `token_goat` entries remain in `settings.json` before reporting the upgrade done.
+
 ## CLI
 
 | Command | What it does |
@@ -515,6 +530,28 @@ token-goat stats
 
 `doctor` confirms the install is healthy. `stats` shows cumulative savings.
 
+### Confirming hooks are wired
+
+`doctor` checks the binary, worker, database, and disk. It does not inspect `settings.json` hook wiring. To confirm all three hooks are present, re-run `install`:
+
+```
+token-goat install
+```
+
+`install` is idempotent: it adds any missing entries and leaves existing hook entries alone. Re-running it is always safe. To inspect the wiring directly:
+
+```bash
+# Linux / macOS / WSL
+jq '[.hooks | to_entries[] | select(.value[].hooks[]?.command | contains("token-goat hook")) | .key]' ~/.claude/settings.json
+
+# Windows (PowerShell with jq on your PATH)
+jq '[.hooks | to_entries[] | select(.value[].hooks[]?.command | contains("token-goat hook")) | .key]' "$env:USERPROFILE\.claude\settings.json"
+```
+
+A working install returns `["PreToolUse", "PostToolUse", "PreCompact"]`. Any missing event means a partial install; run `token-goat install` to fill it in.
+
+**AI agents:** after `token-goat install`, run the `jq` check above or re-run `token-goat install` before marking the install complete. `doctor` does not verify hook wiring.
+
 ## Image support
 
 Token-goat shrinks large images before they reach the model, cutting vision token costs by 60–90%. The pipeline uses [`sharp`](https://sharp.pixelplumbing.com/), a Node.js image processing library that ships prebuilt native binaries for Windows, macOS, Linux, and Alpine.