From 698ef2c9acf1d042ccd8fa40ee1184464b8726f5 Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <jarek@potiuk.com>
Date: Wed, 29 Apr 2026 15:42:30 +0200
Subject: [PATCH] docs(secure-agent-setup): add Linux Mint 22 / Ubuntu Noble
 shortcut
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pinned bubblewrap (0.11.1) and socat (1.8.1.1) versions in
`tools/agent-isolation/pinned-versions.toml` are the upstream
releases that have aged past the framework's 7-day cooldown — they
are NOT in Ubuntu Noble's main repos. Noble ships:

  bubblewrap 0.9.0  (0.9.0-1ubuntu0.1)
  socat      1.8.0.0 (1.8.0.0-4build3)

Both pre-date the framework's pins by months and are well past the
cooldown, so they're a legitimate adopter choice on Mint 22.
Ubuntu 24.04 — but the framework's main install path documents the
upstream pins, which leaves Mint/Noble adopters without a cl
story.

This commit adds a *Distro-specific shortcut* section under
\`Install commands\` that:

- Documents the apt-shipped versions and their \`apt_pin\` s
- Calls out the trade-off explicitly (older feature set, but apt-
  managed security backports, no source build).
- Notes that the framework's \`.claude/settings.json\` works
  unchanged — the sandbox API has been stable since bubblewr
  0.6.x.
- Tells the user how to silence the drift the check script w
  report against the upstream pins (a \`pinned-versions.local.toml\`,
  matching Claude Code's own \`settings.local.json\` convent
- Closes with the rationale for keeping this as a "shortcut" rather
  than the canonical path.

No change to \`pinned-versions.toml\` itself — the framework
default pin still tracks the upstream release stream, which is the
right thing to track for the weekly check-tool-updates routi

Generated-by: Claude Code (Claude Opus 4.7)
---
 secure-agent-setup.md | 47 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/secure-agent-setup.md b/secure-agent-setup.md
index e6f8db75..4a8ed001 100644
--- a/secure-agent-setup.md
+++ b/secure-agent-setup.md
@@ -136,6 +136,53 @@ version, no pin enforced — Homebrew rolls forward, so the
 npm install -g --no-save @anthropic-ai/claude-code@2.1.117
 ```
 
+### Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble
+
+The pinned versions above (bubblewrap `0.11.1`, socat `1.8.1.1`) are
+the *upstream* releases that have aged past the framework's 7-day
+cooldown. **They are not in Ubuntu Noble's main repos** — Noble
+ships `bubblewrap 0.9.0` (`0.9.0-1ubuntu0.1`) and
+`socat 1.8.0.0` (`1.8.0.0-4build3`).
+
+Both Noble-shipped versions pre-date the framework's pins by months
+and are well past the 7-day cooldown, so they're a legitimate
+adopter choice on Mint 22.x / Ubuntu 24.04. The trade-off is the
+usual LTS one: older feature set, but no source build required,
+and security backports flow through Ubuntu's standard update
+channel.
+
+If you accept the trade-off, install via apt:
+
+```bash
+sudo apt-get update
+sudo apt-get install --no-install-recommends \
+    bubblewrap=0.9.0-1ubuntu0.1 \
+    socat=1.8.0.0-4build3
+```
+
+The framework's `.claude/settings.json` works unchanged — the
+sandbox flags don't depend on a specific bubblewrap version (the
+`denyRead`/`allowRead` API has been stable since `0.6.x`).
+
+The framework's `tools/agent-isolation/check-tool-updates.sh` will
+still report upstream `0.11.1` / `1.8.1.1` as the pinned versions —
+that's the manifest's view of what's *upstream-current*, not what
+your distro shipped. If you want to silence the drift, override the
+manifest locally with a `pinned-versions.local.toml` (gitignored)
+declaring the Noble versions; the script's manifest-precedence
+follows the same `*.local` convention as Claude Code's
+`settings.local.json`.
+
+> **Why this is documented as a separate "shortcut" rather than
+> the canonical path.** The framework's default pin tracks the
+> upstream release stream, not any specific distro. Adopters on
+> distros that ship recent versions (Arch, Fedora rolling, NixOS
+> on `nixos-unstable`) can install the upstream-pinned versions
+> directly from their package manager. Adopters on LTS distros
+> like Mint / Ubuntu Noble use this shortcut. The two paths
+> converge — once Noble's next LTS adopts a newer bubblewrap, this
+> section retires.
+
 ### Bumping a pinned version
 
 When an upstream release has aged past the 7-day cooldown and you