isolated-setup-install

<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files): <project-config> → per file: the personal layer, else `.apache-magpie-overrides/` <tracker> → value of `tracker_repo:` in <project-config>/project.md <upstream> → value of `upstream_repo:` in <project-config>/project.md --> # setup-isolated-setup-install ## Runtime routing (run before the Claude-specific procedure) Use the operator's explicitly requested runtime when supplied; otherwise use the active session's runtime. An installed executable or configuration directory alone does not select a runtime. For the routing below, treat that selection as the active harness. Determine the active harness from the session metadata and executable. When it is Codex, Antigravity, Pi, Goose or Copilot CLI, follow that harness's paragraph in [`runtime-routing.md`](runtime-routing.md). When the harness is Claude Code, continue below. If the harness cannot be determined from the session or executable, stop and report that; never guess and never prompt. This skill is the **on-ramp** for adopters who do not yet have the secure setup running. It is a thin walkthrough wrapper around the canonical install path documented in [`docs/setup/secure-agent-setup.md`](../../../../docs/setup/secure-agent-setup.md). The authoritative content lives there; this skill exists so an adopter can say *"set up the secure agent setup"* in a fresh session and land in the right step-by-step flow without first reading the document. ## Adopter overrides <!-- BEGIN MAGPIE BLOCK: adopter-overrides — generated from tools/dev/blocks/adopter-overrides.md --> Before running its default behaviour, this skill consults `setup-isolated-setup-install.md` in the personal layer (`.apache-magpie-local/` when the project adopted Magpie, falling back to the main checkout's in a linked worktree, or `<git-common-dir>/apache-magpie/` when Magpie is only installed; applied first, wins on conflict) and [`.apache-magpie-overrides/setup-isolated-setup-install.md`](../../../../docs/setup/agentic-overrides.md) (committed, project-wide) in the adopter repo, if present, and applies any agent-readable overrides it finds. See [`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md) for the contract. **Hard rule**: agents NEVER modify the snapshot under `<adopter-repo>/.apache-magpie/`. Local modifications go in the override file; framework changes go via PR to `apache/magpie`. <!-- END MAGPIE BLOCK: adopter-overrides --> --- ## Snapshot drift Also at the top of every run, this skill compares the gitignored `.apache-magpie.local.lock` (per-machine fetch) against the committed `.apache-magpie.lock` (the project pin). On mismatch the skill surfaces the gap and proposes [`setup update`](../setup/update.md). The proposal is non-blocking — the user may defer if they want to run with the local snapshot for now. See [`docs/setup/install-recipes.md` § Subsequent runs and drift detection](../../../../docs/quick-start/other-install-methods.md#subsequent-runs-and-drift-detection) for the full flow. Drift severity: - **method or URL differ** → ✗ full re-install needed. - **ref differs** (project bumped tag, or `git-branch` local is behind upstream tip) → ⚠ sync needed. - **`svn-zip` SHA-512 mismatches the committed anchor** → ✗ security-flagged; investigate before upgrading. --- ## Golden rules - **Do not auto-run privilege-elevating commands.** Anything that needs `sudo` (apt / dnf installs, system-wide writes) is *printed* for the user to copy-paste into their own terminal. The skill never invokes `sudo` itself. - **Do not edit shell rc files without approval.** `~/.bashrc` / `~/.zshrc` modifications (sourcing `agent-iso.sh`, the optional `alias claude='claude-iso'`) are surfaced as the exact line to add; the user pastes it themselves. The skill confirms the rc file path with the user first; it does not assume. - **Do not overwrite an existing settings file silently.** If the user already has a project `.claude/settings.json` or a user-scope `~/.claude/settings.json`, the skill *diffs* the desired merge against the existing file and asks for explicit approval before writing. The merge carries the framework's `permissions.allow` set (the read-only reads: `gh` reads, the vetted-ops read dispatcher, archive / mailbox / roster MCP reads, registry `WebFetch` hosts) alongside `deny` and `ask` — leaving it out makes every skill read prompt. Only read-only entries belong in `allow`. Re-installs / partial-state recoveries are common — the skill must not blow away an unrelated pre-existing hook or `permissions.ask` rule. The desired merge **includes the agent-guard `hooks.PreToolUse` entry** (matcher `Bash`, command running the user-scope `~/.claude/scripts/agent-guard.py`) — the deterministic guard from [`tools/agent-guard`](../../../../tools/agent-guard/README.md). Install the script as `~/.claude/scripts/agent-guard.py` and populate `~/.claude/scripts/guards.d/` from both the engine's bundled `guards.d/*.py` and every skill-owned `skills/*/guards/*.py` (so skill-owned guards like `mention` / `mark-ready` are active), alongside the other user-scope scripts (Step P); wire the `PreToolUse` entry once, and preserve any pre-existing `hooks` entries. - **Stop on the first failure.** If a step fails (manifest read fails, framework path wrong, an existing file conflicts in a way the user has not yet decided about), stop and report. Do not push past a failure to the next step. ## Up-front confirmations Before walking any install step, confirm with the user: 1. **OS / distro.** macOS, Ubuntu / Debian (apt), Fedora / RHEL (dnf), or Arch / NixOS / other. macOS skips bubblewrap + socat (Seatbelt is built-in); Linux installs both per the distro shortcut. 2. **Framework checkout path.** The path to the user's local `magpie` clone. Required to read `tools/agent-isolation/pinned-versions.toml`, `.claude/settings.json`, and the `tools/agent-isolation/*.sh` scripts. If the user does not have a clone, walk them through `git clone` first. 3. **Fresh install or re-install.** For a re-install on a partial existing state, the skill must enumerate the existing wiring (project settings.json, user settings.json, hooks dir, the agent-guard `hooks.PreToolUse` entry + `~/.claude/scripts/agent-guard.py`, shell rc) before any merge so the user knows what is being preserved vs replaced. 4. **Sync repo (optional).** Whether the user maintains a private dotfile-style `~/.claude-config` repo per [Syncing user-scope config across machines](../../../../docs/setup/secure-agent-setup.md#syncing-user-scope-config-across-machines). If yes, the skill installs user-scope scripts as **symlinks** into `~/.claude-config/scripts/` rather than `cp`-ing into `~/.claude/scripts/` — the symlink approach is what makes sync push the upgrades to other machines automatically. **Except `container-gateway-hook.sh`**, which is always a plain copy owned by the user: the managed-settings dispatcher that runs it refuses a symlink, whose target could be swapped after the checks. A symlink already in its place is replaced by a copy (`rm` the link first — a `cp` onto it would write through it into the sync repo), and `setup-isolated-setup-update` reports the copy when it drifts from the framework's. ## Walk-through Follow the canonical step list at [docs/setup/secure-agent-setup.md → Adopter setup → Via a Claude Code prompt](../../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt). Each step in that list maps 1:1 to a step in this skill. Do not re-write the list here — read the doc, follow it, and surface each sub-step with the user. The doc names are the source of truth; the skill is the runner. For the verification step at the end, hand off to the `setup-isolated-setup-verify` skill rather than re-walking the checklist inline. ### Agent harness — install `@latest`, enforce the floor `claude-code` is **not** pinned to an exact version. Install it with `npm install -g --no-save @anthropic-ai/claude-code@latest` (the command in the doc's install list) — latest always carries the newest permission-rule / sandbox / prompt-injection fixes. The manifest's `[tools.claude-code]` table in [`pinned-versions.toml`](../../../../tools/agent-isolation/pinned-versions.toml) declares a `min_version` **floor**, not a pin. Because this install is driven from Claude Code, apply the same hard gate `setup-isolated-setup-verify` check 5 applies: read the running version (`command claude --version`, which skips an `alias claude=claude-iso`) and, if it is **below** `min_version`, **hard-fail** — stop the install, tell the operator to upgrade to `@latest`, and have them re-run. The secure setup must not be stood up on a below-floor runtime. ### Step P — Project-root coverage in the sandbox allowlists The harness drops the literal `.` when it pre-resolves `sandbox.filesystem.allowRead: ["."]`, so a session in a fresh clone can write to the project root but not read from it. The fix is to add the root as an absolute path to the project-local `settings.local.json`. This step asks one question first — per-project or whole-user scope — and the whole-user answer overrides git's hook lookup for every repository on the machine, so it carries a disclosure the operator has to acknowledge. **Full procedure, both scopes and both whole-user flavours:** [`step-p-sandbox-allowlists.md`](step-p-sandbox-allowlists.md). ### Step V — The vetted-ops split and exclusion Only applies when the adopter routes forge operations through the `vetted-ops` dispatcher — i.e. the repo has `.apache-magpie-overrides/tools/vetted-ops/config.toml`, the maintainer keeps a personal one (`<personal layer>/tools/vetted-ops/config.toml`, for a project that has not adopted Magpie), or the operator asks for the dispatcher to be wired now. If neither is true, skip this step, report it as **n/a**, and continue with the next step: a missing policy is never a blocker for this install. Do not create a policy the project has not asked for. **Only with the sandbox on.** The allow rules and sandbox exclusions below are a permission bypass: they let the dispatcher run without a prompt, and outside the sandbox. They are safe only because the sandbox confines everything else. If the sandbox is not enabled for this session (Step P declined, or `sandbox.enabled` is not `true` in the scope being wired), skip this step, say so, and leave every vetted operation behind its normal prompt. **Full procedure, including Step V.1 (read-only vetted ops never prompt):** [`step-v-vetted-ops.md`](step-v-vetted-ops.md). ### Step R — The adversarial-review exclusion Only applies when the `magpie-adversarial-review` plugin is installed. If it is not, skip this step and say so. **Full procedure:** [`step-r-adversarial-review.md`](step-r-adversarial-review.md). ### Step W — Working directories for the read block Where the vetted-ops dispatcher is used, Step V.1 already requires `permissions.blockReadsOutsideWorkingDirectories` to be off, and these entries cannot stand in for that: they do not stop the `vetted-op-read` prompt. They remain useful for the agent's own reads of the scratch root where the block is on for other reasons. Nothing extra to write: the `sandbox-add-project-root.sh` run in Step P also adds `/tmp/claude-<uid>`, resolved, to `permissions.additionalDirectories` of each worktree's project-local `settings.local.json`. Under `permissions.blockReadsOutsideWorkingDirectories` the skills read it on every run; without the entry each read prompts, and a bulk sync multiplies that by its gatherer agents. The script also removes `$HOME/.claude/magpie` where an earlier version added it. After Step P, show the operator the resulting `additionalDirectories` list and check three things: - **Never `~/.claude/magpie`.** If any scope lists `$HOME/.claude/magpie` or a parent of it, propose removing it. A working directory is writable to sandboxed Bash, and the vetted-ops commands run from that checkout outside the sandbox. `/add-dir` has the same effect for a session. - **No glob and no `~`.** If the operator already has an entry such as `/tmp/claude-*` in any scope, say it does nothing: the setting matches literal paths only, so the glob is listed but never matched. - **Nothing per-host in a synced or committed file.** If the operator put the paths in a user-scope `~/.claude/settings.json` that is synced across machines, or in the committed project settings, suggest moving them: they name this host's uid. Rationale and the rules in full: [`docs/setup/secure-agent-setup.md` → Working directories under the read-outside-working-directories block](../../../../docs/setup/secure-agent-setup.md#working-directories-under-the-read-outside-working-directories-block). ### Step U — Host-only uv state The excluded `uvx` / `uv run` commands, MCP servers launched with `uv`, hooks that call `python3` and the operator's own terminal all run uv-managed code outside the sandbox. None of it may come from a directory a sandboxed command can write: - **`~/.local/share/uv` is read-only to the sandbox.** No scope may list it, or a parent of it, in `allowWrite` or `additionalDirectories`. The Step P helper removes the write an earlier version added; propose removing any other by hand. - **The host gets its own uv cache.** Read `~/.config/uv/uv.toml`. Unless it sets a `cache-dir` that is absolute and, symlinks resolved, outside every directory a sandboxed command can write (every `allowWrite` and `additionalDirectories` entry in any scope, every project root, and the roots the sandbox writes without a grant (`/tmp`, `/private/tmp`, `/var/folders`, `/private/var/folders`, `$TMPDIR`)), stage it with `cache-dir = "<resolved $HOME>/.local/share/uv-host/cache"` added, keeping every other setting, and give the operator the copy command: `Edit(~/.config/uv/**)` keeps the agent from writing it. Never `~` (uv does not expand it there) and never a relative path. - **The sandbox cannot read that file.** `permissions.deny` carries `Read(~/.config/uv/uv.toml)` and `Edit(~/.config/uv/**)` (both in the framework's `.claude/settings.json`, so Step 2's copy brings them). Sandboxed uv then keeps its default, writable cache. - **Sandboxed prek gets its own home.** The `env` entry is needed only where a repository uses prek (a `prek.toml`, `.pre-commit-config.yaml` or `.pre-commit-config.yml`, or a hook that runs it: [detection](../../../../tools/hook-manager/README.md#detection)); the deny is always kept, since the default home is per-user. The settings carry `"env": {"PREK_HOME": "~/.cache/prek-sandbox"}` and `permissions.deny` carries `Edit(~/.cache/prek/**)` (both in the framework's `.claude/settings.json`): a terminal's git hooks run prek outside the sandbox from `~/.cache/prek`. The whole-user dispatcher (Step P) gives hooks that Claude Code runs outside the sandbox a host-only home and cache root too; if a repository sets its own `core.hooksPath`, propose unsetting it so the dispatcher runs there. Then hand the operator the reinstall commands from the doc to run in a terminal: interpreters and tools the sandbox could write before may already have been changed. Rationale and commands: [`docs/setup/secure-agent-setup.md` → Host-only uv state](../../../../docs/setup/secure-agent-setup.md#host-only-uv-state). ### Step T — Local agent settings The committed `.claude/settings.json` is only the shared floor; the rest of a working setup is personal and goes in `.claude/settings.local.json`. Build and hand over that file exactly as [`setup update` → Reconcile the local agent settings](../setup/update.md#reconcile-the-local-agent-settings) does: the MCP tools for families installed here but not adopted by the project and, **only when this project is the Magpie framework checkout**, its template (`tools/agent-isolation/claude-settings.local.template.json`). Never stage that template into another project: it would widen that project's sandbox beyond what its maintainers configured. An agent