@softspark/ai-toolkit 4.17.0 → 4.18.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.18.0 — rtk-pack, an opt-in command rewriter (2026-07-26)
+
+### Added
+
+- **`rtk-pack`**, an opt-in plugin pack that rewrites Bash commands at
+  `PreToolUse` via [rtk](https://github.com/rtk-ai/rtk) (Apache-2.0). Nothing
+  installs it for you. `ai-toolkit plugin install rtk-pack` fetches a
+  platform-specific binary from an ai-toolkit GitHub Release and verifies its
+  SHA-256 before installing anything; a mismatch aborts and leaves nothing
+  behind. Read `app/plugins/rtk-pack/README.md` before enabling it: the rewrite
+  means what runs is not literally what the model asked for, and rtk applies
+  your permission verdict for the original command to the rewritten one.
+- **`.github/workflows/rtk-build.yml`**, a manual-dispatch pipeline that
+  cross-builds rtk from upstream source for five targets with the compile-time
+  telemetry endpoint left undefined, proves each artifact starts, writes no
+  telemetry state and (on Linux) behaves identically with no network route,
+  then publishes checksummed artifacts with LICENSE and NOTICE.
+- **`scripts/verify_rtk_binary.py`**, the silence verifier that pipeline uses.
+  A target it cannot start reports `inconclusive`, never `pass`.
+- **`kb/procedures/rtk-upstream-sync-sop.md`**, the procedure for moving to a
+  newer upstream tag, including a re-measure gate and a published kill number.
+- Plugin packs can now ship `scripts/status.py` and have `plugin status` pick it
+  up. This replaces a hardcoded `if name == "memory-pack"` branch, so any pack
+  can report its own health.
+
+### Changed
+
+- **`ai-toolkit update` now updates installed plugin packs.** It reads
+  `plugins.json` and runs the equivalent of `plugin update --all` for every
+  installed pack. `--local` leaves packs alone, since they are global.
+- **`plugin update` is version-aware.** `plugins.json` records the pack version
+  installed per editor, and an update whose manifest version matches is a silent
+  no-op. Previously every update removed and reinstalled unconditionally, which
+  for a pack that downloads a binary meant refetching it every time. `--force`
+  overrides; `--dry-run` reports without acting. State written before versions
+  were tracked updates each pack exactly once.
+- Plugin packs are now covered by `audit_skills.py --ci` and by the ShellCheck
+  gate in CI. Both previously scanned only `app/skills`, `app/agents` and
+  `app/hooks`, exempting the highest-risk code in the repo.
+- A pack's install-time script may be named `init.py`; `init_db.py` still works.
+  Previously only the latter ran, so a pack using any other name installed
+  successfully while doing nothing.
+
+### Fixed
+
+- `plugin install` no longer aborts with `IsADirectoryError` when a pack ships a
+  subdirectory under `scripts/`.
+- A failing pack init script now always reports, instead of printing nothing
+  when it exited non-zero with empty stderr.
+
+---
+
 ## v4.17.0 — Native tool-output filter removed (2026-07-26)
 
 ### Removed

package/README.md

@@ -6,17 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1445%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1484%20passing-success)](tests/)
 
-## What's New in v4.17.0
+## What's New in v4.18.0
 
-v4.17.0 removes the native tool-output filter shipped in v4.16.0.
+v4.18.0 adds `rtk-pack`, an opt-in command rewriter, and makes `ai-toolkit update` maintain installed packs.
 
