@softspark/ai-toolkit 4.16.1 → 4.18.0

package/llms-full.txt

@@ -19,7 +19,9 @@
 - [Spike: F2 MCP Context Trim — Hook Feasibility & Path Decision](kb/history/completed/f2-mcp-trim-spike-20260504.md)
 - [Implementation Plan: Native Tool Output Filter](kb/history/completed/native-tool-output-filter-plan.md)
 - [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
+- [Retirement: Native Tool-Output Filter](kb/history/completed/output-filter-retirement-20260726.md)
 - [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
+- [rtk Pack Integration](kb/history/completed/rtk-pack-integration-20260726.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
 - [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/planning/drop-cascade-hooks-after-sunset.md)
@@ -28,6 +30,7 @@
 - [SOP: AI Toolkit Maintenance](kb/procedures/maintenance-sop.md)
 - [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
 - [SOP: Release Verification](kb/procedures/release-verification-sop.md)
+- [SOP: rtk Upstream Sync](kb/procedures/rtk-upstream-sync-sop.md)
 - [Agents Catalog](kb/reference/agents-catalog.md)
 - [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
 - [AI Toolkit Architecture](kb/reference/architecture-overview.md)
@@ -63,7 +66,6 @@
 - [Usage Statistics](kb/reference/stats.md)
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
-- [Native Tool Output Filter](kb/reference/tool-output-filter.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
 - [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
@@ -3048,6 +3050,139 @@ This plan shares modification targets with the Enterprise Config plan:
 
 ---
 
+## kb/history/completed/output-filter-retirement-20260726.md
+
+---
+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.
+
+---
+
 ## kb/history/completed/output-token-discipline-plan-20260504.md
 
 ---
@@ -3314,6 +3449,721 @@ Updated: `README.md`, `kb/reference/architecture-overview.md`, `kb/reference/ski
 
 ---
 
+## kb/history/completed/rtk-pack-integration-20260726.md
+
+---
+title: "Plan: rtk Pack Integration"
+category: planning
+service: ai-toolkit
+tags:
+  - rtk
+  - plugin-pack
+  - token-reduction
+  - vendored-binaries
+  - cross-build
+  - upstream-sync
+doc_type: postmortem
+status: completed
+created: "2026-07-26"
+last_updated: "2026-07-26"
+completion: "100% — phases 0, 1, 2, 4, 5 delivered; phase 3 cut on the measurement"
+shipped_in: "v4.18.0"
+pinned_upstream: "v0.44.0"
+description: "Integrate rtk as an opt-in ai-toolkit plugin pack: binaries cross-built from source in our CI with telemetry disabled, hosted on our own GitHub Release, fetched and checksum-verified at pack install, auto-update on ai-toolkit update, and an SOP for tracking upstream releases. Custom filter presets were cut on the measurement (0.008% of input tokens). Phase 0 validated the premise against v0.44.0 on the full transcript corpus before any build work."
+---
+
+# rtk Pack Integration
+
+**Completed 2026-07-26, shipped in v4.18.0.** Kept whole rather than summarised,
+because the value here is the measurements and the things that turned out to be
+false, not the plan structure. Live procedure:
+`kb/procedures/rtk-upstream-sync-sop.md`.
+
+Headline: rtk-pack ships opt-in, built from source with telemetry compiled out,
+and saves a **measured 0.0615% of input tokens** against a kill number of 0.05%
+published before the measurement. Phase 3 (our own filter presets) was cut at
+0.008%. The projection this plan published for itself was about twice too
+optimistic, and section 10.1 says why.
+
+## 1. Decision
+
+Ship `rtk` to ai-toolkit users as an **opt-in plugin pack**, with the binary
+supply chain owned end to end by us.
+
+Five choices, made and locked:
+
+| Question | Decision |
+|---|---|
+| Delivery | Plugin pack (`rtk-pack`), never a native feature |
+| Binary hosting | Our own GitHub Release, fetched and SHA-256 verified at pack install |
+| Binary provenance | Cross-built from upstream source in our CI, `RTK_TELEMETRY_URL` unset |
+| Pinned upstream tag | **v0.44.0** (2026-07-26). v0.43.0 was ruled out on evidence, see section 2 |
+| Upstream tracking | An SOP that rebuilds, verifies, and re-publishes when rtk ships a release |
+
+Upstream: https://github.com/rtk-ai/rtk, Apache-2.0, Rust 1.91 plus a C
+toolchain (rusqlite `bundled` compiles SQLite from source).
+
+## 2. Phase 0: premise validated before building anything
+
+The retired output filter validated its design across five phases and its
+premise not at all until the fifth. This plan runs premise validation first.
+Everything below is measured, not estimated.
+
+### 2.1 Why v0.43.0 was ruled out
+
+Two structural facts, read from the source of both tags:
+
+- **Custom TOML filters are not wired into the rewrite path in v0.43.0.**
+  `src/discover/registry.rs` at v0.43.0 contains zero references to
+  `toml_filter`. In v0.44.0 they appear at `registry.rs:1047,1055,1058`.
+  *This reason no longer applies:* section 7 cut our own presets, so nothing we
+  ship depends on that wiring. It is recorded because it was one of the two
+  arguments made at pin time, and the pin now rests on the second alone.
+- **`pipeline_final_safe` does not exist in v0.43.0.** It arrives in v0.44.0
+  (`rules.rs:7,115,124`, `registry.rs:605,659,864,1069`). v0.43.0 rewrote the
+  first pipeline stage; v0.44.0 rewrites the last. On this traffic 56.5% of
+  `rtk grep` hits arrive through the pipeline-final path, so they do not exist
+  at all on v0.43.0.
+
+### 2.2 The port models v0.44.0, not v0.43.0
+
+`rtk_port.py` is re-validated by extracting the `assert_eq!` assertions from
+each tag's `registry.rs` `#[cfg(test)]` block and replaying them:
+
+| Port checked against | Assertions | Exact-string agreement |
+|---|---:|---:|
+| **v0.44.0** | 203 | **203/203** |
+| v0.43.0 | 160 | 147/160 |
+
+The 13 v0.43.0 failures are all the same pipeline inversion. The port also
+passes the 15 assertions v0.44.0 added after the port was written. Pinning
+v0.44.0 makes the existing measurement correct rather than requiring rework.
+
+`registry.rs:590-592` returns `Some(unchanged)` for a simple already-`rtk`
+command; the port's equivalent bail must be mapped to that, not to `None`.
+
+### 2.3 The recorded numbers came from an 11% sample
+
+`measure_rtk.py` sets `N_FILES = 134` and takes the most recently modified
+transcripts. The available pool is **1224 transcripts**. At n=134 the projected
+saving swings **8.8x** across windows (0.071% to 0.628%); at n>=408 it converges
+to within **1.05x**. The spread recorded in earlier revisions of this plan was
+sampling noise.
+
+### 2.4 The port over-counted, and by how much
+
+Both real entry points call `contains_unattestable_construct` **before**
+`registry::rewrite_command`: `hook_cmd.rs:149-151` (Defer) and
+`rewrite_cmd.rs:54-56` (Passthrough). Any command carrying a command
+substitution, a process substitution, or a redirect with a file target is
+rejected whole. Upstream's rewrite tests call `rewrite_command` directly, so a
+port validated only against them passes while still over-counting.
+
+The gate is ported from `lexer.rs:295-347` and validated **35/35** against
+upstream's own assertions at `lexer.rs:1186-1276`. Applying it costs 3.1%
+relative coverage.
+
+### 2.5 Corrected numbers
+
+Full corpus, 1224 transcripts, 552 MB, 106 MB of tool results, 26.6 MB of
+successful Bash, entry gate applied:
+
+| Metric | Earlier revision (n=134, ungated) | Phase 0 (n=1224, gated) |
+|---|---:|---:|
+| Coverage of successful Bash bytes | 31.5% | **35.17%** |
+| Coverage of all tool-result bytes | 9.69% | **8.77%** |
+| Ceiling: tool results as share of input volume | 5.52% | **4.54%** |
+| Projection at rtk's 60-90% claim | 0.32-0.48% | **0.239-0.359%** |
+| Projection, mechanism modelled | 0.15-0.21% | **0.117-0.164%** |
+| Reach of our own TOML presets (the number that cut section 7) | 1.91% of Bash | **1.08% of Bash** |
+| `Read` share of tool-result bytes | 53.8% | **62.8%** |
+
+Modelled effectiveness per family against the claim: `rtk grep` 75% claimed and
+**9.0%** modelled; `rtk read` 60% claimed and **0.0%** modelled; `rtk rg` 75%
+and 30%; `rtk make` 65% and 16%; `rtk jq` 74%.
+
+Largest unaddressed buckets, as a share of successful Bash bytes: pipeline not a
+rewritable final stage **39.78%**, ignored by rtk **10.72%**, entry gate
+**8.29%**, multiline script **4.71%**.
+
+### 2.6 Open question 3 answered: no
+
+Patching `pipeline_final_safe` for `head` and `tail` unlocks 10.56 MB, 39.96% of
+Bash bytes. **88.3% of that (9.33 MB) routes to `rtk read`, measured at 0.00%
+saving** on this traffic because it returns files verbatim at the default
+`--level none`. The largest reachable gap is reachable and worthless. The
+argument for maintaining a fork does not survive its own measurement.
+
+## 3. Why a pack rather than a native feature
+
+- **Opt-in is structural, not a policy.** Plugin packs must not be
+  auto-installed [PATH: kb/reference/plugin-pack-conventions.md]. The retired
+  output filter shipped `off` by default and still had to be wired into every
+  install path, which is why v4.17.0 needed a bespoke migration cleanup.
+- **Removal is already solved.** `plugin remove` strips hook entries from
+  `settings.json`, deletes owned `plugin-<pack>-*` assets, and leaves core and
+  user files alone.
+- **The core package stays lean.** ai-toolkit is 4.4 MB unpacked; the platform
+  artifacts are ~19.5 MB compressed. They never enter the base package.
+- **There is a working precedent.** `memory-pack` ships hooks, a shared script
+  directory, an install-time init script, its own data with retention, and a
+  clean uninstall. `rtk-pack` is the same shape with a binary instead of a
+  database.
+
+## 4. Architecture
+
+```text
+app/plugins/rtk-pack/
+├── plugin.json          # pinned rtk version + per-platform SHA-256
+├── README.md
+├── hooks/
+│   └── rewrite.sh       # PreToolUse; delegates to the fetched binary
+└── scripts/
+    ├── init.py          # platform detect → fetch → verify → install
+    └── status.py        # reports binary, digest and hook wiring
+```
+
+Runtime layout on a user machine:
+
+```text
+~/.softspark/ai-toolkit/
+├── hooks/plugin-rtk-pack-rewrite.sh        # installed hook
+└── plugin-scripts/rtk-pack/
+    ├── bin/rtk                              # verified binary, 0755
+    └── version.json                         # pinned version + recorded digest
+```
+
+Everything the pack writes lives under `plugin-scripts/rtk-pack/`, which
+`plugin remove` deletes wholesale (`plugin.py:500-503`). The pack owns no state
+outside the toolkit data directory: no `filters.toml`, no entry in rtk's trust
+store, nothing in an OS config directory. That is a consequence of cutting
+section 7 and it is what keeps removal complete.
+
+Binary supply chain:
+
+```text
+upstream tag  →  our CI cross-build (RTK_TELEMETRY_URL unset)
+              →  our GitHub Release  softspark-rtk-<upstream>-<build>
+              →  SHA-256 recorded in plugin.json
+              →  plugin install: detect platform, fetch, verify, chmod
+```
+
+## 5. Phase 1: build pipeline and binary release
+
+**Outcome:** we can produce, from an upstream tag, a set of binaries that
+provably make no network calls of their own.
+
+**Targets: five, not six.** `x86_64-apple-darwin`, `aarch64-apple-darwin`,
+`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-gnu`,
+`x86_64-pc-windows-msvc`. Earlier revisions added `x86_64-unknown-linux-gnu` on
+the reasoning that upstream does not ship it. It is dropped: upstream's own
+Homebrew formula routes Linux x86_64 to the **musl** tarball
+(`release.yml:314-316`), a static musl binary runs on glibc, and upstream has
+never validated a gnu x86_64 artifact, so we would be first to ship one and
+would own all its breakage plus an uncontrolled glibc floor inherited from the
+runner image.
+
+Build constraints, all read from the pinned checkout:
+
+- **Pin the toolchain.** Upstream uses `dtolnay/rust-toolchain@stable`
+  (`release.yml:65,116`) with `warnings = "deny"` (`Cargo.toml:70-72`) and ships
+  no `rust-toolchain` file. A future rustc lint turns our builds red with no
+  change on either side. We pin an exact version at or above 1.91.
+- **Windows must build natively.** `build.rs:6-13` emits
+  `cargo:rustc-link-arg=/STACK:8388608` under `#[cfg(windows)]`, which in a
+  build script is a **host** predicate. Cross-building Windows from Linux
+  silently drops the 8 MiB stack reservation that upstream's own comment says is
+  what makes `rtk.exe --version`, `--help`, and hook entry points start
+  reliably. Build on `windows-latest`, or pass the link-arg explicitly.
+- **Both darwin targets build on `macos-latest` (arm64).** `macos-13` is the
+  last x86_64 macOS image and GitHub is winding it down: on runs 30212577757 and
+  30214341444 that job sat queued indefinitely while every other target
+  finished. Upstream builds both on arm64 too, but never runs its x86_64
+  artifact. We do: the verifier detects Rosetta 2 and executes it, and reports
+  `inconclusive` rather than `pass` if it cannot.
+- **Every target needs a target-capable C compiler.** rusqlite `bundled`
+  (`Cargo.toml:26`) is not switchable off; there is no `[features]` table and no
+  `cfg(feature` in `src/`. There is no pure-Rust escape route.
+- **aarch64-linux is the hard case, but upstream already solves it** with
+  `cross: true` on `ubuntu-latest` (`release.yml:51-54`). Copy that. Upstream
+  sets only the linker env var and lets the `cc` crate guess the C compiler;
+  export `CC_aarch64_unknown_linux_gnu` and `AR_aarch64_unknown_linux_gnu`
+  explicitly so a runner image change surfaces as a clear error.
+- **Run our own blocking `cargo audit`.** Upstream's is advisory: `ci.yml:88-96`
+  swallows failures into a warning. Rebuilding from a tag inherits that
+  lockfile, and on v0.44.0 it inherits four advisories across three of its 203
+  crates. The audit and the build jobs apply the same remediation, so we audit
+  the dependency set we ship rather than a different one:
+
+  | Crate | Advisory | Disposition |
+  |---|---|---|
+  | `anyhow` 1.0.102 | RUSTSEC-2026-0190 | `cargo update` to 1.0.103, in range |
+  | `crossbeam-epoch` 0.9.18 | RUSTSEC-2026-0204 | `cargo update` to 0.9.20, in range |
+  | `quick-xml` 0.37.5 | RUSTSEC-2026-0194, RUSTSEC-2026-0195 | ignored with reasons |
+
+  The quick-xml fix lands only in 0.41.0 while rtk pins `"0.37"` as a direct
+  dependency (`Cargo.toml:34`), so taking it means editing `Cargo.toml` and the
+  calling code in `src/cmds/dotnet/dotnet_trx.rs`. That would break the promise
+  that the only difference from an upstream build is the undefined telemetry
+  endpoint. The reachable surface is narrow: quick-xml parses .NET TRX test
+  output only, the input is a report produced locally by the user's own test
+  run, and both advisories are availability-only (CVSS `C:N/I:N/A:H`). The SOP
+  re-checks this on every sync and deletes the ignores once upstream moves to
+  quick-xml 0.41 or later.
+- A target that will not build is dropped, not faked.
+
+### 5.1 Proving the binary is silent
+
+The endpoint is compile-time only: `option_env!("RTK_TELEMETRY_URL")` at
+`telemetry.rs:16` and `telemetry_cmd.rs:176`, with the token at
+`telemetry.rs:17` and `telemetry_cmd.rs:189`. Nothing supplies a default:
+`build.rs` emits no `cargo:rustc-env`, `TelemetryConfig` has no URL field, and
+no runtime `std::env::var` resolves the endpoint. Upstream injects it only in
+`release.yml:85-86,124-125,151-152`. Building without it yields a binary whose
+telemetry destination cannot be re-enabled by any env var or config at runtime.
+
+**The acceptance criterion in earlier revisions was untestable and is replaced.**
+"No telemetry symbols in the binary" cannot be checked: the guard is a runtime
+`if TELEMETRY_URL.is_none()` on a const (`telemetry.rs:23-26`), not a `#[cfg]`,
+so the code compiles in and is only eliminated by LLVM as an optimisation; and
+`Cargo.toml:51` sets `strip = true`, which removes the symbols regardless of
+whether the code is present. A symbol check would pass for the wrong reason.
+
+What we assert instead:
+
+0. **The artifact was actually started.** Every other assertion is worthless on
+   a binary nobody executed, and two of the five targets are not native to their
+   runner. `aarch64-unknown-linux-gnu` runs under `qemu-user` with the cross
+   sysroot passed as `-L`, and `x86_64-apple-darwin` runs under Rosetta 2 on the
+   arm64 runner. A target that cannot be started reports `inconclusive`, never
+   `pass`.
+1. **Build gate.** `RTK_TELEMETRY_URL` and `RTK_TELEMETRY_TOKEN` are unset in
+   the build environment, asserted in CI before `cargo build`, with a clean
+   target directory per build.
+2. **Offline smoke run.** Each artifact runs its real command surface with no
+   network route available and makes zero outbound connections. This is
+   Linux-only: `unshare -rn` has no unprivileged equivalent on macOS or Windows
+   runners, and Ubuntu 24.04's
+   `kernel.apparmor_restrict_unprivileged_userns=1` means even there it needs
+   `sudo`. On the first run this assertion silently degraded to a skip on every
+   target while the verdict still read `pass`, so the manifest now records which
+   isolator was used and a target that could not be started at all reports
+   `inconclusive` rather than `pass`.
+3. **Filesystem assertion.** No telemetry state is created under the resolved
+   data directory.
+4. **Drift detection.** Record artifact size and a string-allowlist hash per
+   target and fail the build on unexplained drift, since whether `ureq`,
+   `rustls`, `ring` and `webpki-roots` are actually eliminated is an LLVM
+   outcome under `lto = true`, not a guarantee.
+
+Three findings that must reach the pack README:
+
+- **`rtk cc` shells out to `npx --yes ccusage`** when `ccusage` is not on PATH
+  (`ccusage.rs:104-119`). That is a runtime npm fetch and third-party code
+  execution. It is not telemetry and not automatic, but it is outbound network
+  from a binary we tell users makes no network calls.
+- **`RTK_TELEMETRY_DISABLED` only accepts the exact string `1`**
+  (`telemetry_cmd.rs:31-33`, locked by the test at `:222-229`). `true` and `yes`
+  are silent no-ops. Never write anything else anywhere in the pack.
+- **`rtk telemetry forget` on an endpoint-free build prints a misleading
+  failure** telling the user to email upstream to complete erasure
+  (`telemetry_cmd.rs:158-169`), when nothing was ever sent.
+
+Apache-2.0 obligations ship alongside: upstream `LICENSE`, a `NOTICE` file
+(upstream has none), and a statement that the only build-time change is leaving
+the telemetry endpoint undefined. **Do not redistribute upstream
+`DISCLAIMER.md` verbatim**: `DISCLAIMER.md:25` states telemetry is collected by
+default, which the code contradicts and which a compliance reviewer would read
+as a reason to block the pack. `docs/TELEMETRY.md:180` calls the mechanism
+"compile-time gating" where "all telemetry code is dead", which is imprecise for
+the same reason our own criterion changed.
+
+**Success criteria:** five artifacts build from the pinned tag; each runs
+`rtk --version` on its target; the silence assertions pass or say plainly that
+they did not run; checksums published.
+
+### 5.2 Result, run 30214882862
+
+All five targets build and verify. Every artifact was actually started, none
+shipped on a skipped assertion.
+
+| Target | `runs` | `offline` |
+|---|---|---|
+| `aarch64-apple-darwin` | native | not applicable |
+| `x86_64-apple-darwin` | translated via Rosetta 2 | not applicable |
+| `x86_64-unknown-linux-musl` | native | passed under `sudo -n unshare -rn` |
+| `aarch64-unknown-linux-gnu` | emulated via `qemu-aarch64-static` | passed under `sudo -n unshare -rn` |
+| `x86_64-pc-windows-msvc` | native | not applicable |
+
+No TLS markers in any artifact, so `ureq`, `rustls`, `ring` and `webpki-roots`
+appear to be eliminated under LTO once the endpoint const is `None`. That is an
+optimisation outcome rather than a guarantee, which is why the fingerprint is
+recorded per target and drift fails the build.
+
+**Four of five targets are bit-reproducible.** Across independent runs with
+identical inputs, `aarch64-apple-darwin`, `x86_64-apple-darwin`,
+`aarch64-unknown-linux-gnu` and `x86_64-unknown-linux-musl` produced
+byte-identical binaries. The concern about unset `trim-paths` embedding registry
+paths does not materialise on these runners.
+
+`x86_64-pc-windows-msvc` did not, and the cause was bounded: **24 bytes out of
+8,018,432 differed**, in five regions. Four were the same two-byte value at
+`0x100` and in the debug directory, which is the MSVC link timestamp; the fifth
+was a 16-byte CodeView GUID. The code was identical; only the link stamp varied.
+
+`-C link-arg=/Brepro` is now set for the Windows target, which makes the linker
+derive that timestamp from content rather than the clock. **The shipped
+`softspark-rtk-v0.44.0-1` artifacts predate that change**, so the Windows digest
+in `plugin.json` is from a non-deterministic link; the flag takes effect on the
+next rebuild, which will produce a different Windows digest for the same source.
+
+This matters for the sync SOP: a changed digest means changed input rather than
+build noise. That inference holds on four targets today and on all five from the
+next rebuild onward.
+
+Note that the **archives** are not reproducible even where the binaries are,
+because gzip records a timestamp. Compare extracted binaries, never the
+tarballs.
+
+Three defects the run surfaced, all now fixed and guarded:
+
+- The gnu target is dynamically linked, so `qemu-user` needs the cross sysroot.
+  It is passed as `-L` rather than `QEMU_LD_PREFIX`, because the offline check
+  runs under `sudo` and `env_reset` drops the variable.
+- The offline check compared a plain run against a namespaced one, so `sudo`'s
+  environment handling was confounded with the network variable and a harness
+  failure was reported as a behaviour difference in the binary. Both sides now
+  run in a namespace and differ only in `-n`.
+- `7z` stored the full relative path, so the Windows zip held
+  `rtk-src/target/<triple>/release/rtk.exe` while every tar.gz held a bare
+  `rtk`. The pack installer extracts all five the same way, so this was a
+  silent install failure on one platform. A `collect` step now asserts every
+  archive holds exactly one flat entry.
+
+## 6. Phase 2: the pack
+
+**Outcome:** `ai-toolkit plugin install rtk-pack` produces a working setup and
+`plugin remove` leaves nothing behind.
+
+- `scripts/init.py` detects platform and libc, fetches the matching artifact,
+  verifies its SHA-256 against `plugin.json`, and installs to
+  `plugin-scripts/rtk-pack/bin/rtk`. A mismatch aborts and removes the partial
+  download. No network at runtime, only at install.
+- Failure to fetch is not an install failure: the pack degrades to inert and
+  says so, matching how the core behaves when `jq` is missing.
+- The hook is wired at `PreToolUse` through the existing pack hook mechanism, so
+  `plugin remove` strips it via the `_source` marker.
+- `plugin status` dispatches to the pack's own `scripts/status.py`, which is
+  generic rather than another hardcoded `if name == ...` branch. It reports the
+  binary, the install record, the live version, and hook wiring, and announces a
+  missing binary as inert rather than letting a green install imply it works.
+
+### 6.1 No trust step, because the pack ships no filters
+
+Section 7 is cut, so the pack writes no `filters.toml` and takes no entry in
+rtk's trust store. That removes the single highest-ranked risk this plan
+carried: an untrusted or content-changed preset produces **zero output on the
+command path with no warning, no stderr line, and no non-zero exit**
+(`toml_filter.rs:220-221`, `:450-458`) — installed, apparently fine, doing
+nothing, which is exactly the shape of failure that retired the in-house filter.
+
+The pack instead reports whether it is actually working. `scripts/status.py`
+distinguishes installed from functioning: a missing binary is announced as
+`MISSING — the hook is inert and every command runs unchanged` rather than
+inferred from a green install.
+
+**If presets are ever revisited, these are the constraints, kept because they
+were expensive to establish:**
+
+- Trust is a byte-exact SHA-256 (`trust.rs:142-163`), so every write, upgrade,
+  repair, trailing newline, or git CRLF normalisation invalidates it.
+- `rtk trust --yes` is indiscriminate: it trusts every gated file that exists,
+  including a `.rtk/filters.toml` an attacker committed into the CWD
+  (`trust.rs:262-305`, project path is CWD-relative at `:207`).
+- It exits 1 both when there is nothing to trust and when the file is invalid
+  TOML (`trust.rs:307-312`), so `set -e` aborts on the benign case.
+- There is no `rtk doctor`, and `rtk trust --list` never re-hashes
+  (`trust.rs:242-256`). Verification means reading the store and recomputing.
+- The global path is not `~/.config/rtk/filters.toml` everywhere: it comes from
+  `dirs::config_dir()` (`trust.rs:206-216`), which on macOS is
+  `~/Library/Application Support`. rtk's own error text hardcodes the Linux path
+  and is wrong there.
+- One global file, no include mechanism, so injection would have to follow the
+  merge-friendly install model [PATH: kb/reference/merge-friendly-install-model.md]
+  with comment markers rather than owning the file.
+
+**Success criteria:** install, status, update, remove, and re-install are
+idempotent; a machine without the pack behaves exactly as today; uninstalling
+ai-toolkit removes every pack artifact.
+
+## 7. Phase 3: cut
+
+**Cut on the measurement, 2026-07-26.** Custom TOML presets reach **1.08% of
+Bash bytes**, which is 0.27% of tool-result bytes. At a generous 60% reduction
+that is **0.008% of input tokens**, roughly one part in twelve thousand.
+
+Against that: presets would have required a trust step that fails silently, a
+doctor check that recomputes digests, marker injection into a file the user may
+also edit, re-trusting after every write, and a per-upstream-release review of a
+DSL whose `deny_unknown_fields` rejects the entire file on one unknown key. The
+maintenance surface is large, the payoff is not measurable, and every item on
+that list is a way for the pack to look installed while doing nothing.
+
+The pack therefore ships upstream rtk's built-in filters and nothing of our own.
+The 35.2% coverage quoted in section 2.5 is already what those built-ins
+deliver; it does not shrink as a result of this cut.
+
+Two consequences recorded so they are not rediscovered:
+
+- The pack owns no state outside `~/.softspark/ai-toolkit/plugin-scripts/rtk-pack/`,
+  which is what makes `plugin remove` complete.
+- One of the two arguments for pinning v0.44.0 was that custom filters are only
+  wired into the rewrite path there. That argument is now moot; the pin rests on
+  `pipeline_final_safe`, which carries 56.5% of `rtk grep` hits on this traffic
+  and does not exist in v0.43.0. See section 2.1.
+
+Reopening this is a plan change, not a task: it needs a workload where rtk's
+built-ins measurably under-perform and a preset that measurably closes the gap,
+demonstrated by replay before any code is written.
+
+## 8. Phase 4: auto-update on `ai-toolkit update`
+
+**Outcome:** a user who installed the pack gets the new binary by running the
+update they already run.
+
+Verified gap: `handleUpdate` in `bin/ai-toolkit.js` reads installed modules from
+`state.json` and does not touch `plugins.json`. Nothing propagates to packs
+today, so this is new wiring, not a configuration change.
+
+**Done.** `ai-toolkit update` now calls `plugin update --editor all --all`
+after the core update. Two things had to change first, both generic rather than
+rtk-specific:
+
+- `update_pack` was an unconditional remove-then-reinstall, so wiring it into
+  the core update would have refetched the binary on every run. `plugins.json`
+  now records the pack version installed per editor, and an update whose
+  manifest version matches is a silent no-op. `--force` overrides.
+- State written before versions were tracked has no `versions` map, so every
+  pack reads as stale exactly once and is updated once. That is the intended
+  migration, not a bug.
+
+`--local` leaves packs alone: they live in `~/.softspark/ai-toolkit` and are
+global, while `--local` is project-local config only.
+
+- After the core update completes, `ai-toolkit update` reads `plugins.json` and
+  runs the equivalent of `plugin update` for every **currently installed** pack.
+  Packs that are not installed stay untouched, which preserves adoption rule 1.
+- The rtk-pack update path is: compare the manifest's pinned version against the
+  recorded pack version; if they differ, fetch and verify the new binary and
+  re-install the hook.
+- `--dry-run` reports what would change per pack.
+- A pack update failure warns and continues; it never fails the core update.
+- Bats coverage in `tests/test_plugin_update.bats`: stale version replaced;
+  current version untouched and silent; pack absent means no work; `--dry-run`
+  reports without acting; legacy state with no version map updates once; a
+  corrupt `plugins.json` does not crash the run.
+
+**Success criteria:** the wiring is generic across packs, not rtk-specific;
+`update` remains idempotent; a failed pack update never leaves a half-installed
+binary.
+
+## 9. Phase 5: upstream sync SOP
+
+**Outcome:** a written procedure so tracking upstream is routine rather than a
+research project each time. **Written**, at
+`kb/procedures/rtk-upstream-sync-sop.md`, modelled on the existing
+ecosystem-sync SOP.
+
+The 0.43.0 to 0.44.0 bump is a worked example of why the review step exists: 200
+commits, and every file the SOP names changed, including a semantic inversion in
+pipeline rewriting and the arrival of the trust gate.
+
+Steps the SOP must cover:
+
+1. **Detect.** Check the upstream releases feed for a tag newer than the pinned
+   one. Their stable cadence is roughly two to four weeks, behind a long
+   release-candidate train. Cadence: on demand, plus a check folded into release
+   preparation.
+2. **Review before building.** Read the changelog and diff `src/discover/rules.rs`,
+   `src/discover/registry.rs`, `src/discover/lexer.rs`, `IGNORED_PREFIXES`, the
+   TOML DSL structs in `src/core/toml_filter.rs`, `src/hooks/trust.rs`, and
+   anything touching telemetry. A change to the DSL or to trust handling is a
+   stop-and-think, not a rebuild.
+3. **Re-validate the port.** Re-extract the `rewrite_command` assertions from the
+   new tag's `registry.rs` test block and the gate assertions from `lexer.rs`,
+   and replay both. Anything short of full agreement invalidates every coverage
+   number until the port is fixed.
+4. **Rebuild** all five targets from the new tag with telemetry unset.
+5. **Verify.** Binary runs on each target; the silence assertions pass; the
+   pack's fixtures still produce the expected decisions.
+6. **Publish** a new release in our namespace and record the new digests.
+7. **Bump** `rtk-pack` version in `plugin.json` and note the upstream version it
+   tracks. The bump is what makes `plugin update` fire at all, since a pack whose
+   recorded version still matches is skipped silently.
+8. **Ship** in the next ai-toolkit release; installed packs pick it up through
+   Phase 4.
+9. **Record** the licence position if upstream relicenses or adds a NOTICE.
+
+There is no upstream test asserting network silence, so that property can
+regress on any bump without turning their CI red. We own that test and re-run it
+every time.
+
+**Success criteria:** a maintainer who has never done it can follow the SOP end
+to end; the review step names specific files rather than saying "check for
+breaking changes".
+
+## 10. Verification
+
+The pack must be able to answer "did this help?" with a number.
+
+**The before-and-after design is replaced.** Phase 0 measured its noise floor:
+on a 134-transcript window the projected saving varies by 8.8x while the
+mechanism is unchanged. A before-and-after comparison cannot detect an effect of
+0.117% to 0.164% against that. Two changes make the measurement possible:
+
+- **Measure over the whole transcript pool, not a recency window.** At n>=408
+  the same metric converges to within 1.05x.
+- **Measure by replay, not by elapsed calendar time.** Run real captured tool
+  output through the built binary and compare byte counts directly. That is the
+  method that produced the honest 0% which retired the in-house filter, and it
+  removes the confound of what work the user happened to do that week.
+
+The harness is `replay_rtk.py` in the measurement archive, not a script inside
+the pack. It pairs each successful Bash result with the command that produced
+it, keeps the ones the validated port says rtk would rewrite, and pipes the
+captured bytes through the shipped binary via `rtk pipe -f <filter>`.
+
+Two limits, stated because the number is meaningless without them:
+
+- `rtk pipe` runs the same filter code as the command path but knows less than
+  it does: no result caps, no exit code, no file set. For search families the
+  replay figure is a **lower bound** on what the command path would save.
+- Families with no pipe filter (`rtk read`, `rtk ls`, `rtk wc`) cannot be
+  measured this way at all. They are reported as **unmeasurable**, never folded
+  in as zero, because a zero that is really an absence is how the previous
+  effort talked itself into shipping.
+
+Session-level token accounting, when it is wanted, comes from the session JSONL
+[PATH: scripts/session_token_stats.py], summing all four usage fields: in a
+cached session most context tokens land in the cache fields rather than
+`input_tokens`.
+
+**Kill number, published before the measurement rather than argued after it:**
+if replay on the full corpus shows the shipped binary saving less than 0.05% of
+input tokens, the pack is not worth its maintenance and supply-chain surface,
+and it is retired the way the output filter was.
+
+### 10.1 Result: measured 0.0615%, kill number survived by 23%
+
+Full pool, 28.56 MB of successful Bash output, replayed through the published
+`softspark-rtk-v0.44.0-1` binary:
+
+| | |
+|---|---:|
+| Addressed by rtk | 9.99 MB, **35.00%** of Bash bytes |
+| Measurable through `rtk pipe` | 5.66 MB |
+| After filtering | 4.22 MB |
+| **Measured saving** | **1.44 MB = 360,529 tokens** |
+| As a share of tool-result bytes | 1.35% |
+| **As a share of input tokens** | **0.0615%** |
+
+Against a kill number of 0.05%, the pack survives by a factor of 1.23. That is a
+pass, not a vindication.
+
+**The projection published in section 2.5 was roughly twice too optimistic.**
+It said 0.117% to 0.164%; the measurement says 0.0615%. The error has a single
+identifiable cause: the model credited families it could not simulate with
+rtk's own claimed 60-90%. Replayed, the families that can be measured deliver
+**25.5%** in aggregate.
+
+Per family, measured against modelled and against upstream's claim:
+
+| Family | Measured | Modelled | Claimed |
+|---|---:|---:|---:|
+| `rtk grep` | **22.3%** | 9.0% | 75% |
+| `rtk git` | **33.1%** | — | 70% |
+| `rtk find` | **35.6%** | — | 70% |
+| `rtk rg` | **7.0%** | 30% | 75% |
+| `rtk ruff` | **0.0%** | — | — |
+
+The model **understated** grep by 2.5x and the total still came out high, so the
+two errors are unrelated: coverage modelling was sound, per-family effectiveness
+was guesswork wherever the source was not read closely.
+
+**What the replay does not settle.** 43.3% of addressed bytes (4.33 MB) have no
+`rtk pipe` filter and are unmeasurable, the largest being `rtk read` at 1.55 MB.
+That family is known from source to return files verbatim at the default
+`--level none`, so the headroom is smaller than 43.3% suggests. No extrapolation
+is applied: a zero that is really an absence of measurement is how the previous
+effort talked itself into shipping. For search families the pipe path also lacks
+the command path's result caps, making these figures a lower bound.
+
+**One independent confirmation.** The replay measured coverage at 35.00% of Bash
+bytes; the gated port measured 35.17% on the same pool by a different method.
+The port is right about *which* commands rtk touches even where it was wrong
+about how much each saves.
+
+Reproduce with `replay_rtk.py --pool 1300 --rtk <binary>` in the measurement
+archive.
+
+## 11. Licence and security obligations
+
+- **Apache-2.0.** Ship upstream `LICENSE` with the binaries, add a `NOTICE`, and
+  state the build-time change. Never relabel any upstream file MIT. Do not ship
+  `DISCLAIMER.md` verbatim, see section 5.1.
+- **Telemetry.** Proven absent per build by the four assertions in section 5.1,
+  re-proven on every upstream sync.
+- **Supply chain.** Digests pinned in `plugin.json`, verified on fetch,
+  re-verified by `doctor`. This mirrors the existing checksum-pin discipline for
+  URL-sourced rules and hooks. Run a blocking `cargo audit` on the pinned
+  lockfile, because upstream's is advisory.
+- **Trust boundary.** rtk rewrites commands before execution, which the retired
+  in-house contract explicitly forbade for itself. Adopting it is a conscious
+  reversal of that constraint and its own threat surface: what runs is not what
+  the model asked for. The pack's README must say this plainly, and
+  `plugin install` must not be silent about it. The README must also disclose
+  the `rtk cc` npx path.
+
+  The sharp edge is more specific than "the command changes". rtk evaluates the
+  host's permission rules against the **original** command and applies the
+  verdict to the **rewritten** one: `decide_hook_action(cmd, ...)` takes the
+  command the model asked for, and `permissionDecision: allow` is then emitted
+  for the substituted `rtk …` form (`hook_cmd.rs:405-436`). An allowlist entry
+  for `git status` therefore authorises `rtk git status`, which the user never
+  wrote a rule for. Upstream documents the absence case in its own test
+  (`hook_cmd.rs:1272-1283`): with no matching allow rule, no decision is emitted
+  and the normal prompt stands. Both halves belong in the README.
+
+## 12. Pre-mortem
+
+| Rank | Failure mode | Probability | Impact | Mitigation |
+|---:|---|:---:|:---:|---|
+| — | ~~Presets install but are untrusted, so they silently do nothing~~ | — | — | **Eliminated**, not mitigated: section 7 is cut, so the pack ships no filters and takes no trust-store entry |
+| 2 | Cross-building with bundled SQLite is fragile in CI | Medium | Medium | Copy upstream's `cross` setup for aarch64-linux; five targets not six; a target that will not build is dropped, not faked |
+| 3 | Pre-execution rewriting changes command semantics | Medium | High | Opt-in pack, documented one-flag disable, upstream's own review process, our integration tests on real commands |
+| 4 | Windows binary cross-built without the 8 MiB stack reservation | Medium | High | Build natively on `windows-latest`, or pass the link-arg explicitly. `build.rs:6-13` |
+| 5 | Upstream velocity breaks the rewrite logic the coverage numbers model | Medium | Medium | Pinned version, SOP review step naming exact files, port re-validation as a gate, fork option preserved by Apache-2.0 |
+| 6 | Unpinned toolchain plus `warnings = "deny"` turns builds red with no change | Medium | Low | Pin an exact rustc version; treat bumps as deliberate |
+| 7 | A fetch failure leaves a half-installed pack | Medium | Medium | Verify-then-install, abort and clean on digest mismatch, `doctor` detects drift |
+| 8 | Live saving lands near the projection, not the claim | High | Medium | Section 10 measures it by replay either way, against a published kill number |
+| 9 | The auto-update wiring makes `update` slower or flakier | Low | Medium | Skip when versions match, warn-and-continue on failure, `--dry-run` coverage |
+| 10 | The pack drifts into being installed by default | Low | High | Adoption rule 1 plus a test asserting `install` never pulls it in |
+
+## 13. Open questions
+
+1. ~~Which upstream tag do we pin first?~~ **Answered: v0.44.0.** See section 2.1.
+2. ~~User scope only, or a project-scoped preset variant too?~~ **Moot:** section 7 is cut, so the pack installs no presets at any scope.
+3. ~~Is patching `pipeline_final_safe` for `head`/`tail` in scope later?~~
+   **Answered: no.** See section 2.6.
+4. ~~Does Phase 3 survive its own measurement at 0.008% of input tokens?~~
+   **Answered: no, cut 2026-07-26.** See section 7.
+5. ~~How does the pack share rtk's single global `filters.toml`?~~ **Moot:** it
+   writes no filters at all. The marker-injection design and the trust
+   constraints that would have applied are kept in section 6.1 in case presets
+   are ever revisited.
+
+---
+
 ## kb/howto/README.md
 
 ---
@@ -5320,7 +6170,7 @@ python3 scripts/validate.py --strict
 ai-toolkit plugin list                             # show available packs
 ai-toolkit plugin install --editor claude <name>  # install for Claude Code global target
 ai-toolkit plugin install --editor codex <name>   # install for Codex global target
-ai-toolkit plugin install --editor all --all      # install all 11 packs for both runtimes
+ai-toolkit plugin install --editor all --all      # install all 12 packs for both runtimes
 ai-toolkit plugin update --editor all --all       # re-apply all installed packs after toolkit updates
 ai-toolkit plugin clean <name>                    # prune data older than 90 days
 ai-toolkit plugin clean <name> --days 30  # custom retention
@@ -5771,12 +6621,17 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 
 ## Phase 4: Regenerate Artifacts
 
+Use the npm scripts, not the generators directly:
+
 ```bash
-python3 scripts/generate_agents_md.py > AGENTS.md
-python3 scripts/generate_llms_txt.py > llms.txt
-python3 scripts/generate_llms_txt.py --full > llms-full.txt
+npm run generate:agents   # AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_agents_md.py > AGENTS.md
+npm run generate:llms     # llms.txt + llms-full.txt
 ```
 
+`generate:agents` sets `AI_TOOLKIT_NO_CUSTOM_RULES=1`. Running
+`generate_agents_md.py` bare picks up whatever is registered in the maintainer's
+own `~/.softspark/ai-toolkit/rules/`, which then ships inside `AGENTS.md`.
+
 Check if anything actually changed:
 
 ```bash
@@ -6485,6 +7340,290 @@ ai-toolkit eject /tmp/test # retry
 
 ---
 
+## kb/procedures/rtk-upstream-sync-sop.md
+
+---
+title: "SOP: rtk Upstream Sync"
+category: procedures
+service: ai-toolkit
+tags: [sop, rtk, rtk-pack, upstream, cross-build, telemetry, checksum, port-validation, advisory]
+version: "1.0.0"
+created: "2026-07-26"
+last_updated: "2026-07-26"
+description: "Procedure for moving rtk-pack to a newer upstream rtk release: detect the tag, review the files we depend on, re-validate the Python port that every coverage number rests on, rebuild five targets with telemetry undefined, verify silence, publish to our own release namespace, and bump the pack. Written after the v0.43.0 to v0.44.0 bump, which changed every file this SOP names."
+---
+
+# SOP: rtk Upstream Sync
+
+Moves `rtk-pack` from one pinned upstream tag to the next.
+
+Currently pinned: **v0.44.0**, shipped as
+`softspark-rtk-v0.44.0-1`. The pin lives in
+`app/plugins/rtk-pack/plugin.json` under `upstream.version`.
+
+Upstream ships stable tags roughly every two to four weeks behind a long
+release-candidate train (300+ RCs preceded v0.44.0). Do not track RCs.
+
+Background and the measured numbers: `kb/history/completed/rtk-pack-integration-20260726.md`.
+
+## Why this SOP is not "just rebuild"
+
+The v0.43.0 to v0.44.0 bump was 200 commits and touched **every file listed in
+Phase 2 below**. It also inverted pipeline rewriting: v0.43.0 rewrote the first
+stage of a pipeline, v0.44.0 rewrites the last. A rebuild without the review
+step would have shipped that silently, and the coverage numbers quoted to users
+would have described a version we no longer ship.
+
+## Phase 1: Detect
+
+```bash
+gh api repos/rtk-ai/rtk/releases --paginate \
+  --jq '.[] | select(.tag_name | test("^v[0-9]")) | "\(.tag_name)\t\(.published_at)"' | head -5
+```
+
+Compare against `upstream.version` in `app/plugins/rtk-pack/plugin.json`.
+
+Cadence: on demand, plus a check folded into release preparation.
+
+## Phase 2: Review before building
+
+Fetch the diff for the areas the pack depends on:
+
+```bash
+gh api repos/rtk-ai/rtk/compare/<pinned>...<new> \
+  --jq '{ahead: .ahead_by, files: [.files[] | {f: .filename, add: .additions, del: .deletions}]}'
+```
+
+Read the changelog, then diff these specifically:
+
+| File | Why it matters |
+|---|---|
+| `src/discover/registry.rs` | rewrite eligibility, pipeline handling, the TOML call sites |
+| `src/discover/rules.rs` | the rule table and `IGNORED_PREFIXES` |
+| `src/discover/lexer.rs` | tokenisation and `contains_unattestable_construct` |
+| `src/core/toml_filter.rs` | the filter DSL, which affects users who write their own filters |
+| `src/hooks/trust.rs` | the trust gate and its paths |
+| `src/hooks/hook_cmd.rs` | the Claude hook contract and permission handling |
+| `src/core/telemetry.rs`, `src/core/telemetry_cmd.rs` | the compile-time endpoint gate |
+| `Cargo.toml`, `Cargo.lock` | native deps, the MSRV, and new advisories |
+
+**A change to the DSL, to trust handling, or to the permission flow is a
+stop-and-think, not a rebuild.** In particular:
+
+- The pack ships no filters of its own, so a DSL change cannot break us. It can
+  still break a **user's** `filters.toml`, which upstream then skips silently
+  (`toml_filter.rs:220-221`). Worth a release-note line, not a code change.
+- If `hook_cmd.rs` changes when `permissionDecision` is emitted, the trust
+  boundary documented in the pack README changes with it.
+- If `IGNORED_PREFIXES` or the `pipeline_final_safe` rule set moves, every
+  coverage number is stale.
+
+## Phase 3: Re-validate the port
+
+Every coverage and saving figure the pack quotes comes from `rtk_port.py`, a
+Python model of rtk's rewrite pipeline. **Anything short of full agreement
+invalidates those numbers until the port is fixed.** Tooling lives in
+`~/rtk-measurement-archive/`.
+
+```bash
+git clone --depth 1 --branch <new-tag> https://github.com/rtk-ai/rtk.git /tmp/rtk-new
+cd ~/rtk-measurement-archive
+
+# Rewrite assertions from the tag's own test block.
+python3 extract_cases.py /tmp/rtk-new/src/discover/registry.rs cases.json
+python3 validate_port.py cases.json
+
+# The entry gate both real hook paths apply before rewrite_command.
+# Its assertions live in lexer.rs; re-extract if that block moved.
+python3 -c "import entry_gate; print('gate import ok')"
+```
+
+Baseline at v0.44.0: **203/203** rewrite assertions, **35/35** gate assertions.
+
+If the port diverges, fix the port first, then re-measure:
+
+```bash
+python3 measure_gated.py gated 0:1224
+```
+
+Measure over the whole transcript pool, never the default 134-file window: at
+that size the projection swings 8.8x on an unchanged mechanism.
+
+### 3.1 Re-measure, do not just re-validate
+
+Port agreement proves rtk still rewrites the same commands. It says nothing
+about how much each rewrite saves, and that is where the value actually sits.
+
+**`rtk grep` carries 4.04 MB of the 5.66 MB measurable saving: 71% of the total
+rests on one family.** If upstream changes that one filter, the headline number
+moves even with the port at full agreement. Measured effectiveness has already
+diverged from expectation in both directions once: `rtk grep` measured 22.3%
+against 9.0% modelled, `rtk rg` 7.0% against 30% modelled.
+
+So on every bump, after the port passes, replay against the newly built binary:
+
+```bash
+python3 replay_rtk.py --pool 1300 --rtk <path-to-the-new-binary>
+```
+
+Compare per family against the recorded baseline:
+
+| Family | Measured at v0.44.0 | Share of total saving |
+|---|---:|---:|
+| `rtk grep` | 22.3% | 71% |
+| `rtk git` | 33.1% | 21% |
+| `rtk find` | 35.6% | 8% |
+
+**Act on the result, do not just record it.** If the total lands below the
+published kill number of **0.05% of input tokens**, the pack has stopped earning
+its supply-chain surface and retiring it is the correct outcome, exactly as the
+in-house filter was retired. The margin at v0.44.0 is 0.0615%, which is 1.23x
+the kill number, so a single-family regression is enough to cross it.
+
+## Phase 4: Rebuild
+
+```bash
+gh workflow run rtk-build.yml --ref main \
+  -f upstream_tag=<new-tag> -f build_revision=1 -f rust_version=<pinned> -f publish=false
+```
+
+Five targets: `x86_64-apple-darwin`, `aarch64-apple-darwin`,
+`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-gnu`,
+`x86_64-pc-windows-msvc`. A target that will not build is dropped, not faked.
+
+Pin `rust_version` explicitly. Upstream uses unpinned `stable` with
+`warnings = "deny"`, so a new rustc lint can turn the build red with no change
+on either side.
+
+**Advisories.** The `audit` job blocks. Re-derive the disposition rather than
+carrying the previous one forward:
+
+```bash
+# Cross-reference the new lockfile against OSV without waiting for CI.
+python3 - <<'PY'
+import json, re, urllib.request, pathlib
+lock = pathlib.Path("/tmp/rtk-new/Cargo.lock").read_text()
+pkgs = [(re.search(r'^name = "([^"]+)"', b, re.M).group(1),
+         re.search(r'^version = "([^"]+)"', b, re.M).group(1))
+        for b in lock.split("[[package]]")[1:]
+        if re.search(r'^name = ', b, re.M) and re.search(r'^version = ', b, re.M)]
+q = [{"package": {"name": n, "ecosystem": "crates.io"}, "version": v} for n, v in pkgs]
+req = urllib.request.Request("https://api.osv.dev/v1/querybatch",
+    data=json.dumps({"queries": q}).encode(), headers={"Content-Type": "application/json"})
+res = json.load(urllib.request.urlopen(req, timeout=60))
+for (n, v), r in zip(pkgs, res["results"]):
+    if r.get("vulns"):
+        print(n, v, [x["id"] for x in r["vulns"]])
+PY
+```
+
+For each advisory decide, and record the reason in the workflow:
+
+- **In-range fix** (`cargo update -p <crate>` works): add the crate to
+  `RTK_CARGO_UPDATES` in `.github/workflows/rtk-build.yml`. Both the audit job
+  and every build job apply it, so we audit what we ship.
+- **Needs a `Cargo.toml` change**: that is a source modification and breaks the
+  NOTICE claim. Ignore with a written reason, or escalate.
+- **Carried-forward ignores**: re-check every `--ignore` still applies. The
+  quick-xml pair exists only because upstream pins `"0.37"`; **delete both the
+  moment upstream moves to 0.41 or later** rather than carrying them.
+
+## Phase 5: Verify
+
+CI asserts this per target and the run fails on any `fail` verdict:
+
+1. `RTK_TELEMETRY_URL` and `RTK_TELEMETRY_TOKEN` unset at build time
+2. the artifact starts and reports the expected version
+3. no telemetry state written into a sandboxed home
+4. on Linux, identical behaviour with no network route
+5. every archive holds exactly one flat entry
+
+Then check by hand:
+
+```bash
+gh run download <run-id> --dir /tmp/rtk-verify
+cd /tmp/rtk-verify && shasum -a 256 -c checksums.txt
+```
+
+Three things CI cannot tell you:
+
+- **`strings` markers.** Compare `tls_markers_present` per target against the
+  previous build. Their absence is an LLVM outcome under LTO, not a guarantee,
+  so a sudden appearance means the telemetry stack survived and is worth
+  understanding before shipping.
+- **Reproducibility.** Four of five targets are bit-reproducible; compare
+  extracted binaries, never the tarballs, because gzip records a timestamp.
+  `x86_64-pc-windows-msvc` differs by 24 bytes per link (MSVC timestamp plus a
+  CodeView GUID), so a changed Windows digest proves nothing on its own.
+- **Upstream has no test asserting network silence.** That property can regress
+  on any bump without turning their CI red. We own it.
+
+## Phase 6: Publish
+
+```bash
+gh workflow run rtk-build.yml --ref main \
+  -f upstream_tag=<new-tag> -f build_revision=1 -f rust_version=<pinned> -f publish=true
+```
+
+Creates `softspark-rtk-<upstream>-<revision>`. Bump the revision, not the
+upstream part, when rebuilding the same upstream tag.
+
+## Phase 7: Bump the pack
+
+In `app/plugins/rtk-pack/plugin.json`:
+
+- `upstream.version` to the new tag
+- `binary.release_tag` to the new release
+- every `assets.*.sha256` from the published `checksums.txt`
+- `version` (the pack's own) — bump it whether or not the upstream tag moved,
+  because `plugin update` skips a pack whose recorded version still matches, so
+  an unbumped pack never reaches installed users. The two fields are separate so
+  a pack-only fix does not pretend to be an upstream bump
+
+Then:
+
+```bash
+npm test          # tests/test_rtk_pack.bats asserts digest shape and layout
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+shellcheck --severity=warning app/hooks/*.sh app/plugins/*/hooks/*.sh
+```
+
+Verify a real install end to end, against the published release rather than a
+mirror:
+
+```bash
+H=$(mktemp -d)
+AI_TOOLKIT_DATA_DIR="$H" python3 app/plugins/rtk-pack/scripts/init.py
+AI_TOOLKIT_DATA_DIR="$H" python3 app/plugins/rtk-pack/scripts/status.py
+```
+
+## Phase 8: Ship
+
+The pack version bump reaches installed users through `ai-toolkit update`,
+which runs `plugin update --editor all --all`. A pack whose recorded version
+matches its manifest is skipped silently, so the bump in Phase 7 is what makes
+the update fire at all. Forgetting it means nobody gets the new binary.
+
+## Phase 9: Record the licence position
+
+If upstream relicenses, adds a `NOTICE`, or changes `DISCLAIMER.md`, update the
+NOTICE generated in `.github/workflows/rtk-build.yml`. It currently records two
+build-time differences: the undefined telemetry endpoint, and in-range lockfile
+security updates. If Phase 4 changes that set, the NOTICE text changes with it.
+
+`DISCLAIMER.md` is deliberately not redistributed because it states telemetry is
+collected by default, which our builds contradict. Re-check that this is still
+the reason before changing the decision.
+
+## Related
+
+- `kb/history/completed/rtk-pack-integration-20260726.md` — decisions, measurements, pre-mortem
+- `kb/history/completed/output-filter-retirement-20260726.md` — why premise validation comes first
+- `app/plugins/rtk-pack/README.md` — the user-facing trust boundary
+
+---
+
 ## kb/reference/agents-catalog.md
 
 ---
@@ -6844,9 +7983,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.5.0"
+version: "1.6.0"
 created: "2026-03-23"
-last_updated: "2026-07-23"
+last_updated: "2026-07-26"
 description: "Architecture of ai-toolkit: directory layout, Claude app export, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -7141,7 +8280,6 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | UserPromptSubmit | Before user prompt execution | `track-usage.sh` | Record skill invocations to stats.json |
 | PostToolUse | After edit/write tools | `post-tool-use.sh` | Lightweight validation reminders |
 | PostToolUse | After any tool | `governance-capture.sh` | Log security-sensitive operations |
-| PostToolUse | After successful Bash | `filter-tool-output.sh` | Observe eligible text or replace it only after exact recovery succeeds; Claude Code only |
 | Stop | After response | `quality-check.sh` | Multi-language lint |
 | Stop | After response | `save-session.sh` | Persist session context |
 | Stop | Before final stop | `quality-gate.sh` | Block final response on lint/type errors |
@@ -7558,9 +8696,9 @@ The reference benchmark set is intentionally curated:
 title: "CLI Reference"
 category: reference
 service: ai-toolkit
-tags: [cli, commands, reference, install, update, plugin, mcp, telemetry, output-filter]
+tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-07-23"
+last_updated: "2026-07-26"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -7614,7 +8752,7 @@ Usage: ai-toolkit <command> [options]
 |---------|-------------|
 | `plugin list` | Show available plugin packs with install status |
 | `plugin install <name> [--editor claude\|codex\|all]` | Install a plugin pack for Claude Code and/or Codex (`claude` means Claude Code, not the Claude app) |
-| `plugin install --all [--editor claude\|codex\|all]` | Install all 11 plugin packs |
+| `plugin install --all [--editor claude\|codex\|all]` | Install all 12 plugin packs |
 | `plugin update <name> [--editor claude\|codex\|all]` | Update a plugin pack (remove + reinstall, preserves data) |
 | `plugin update --all [--editor claude\|codex\|all]` | Update all installed plugin packs |
 | `plugin clean <name> [--days N]` | Prune old plugin data (default: 90 days) |
@@ -7635,18 +8773,8 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `output-filter status [--policy PATH]` | Print the effective trusted project/global policy, or inspect an explicit policy |
-| `output-filter inspect --profile repeat-lines\|tap-success` | Read stdin and print content-free candidate metadata without changing or echoing the input |
-| `output-filter recover <handle> [--base-directory PATH] [--session-id ID]` | Print the exact stored native response object for an opaque recovery handle |
-| `output-filter clean [--base-directory PATH] [--session-id ID]` | Remove owned filter artifacts for one session or all sessions in the current repository |
-| `output-filter clean --session-id ID --expired` | Remove expired exact-response artifacts for one native session |
-| `output-filter hook --policy PATH` | **Internal, not for manual use.** `PostToolUse` entry point that reads the native hook payload on stdin and emits any replacement. The installed hook `filter-tool-output.sh` calls the same runtime through the lean `output_filter_hook.py` process instead |
-
-`off` is the default. Configure `toolOutputFilter.mode` in
-`.softspark-toolkit.json`, then run `install --local` or `update --local`.
+
 `AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1` bypasses active filtering immediately.
-See [Native Tool Output Filter](tool-output-filter.md) for eligibility,
-privacy, recovery, and runtime support.
 
 ## Project Registry
 
@@ -8944,7 +10072,7 @@ tags:
   - multi-repo
 doc_type: reference
 created: "2026-04-11"
-last_updated: "2026-07-23"
+last_updated: "2026-07-26"
 description: "Comprehensive guide for setting up and using ai-toolkit configuration inheritance. Covers base config creation, project setup, enforcement rules, CI integration, and troubleshooting."
 ---
 
@@ -9011,7 +10139,6 @@ ai-toolkit config check       # CI enforcement check
 |-------|------|-------------|
 | `extends` | string | Base config source (npm, git URL, local path) |
 | `profile` | enum | `minimal`, `standard`, `strict`, `full`, `offline-slm` |
-| `toolOutputFilter` | object | Native Bash result filtering policy: mode, profiles, savings thresholds, and recovery limits |
 | `agents` | object | `enabled`, `disabled`, `custom` arrays |
 | `plugins` | object | Resolved `enabled` and `disabled` plugin intent |
 | `rules` | object | `inject`, `remove` arrays |
@@ -9091,25 +10218,6 @@ effective intent explicit and causes validation to reject a conflicting
 `plugins.disabled` entry. Install the named plugin pack separately with
 `ai-toolkit plugin install <name>` or your organization deployment workflow.
 
-### Native tool-output filtering
-
-Projects can opt into the dependency-free output filter without changing the
-organization-wide default:
-
-```json
-{
-  "toolOutputFilter": {
-    "mode": "observe",
-    "profiles": ["repeat-lines", "tap-success"]
-  }
-}
-```
-
-`ai-toolkit install --local` materializes the effective policy as the managed
-`.claude/ai-toolkit-output-filter.json` file. `off` is the default, `observe`
-collects metadata without changing model-visible output, and `safe` permits
-replacement only when every invariant and exact-recovery check succeeds.
-
 ### Overrides
 
 Projects can override base settings, but must declare intent:
@@ -10054,9 +11162,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.8.0"
+version: "1.9.0"
 created: "2026-03-27"
-last_updated: "2026-07-23"
+last_updated: "2026-07-26"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -10082,9 +11190,6 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 **File locations:**
 
 - Scripts: `~/.softspark/ai-toolkit/hooks/*.sh`
-- Output-filter runtime: `~/.softspark/ai-toolkit/scripts/output_filter_hook.py`, `output_filter_cli.py`, and `tool_output_filter/`
-- Global output-filter policy: `~/.softspark/ai-toolkit/hooks/output-filter-policy.json`
-- Managed project policy: `<project>/.claude/ai-toolkit-output-filter.json`
 - Config: `~/.claude/settings.json` → `hooks` key
 - Source: `ai-toolkit/app/hooks/*.sh` + `app/hooks.json`
 
@@ -10229,59 +11334,6 @@ arms the corrective Stop hook.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
-### PostToolUse (native Bash output filter): `filter-tool-output.sh`
-
-| Field | Value |
-|-------|-------|
-| Event | `PostToolUse` |
-| Matcher | `Bash` |
-| Script | `~/.softspark/ai-toolkit/hooks/filter-tool-output.sh` |
-| Fires | After a successful Claude Code Bash tool call |
-
-The hook is disabled by default and runs last among the installed
-`PostToolUse` handlers. Its modes are:
-
-| Mode | Behavior |
-|------|----------|
-| `off` | Shell fast path exits before Python starts |
-| `observe` | Evaluates eligible output and writes content-free metadata, but emits no replacement |
-| `safe` | Replaces eligible output only after invariants pass and the exact native response is stored for recovery |
-
-Only explicitly allowlisted test, lint, typecheck, and validation command
-shapes are eligible. Failed or interrupted tools, non-empty stderr, image or
-binary results, pipes, redirects, deployment, migrations, audits, security
-scanners, malformed payloads, unavailable recovery, and any uncertain case
-remain unchanged.
-
-The per-project policy `<project>/.claude/ai-toolkit-output-filter.json` is
-honored only when **both** checks pass: the project root is registered in
-`~/.softspark/ai-toolkit/projects.json`, and the sibling regular file
-`<project>/.claude/.ai-toolkit-output-filter.owner` holds the ai-toolkit owner
-marker. `ai-toolkit install --local` writes both. Registration is required
-because the owner marker is a public constant, so a cloned or untrusted
-checkout must never be able to self-enable filtering by shipping its own
-marker. An unregistered project, a missing or foreign marker, or a symlinked
-project root or `.claude` directory falls back to the installed global policy
-at `~/.softspark/ai-toolkit/hooks/output-filter-policy.json`, which ships as
-`off`.
-
-`jq` is a required system dependency (`python3 scripts/check_deps.py`
-verifies it alongside `python3`, `git`, and `node`); without it `guard-path.sh`
-blocks file tools rather than skipping path validation.
-
-Recovery data is private and session-scoped under
-`~/.softspark/ai-toolkit/sessions/<repo-key>/output-filter/`. Telemetry records
-only profile/version, byte and line counts, latency, outcome, and fallback
-reason. Recovery-backed modes require a bounded native session ID containing
-only ASCII letters, digits, underscores, or hyphens. Three consecutive
-profile, invariant, or recovery safety failures open a session circuit
-breaker. Set `AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1` for an immediate bypass.
-
-The replacement adapter is Claude Code-specific. Claude Chat/Cowork exports
-exclude it, and the generated hooks for other editors do not activate it.
-The `minimal` hook profile and `AI_TOOLKIT_DISABLED_HOOKS=filter-tool-output`
-bypass it before the Python runtime starts.
-
 ### Stop (quality check) — `quality-check.sh`
 
 | Field | Value |
@@ -10395,8 +11447,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Removes private output-filter artifacts and isolated edit state for
-the ending native session, then writes `session-end.md` to the per-repo session store
+**Action:** Removes isolated edit state for the ending native session, then writes `session-end.md` to the per-repo session store
 (`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note
 for the next session.
 
@@ -12446,10 +13497,10 @@ Required keys:
 ## CLI Management
 
 ```bash
-ai-toolkit plugin list               # show all 11 packs with install status
+ai-toolkit plugin list               # show all 12 packs with install status
 ai-toolkit plugin install --editor claude <name>   # Claude Code global target
 ai-toolkit plugin install --editor codex <name>    # Codex global target
-ai-toolkit plugin install --editor all --all       # install all 11 packs for both runtimes
+ai-toolkit plugin install --editor all --all       # install all 12 packs for both runtimes
 ai-toolkit plugin update --editor all --all        # update all installed packs
 ai-toolkit plugin clean <name>       # prune data older than 90 days (default)
 ai-toolkit plugin clean <name> --days 30  # prune data older than 30 days
@@ -12512,6 +13563,21 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 | `kotlin-pack` | kotlin | 0 | 1 | 0 | Kotlin patterns |
 | `swift-pack` | swift | 0 | 1 | 0 | Swift patterns |
 | `ruby-pack` | ruby | 0 | 1 | 0 | Ruby patterns |
+| `rtk-pack` | token-reduction | 0 | 0 | 1 | Command rewriting via a checksum-pinned rtk binary fetched at install |
+
+`rtk-pack` is the first pack to break three assumptions the others share, so it
+is the one to read when extending the contract:
+
+- **It fetches from the network at install time.** `scripts/init.py` downloads a
+  platform-specific artifact and verifies its SHA-256 against `plugin.json`
+  before installing anything. A mismatch aborts and leaves nothing behind.
+- **It declares platform assets and digests in `plugin.json`.** The manifest
+  schema tolerates extra keys, so `upstream` and `binary` are additive; nothing
+  validates them, which means a malformed block fails at install rather than in
+  `validate.py --strict`.
+- **It reports its own health.** `scripts/status.py` is picked up generically by
+  `plugin status`, replacing what used to be a hardcoded `if name == "memory-pack"`
+  branch. Any pack can now ship one.
 
 ## Optional Hook Modules
 
@@ -13157,7 +14223,6 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
 | Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
 | Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool`, `http` (POST event JSON to allowlisted URLs via `allowedHttpHookUrls`) |
-| Tool-output replacement | Native `PostToolUse.updatedToolOutput`; ai-toolkit exposes dependency-free `off`, byte-identical `observe`, and opt-in recoverable `safe` modes for eligible successful Bash text |
 | Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
 | Version probe | `claude --version` |
 | Notes | v2.1.169 added `disableBundledSkills` setting + `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` env var (hides bundled skills/built-in slash commands from the model; toolkit skills in `.claude/skills/` are unaffected — useful when toolkit skills overlap built-ins) and `claude --safe-mode` / `CLAUDE_CODE_SAFE_MODE` (starts with hooks, skills, agents, and CLAUDE.md disabled — first isolation step when debugging toolkit rule enforcement). `fallbackModel` settings key (v2.1.166) noted as not-adopted (class C, no toolkit surface writes model settings). |
@@ -13177,7 +14242,6 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Plugin layout | `.claude-plugin/plugin.json`, `skills/*/SKILL.md`, `agents/*.md`, `hooks/hooks.json`; ai-toolkit uses manifest paths under `claude-app/` for its generated app-only rules and hooks |
 | Our generator | `scripts/claude_app.py` (`ai-toolkit claude-app export`) |
 | Runtime split | Skills work in Chat (web/Desktop) and Cowork. Hooks and sub-agents run only in Cowork. Claude app does **not** scan Claude Code's `~/.claude/rules/`, `CLAUDE.md`, or `~/.claude/settings.json`. |
-| Tool-output replacement | Not shipped. The Claude Code-only filter hook and runtime are excluded from the app archive until Cowork has an independently verified replacement contract. |
 | Install/update | Export the ZIP, upload it from `Customize > Plugins`, then paste the generated global-instructions file into `Settings > Cowork > Global instructions`. Re-export/re-upload after toolkit updates. |
 
 ---
@@ -13325,7 +14389,6 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_agents.py` (native custom-agent TOML), `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. Global install writes `~/.codex/AGENTS.md` (not `~/AGENTS.md`, which Codex never loads globally); plugin-pack rules are marker-injected into the same file. `project_doc_max_bytes` default is 32 KiB and Codex silently truncates AGENTS.md past that (see codex-cli-compatibility.md). |
 | Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 through an explicit Codex map, including destructive-command and wrong-home path guards on both Bash `PreToolUse` and `PermissionRequest`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
-| Tool-output replacement | Manual `ai-toolkit output-filter inspect` only. The Claude-specific `updatedToolOutput` adapter is not emitted into Codex hooks. |
 | Tracked handler types | `command` (emitted by default; the only handler Codex actually runs). `prompt` and `agent` are parsed by Codex but NOT yet executed, so hand-authored handlers of those types are inert. |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path), `.codex/agents/*.toml` (native custom agents) |
 | Version probe | `codex --version` |
@@ -13340,7 +14403,6 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Config paths | `opencode.json`, `.opencode/agents/*.md`, `.opencode/commands/*.md`, `.opencode/plugins/*`, `.opencode/skills/*/SKILL.md` (v1.14+), `AGENTS.md`; skill fallback discovery: `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
 | Our generators | `scripts/generate_opencode.py`, `scripts/generate_opencode_agents.py`, `scripts/generate_opencode_commands.py`, `scripts/generate_opencode_json.py`, `scripts/generate_opencode_plugin.py` |
 | Hook isolation | Tool hooks preserve native `sessionID` as normalized `session_id`; exit code 2 from a blocking pre-tool guard is raised back to OpenCode instead of being ignored. |
-| Tool-output replacement | Manual `ai-toolkit output-filter inspect` only. No active OpenCode output adapter is shipped. |
 | Tracked plugin events | `session.created`, `session.compacted`, `session.deleted`, `message.updated`, `tool.execute.before`, `tool.execute.after`, `permission.asked`, `command.executed` |
 | Other capabilities | `opencode.json` config, primary + subagent modes, `@`-mention subagents, `/`-invocation commands, MCP (local + remote), plugin hooks in JS/TS, native `SKILL.md` discovery with Claude-compatible fallback, `permission.skill.*` matrix |
 | Version probe | `opencode --version` |
@@ -13478,299 +14540,6 @@ ai-toolkit sync --pull abc123def456   # Use gist ID from first push
 
 ---
 
-## kb/reference/tool-output-filter.md
-
----
-title: "Native Tool Output Filter"
-category: reference
-service: ai-toolkit
-tags: [output-filter, hooks, recovery, telemetry, claude-code]
-version: "1.0.0"
-created: "2026-07-23"
-last_updated: "2026-07-23"
-description: "Contract, configuration, safety boundaries, recovery, CLI, and runtime support for the native ai-toolkit output filter."
----
-
-# Native Tool Output Filter
-
-## Overview
-
-ai-toolkit includes an original, dependency-free filter for selected
-post-execution tool results. It is disabled by default and does not depend on,
-vendor, execute, or copy another output-filter package.
-
-The active adapter targets Claude Code because its `PostToolUse` contract can
-replace a native tool response through
-`hookSpecificOutput.updatedToolOutput`. The replacement object retains the
-native response shape and changes only `stdout`. See the
-[Claude Code hooks reference](https://code.claude.com/docs/en/hooks).
-
-The filter never changes the command, arguments, environment, working
-directory, permission decision, exit status, or signal. [PATH:
-scripts/tool_output_filter/hook_runtime.py] [PATH:
-scripts/tool_output_filter/engine.py]
-
-## Modes
-
-| Mode | Model-visible result | Recovery | Telemetry |
-|------|----------------------|----------|-----------|
-| `off` | Original | None | None |
-| `observe` | Original | No raw response | Content-free decision metadata |
-| `safe` | Replacement only after every gate passes | Exact native response saved first | Content-free decision metadata |
-
-`off` is a shell fast path, so the Python runtime is not started. Any runtime
-error, malformed payload, unsafe command, failed invariant, unavailable secure
-storage, or insufficient saving leaves the original response unchanged.
-
-Three consecutive profile, invariant, or recovery safety failures open a
-persistent session-scoped circuit breaker. One bounded Claude system message
-reports the bypass, then later results stay unchanged for that session.
-
-## Configuration
-
-Configure the project in `.softspark-toolkit.json`:
-
-```json
-{
-  "toolOutputFilter": {
-    "mode": "observe",
-    "profiles": ["repeat-lines", "tap-success"],
-    "maxInputBytes": 8388608,
-    "minSavingsBytes": 1024,
-    "minSavingsRatio": 0.15,
-    "recovery": {
-      "mode": "ephemeral",
-      "ttlMinutes": 60,
-      "maxSessionBytes": 33554432
-    }
-  }
-}
-```
-
-Run `ai-toolkit install --local` or `ai-toolkit update --local` to materialize
-the effective policy as:
-
-```text
-<project>/.claude/ai-toolkit-output-filter.json
-<project>/.claude/.ai-toolkit-output-filter.owner
-```
-
-The managed files use mode `0600`. The hook accepts a project policy only when
-the project root is registered in `~/.softspark/ai-toolkit/projects.json`
-**and** the regular owner marker matches ai-toolkit. Registration is the
-security boundary: the owner marker is a public constant, so requiring the
-registry stops a cloned or untrusted checkout from self-enabling filtering by
-committing its own marker. An unregistered project, a missing or foreign
-marker, or a symlinked project root or `.claude` directory falls back to the
-installed global policy at
-`~/.softspark/ai-toolkit/hooks/output-filter-policy.json`, which defaults to
-`off`. [PATH: app/hooks/filter-tool-output.sh] [PATH:
-scripts/install_steps/ai_tools.py]
-
-`jq` is a required system dependency for the lifecycle hooks and is verified
-by `python3 scripts/check_deps.py` alongside `python3`, `git`, and `node`.
-
-Before executing anything, the hook validates the resolved Python runtime path:
-it must be a readable regular file and must not be a symlink. A missing,
-non-regular, unreadable, or symlinked runtime makes the hook exit silently and
-leave the tool response unchanged, so a tampered or half-installed runtime
-cannot be invoked. The same regular-file rule applies to every policy file the
-hook reads. [PATH: app/hooks/filter-tool-output.sh]
-
-Set `AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1` for an immediate bypass without
-reinstalling. `AI_TOOLKIT_OUTPUT_FILTER_POLICY` may point the hook to an
-explicit regular policy file for controlled operational testing. The hook is
-also skipped by the `minimal` hook profile and may be listed in
-`AI_TOOLKIT_DISABLED_HOOKS`. `AI_TOOLKIT_OUTPUT_FILTER_HOOK_RUNTIME` is reserved
-for controlled runtime testing; the manual and cleanup CLI remains
-`output_filter_cli.py`.
-
-## Eligibility
-
-The Claude adapter considers only a completed `PostToolUse` event with:
-
-- tool name `Bash`;
-- a non-empty native session ID of at most 160 ASCII letters, digits,
-  underscores, or hyphens;
-- string `stdout`;
-- empty `stderr`;
-- `interrupted: false`;
-- `isImage: false`;
-- a command that matches a strict allowlist for test, lint, typecheck, or
-  validation tools;
-- input at or below 8 MiB;
-- valid text without binary or terminal-control content.
-
-The following always pass through unchanged:
-
-- failed, interrupted, image, binary, invalid-text, TTY, or streaming results;
-- pipes, redirects, shell chaining, substitutions, and multiline commands;
-- deployment, release, migration, publish, destroy, audit, and security-scanner
-  commands;
-- arbitrary Python scripts and unknown command shapes;
-- output with non-empty stderr;
-- unknown profiles or native payload shapes;
-- candidates that save less than both the configured byte and ratio threshold.
-
-The command classifier is eligibility logic only. It never parses and
-re-executes a command. [PATH: scripts/tool_output_filter/hook_runtime.py]
-
-## Profiles
-
-### `repeat-lines`
-
-Collapses only adjacent identical, non-diagnostic lines. It retains the first
-line and adds a versioned marker with the exact number of omitted copies.
-Warnings, failures, permissions, security diagnostics, blank lines, comments,
-existing filter markers, and control-bearing output are not collapsed.
-
-### `tap-success`
-
-Accepts only a strict, complete, successful TAP stream with a single plan and
-contiguous `ok` result numbers. It retains the TAP version, plan, directives,
-comments, totals, duration, and other summary lines. Diagnostics, `not ok`,
-non-zero failure summaries, malformed plans, gaps, duplicates, and unknown
-content reject the whole profile.
-
-Both profiles are deterministic and idempotent. A safe replacement must remain
-smaller after the recovery marker is added. [PATH:
-scripts/tool_output_filter/profiles/] [PATH:
-tests/test_tool_output_filter_properties.py]
-
-## Exact Recovery and Privacy
-
-Before `safe` mode emits a replacement, it stores and reloads the complete
-native tool-response object. Equality must succeed before the hook prints
-`updatedToolOutput`.
-
-```text
-~/.softspark/ai-toolkit/sessions/<repo-key>/
-└── output-filter/
-    └── <hashed-session>/
-        ├── <opaque-handle>.json
-        ├── .circuit-state.json
-        └── .telemetry.jsonl
-```
-
-Recovery directories use `0700`; response, state, and telemetry files use
-`0600`. Creation and cleanup use pinned directory descriptors, no-follow
-operations, atomic publication, opaque random handles, a per-session quota,
-and TTL cleanup. If this secure contract is unavailable, `safe` mode returns
-the original response.
-
-The replacement ends with a marker similar to:
-
-```text
-[ai-toolkit-output-filter repeat-lines/v1; original_lines=500; emitted_lines=3; recovery=<opaque-handle>]
-```
-
-The recovery file can contain everything returned by the tool, including
-secrets. Treat the session directory as sensitive. Telemetry never stores raw
-output, commands, paths, environment values, session IDs, or recovery handles.
-It contains only profile/version, input/output byte and line counts, latency,
-outcome, and a bounded fallback reason.
-
-Session end, explicit cleanup, and global uninstall remove only validated
-ai-toolkit-owned filter artifacts. Foreign files and directories are
-preserved. [PATH: scripts/tool_output_filter/recovery.py] [PATH:
-app/hooks/session-end.sh] [PATH: scripts/uninstall.py]
-
-## CLI
-
-Inspect candidate savings without changing output:
-
-```bash
-some-test-command | ai-toolkit output-filter inspect --profile repeat-lines
-some-tap-command | ai-toolkit output-filter inspect --profile tap-success
-```
-
-The JSON report contains counts, eligibility, outcome, and fallback reason. It
-does not echo stdin.
-
-Inspect the effective trusted project or global policy:
-
-```bash
-ai-toolkit output-filter status
-ai-toolkit output-filter status --policy /path/to/materialized-policy.json
-```
-
-Recover the exact native response object using the handle printed in a safe
-replacement:
-
-```bash
-ai-toolkit output-filter recover <opaque-handle>
-```
-
-The default lookup derives the current repository session directory. Advanced
-or test workflows can add `--base-directory PATH` or `--session-id ID`.
-
-Clean the ending session, expired exact responses, or all filter artifacts for
-the current repository:
-
-```bash
-ai-toolkit output-filter clean --session-id <native-session-id>
-ai-toolkit output-filter clean --session-id <native-session-id> --expired
-ai-toolkit output-filter clean
-```
-
-`--expired` requires `--session-id`. Cleanup prints only the removed artifact
-count and scope.
-
-## Runtime Capability Matrix
-
-| Runtime | Active result replacement | Capability |
-|---------|---------------------------|------------|
-| Claude Code | Yes, opt-in | Native `PostToolUse.updatedToolOutput` adapter |
-| Claude Chat / Cowork | No | Plugin export explicitly excludes the Claude Code-only hook |
-| Cursor | No | Manual `output-filter inspect` only |
-| Windsurf / Devin | No | Manual `output-filter inspect` only |
-| GitHub Copilot | No | Manual `output-filter inspect` only |
-| Gemini CLI | No | Manual `output-filter inspect` only |
-| Cline | No | Manual `output-filter inspect` only |
-| Roo Code | No | Manual `output-filter inspect` only |
-| Aider | No | Manual `output-filter inspect` only |
-| Augment | No | Manual `output-filter inspect` only |
-| Google Antigravity | No | Manual `output-filter inspect` only |
-| Codex CLI | No | Manual `output-filter inspect` only |
-| OpenCode | No | Manual `output-filter inspect` only |
-
-An editor hook, extra context message, or command wrapper is not treated as
-result replacement. A new adapter requires a verified native replacement
-contract and dedicated native payload tests.
-
-## Benchmark Semantics
-
-Run the deterministic offline corpus:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 python3 scripts/benchmark_output_filter.py
-```
-
-The benchmark measures profile p95 latency, production Bash-wrapper latency
-with a fresh Python process per sample in one native session, traced peak
-allocation, and eligible-output byte reduction. It uses 100 samples by default
-to avoid a one-sample p95 swing. The current gates are:
-
-- at least 30% candidate byte reduction;
-- at most 20 ms p95 for profile inputs up to 100 KiB;
-- at most 150 ms p95 for the 8 MiB profile case;
-- at most 75 ms p95 for a cold end-to-end hook process;
-- peak traced allocation no greater than three input sizes plus 16 MiB.
-
-Byte reduction is not billed-token savings and is not a whole-session cost
-claim. Measure actual model token receipts separately before changing the
-default mode. [PATH: scripts/benchmark_output_filter.py] [PATH:
-benchmarks/output-filter/]
-
-## Related
-
-- [Hooks Catalog](hooks-catalog.md)
-- [Supported Tools Registry](supported-tools-registry.md)
-- [Architecture Overview](architecture-overview.md)
-- [Output Token Discipline Plan](../history/completed/output-token-discipline-plan-20260504.md)
-
----
-
 ## kb/reference/unique-features.md
 
 ---