magpie-setup-isolated-setup-install

<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files): <project-config> → adopting project's `.apache-magpie/` directory <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) Determine the active harness from the session metadata and executable. When it is Codex, follow the install lifecycle in [docs/adapters/codex.md](../../docs/adapters/codex.md#install), including the project profile merge, static lint, project trust, and `agent-iso codex` steps. Do not write Claude settings or report a missing `.claude` file as a Codex failure. After completing the Codex branch, stop; the remainder of this skill is the Claude Code branch. When the harness is Claude Code, continue below. If the harness cannot be determined, ask once rather than applying one runtime's policy to another. 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 Before running the default behaviour documented below, this skill consults [`.apache-magpie-local/setup-isolated-setup-install.md`](../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/setup-isolated-setup-install.md`](../../docs/setup/agentic-overrides.md) (committed, project-wide) in the adopter repo if it exists, and applies any agent-readable overrides it finds. See [`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md) for the contract — what overrides may contain, hard rules, the reconciliation flow on framework upgrade, upstreaming guidance. **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`. --- ## 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 [`/magpie-setup upgrade`](../setup/upgrade.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/setup/install-recipes.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. 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. ## 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 runtime — 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 (`claude --version`) 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 Per [`docs/setup/secure-agent-setup.md` → *Project-root coverage in the sandbox allowlists*](../../docs/setup/secure-agent-setup.md#project-root-coverage-in-the-sandbox-allowlists) and [issue #197](https://github.com/apache/magpie/issues/197), the harness pre-resolves `sandbox.filesystem.allowRead: ["."]` at session start in a way that silently drops the literal `.` from the resolved set, so a session in a freshly-cloned adopter repo can write to CWD but cannot **read** from it under the sandbox. The defensive measure is to add the project root as an explicit **absolute path** to `sandbox.filesystem.allowRead` and `allowWrite` in the adopter's **project-local** settings file (`<repo>/.claude/settings.local.json`) — gitignored, per-machine, per-project, merged on top of the committed project-scope and user-scope by the harness. Worktrees handle themselves: each worktree has its own `<worktree>/.claude/settings.local.json`, and each gets its own root added. #### Step P.0 — Ask the user: per-project or whole-user scope? Before installing anything, ask the operator which scope they want — see [`docs/setup/secure-agent-setup.md` → *Per-project vs whole-user scope*](../../docs/setup/secure-agent-setup.md#per-project-vs-whole-user-scope) for the full rationale + trade-offs: - **Per-project.** The skill runs the helper for the current project only. Future projects on this host need the skill re-run in each, OR the operator can pick whole-user later. No global git config changes. - **Whole-user (global).** The skill walks the operator's existing local git checkouts and populates their `settings.local.json` files, then sets `git config --global core.hooksPath` so every future `git checkout` / `git clone` / `git worktree add` on the host picks up the framework's universal post-checkout hook. **Detect whether whole-user (global) scope is already active first.** Read `git config --global --get core.hooksPath`: - If it is **unset** (or does not point at the framework's shared hook dir), whole-user isolation is **not yet set up on this host**. In that case **propose whole-user (global) as the default** — it is the recommended baseline because it covers every current and future repo on the host in one pass, so the operator does not have to re-run this skill per project. Present per-project as the narrower alternative for operators who deliberately want to keep their per-repo git hooks (see the Step P.0a caveats). - If it is **already set** to the framework's shared hook dir, whole-user isolation is already in place; default to **per-project** for this specific project (the global hook already covers the host, so only this project's `settings.local.json` needs the local pass). **Prefer structured Q&A.** When the agent harness offers a structured-question tool (e.g. Claude Code's `AskUserQuestion`), use a single-select prompt whose default is chosen by the detection above — `Whole-user (global, recommended)` when whole-user is not yet set up, otherwise `Per-project`. Free-form chat is the fallback. If the user picks **per-project**, skip to *Step P.1 — Install the helper script* and *Step P.2 — Run the helper for this project*, then move on to the next step in the canonical install list. If the user picks **whole-user**, follow Step P.0a's loud disclosure first, then Step P.0b (pick the whole-user *flavour* — simple vs dispatcher), then Step P.1, then Steps P.2-whole-user (walk existing checkouts) and P.3-whole-user (install the global hook + set `core.hooksPath`). If they chose the dispatcher flavour, also run Step P.3b-whole-user (install the dispatcher + prek shim). ##### Step P.0a — Loud disclosure before setting whole-user scope If the operator picked whole-user, surface this disclosure **before** any global config write. The operator must acknowledge it explicitly; no silent proceed: > **!!! WHOLE-USER SCOPE — `core.hooksPath` GLOBAL OVERRIDE !!!** > > Setting `git config --global core.hooksPath` makes git look up > hooks in **one shared directory** for every repo on this host. > Every `.git/hooks/*` in every existing repo on this machine > becomes **inert** — git will no longer fire your per-repo > `pre-commit`, `commit-msg`, `pre-push`, or any other hook > unless the shared dir chains back to them. > > There are two whole-user flavours (you choose next, Step P.0b): > > - **Simple** — the framework installs **only** the > `post-checkout` hook in the shared dir. Every other per-repo > hook stays inert until you migrate it into `~/.claude/git-hooks/` > yourself. Pick this only if you don't rely on per-repo hooks. > - **With per-repo dispatcher (recommended if you use prek / > pre-commit / husky / any per-repo hook)** — the framework > installs a **dispatcher** for each hook type. Each dispatcher > runs the framework's own logic (the `post-checkout` > sandbox-allowlist sync) **and then chains through to that > repo's own `.git/hooks/<name>`**. Your per-repo hooks keep > firing, and a repo with no hook is a clean no-op. A bundled > `prek` PATH shim makes `prek install` write its shim into the > repo-local `.git/hooks/` (via `--git-dir`) so the dispatcher > can find it. > > Either way, whole-user scope is reversible: > `git config --global --unset core.hooksPath` restores per-repo > hook lookup, and (dispatcher flavour) removing > `~/.claude/bin` from PATH restores the stock `prek`. Confirm the operator wants to proceed with whole-user scope after reading the disclosure. If they hesitate or pick per-project, fall back to the per-project path. ##### Step P.0b — Choose the whole-user flavour: simple or dispatcher If the operator confirmed whole-user, ask which flavour (see the disclosure above for the trade-off). **Default to the dispatcher flavour** — it is a strict superset of simple (it still runs the `post-checkout` sync everywhere) and it avoids silently shadowing per-repo hooks, which is the most common whole-user surprise. Pick simple only if the operator explicitly wants the minimal footprint and confirms they run no per-repo hooks. **Prefer structured Q&A** here too: a single-select with `With per-repo dispatcher (recommended)` as the default and `Simple (post-checkout only)` as the alternative. - **Simple** → Step P.3-whole-user installs `git-global-post-checkout.sh` only. - **Dispatcher** → Step P.3-whole-user still runs, and Step P.3b-whole-user additionally installs `git-hook-dispatcher.sh` (symlinked to each hook name, including `post-checkout` — which in this flavour supersedes the standalone `git-global-post-checkout.sh`) and the `prek` PATH shim. #### Step P.1 — Install the helper script (Both scopes.) Copy `tools/agent-isolation/sandbox-add-project-root.sh` into `~/.claude/scripts/sandbox-add-project-root.sh` (or symlink it from `~/.claude-config/scripts/` if the operator uses the private sync repo), mode `0755`. The script file lives user-scope so a single install covers every adopter project on the host; what it **writes** is project-local. The same install mechanism the `sandbox-bypass-warn.sh` and `sandbox-status-line.sh` helpers use (see the *Sandbox-bypass visibility hook* and *Sandbox-state status line* sections of the doc). #### Step P.2 — Run the helper for this project (per-project scope) Skip if the operator picked whole-user scope (Step P.2-whole-user below covers the equivalent). Run the helper once with `--all-worktrees` in the adopter repo's main checkout. The helper enumerates `git worktree list --porcelain` and, for each worktree, writes that worktree's absolute path into that worktree's own `<worktree>/.claude/settings.local.json` (creating the file if it does not yet exist). Idempotent, atomic, tolerant of missing prereqs (see the script's header comment for the full failure-mode list). On success, surface the diff so the operator sees which entries landed; on no-op (paths already present), surface a one-line "already covered" confirmation. **Sandbox-bypass requirement when invoked from inside an agent session.** `.claude/settings.local.json` is in Claude Code's built-in sandbox `denyWithinAllow` set (verified empirically — see