From 54978561f786a9e8eed5cf2637a235a415034957 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Sun, 25 Oct 2026 02:04:53 +0200 Subject: [PATCH] docs(setup): register the container-gateway hook per machine Since #1793 the gateway hook is registered by its absolute path, which differs between macOS (/Users/) and Linux (/home/). In a ~/.claude/settings.json synced across machines that path points at nothing on the next machine and the gateway never starts. The setup guide and install Step L now put the hook in ~/.claude/settings.local.json when the user settings are synced, with a "Fixing your other machines" passage (move the entries, then a jq one-liner per machine). Verify check 12a and the update skill flag a registered path that does not exist on the machine they run on, and a synced registration as drift. Generated-by: Claude (Opus 5.5) --- docs/setup/secure-agent-setup.md | 27 ++++++++++++++----- .../isolated-setup-install/optional-steps.md | 9 +++++-- .../skills/isolated-setup-update/SKILL.md | 5 +++- .../conditional-checks.md | 12 ++++++--- 4 files changed, 40 insertions(+), 13 deletions(-) diff --git a/docs/setup/secure-agent-setup.md b/docs/setup/secure-agent-setup.md index d9536b16a..eea722bd0 100644 --- a/docs/setup/secure-agent-setup.md +++ b/docs/setup/secure-agent-setup.md @@ -2864,7 +2864,7 @@ records which main checkout it confirmed the first time, under sandbox-writable; a later session that derives a different one is refused until you delete that record (the log line names it). -Wire it as a `SessionStart` / `SessionEnd` pair in `~/.claude/settings.json`, alongside any other hooks already there, **by its absolute path** (your real home, `/home/` on Linux). A `~` in a hook command is expanded from `$HOME` by the launching shell, and a session environment that redirects `$HOME` would run another script: +Wire it as a `SessionStart` / `SessionEnd` pair in your user settings, alongside any other hooks already there, **by its absolute path** (your real home, `/home/` on Linux). A `~` in a hook command is expanded from `$HOME` by the launching shell, and a session environment that redirects `$HOME` would run another script. Because that path is per-machine, it goes in `~/.claude/settings.local.json` when your `~/.claude/settings.json` is [synced across machines](#syncing-user-scope-config-across-machines) — a `/Users//...` path synced to a Linux box points at nothing, and the gateway never starts there; otherwise `~/.claude/settings.json` is fine. Claude Code merges hooks from both files: ```jsonc { @@ -2879,6 +2879,17 @@ Wire it as a `SessionStart` / `SessionEnd` pair in `~/.claude/settings.json`, al } ``` +**Fixing your other machines.** If the hook was registered in a synced `~/.claude/settings.json`, move it: delete the two `container-gateway-hook.sh` entries from the synced file (once, on any machine), then on **every** machine add them to its own `~/.claude/settings.local.json` with that machine's home: + +```bash +jq --arg h "$(cd ~ && pwd -P)" ' + .hooks.SessionStart += [{"hooks":[{"type":"command","command":($h+"/.claude/scripts/container-gateway-hook.sh start")}]}] + | .hooks.SessionEnd += [{"hooks":[{"type":"command","command":($h+"/.claude/scripts/container-gateway-hook.sh stop")}]}] +' ~/.claude/settings.local.json > ~/.claude/settings.local.json.new && mv ~/.claude/settings.local.json.new ~/.claude/settings.local.json +``` + +`setup-isolated-setup-verify` (check 12a) and `setup-isolated-setup-update` flag a hook whose registered path does not exist on the machine they run on. + Every setting that points something at a gateway socket needs that socket's **absolute** path, which is per-machine, so the whole project-settings block belongs in the gitignored `.claude/settings.local.json` — nothing is committed. Add it by hand, substituting your own project's absolute path for `` — nothing writes it for you. The gateway serves from the `run/` directory of the personal config layer: @@ -3214,6 +3225,8 @@ Three reasons make this non-negotiable: Public dotfile repos are fine for shell aliases and editor configs; they are the wrong shape for agent-runtime files. +**Per-machine entries stay out of the synced file.** Anything that names an absolute path under your home — the container gateway's `SessionStart` / `SessionEnd` hooks above, a pinned interpreter, socket paths — differs between macOS (`/Users/`) and Linux (`/home/`). Keep those in each machine's `~/.claude/settings.local.json`, which is never synced; Claude Code merges hooks and settings from both files. + ## Adopter setup If you are adopting the framework into your own tracker repo, copy @@ -3601,11 +3614,13 @@ below and report ✓ done / ✗ missing / ⚠ partial, with the evidence and the `gh tofile` alias workaround). 12. **Container gateway wired.** Only meaningful when `podman` or `docker` is on `PATH`; report n/a otherwise. Four things: - - User-scope `~/.claude/settings.json` has a `SessionStart` - hook running `container-gateway-hook.sh start` and a - `SessionEnd` hook running `container-gateway-hook.sh stop`, - and `~/.claude/scripts/container-gateway-hook.sh` exists and - is executable. + - User-scope `~/.claude/settings.json` or + `~/.claude/settings.local.json` has a `SessionStart` hook + running `container-gateway-hook.sh start` and a `SessionEnd` + hook running `container-gateway-hook.sh stop`, by an absolute + path that exists on this machine (✗ if it names another + machine's home), and `~/.claude/scripts/container-gateway-hook.sh` + exists and is executable. - The project `.claude/settings.json` or `.claude/settings.local.json` has `env.CONTAINER_HOST` and `env.DOCKER_HOST`, and both gateway sockets appear in diff --git a/plugins/magpie-setup/skills/isolated-setup-install/optional-steps.md b/plugins/magpie-setup/skills/isolated-setup-install/optional-steps.md index 65e801c73..3f73f1ab8 100644 --- a/plugins/magpie-setup/skills/isolated-setup-install/optional-steps.md +++ b/plugins/magpie-setup/skills/isolated-setup-install/optional-steps.md @@ -177,13 +177,18 @@ until you delete that record (the log line names it). **L.2 — Hooks.** Wire a `SessionStart` hook running `container-gateway-hook.sh start` and a `SessionEnd` hook running -`container-gateway-hook.sh stop` into `~/.claude/settings.json`, each +`container-gateway-hook.sh stop` into the user settings, each **by the script's absolute path** with the home directory written out (a `~` there is expanded from `$HOME`, which the session environment can redirect), executed directly rather than through `bash`/`sh` (its `#!/bin/bash -p` shebang keeps `BASH_ENV` and exported functions out) — merging into existing arrays with a diff the operator approves, -exactly as for K.2's touch-overlay hooks. +exactly as for K.2's touch-overlay hooks. The file is +`~/.claude/settings.local.json` when `~/.claude/settings.json` is a link +into a synced config repo (the absolute path differs per machine; +macOS `/Users/`, Linux `/home/`), and `~/.claude/settings.json` +otherwise. If a synced file already carries the two entries, propose moving +them, per the setup guide's "Fixing your other machines". **L.3 — Project wiring.** Propose the `env` block (`CONTAINER_HOST` / `DOCKER_HOST`) and the `allowUnixSockets` pair diff --git a/plugins/magpie-setup/skills/isolated-setup-update/SKILL.md b/plugins/magpie-setup/skills/isolated-setup-update/SKILL.md index 4c8c53611..b183aa423 100644 --- a/plugins/magpie-setup/skills/isolated-setup-update/SKILL.md +++ b/plugins/magpie-setup/skills/isolated-setup-update/SKILL.md @@ -18,7 +18,7 @@ when_to_use: >- capability: capability:platform surface_hash: sha256:1f327e069312dad2 license: Apache-2.0 -measured_tokens: 6557 +measured_tokens: 6705 ---