-- **Native tool-output filter removed**: measured whole-session token saving was 0.0000% on real traffic, because agent-issued commands are overwhelmingly compound and the filter only accepted simple registered shapes. The `PostToolUse` hook, the CLI, and the `toolOutputFilter` config key are gone.
-- **Automatic cleanup on update**: `ai-toolkit update` removes the orphaned hook script, the global and project policy files, and any stored recovery artifacts left by v4.16.x. Foreign files in those directories are preserved.
-- **Stricter config validation**: unknown top-level config keys are rejected, plugin manifests must declare `requires`, and lock files go stale on toolkit version bumps.
-- **GitHub Copilot compatibility reference**: new `kb/reference/copilot-compatibility.md` documenting the Copilot integration surface.
-- **Copilot remnant recovery**: asset-only `.github/skills/ai-toolkit-*` leftovers from older cleanups are rebuilt in place instead of aborting `install --local` / `update`.
+- **`rtk-pack`, opt-in only**: rewrites Bash commands at `PreToolUse` via [rtk](https://github.com/rtk-ai/rtk) (Apache-2.0). Nothing installs it for you. `plugin install` fetches a platform binary from an ai-toolkit Release and verifies its SHA-256 before installing anything. Measured saving on the reference workload is 0.0615% of input tokens; the pack README states the trust boundary and the numbers up front.
+- **Binaries built from source, telemetry compiled out**: a manual-dispatch workflow cross-builds five targets with the compile-time telemetry endpoint undefined, proves each artifact starts, writes no telemetry state, and on Linux behaves identically with no network route.
+- **`ai-toolkit update` maintains installed packs**: it now runs the equivalent of `plugin update --all`. Updates are version-aware, so a pack whose manifest has not moved is a silent no-op instead of a remove-and-reinstall.
+- **Packs can report their own health**: `plugin status` picks up a pack's `scripts/status.py`, replacing a hardcoded per-pack branch.
+- **Security gates cover packs**: `audit_skills.py --ci` and the ShellCheck gate now scan `app/plugins/`, which they previously skipped.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -143,7 +143,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `skills/` (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
-| `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
+| `plugins/` | 12 packs | Opt-in domain bundles (security, research, frontend, enterprise, memory, rtk, 6 language packs) |
 | `constitution.md` | 7 articles | Machine-enforced safety rules |
 | `rules/` | auto-synced | Global/project rule files for Claude and other editors |
 | `kb/` | reference docs | Architecture, procedures, and best practices |
@@ -166,7 +166,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats and Python test suite (1445 tests)
+├── tests/               # Bats and Python test suite (1484 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.17.0",
+  "version": "4.18.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/plugins/README.md

@@ -17,10 +17,22 @@ Plugin packs can target:
 These packs are not directly uploadable Claude app plugins. For Claude Chat,
 Desktop, and Cowork use `ai-toolkit claude-app export`.
 
-Current packs:
-- `security-pack`
-- `research-pack`
-- `frontend-pack`
+Current packs (12):
+- `csharp-pack`
 - `enterprise-pack`
+- `frontend-pack`
+- `java-pack`
+- `kotlin-pack`
+- `memory-pack`
+- `research-pack`
+- `rtk-pack`
+- `ruby-pack`
+- `rust-pack`
+- `security-pack`
+- `swift-pack`
+
+`rtk-pack` is the only one that fetches a native binary at install time and the
+only one that rewrites commands before they run. Read its README before
+installing it.
 
 See `kb/reference/plugin-pack-conventions.md` for pack rules, validation, and adoption guidance.

package/app/plugins/rtk-pack/README.md

@@ -0,0 +1,123 @@
+# rtk-pack
+
+Opt-in command rewriting via [rtk](https://github.com/rtk-ai/rtk), Apache-2.0.
+
+Install: `ai-toolkit plugin install rtk-pack`. Remove: `ai-toolkit plugin remove rtk-pack`.
+Nothing installs it for you, and nothing in the core depends on it.
+
+## Read this before installing
+
+**This pack rewrites your commands before they run.** A `PreToolUse` hook hands
+each command to `rtk`, which may replace it with an `rtk` equivalent that
+produces shorter output. What executes is therefore not literally what the model
+asked for.
+
+That is a real trade-off and the reason this ships as an opt-in pack rather than
+a core feature. ai-toolkit's own retired output filter explicitly refused to do
+this. Adopting rtk is a deliberate reversal, made with the mechanism understood
+rather than assumed.
+
+**Your permission rules are evaluated against the original command, and the
+verdict is applied to the rewritten one.** rtk checks what the model asked for
+against your `settings.json`, and if a rule allows it, emits
+`permissionDecision: allow` for the `rtk …` form it substituted. So an allowlist
+entry for `git status` transitively authorises `rtk git status`, a command you
+never wrote a rule for. With no matching allow rule, no decision is emitted and
+your normal prompt appears. Verified against upstream's own test at
+`src/hooks/hook_cmd.rs:1272-1283`.
+
+If your allowlist is broad, review it before installing. If it is narrow, expect
+prompts on commands that used to run without one.
+
+Every failure path degrades to passthrough: no binary, a non-zero exit, a
+timeout, or unparseable output all result in the original command running
+unchanged. Removing the pack strips the hook from `settings.json`.
+
+## What you get, measured
+
+On the reference workload (1224 local transcripts, 26.6 MB of successful Bash
+output) rtk addresses **35.2%** of Bash bytes, which is **8.8%** of all
+tool-result bytes. The projected saving is **0.12% to 0.16%** of session input
+tokens, or 0.24% to 0.36% if rtk's own 60-90% claim holds on your traffic.
+
+That is small, and it is stated up front on purpose. The arithmetic ceiling for
+any tool-output mechanism on that workload is 4.5%, because tool results are
+that share of input token volume, and `Read` results are 63% of them. If your
+work is dominated by `cargo test`, `mvn` or `jest` output rather than file
+reading, rtk is calibrated for you and will do better. Measure before believing
+either number.
+
+Full method and caveats: `kb/history/completed/rtk-pack-integration-20260726.md`.
+
+## The binary
+
+Not bundled. `plugin install` fetches the artifact for your platform from an
+ai-toolkit GitHub Release and verifies its SHA-256 against `plugin.json` before
+installing anything. A digest mismatch aborts and leaves nothing behind. This is
+the only moment the pack uses the network.
+
+Binaries are cross-built from upstream source in ai-toolkit CI with
+`RTK_TELEMETRY_URL` and `RTK_TELEMETRY_TOKEN` left undefined, so the
+compile-time telemetry endpoint is absent and cannot be supplied at runtime.
+Each build asserts that, runs the artifact, checks no telemetry state is
+written, and on Linux confirms behaviour is unchanged with no network route.
+
+| Platform | Artifact |
+|---|---|
+| macOS arm64 | `rtk-aarch64-apple-darwin.tar.gz` |
+| macOS x86_64 | `rtk-x86_64-apple-darwin.tar.gz` |
+| Linux x86_64 | `rtk-x86_64-unknown-linux-musl.tar.gz` (static, runs on glibc) |
+| Linux aarch64 | `rtk-aarch64-unknown-linux-gnu.tar.gz` |
+| Windows x86_64 | `rtk-x86_64-pc-windows-msvc.zip` |
+
+## One thing the binary does reach the network for
+
+`rtk cc` (Claude economics) shells out to `npx --yes ccusage` when `ccusage` is
+not already on `PATH`, which fetches and executes a third-party npm package.
+That is not telemetry and never happens automatically, but it is outbound
+network from a binary otherwise described as silent. Do not run `rtk cc` in an
+air-gapped or policy-restricted environment.
+
+Related: `rtk telemetry forget` on these builds prints a failure telling you to
+email upstream to complete erasure. Nothing was ever sent; the message is
+upstream's and does not apply here.
+
+## Layout
+
+```
+~/.softspark/ai-toolkit/
+├── hooks/plugin-rtk-pack-rewrite.sh     # the PreToolUse hook
+└── plugin-scripts/rtk-pack/
+    ├── bin/rtk                          # verified binary
+    └── version.json                     # pinned versions and recorded digest
+```
+
+## Installing from a mirror
+
+Set `RTK_PACK_RELEASE_BASE_URL` to a base URL holding the release assets and the
+install fetches from there instead of GitHub, for networks that cannot reach it
+directly:
+
+```bash
+RTK_PACK_RELEASE_BASE_URL=https://mirror.internal/rtk/v0.44.0-1 \
+  ai-toolkit plugin install rtk-pack
+```
+
+The digest check is unchanged. A mirror serving different bytes is rejected
+exactly like a corrupt download, so this widens where the artifact comes from
+without widening what is accepted.
+
+## Disabling without removing
+
+`rtk` honours `RTK_DISABLED=1` as a per-command prefix. To turn the pack off
+entirely, remove it: `ai-toolkit plugin remove rtk-pack`.
+
+## Licence
+
+rtk is Apache-2.0. `LICENSE` and `NOTICE` ship with every release artifact. The
+NOTICE records the two build-time differences from an upstream build: the
+undefined telemetry endpoint, and in-range lockfile security updates for
+`anyhow` and `crossbeam-epoch`. No upstream source is modified.
+
+Upstream `DISCLAIMER.md` is deliberately not redistributed: it states that
+telemetry is collected by default, which is not true of these builds.

package/app/plugins/rtk-pack/hooks/rewrite.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# rewrite.sh — delegate PreToolUse command rewriting to the rtk binary.
+#
+# Fires on: PreToolUse
+# Reads the Claude Code hook JSON from stdin and hands it to `rtk hook claude`,
+# which emits hookSpecificOutput with permissionDecision and updatedInput.
+#
+# This hook rewrites the command before it runs, so what executes is not
+# literally what the model asked for. That is the pack's stated trade-off; see
+# the pack README. Everything here is built so that any failure degrades to
+# passthrough rather than to a broken or altered command:
+#
+#   no binary        -> no output, exit 0 (command runs unchanged)
+#   rtk fails        -> no output, exit 0
+#   rtk times out    -> no output, exit 0
+#   rtk prints junk  -> no output, exit 0
+#
+# Emitting nothing is the safe default: Claude Code treats an empty hook
+# response as "no opinion" and runs the original command.
+
+set -u
+
+PACK_BIN_DIR="${HOME}/.softspark/ai-toolkit/plugin-scripts/rtk-pack/bin"
+TIMEOUT_SECONDS=5
+
+# Read stdin once; it is not replayable.
+INPUT=$(cat)
+[ -n "$INPUT" ] || exit 0
+
+# jq is needed both to gate on the tool name and to check rtk's reply. Without
+# it we cannot do either safely, so stay out of the way entirely.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# A pack hook cannot declare its own matcher: plugin.py:408 looks the basename
+# up in core app/hooks.json and falls back to "", so this registers against
+# every tool rather than Bash alone. Gate here instead, otherwise every Read,
+# Edit and Grep would spawn a subprocess for nothing.
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" = "Bash" ] || exit 0
+
+RTK=""
+for candidate in "${PACK_BIN_DIR}/rtk" "${PACK_BIN_DIR}/rtk.exe"; do
+    if [ -x "$candidate" ]; then
+        RTK="$candidate"
+        break
+    fi
+done
+
+# Inert when init.py could not install a binary. The pack stays wired so that a
+# later `ai-toolkit plugin install rtk-pack` fixes it without touching settings.
+[ -n "$RTK" ] || exit 0
+
+# GNU timeout is `timeout`, Homebrew coreutils installs it as `gtimeout`, and
+# on a bare macOS it is absent. A hung rewriter would hang the session, so use
+# it when we can and accept the risk when we cannot.
+TIMEOUT_CMD=""
+if command -v timeout >/dev/null 2>&1; then
+    TIMEOUT_CMD="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then
+    TIMEOUT_CMD="gtimeout"
+fi
+
+if [ -n "$TIMEOUT_CMD" ]; then
+    OUTPUT=$(printf '%s' "$INPUT" | "$TIMEOUT_CMD" "$TIMEOUT_SECONDS" "$RTK" hook claude 2>/dev/null)
+else
+    OUTPUT=$(printf '%s' "$INPUT" | "$RTK" hook claude 2>/dev/null)
+fi
+STATUS=$?
+
+[ "$STATUS" -eq 0 ] || exit 0
+[ -n "$OUTPUT" ] || exit 0
+
+# Only forward something that parses as JSON. A partial write or a stray
+# diagnostic on stdout would otherwise reach Claude Code as a malformed hook
+# response.
+printf '%s' "$OUTPUT" | jq -e . >/dev/null 2>&1 || exit 0
+
+printf '%s\n' "$OUTPUT"
+exit 0

package/app/plugins/rtk-pack/plugin.json

@@ -0,0 +1,60 @@
+{
+  "name": "rtk-pack",
+  "description": "Opt-in command rewriting via rtk, cross-built from source with telemetry disabled and fetched from a checksum-pinned release",
+  "version": "0.1.0",
+  "domain": "token-reduction",
+  "type": "plugin-pack",
+  "status": "experimental",
+  "requires": {
+    "ai-toolkit": ">=4.17.0",
+    "claude-code": ">=1.0.33"
+  },
+  "includes": {
+    "agents": [],
+    "skills": [],
+    "rules": [],
+    "hooks": ["rewrite.sh"]
+  },
+  "hook_events": {
+    "rewrite.sh": "PreToolUse"
+  },
+  "upstream": {
+    "project": "rtk",
+    "repository": "https://github.com/rtk-ai/rtk",
+    "license": "Apache-2.0",
+    "version": "v0.44.0",
+    "note": "Built from source in our CI with RTK_TELEMETRY_URL and RTK_TELEMETRY_TOKEN undefined. Cargo.lock carries in-range security updates for anyhow and crossbeam-epoch. No source modifications."
+  },
+  "binary": {
+    "release_repo": "softspark/ai-toolkit",
+    "release_tag": "softspark-rtk-v0.44.0-1",
+    "install_name": "rtk",
+    "assets": {
+      "darwin-arm64": {
+        "file": "rtk-aarch64-apple-darwin.tar.gz",
+        "sha256": "a69b8ccb7c516a1d6e06aff714bdc8bf0afcb2af240c5b2f6c83122743c93c56",
+        "member": "rtk"
+      },
+      "darwin-x86_64": {
+        "file": "rtk-x86_64-apple-darwin.tar.gz",
+        "sha256": "bda9f4a6acf87be859394d5da3a064db211a869cf331ed2c485e174f5fd81dcb",
+        "member": "rtk"
+      },
+      "linux-aarch64": {
+        "file": "rtk-aarch64-unknown-linux-gnu.tar.gz",
+        "sha256": "fd5f4b10ca2e96e674b437f9a00639f376b215e7d15373327142f5f8e9642795",
+        "member": "rtk"
+      },
+      "linux-x86_64": {
+        "file": "rtk-x86_64-unknown-linux-musl.tar.gz",
+        "sha256": "1d886b748181b78e11ea99c2f2ff60ad04a73dbc29ca20ca807f01642ebcea32",
+        "member": "rtk"
+      },
+      "windows-x86_64": {
+        "file": "rtk-x86_64-pc-windows-msvc.zip",
+        "sha256": "83ebf53af4f15d860cef16e8ff6fe9a5cf25fa10ed4c48a1544d359a2796ef38",
+        "member": "rtk.exe"
+      }
+    }
+  }
+}

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())