@softspark/ai-toolkit 4.16.1 → 4.18.0

package/app/plugins/rtk-pack/scripts/init.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Fetch, verify and install the rtk binary for this platform.
+
+Run by `ai-toolkit plugin install rtk-pack` (scripts/plugin.py invokes
+`init.py` if present). This is the only point at which the pack touches the
+network; nothing is fetched at runtime.
+
+Design constraints from kb/history/completed/rtk-pack-integration-20260726.md section 6:
+
+- Verify before install. A digest mismatch aborts and removes the partial
+  download; a half-installed binary is worse than none.
+- A fetch failure is not an install failure. The pack degrades to inert and
+  says so, matching how the core behaves when jq is missing. plugin.py only
+  warns on a non-zero exit, so the message has to carry the meaning.
+- Never silent. Every path that ends without a working binary prints why.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import shutil
+import ssl
+import sys
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+
+PACK_NAME = "rtk-pack"
+TOOLKIT_DATA_DIR = Path(os.environ.get("AI_TOOLKIT_DATA_DIR", Path.home() / ".softspark" / "ai-toolkit"))
+INSTALL_DIR = TOOLKIT_DATA_DIR / "plugin-scripts" / PACK_NAME / "bin"
+VERSION_FILE = TOOLKIT_DATA_DIR / "plugin-scripts" / PACK_NAME / "version.json"
+
+DOWNLOAD_TIMEOUT = 120
+CHUNK = 1 << 16
+
+# Bounded so a wrong URL cannot fill the disk. The largest real asset is ~4 MB.
+MAX_ASSET_BYTES = 64 * 1024 * 1024
+
+
+class InstallError(Exception):
+    """Anything that leaves the pack without a usable binary."""
+
+
+def manifest_path() -> Path:
+    """The pack manifest, resolved relative to this script's source location."""
+    return Path(__file__).resolve().parent.parent / "plugin.json"
+
+
+def detect_platform() -> str:
+    """Map this host to an asset key in plugin.json.
+
+    Linux x86_64 is served the static musl build, which runs on glibc; upstream
+    routes Linux x86_64 to musl in its own Homebrew formula for the same reason.
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    arch = {
+        "x86_64": "x86_64",
+        "amd64": "x86_64",
+        "arm64": "arm64" if system == "darwin" else "aarch64",
+        "aarch64": "arm64" if system == "darwin" else "aarch64",
+    }.get(machine)
+    if arch is None:
+        raise InstallError(f"unsupported architecture: {platform.machine()}")
+    if system not in ("darwin", "linux", "windows"):
+        raise InstallError(f"unsupported platform: {platform.system()}")
+    return f"{system}-{arch}"
+
+
+def asset_url(binary: dict, asset: dict) -> str:
+    """Where to fetch this asset from.
+
+    RTK_PACK_RELEASE_BASE_URL points the fetch at a mirror instead of GitHub,
+    for networks that cannot reach it directly. The digest check is unchanged,
+    so a mirror serving different bytes is rejected exactly like a corrupt
+    download.
+    """
+    base = os.environ.get("RTK_PACK_RELEASE_BASE_URL", "").rstrip("/")
+    if base:
+        return f"{base}/{asset['file']}"
+    return (
+        f"https://github.com/{binary['release_repo']}/releases/download/"
+        f"{binary['release_tag']}/{asset['file']}"
+    )
+
+
+def download(url: str, dest: Path) -> str:
+    """Fetch to dest, returning the SHA-256 of what actually landed."""
+    digest = hashlib.sha256()
+    total = 0
+    request = urllib.request.Request(url, headers={"User-Agent": "ai-toolkit-rtk-pack"})
+    # A default TLS context for https; file:// mirrors (and the tests) take the
+    # handler that ignores it.
+    kwargs = {"timeout": DOWNLOAD_TIMEOUT}
+    if url.startswith("https:"):
+        kwargs["context"] = ssl.create_default_context()
+    try:
+        with urllib.request.urlopen(request, **kwargs) as response:
+            with dest.open("wb") as handle:
+                while True:
+                    chunk = response.read(CHUNK)
+                    if not chunk:
+                        break
+                    total += len(chunk)
+                    if total > MAX_ASSET_BYTES:
+                        raise InstallError(f"asset exceeds {MAX_ASSET_BYTES} bytes, refusing to continue")
+                    digest.update(chunk)
+                    handle.write(chunk)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"HTTP {exc.code} fetching {url}") from exc
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise InstallError(f"could not fetch {url}: {exc}") from exc
+    if total == 0:
+        raise InstallError(f"empty response from {url}")
+    return digest.hexdigest()
+
+
+def extract_member(archive: Path, member: str, dest: Path) -> None:
+    """Pull exactly one flat entry out of the archive.
+
+    The archives are built to hold a single flat binary and CI asserts it, so
+    anything else means the asset is not what the manifest claims and is
+    refused rather than extracted.
+    """
+    if archive.suffix == ".zip":
+        with zipfile.ZipFile(archive) as zf:
+            names = zf.namelist()
+            if names != [member]:
+                raise InstallError(f"expected exactly [{member}] in {archive.name}, found {names}")
+            with zf.open(member) as src, dest.open("wb") as out:
+                shutil.copyfileobj(src, out)
+        return
+
+    with tarfile.open(archive, "r:gz") as tf:
+        names = tf.getnames()
+        if names != [member]:
+            raise InstallError(f"expected exactly [{member}] in {archive.name}, found {names}")
+        extracted = tf.extractfile(member)
+        if extracted is None:
+            raise InstallError(f"{member} in {archive.name} is not a regular file")
+        with extracted as src, dest.open("wb") as out:
+            shutil.copyfileobj(src, out)
+
+
+def already_installed(asset: dict, target: Path) -> bool:
+    """True when this exact asset is already in place.
+
+    `ai-toolkit plugin install --editor all` calls the init step twice in a
+    single command (plugin.py invokes _copy_plugin_scripts per editor), so
+    without this the binary is downloaded twice. It also makes a re-install
+    cheap instead of re-fetching.
+    """
+    if not target.is_file():
+        return False
+    try:
+        record = json.loads(VERSION_FILE.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return record.get("sha256") == asset["sha256"] and record.get("asset") == asset["file"]
+
+
+def install(manifest: dict) -> dict | None:
+    binary = manifest.get("binary")
+    if not binary:
+        raise InstallError("plugin.json has no 'binary' section")
+
+    key = detect_platform()
+    asset = binary.get("assets", {}).get(key)
+    if asset is None:
+        raise InstallError(f"no asset published for {key}")
+
+    url = asset_url(binary, asset)
+    install_name = binary.get("install_name", "rtk")
+    if platform.system().lower() == "windows":
+        install_name += ".exe"
+    target = INSTALL_DIR / install_name
+
+    if already_installed(asset, target):
+        return None
+
+    with tempfile.TemporaryDirectory() as tmp:
+        staged = Path(tmp) / asset["file"]
+        actual = download(url, staged)
+        if actual != asset["sha256"]:
+            # Nothing is installed on a mismatch. The temp dir takes the
+            # partial download with it.
+            raise InstallError(
+                f"digest mismatch for {asset['file']}: "
+                f"expected {asset['sha256']}, got {actual}"
+            )
+        unpacked = Path(tmp) / install_name
+        extract_member(staged, asset["member"], unpacked)
+
+        INSTALL_DIR.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(unpacked), str(target))
+
+    target.chmod(target.stat().st_mode | 0o111)
+
+    record = {
+        "pack_version": manifest.get("version"),
+        "upstream_version": manifest.get("upstream", {}).get("version"),
+        "release_tag": binary["release_tag"],
+        "platform": key,
+        "asset": asset["file"],
+        "sha256": asset["sha256"],
+        "binary": str(target),
+    }
+    VERSION_FILE.parent.mkdir(parents=True, exist_ok=True)
+    VERSION_FILE.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    return record
+
+
+def main() -> int:
+    try:
+        manifest = json.loads(manifest_path().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"rtk-pack: cannot read plugin.json: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        record = install(manifest)
+        if record is None:
+            print("rtk already installed and digest matches, nothing to do")
+            return 0
+    except InstallError as exc:
+        # plugin.py prints this as "WARN init failed" and continues, which is
+        # the intended behaviour: the hook stays wired but finds no binary and
+        # passes every command through untouched.
+        print(
+            f"rtk-pack: no binary installed ({exc}). "
+            "The pack is inert: commands are passed through unchanged. "
+            "Re-run 'ai-toolkit plugin install rtk-pack' once the cause is resolved.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"rtk {record['upstream_version']} installed for {record['platform']} "
+        f"({record['binary']}), digest verified"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/app/plugins/rtk-pack/scripts/status.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Report rtk-pack health: binary, digest, and hook wiring.
+
+Invoked by `ai-toolkit plugin status` and `ai-toolkit doctor` through the
+generic scripts/status.py hook in scripts/plugin.py.
+
+The point of this script is to distinguish "installed" from "working". The pack
+can be recorded as installed, have its hook wired, and still do nothing at all
+because the binary never downloaded. That is the failure mode this project has
+already shipped once, so it gets its own line rather than being inferred.
+
+Stdlib only. Never raises; exit code is always 0.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+PACK_NAME = "rtk-pack"
+TOOLKIT_DATA_DIR = Path(
+    os.environ.get("AI_TOOLKIT_DATA_DIR", Path.home() / ".softspark" / "ai-toolkit")
+)
+PACK_STATE_DIR = TOOLKIT_DATA_DIR / "plugin-scripts" / PACK_NAME
+VERSION_FILE = PACK_STATE_DIR / "version.json"
+HOOK_FILE = TOOLKIT_DATA_DIR / "hooks" / f"plugin-{PACK_NAME}-rewrite.sh"
+CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
+
+
+def find_binary() -> Path | None:
+    for candidate in (PACK_STATE_DIR / "bin" / "rtk", PACK_STATE_DIR / "bin" / "rtk.exe"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def digest_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 16), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def hook_registered() -> bool:
+    """True when settings.json still points at this pack's hook."""
+    try:
+        settings = json.loads(CLAUDE_SETTINGS.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return f"plugin-{PACK_NAME}-rewrite.sh" in json.dumps(settings.get("hooks", {}))
+
+
+def main() -> int:
+    binary = find_binary()
+    if binary is None:
+        print("rtk binary: MISSING — the hook is inert and every command runs unchanged")
+        print("  fix: ai-toolkit plugin install rtk-pack")
+        return 0
+
+    record: dict = {}
+    try:
+        record = json.loads(VERSION_FILE.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        pass
+
+    upstream = record.get("upstream_version", "unknown")
+    print(f"rtk binary: {binary} (upstream {upstream})")
+
+    # The recorded digest is of the archive, not the extracted binary, so it
+    # cannot be recomputed here. Report the binary's own digest and whether the
+    # install record still exists, and say which is which rather than implying
+    # a verification that is not happening.
+    if record:
+        print(f"  install record: {record.get('asset', '?')} sha256 {record.get('sha256', '?')[:16]}…")
+    else:
+        print("  install record: MISSING — reinstall to restore provenance")
+    print(f"  binary sha256: {digest_of(binary)[:16]}…")
+
+    if not os.access(binary, os.X_OK):
+        print("  executable: NO — the hook cannot run it")
+
+    try:
+        proc = subprocess.run([str(binary), "--version"], capture_output=True, text=True, timeout=15)
+        reported = (proc.stdout.strip() or proc.stderr.strip()).splitlines()[0] if proc.returncode == 0 else ""
+    except (OSError, subprocess.SubprocessError, IndexError):
+        reported = ""
+    if reported:
+        print(f"  runs: {reported}")
+        expected = str(upstream).lstrip("v")
+        if expected and expected not in reported:
+            print(f"  WARNING: binary reports {reported}, manifest pins {upstream}")
+    else:
+        print("  runs: NO — binary present but will not start")
+
+    print(f"  hook script: {'present' if HOOK_FILE.is_file() else 'MISSING'}")
+    print(f"  hook registered in settings.json: {'yes' if hook_registered() else 'no'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-07-24T03:52:58Z",
+  "last_run": "2026-07-26T11:36:57Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "388c0b5e25ab4906",
+      "docs_hash": "1dd9e9f490e7103a",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "3c7ff437aec0ab98",
+      "docs_hash": "9a5cb995316c7c71",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -107,7 +107,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "a6ae93657498688c",
+      "docs_hash": "d373a3e4db1f4c79",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -163,10 +163,10 @@
         "slash command": false,
         "sub-agent": true
       },
-      "version": "2.1.218 (Claude Code)"
+      "version": "2.1.220 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "3eaa20e45d385a1f",
+      "docs_hash": "d76db24ff58cb7ea",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -213,7 +213,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "87a5a879a39dc62c",
+      "docs_hash": "379d4d3760235c7f",
       "headings": [
         "API",
         "API Reference",
@@ -243,12 +243,10 @@
         "Connect tools and data",
         "Connection methods",
         "Contribute",
-        "Conversion apps",
-        "Core Concepts",
+        "Conversion specs",
         "Core concepts",
         "Cost and throughput",
         "Customization",
-        "Deploy",
         "Deployment and model providers",
         "Desktop app",
         "Development workflows",
@@ -309,6 +307,7 @@
         "Start your first task",
         "Stay in control",
         "Suggested",
+        "Test and publish",
         "Text and code",
         "Third-party integrations",
         "Topics",
@@ -349,7 +348,7 @@
       "version": "codex-cli 0.145.0"
     },
     "cursor": {
-      "docs_hash": "5387d04443d26da1",
+      "docs_hash": "74d1366066760874",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -365,7 +364,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "8db25b552ffbed80",
+      "docs_hash": "c6d93617f9359329",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -408,7 +407,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "5d021df2f3b4d39b",
+      "docs_hash": "1c6e0fd930f573fa",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -461,7 +460,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "f1dd69ffcfb280fa",
+      "docs_hash": "297813a7e2881afe",
       "headings": [
         "Add features",
         "Ask questions",
@@ -521,7 +520,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "bee6ba0ee1a517dd",
+      "docs_hash": "d57d379406804a4b",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -50,7 +50,6 @@ const SCRIPT_COMMANDS = {
   'benchmark-ecosystem':  { script: 'benchmark_ecosystem.py', toolkitCwd: true },
   'evaluate':             { script: 'evaluate_skills.py',    toolkitCwd: true },
   'stats':                { script: 'stats.py' },
-  'output-filter':        { script: 'output_filter_cli.py' },
   'compile-slm':          { script: 'compile_slm.py' },
   'pack-codebase':        { script: 'pack_codebase.py' },
   'claude-app':           { script: 'claude_app.py',          toolkitCwd: true },
@@ -80,7 +79,6 @@ const COMMANDS = {
   'benchmark-ecosystem': 'Generate ecosystem benchmark snapshot (GitHub metadata + offline fallback)',
   evaluate: 'Run skill evaluation suite',
   stats: 'Show skill usage statistics (--summary for product telemetry, --reset to clear)',
-  'output-filter': 'Manage native tool-output filter (status, inspect, recover, clean)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
   mcp: 'Manage MCP templates and install native editor MCP configs',
   config: 'Manage config inheritance (validate, diff, init, create-base, check)',
@@ -576,6 +574,21 @@ function handleUpdate(args) {
   // User-provided args override state-derived args
   run(scriptPath('install.py'), [...stateArgs, ...args]);
 
+  // Installed plugin packs live under ~/.softspark/ai-toolkit and are global,
+  // so --local (project-local config only) leaves them alone. The wiring is
+  // generic: plugin.py decides per pack whether anything changed and stays
+  // silent when nothing has, so this adds no noise for the common case.
+  if (!isLocal) {
+    const pluginArgs = ['update', '--editor', 'all', '--all'];
+    if (isDryRun) pluginArgs.push('--dry-run');
+    try {
+      run(scriptPath('plugin.py'), pluginArgs);
+    } catch (_err) {
+      // A pack update never fails the core update that already succeeded.
+      console.warn('WARN: plugin pack update skipped');
+    }
+  }
+
   // After global update (not --local), propagate to all registered projects
   if (!isLocal && !isDryRun) {
     const registryPath = path.join(process.env.HOME, '.softspark', 'ai-toolkit', 'projects.json');

package/kb/history/completed/output-filter-retirement-20260726.md

@@ -0,0 +1,128 @@
+---
+title: "Retirement: Native Tool-Output Filter — Measured 0% and Removed"
+category: planning
+service: ai-toolkit
+tags:
+  - output-filter
+  - token-reduction
+  - postmortem
+  - measurement
+  - claude-code
+doc_type: postmortem
+status: completed
+created: "2026-07-26"
+last_updated: "2026-07-26"
+shipped_in: "v4.17.0 (removal)"
+description: "Why the native tool-output filter shipped in v4.16.0 was removed in v4.17.0: measured 0.0000% whole-session token saving on real traffic, because agent-issued commands are compound and the design accepted only simple registered shapes."
+---
+
+# Retirement: Native Tool-Output Filter
+
+**Shipped:** v4.16.0 (2026-07-23). **Removed:** v4.17.0 (2026-07-26).
+
+## The number
+
+Measured whole-session input-token saving: **0.0000%**.
+
+Real Bash results from local Claude Code transcripts were replayed through the
+shipped classifier and the full filter registry. The filters ran on the actual
+captured output; this is a measurement, not an estimate.
+
+| Scope | Value |
+|---|---:|
+| Transcripts replayed | 134, across 22 distinct projects |
+| Successful Bash results | 7600 |
+| Of those, parsed as a simple command shape | 145 (1.9%) |
+| Of those, matched a registered shape | 18 (0.24%) — 16 `git diff`, 2 `git show` |
+| Accepted by any filter | **0** |
+| Bytes saved | **0** |
+
+The classifier was verified working before the result was accepted: `git
+status`, `git log -n 20`, `pytest -v`, `bats --tap`, and `npm test` each
+produced exactly one candidate. The zero is real.
+
+## Why: the premise, not the implementation
+
+Seventeen filters were correct. They cleared their byte floors on owned
+fixtures (44–95% reduction), stayed inside every latency budget at the 8 MiB
+engine cap, passed adversarial safety review, and never once compressed a
+failure. None of that mattered, because the commands they were built for are
+not the commands that get issued.
+
+95% of successful Bash invocations are compound. The byte pool breaks down as:
+
+| Class | Share of compound bytes | Why the filter refused it |
+|---|---:|---|
+| `;` chain | 44.3% | multiple output producers, attribution ambiguous |
+| multiline script | 29.1% | rejected at the raw-string boundary |
+| pipeline | 12.7% | the pipe transformed the output |
+| `&&` chain with producing segments | 5.6% | multiple output producers |
+| redirect, substitution | 4.4% | rejected at the raw-string boundary |
+| heredoc | 3.5% | rejected at the raw-string boundary |
+
+Every one of those refusals was the correct safety decision in isolation.
+Together they excluded the entire population.
+
+The most-frequent single shape was `cd <path> && …`, at 375 results and 480 KB.
+A bounded `cd`-prefix subset had already been designed, threat-modelled, and
+measured during Phase 3, and it was dropped because it covered 0.00% of the
+compound pool. The retirement measurement confirms why: of those 375 results,
+only 5 had a single simple second segment, and those 5 produced 0 bytes of
+output.
+
+## What was already rejected on the way, and still stands
+
+- **Read-result coverage: rejected on the `Edit` exact-match hazard.** On
+  670.7 KB of real Read content, adjacent-duplicate collapse saves 0.00%,
+  blank-run collapse 0.04%, trailing-whitespace 0.00%. Anything above noise
+  requires elision, and 80.7% of `Edit` old-strings target a file read earlier
+  in the same session, 63.4% of them multi-line byte-exact quotes. A Read
+  result asserts what is on disk, so omission is a false claim rather than a
+  summary.
+- **Compound-command subset: designed, measured at 0.00% coverage, dropped.**
+  The pipeline-truncator shape failed on an inversion: a truncated document
+  parses cleanly exactly where the shape would pay, and rejects exactly where
+  truncation is detectable.
+
+## The process lesson
+
+The plan validated its **design** exhaustively across five phases and its
+**premise** not at all until the fifth. Fixtures measured the filter; only real
+traffic measured the value, and the two disagreed by two orders of magnitude.
+
+The end-to-end replay that produced the 0% took under an hour and could have
+run on day one, before any filter existed. Any future plan of this shape must
+put premise validation in Phase 0, with a kill number published before the
+measurement rather than argued after it.
+
+## Evaluated as a replacement: rtk
+
+`rtk` (https://github.com/rtk-ai/rtk, Apache-2.0) rewrites commands at
+`PreToolUse` rather than filtering output afterwards, which is the mechanism
+this project's own safety contract had excluded. Its rewrite pipeline was
+ported and validated against 197 of its own test assertions (197/197 exact
+agreement), then applied to the same traffic:
+
+- addresses **31.5%** of successful Bash bytes, **9.7%** of all tool-result
+  bytes — genuinely non-zero, so the in-house 0% was a coverage failure rather
+  than a law of nature;
+- projected saving is **0.32–0.48%** of session input tokens on rtk's own
+  60–90% claim, and **0.15–0.21%** once its filters' actual behaviour is
+  modelled;
+- its two largest families here under-deliver: `rtk read` returns files
+  verbatim at the default `--level none`, and `rtk grep` models at 12.3%
+  against a claimed 75%;
+- custom TOML filters, the documented extension point, would reach 1.91% of
+  Bash bytes. The large misses are structurally unreachable from config:
+  `| head` and `| tail` (34.6%) are blocked by the pipeline-final rule, and
+  `sed` (19.4%) sits in the hard-ignored prefix list.
+
+Not adopted.
+
+## Where the tokens actually are
+
+The measurement points somewhere other than command output. In this traffic,
+`Read` is 53.8% of tool-result bytes, and within Bash the two largest buckets
+are `sed` used as a file reader (16.2%) and `| head` / `| tail` pipeline tails
+(34.6%). Those are file-reading patterns, not tool reports. Any future attempt
+at token reduction should start there, and should start by measuring.