vinta-ai-workflows 0.2.0-alpha2 → 0.2.0-alpha4

package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/resources/ai-models.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=https://github.com/vintasoftware/vinta-ai-workflows/schemas/ai-models.v1.schema.json
+#
+# Per-tier AI model recommendations consumed by the `plan-feature` skill's
+# "AI model selection per phase" section. This file is the single source of
+# truth for concrete model IDs — the SKILL.md body carries the *selection
+# guidance* (when each tier applies, how to write the suggestion) but never
+# hard-codes model IDs, so the prose never goes stale.
+#
+# `last_verified` is the date a maintainer (or the nightly `check-ai-models`
+# job in vinta-ai-workflows) last confirmed every `id` below still exists.
+# Tier *placement* is human/LLM judgement — the job flags drift and proposes
+# edits, it does not blindly reassign tiers. See scripts/check-ai-models.mjs.
+schema_version: 1
+last_verified: 2026-06-22
+
+# Drift is checked against a free, no-key community aggregator (models.dev,
+# vendor-keyed with release dates + pricing), cross-checked against LiteLLM's
+# price/context JSON. No vendor API keys are needed to detect staleness — the
+# checker only needs network access. The vendors tracked are derived from the
+# `models:` keys under `tiers` below (anthropic / openai / google), which must
+# match the provider keys used by the aggregator.
+source:
+  primary: https://models.dev/api.json
+  fallback: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
+
+# Tiers run cheapest/fastest (1) → architectural/hard (4). Default to the
+# cheapest tier that plausibly one-shots the work; a cheap model failing fast
+# beats an expensive one succeeding slowly.
+tiers:
+  - tier: 1
+    label: cheapest/fastest (boilerplate, exact-precedent edits)
+    use_for: >-
+      single migration adding column or index, exporting from __init__.py,
+      registering admin, scaffolding empty Django app, thin serializer
+      mirroring existing pattern verbatim.
+    models:
+      anthropic:
+        - id: claude-haiku-4-5
+      openai:
+        - id: gpt-5-nano
+          note: fall back to gpt-5-mini if file has any branching logic
+      google:
+        - id: gemini-2.5-flash-lite
+
+  - tier: 2
+    label: standard pattern application
+    use_for: >-
+      repository methods, DRF serializer with non-trivial validation, ViewSet
+      wiring with filterset, pytest unit/integration tests against established
+      fixtures, simple HStore/ArrayField additions.
+    models:
+      anthropic:
+        - id: claude-haiku-4-5
+          note: with iteration; step up to claude-sonnet-4-6 if phase touches >3 files
+        - id: claude-sonnet-4-6
+          note: step-up target when phase touches >3 files
+      openai:
+        - id: gpt-5-mini
+      google:
+        - id: gemini-2.5-flash
+
+  - tier: 3
+    label: multi-file orchestration, business logic, SQL views
+    use_for: >-
+      use case coordinating across repositories with non-trivial branching,
+      new vw_* view + non-managed model + migration, serializer with
+      cross-field validation affecting use-case behavior, integration tests
+      covering concurrency edges.
+    models:
+      anthropic:
+        - id: claude-sonnet-4-6
+      openai:
+        - id: gpt-5
+      google:
+        - id: gemini-2.5-pro
+        - id: gemini-3-pro
+          note: stronger code recall
+
+  - tier: 4
+    label: architectural / novel / hard
+    use_for: >-
+      cycle detection in user-mutable trees, transactional batch protocols
+      with deferred constraints, partitioned-to-partitioned FK design, perf
+      tuning slow query against partitioned hot table, debugging heisenbug.
+    models:
+      anthropic:
+        - id: claude-opus-4-7
+          note: "[1m] 1M-context variant for large codebases"
+      openai:
+        - id: gpt-5
+          note: with extended thinking
+        - id: o3
+          note: pure reasoning
+        - id: o4
+          note: pure reasoning
+      google:
+        - id: gemini-3-pro
+          note: with thinking

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md

@@ -199,6 +199,73 @@ Quick walk-through of common gotchas. For each, follow the same fork/share patte
 
 If the **Plan inspection** step inferred the plan doesn't touch any of these: symlink / share. If unsure: fork. Cheap.
 
+## Step 5.5 — Filesystem sandbox (OS-level write guard)
+
+Symlinking + threading the worktree path through prompts keeps *cooperative* agents in the worktree, but it's not a guarantee: a buggy agent (often a smaller model spawned for a phase) can resolve an absolute path back to the **main checkout** and silently write there. Those writes never reach the worktree's commit — they sit as uncommitted thrash in the main checkout, and the "missing" edits read as a silent agent failure. Prompt instructions don't stop it; they rely on the agent's goodwill.
+
+The deterministic fix is to confine the *process* (not the tool) at the OS filesystem layer: make the main checkout read-only for any command run inside the sandbox, regardless of which agent CLI issues the writes. The bundled [scripts/sandbox-run.sh](scripts/sandbox-run.sh) does this — `sandbox-exec` on macOS, `bwrap` (bubblewrap) on Linux. **This process-wrapping model works for runtimes that spawn subagents as subprocesses** (`codex exec`, a `claude -p` child, a custom runner). Runtimes that run subagents **in-process** — notably claude-code's Task tool, where there's no child command to wrap — use the harness-config guard in [In-process runtimes (claude-code)](#55a--in-process-runtimes-claude-code) instead.
+
+**Model: deny-main, allow-rest.** The whole filesystem stays writable EXCEPT the main checkout, with the worktree (and the shared `.vinta-ai-workflows` dir) punched back to writable — even though the worktree usually lives *under* the main checkout (`.claude/worktrees/<name>/`). This deliberately does **not** lock `HOME` / caches / `/tmp`, so package managers, build tools, and test runners behave exactly as unsandboxed. The only thing the cage blocks is a write to the main checkout's own tracked tree — which is exactly the bug.
+
+Wrapper contract:
+
+```bash
+sandbox-run.sh \
+  --deny  <main-checkout-root> \
+  --allow <worktree-path> \
+  --allow <summary_dir-and-prs-context-parent>   # the .vinta-ai-workflows dir
+  -- <command> [args...]
+```
+
+The command runs with main-checkout writes blocked. A stray write fails with `Operation not permitted` (macOS) / `EROFS` (Linux) — the agent sees an ordinary error and retries against the correct path; the worktree stays the only writable copy of the repo.
+
+**Capability probe (run here, record the result):**
+
+```bash
+command -v sandbox-exec >/dev/null && tier=enforced   # macOS
+command -v bwrap        >/dev/null && tier=enforced   # Linux
+# neither → tier=none (sandbox unavailable)
+```
+
+- `tier=enforced` → the OS guarantee holds. The caller ([implement-plan](../implement-plan/SKILL.md)) can downgrade its post-run stray-write check to a backstop.
+- `tier=none` → no sandbox tool on this machine (locked-down CI without `bwrap`'s user-namespace support, Windows, etc.). `sandbox-run.sh` still runs the command (best-effort, unsandboxed) and prints a loud warning; prevention falls back to the caller's reactive stray-write detection. **Don't fail provisioning over this** — surface the degraded tier and continue.
+
+Escape hatch: `VINTA_SANDBOX=off` makes the wrapper a transparent pass-through (for the rare tool that needs access the sandbox blocks). Record the achieved tier in the summary (next step) so the caller knows whether it's running guaranteed or best-effort.
+
+**Sandbox-mode shared-state rule.** Because main is read-only inside the cage, any path the *run* writes must live in the worktree or in an `--allow`'d dir — never a symlink that resolves back into the main checkout. Two follow-ons:
+- The existing `deps_change=true` → copy/reinstall logic already gives the worktree its own writable `node_modules/` when a phase installs deps; non-churn phases keep the read-only symlink (agents shouldn't write deps anyway — correct).
+- The `.vinta-ai-workflows/` dir (summary YAMLs, prs-context) is shared/symlinked but **written** during a run, so it must be passed as an `--allow` path (or made a real writable dir in the worktree). Record which.
+
+### 5.5a — In-process runtimes (claude-code)
+
+`sandbox-run.sh` confines a **process**: it wraps the command that launches a subagent. That only works when the runtime spawns subagents as **subprocesses** (`codex exec …`, a `claude -p …` child, a custom runner) — you wrap that argv and the kernel blocks the child's main-checkout writes.
+
+**Claude Code runs subagents in-process.** Its Task tool shares the orchestrator's OS process and tool pipeline — there's no child launch command to wrap. The guard has to live in the harness's own config instead. Two complementary layers, both bundled here, both matching the same deny-main/allow-rest model:
+
+- **Layer A — `PreToolUse` write-guard hook** ([scripts/claude-worktree-write-guard.py](scripts/claude-worktree-write-guard.py)). A session-level `PreToolUse` hook fires for **every** tool call in the session — orchestrator **and** every in-process Task subagent — because they run through the same pipeline. This hook matches the file-editing tools (`Edit|Write|MultiEdit|NotebookEdit`), realpath-resolves the target, and blocks (exit 2 → the model gets the reason and retries) any write that escapes the worktree into the main checkout. Filesystem-only, **no network impact**. This is the load-bearing claude-code guard and the concrete form of implement-plan's "runtime pre-write guard hook" option.
+
+- **Layer B — Claude Code's native OS sandbox** (opt-in). Claude Code has adopted the same OS model `sandbox-run.sh` implements (`sandbox-exec` / `bwrap`), configured via `sandbox.filesystem.denyWrite` / `allowWrite` in `settings.json` instead of a wrapper, and it applies to **Bash run inside subagents** too. Turning it on closes the one gap Layer A leaves — a write issued through **Bash** (`echo > <main>/f`), which a file-tool hook can't see. **Caveat: enabling the native sandbox also turns on network isolation**, so `pnpm install` / `git push` break unless you allow-list the registry + git-remote hosts. Without Layer B, Bash-issued stray writes fall back to implement-plan's post-run `git -C <main> status` backstop (Layer 1).
+
+Generate both with [scripts/gen-claude-sandbox-settings.sh](scripts/gen-claude-sandbox-settings.sh):
+
+```bash
+# Layer A only (filesystem-only, no network config needed):
+scripts/gen-claude-sandbox-settings.sh --worktree <worktree-path> --main <main-checkout-root>
+
+# Layer A + B (also OS-block Bash writes; must allow-list network hosts):
+scripts/gen-claude-sandbox-settings.sh --worktree <worktree-path> --main <main-checkout-root> \
+  --os-sandbox --allow-domain <registry-host> --allow-domain <git-remote-host>
+```
+
+It writes `<worktree>/.claude/settings.json` (merging, not clobbering) with `<worktree>`, `<main>/.git` (git worktrees commit into the main repo's `.git` — **must** stay writable), and `.vinta-ai-workflows` punched back to writable.
+
+**Two deployment models — settings are read at session start:**
+
+1. **Worktree-rooted session (recommended).** Run the plan from inside the worktree (`cd <worktree> && claude`). The generated `<worktree>/.claude/settings.json` governs that session and all its Task subagents. As a bonus, claude-code's default working-directory boundary already discourages file writes above cwd, so this is belt-and-suspenders. Provision the worktree + settings **before** starting the plan session.
+2. **Config in the invocation's project root.** If the orchestrator already runs in the main checkout (implement-plan's default topology), the hook + sandbox must instead live in the main checkout's `settings.json` / `settings.local.json` **before** that session starts — the native `sandbox` block in particular is read at launch and won't retroactively cage an already-running session. Provision first, then start the plan; don't expect a mid-run `use_worktree` opt-in to enable the OS sandbox for the session that requested it.
+
+Record the achieved tier the same way as the subprocess path: `enforced` when Layer B is active (or Layer A alone if the team accepts hook-only), `none` when neither is wired.
+
 ## Step 6 — Write the summary file
 
 `.vinta-ai-workflows/worktrees/<name>.yaml` (committed to `.gitignore` via the existing `.vinta-ai-workflows/` umbrella). Schema:
@@ -240,6 +307,15 @@ state:
     redis_db_index: <int>
     s3_prefix: wt-<name>/
     cron_disabled: <bool>
+  sandbox:
+    tier: enforced | none          # from the Filesystem sandbox step's capability probe
+    launcher: sandbox-exec | bwrap | claude-hook | claude-native-sandbox | null
+    # sandbox-exec / bwrap        → subprocess runtimes via scripts/sandbox-run.sh
+    # claude-hook                 → in-process (claude-code) Layer A hook only (file tools)
+    # claude-native-sandbox       → in-process (claude-code) Layer A hook + Layer B OS sandbox
+    # null                        → tier=none (no guard wired)
+    deny: [<main-checkout-root>]   # subtree(s) made read-only inside the cage
+    allow: [<worktree-path>, <main-checkout-root>/.git, <.vinta-ai-workflows-dir>]  # writable exceptions
 notes: |
   <freeform — anything the user / agent should know>
 ```
@@ -254,6 +330,12 @@ Branch: `<branch>` (based on `<base-ref>`).
 ## What's forked vs shared
 <one-line per row in `state` above>
 
+## Write protection
+Sandbox tier: `<enforced | none>` (launcher: `<sandbox-exec | bwrap | none>`).
+When `enforced`, commands run via `sandbox-run.sh` cannot write to the main
+checkout — only this worktree (+ `.vinta-ai-workflows`). When `none`, no OS
+guard is active; the orchestrator's post-run stray-write check is the backstop.
+
 ## How to run things
 - Lint: `<project lint command>` (runs inside this worktree)
 - Tests: `<project test command>` (against `<test_db.forked_name>`)
@@ -276,6 +358,7 @@ One paragraph to the caller:
 
 - Worktree path + branch.
 - One line per fork decision (deps / env / dev DB / test DB / compose / other).
+- **Sandbox tier** (`enforced` via `sandbox-exec` / `bwrap`, or `none`) — so the caller knows whether main-checkout writes are OS-blocked or only caught after the fact.
 - Anything the user must do manually before running the app (`source .envrc`, `direnv allow`, login to a cloud CLI in the worktree, etc.).
 - Teardown command.
 
@@ -300,6 +383,9 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 - **Every fork decision lands in `.vinta-ai-workflows/worktrees/<name>.yaml`.** Teardown reads it; humans grep it; agents resuming a stalled plan read it. No decision lives only in conversation memory.
 - **Worktree root governed by runtime conventions.** claude-code uses `.claude/worktrees/`; other harnesses use sibling dirs. Don't fight the harness — match it.
 - **Don't mutate the main checkout from this skill.** Every write goes to the worktree or to `.vinta-ai-workflows/`. Forking a Postgres DB is the one exception (the new DB lives in the same server) — document it loudly in the summary.
+- **Sandbox is the deterministic guard; the prompt is not.** When a sandbox tool exists, the [Filesystem sandbox](#step-55--filesystem-sandbox-os-level-write-guard) step's `sandbox-run.sh` makes the main checkout read-only for any spawned command — this is what actually *prevents* stray main-checkout writes for subprocess runtimes. For **in-process** runtimes (claude-code's Task tool) there's no subprocess to wrap: wire the `PreToolUse` hook (+ optional native OS sandbox) from [In-process runtimes (claude-code)](#55a--in-process-runtimes-claude-code) into the session's `settings.json` instead. Telling the agent "stay in the worktree" is best-effort only either way. Always probe + record the tier; never claim prevention when `tier=none`.
+- **`<main>/.git` stays writable in every model.** Git worktrees store their commits in the main repo's `.git`; a deny that also blocks `<main>/.git` breaks every commit made inside the worktree. `sandbox-run.sh` callers and the generated claude-code settings must both `--allow` / `allowWrite` `<main>/.git`.
+- **Deny-main, allow-rest — never allow-worktree-only.** Locking everything except the worktree breaks package managers / caches / `$HOME`. Lock only the main checkout subtree; re-allow the worktree (nested under it) and the written `.vinta-ai-workflows` dir. Don't tighten further without testing the project's real lint / test / build / migrate commands inside the cage.
 - **Worktree base = `origin/<default-branch>` by default.** `HEAD` only when the user explicitly confirms; record the choice in the summary.
 - **Refuse to provision a second worktree for the same branch.** Git enforces this — don't try to work around it.
 - **Don't auto-install heavy deps** (e.g. `pnpm install` from scratch) without confirmation when the project's main `node_modules/` is already populated — symlink first, ask if reinstall is needed.
@@ -311,6 +397,9 @@ Every step gated on user confirmation when the worktree has un-pushed branches.
 - **Forgetting `COMPOSE_PROJECT_NAME`.** Containers from worktree-A overwrite worktree-B's containers; volumes get nuked. Set it in `.env` so every `docker compose` call inherits.
 - **Sharing a Redis DB without per-worktree prefix.** Tests writing `user:123` collide across worktrees. Pick an index OR a key prefix.
 - **Copying `node_modules` for yarn PnP / absolute-path setups.** The copy carries baked-in paths from the main checkout. Reinstall instead — pnpm's relative-symlink store is the safe-to-copy exception.
+- **Forgetting to `--allow` the `.vinta-ai-workflows` dir under sandbox.** It's shared/symlinked but the run *writes* it (summary YAMLs, prs-context). If it's not an `--allow` exception, those writes hit the read-only main subtree and fail mid-run. Pass it alongside the worktree path.
+- **Assuming the sandbox is always there.** `bwrap` needs user namespaces enabled — some hardened kernels and CI images disable them. Probe (`command -v bwrap`); on `tier=none` degrade to the post-run check, don't silently believe writes are blocked.
+- **Over-tightening into an allow-worktree-only cage.** Tempting, but it breaks every tool that writes outside the repo (npm cache, `~/.config`, `$TMPDIR`). The deny-main model is the one that needs no per-stack allowlist tuning.
 - **Leaving cron / background workers on in the worktree.** They poll the shared DB and double-process jobs. Default to off.
 - **Provisioning a worktree, running migrations, then realizing the user wanted to share the DB.** The **Database fork** step asks BEFORE migrating; rollback of a forked-DB migration is mechanical (drop the DB), but rollback of a shared-DB migration is a half-day.
 - **Symlinking `.env` and then editing it.** The edit leaks into main. Copy (not symlink) the moment `env_change = true`.

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/claude-worktree-write-guard.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""claude-worktree-write-guard.py — Claude Code PreToolUse hook that blocks
+file-tool writes escaping a worktree into the protected main checkout.
+
+Why this exists: Claude Code runs sub-agents (the Task tool) IN-PROCESS — they
+share the orchestrator's OS process and tool pipeline, so there is no child
+launch command to wrap with an OS sandbox (that model only works on harnesses
+that spawn sub-agents as subprocesses, e.g. `codex exec`). A session-level
+PreToolUse hook, by contrast, fires for every tool call in the session —
+orchestrator AND Task sub-agents alike — because they run through the same
+pipeline. This hook is the in-process equivalent of prepare-worktree's
+`sandbox-run.sh` deny-main/allow-rest guard, scoped to the file-editing tools.
+
+Scope: the file-write tools only — Edit, Write, MultiEdit, NotebookEdit. Bash
+writes are NOT covered here (a hook can't reliably know every path a shell
+command touches); use Claude Code's native `sandbox` (see
+gen-claude-sandbox-settings.sh `--os-sandbox`) for OS-level Bash confinement,
+and rely on implement-plan's post-run `git -C <main> status` backstop otherwise.
+
+Model — deny-main, allow-rest (mirrors sandbox-run.sh): every path is allowed
+EXCEPT ones that resolve under a --deny root, and an --allow root punches a
+subtree back to writable even when nested under a --deny root. The worktree
+usually lives UNDER the main checkout (.claude/worktrees/<name>/), and git
+worktrees write commits into <main>/.git, so both the worktree and <main>/.git
+are passed as --allow. Symlinks are resolved (realpath) before the check, so a
+write through a symlink that lands back in the main checkout (e.g. a shared
+node_modules) is correctly caught.
+
+Usage (wired by gen-claude-sandbox-settings.sh into settings.json hooks):
+    claude-worktree-write-guard.py \
+        --deny  <main-checkout-root> \
+        --allow <worktree-path> \
+        --allow <main-checkout-root>/.git \
+        --allow <main-checkout-root>/.vinta-ai-workflows
+
+Reads the PreToolUse event JSON on stdin. Blocks by exiting 2 with a reason on
+stderr — Claude Code feeds that stderr back to the model as the denial reason,
+so the agent retries against the correct worktree path. Any non-write tool, or
+a write that stays inside an --allow subtree, exits 0 (allowed). The guard fails
+OPEN (exit 0) on malformed input or its own errors — it is a safety net layered
+under the OS sandbox and the post-run backstop, never the sole gate, and must
+never wedge a run by denying on a parsing hiccup.
+"""
+import json
+import os
+import sys
+
+# Tool-input keys that carry a write target, per tool.
+PATH_KEYS = ("file_path", "notebook_path")
+GUARDED_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+
+
+def canon(path):
+    """Absolute, symlink-resolved path. realpath resolves a shared node_modules
+    / .vinta-ai-workflows symlink back to its real location so the prefix check
+    reflects where the byte actually lands, not the symlink's apparent path."""
+    return os.path.realpath(os.path.abspath(path))
+
+
+def under(path, root):
+    """True if `path` is `root` or nested beneath it. Compares canonical paths
+    with a trailing separator so /main-evil is not treated as under /main."""
+    path, root = canon(path), canon(root)
+    return path == root or path.startswith(root.rstrip(os.sep) + os.sep)
+
+
+def parse_args(argv):
+    deny, allow = [], []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--deny" and i + 1 < len(argv):
+            deny.append(argv[i + 1]); i += 2
+        elif argv[i] == "--allow" and i + 1 < len(argv):
+            allow.append(argv[i + 1]); i += 2
+        else:
+            i += 1
+    return deny, allow
+
+
+def main():
+    deny, allow = parse_args(sys.argv[1:])
+    if not deny:
+        # Nothing to protect — nothing to do.
+        return 0
+
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0  # fail open — never wedge a run on a parse error
+
+    if event.get("tool_name") not in GUARDED_TOOLS:
+        return 0
+
+    tool_input = event.get("tool_input") or {}
+    target = next((tool_input[k] for k in PATH_KEYS if tool_input.get(k)), None)
+    if not target:
+        return 0  # no write target we recognize
+
+    # allow wins over deny (the worktree + .git + .vinta-ai-workflows are nested
+    # under the denied main root and must stay writable).
+    if any(under(target, a) for a in allow):
+        return 0
+    if any(under(target, d) for d in deny):
+        resolved = canon(target)
+        wt = allow[0] if allow else "the worktree"
+        sys.stderr.write(
+            f"Blocked write to the main checkout: {resolved}\n"
+            f"This file is outside the worktree. Write to the worktree instead "
+            f"(under {wt}). If you meant to edit a shared file, it is protected "
+            f"for the duration of this plan run.\n"
+        )
+        return 2  # exit 2 → Claude Code blocks the call, stderr is the reason
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/gen-claude-sandbox-settings.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# gen-claude-sandbox-settings.sh — generate a Claude Code settings.json that
+# confines a worktree session (orchestrator + its in-process Task sub-agents)
+# to writing inside the worktree, blocking stray writes to the main checkout.
+#
+# Claude Code runs sub-agents in-process (the Task tool shares the orchestrator's
+# OS process), so the subprocess-wrapping model of sandbox-run.sh does not apply
+# — the guard has to live in the harness's own settings. This script wires two
+# complementary layers, matching prepare-worktree's deny-main/allow-rest model:
+#
+#   Layer A (always) — a PreToolUse hook (claude-worktree-write-guard.py) that
+#     blocks the file-editing tools (Edit/Write/MultiEdit/NotebookEdit) from
+#     writing outside the worktree. Filesystem-only; no network impact. Fires
+#     for the orchestrator AND every Task sub-agent (shared session pipeline).
+#
+#   Layer B (opt-in, --os-sandbox) — Claude Code's NATIVE OS sandbox
+#     (`sandbox.filesystem.denyWrite`/`allowWrite`, Seatbelt on macOS / bwrap on
+#     Linux) so Bash-issued writes are blocked at the kernel too. NOTE: enabling
+#     the native sandbox also turns on NETWORK isolation — dep installs and
+#     `git push` break unless you allow-list registries/remotes. Pass the hosts
+#     the plan needs via --allow-domain (repeatable). Without --os-sandbox, Bash
+#     writes fall back to implement-plan's post-run `git -C <main> status` check.
+#
+# Both layers keep <worktree>, <main>/.git (git worktrees commit into the main
+# repo's .git), and the shared .vinta-ai-workflows dir writable.
+#
+# Usage:
+#   gen-claude-sandbox-settings.sh \
+#     --worktree <worktree-path> \
+#     --main     <main-checkout-root> \
+#     [--allow <extra-writable-path>]...   # e.g. .vinta-ai-workflows if elsewhere
+#     [--out <settings-file>]              # default: <worktree>/.claude/settings.json
+#     [--os-sandbox]                       # also emit the native sandbox block
+#     [--allow-domain <host>]...           # network hosts to allow under --os-sandbox
+#
+# The generated file is meant to govern a Claude Code session ROOTED IN THE
+# WORKTREE (`cd <worktree> && claude`), the recommended claude-code topology for
+# an isolated plan run — the settings are read at session start. See Step 5.5 of
+# ../SKILL.md for the two deployment models and their timing caveats.
+#
+# Exit: 0 on success; 2 on argument/setup errors.
+
+set -u
+
+die() { echo "gen-claude-sandbox-settings: $*" >&2; exit 2; }
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+GUARD="$SCRIPT_DIR/claude-worktree-write-guard.py"
+
+WORKTREE=""; MAIN=""; OUT=""; OS_SANDBOX=0
+EXTRA_ALLOW=(); DOMAINS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --worktree)     shift; [ $# -gt 0 ] || die "--worktree needs a path"; WORKTREE="$1"; shift ;;
+    --main)         shift; [ $# -gt 0 ] || die "--main needs a path"; MAIN="$1"; shift ;;
+    --out)          shift; [ $# -gt 0 ] || die "--out needs a path"; OUT="$1"; shift ;;
+    --allow)        shift; [ $# -gt 0 ] || die "--allow needs a path"; EXTRA_ALLOW+=("$1"); shift ;;
+    --allow-domain) shift; [ $# -gt 0 ] || die "--allow-domain needs a host"; DOMAINS+=("$1"); shift ;;
+    --os-sandbox)   OS_SANDBOX=1; shift ;;
+    *)              die "unknown arg: $1" ;;
+  esac
+done
+
+[ -n "$WORKTREE" ] || die "--worktree <path> required"
+[ -n "$MAIN" ]     || die "--main <path> required"
+[ -f "$GUARD" ]    || die "guard hook not found next to this script: $GUARD"
+
+# Canonicalize (leaf need not exist).
+canon() {
+  local p="$1" d b
+  if [ -d "$p" ]; then (cd "$p" && pwd -P); return; fi
+  d=$(dirname "$p"); b=$(basename "$p")
+  if [ -d "$d" ]; then echo "$(cd "$d" && pwd -P)/$b"; else echo "$p"; fi
+}
+
+WORKTREE=$(canon "$WORKTREE")
+MAIN=$(canon "$MAIN")
+[ -d "$WORKTREE" ] || die "worktree path is not a directory: $WORKTREE"
+[ -d "$MAIN" ]     || die "main checkout path is not a directory: $MAIN"
+[ -z "$OUT" ] && OUT="$WORKTREE/.claude/settings.json"
+
+# Writable exceptions punched back through the main-checkout deny: the worktree,
+# the shared git database (worktree commits land in <main>/.git), the shared
+# .vinta-ai-workflows dir, plus any caller extras.
+ALLOW=("$WORKTREE" "$MAIN/.git" "$MAIN/.vinta-ai-workflows")
+for p in "${EXTRA_ALLOW[@]:-}"; do [ -n "$p" ] && ALLOW+=("$(canon "$p")"); done
+
+if [ "$OS_SANDBOX" -eq 1 ] && [ "${#DOMAINS[@]}" -eq 0 ]; then
+  echo "gen-claude-sandbox-settings: WARNING --os-sandbox with no --allow-domain — network" >&2
+  echo "  isolation is ON, so dep installs / git push over the network will fail. Pass the" >&2
+  echo "  registry + git remote hosts via --allow-domain, or drop --os-sandbox for hook-only." >&2
+fi
+
+mkdir -p "$(dirname "$OUT")" || die "cannot create settings dir for $OUT"
+
+# Emit JSON via python3 (safe escaping of paths); merge into an existing file if
+# one is present so we don't clobber unrelated settings the worktree may carry.
+GUARD="$GUARD" OUT="$OUT" MAIN="$MAIN" WORKTREE="$WORKTREE" OS_SANDBOX="$OS_SANDBOX" \
+python3 - "${ALLOW[@]}" -- "${DOMAINS[@]:-}" <<'PY' || die "failed to write settings"
+import json, os, sys
+
+guard, out, main, worktree = (os.environ[k] for k in ("GUARD", "OUT", "MAIN", "WORKTREE"))
+os_sandbox = os.environ["OS_SANDBOX"] == "1"
+
+sep = sys.argv.index("--")
+allow = [a for a in sys.argv[1:sep] if a]
+domains = [d for d in sys.argv[sep + 1:] if d]
+
+# Layer A — PreToolUse write-guard hook (always).
+guard_cmd = " ".join(
+    [json.dumps(guard) if " " in guard else guard, "--deny", main]
+    + sum((["--allow", a] for a in allow), [])
+)
+hook_entry = {
+    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+    "hooks": [{"type": "command", "command": guard_cmd}],
+}
+
+# Merge into an existing settings file if present (preserve unrelated keys).
+settings = {}
+if os.path.exists(out):
+    try:
+        with open(out) as f:
+            settings = json.load(f) or {}
+    except Exception:
+        settings = {}
+
+hooks = settings.setdefault("hooks", {})
+pre = hooks.setdefault("PreToolUse", [])
+# Drop any prior guard entry (idempotent re-runs) then append the fresh one.
+pre = [e for e in pre if "claude-worktree-write-guard" not in json.dumps(e)]
+pre.append(hook_entry)
+hooks["PreToolUse"] = pre
+
+# Layer B — native OS sandbox (opt-in).
+if os_sandbox:
+    settings["sandbox"] = {
+        "enabled": True,
+        # Degrade to unsandboxed on platforms without Seatbelt/bwrap rather than
+        # hard-failing the run; the hook (Layer A) still guards file writes.
+        "failIfUnavailable": False,
+        "filesystem": {
+            "denyWrite": [main],
+            "allowWrite": allow,
+        },
+        "network": {
+            # Sandbox forces network isolation; without an allow-list, installs
+            # and pushes break. Callers pass registry + remote hosts.
+            "allowedDomains": domains,
+        },
+    }
+
+with open(out, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+
+print(f"wrote {out}")
+print(f"  layer A (hook): guard on Edit|Write|MultiEdit|NotebookEdit, deny {main}")
+print(f"  allow-write: {', '.join(allow)}")
+if os_sandbox:
+    dom = ", ".join(domains) if domains else "(none — network will be blocked)"
+    print(f"  layer B (os sandbox): enabled, network allowedDomains: {dom}")
+else:
+    print("  layer B (os sandbox): OFF (hook-only; Bash writes rely on the post-run backstop)")
+PY
+
+echo "gen-claude-sandbox-settings: done."

package/skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# sandbox-run.sh — run a command with writes to a protected subtree (the main
+# checkout) blocked at the OS level, regardless of which agent harness issues
+# the writes. Harness-agnostic: it confines the *process*, not the tool.
+#
+# Model: deny-main, allow-rest. The whole filesystem stays writable EXCEPT the
+# --deny subtree(s), with --allow subtree(s) punched back to writable (so a
+# worktree nested under the main checkout, and the shared .vinta-ai-workflows
+# dir, keep working). This deliberately does NOT lock HOME / caches / tmp, so
+# package managers, build tools, and test runners behave exactly as unsandboxed.
+#
+# Usage:
+#   sandbox-run.sh --deny <path> [--deny <path>...] \
+#                  [--allow <path>...] -- <command> [args...]
+#
+# Required:
+#   --deny  <path>   subtree to make read-only (the main checkout root). Repeatable.
+# Optional:
+#   --allow <path>   subtree to keep writable even if nested under a --deny path
+#                    (the worktree; the .vinta-ai-workflows summary/prs-context dir).
+#                    Repeatable.
+#
+# Environment:
+#   VINTA_SANDBOX=off         bypass entirely — exec the command unsandboxed and
+#                             print a warning (escape hatch when a tool needs
+#                             access the sandbox blocks, or on an unsupported FS).
+#   VINTA_SANDBOX_TIER_FILE   if set, write the achieved tier to this file:
+#                             "enforced" (sandbox active) or "none" (no sandbox
+#                             tool available / bypassed). Callers read it to know
+#                             whether the OS guarantee held or a backstop is needed.
+#
+# Exit: the command's own exit code. Setup failures exit 2.
+
+set -u
+
+die() { echo "sandbox-run: $*" >&2; exit 2; }
+
+DENY=()
+ALLOW=()
+CMD=()
+parsing_cmd=0
+while [ $# -gt 0 ]; do
+  if [ "$parsing_cmd" -eq 1 ]; then CMD+=("$1"); shift; continue; fi
+  case "$1" in
+    --deny)  shift; [ $# -gt 0 ] || die "--deny needs a path"; DENY+=("$1"); shift ;;
+    --allow) shift; [ $# -gt 0 ] || die "--allow needs a path"; ALLOW+=("$1"); shift ;;
+    --)      parsing_cmd=1; shift ;;
+    *)       die "unknown arg: $1 (did you forget '--' before the command?)" ;;
+  esac
+done
+
+[ "${#CMD[@]}" -gt 0 ] || die "no command given after '--'"
+[ "${#DENY[@]}" -gt 0 ] || die "at least one --deny <path> required"
+
+# Canonicalize a path without requiring the leaf to exist.
+canon() {
+  local p="$1" d b
+  if [ -d "$p" ]; then (cd "$p" && pwd -P); return; fi
+  d=$(dirname "$p"); b=$(basename "$p")
+  if [ -d "$d" ]; then echo "$(cd "$d" && pwd -P)/$b"; else echo "$p"; fi
+}
+
+DENY_C=();  for p in "${DENY[@]}";  do DENY_C+=("$(canon "$p")");  done
+ALLOW_C=(); for p in "${ALLOW[@]}"; do ALLOW_C+=("$(canon "$p")"); done
+
+record_tier() {
+  [ -n "${VINTA_SANDBOX_TIER_FILE:-}" ] && printf '%s' "$1" > "$VINTA_SANDBOX_TIER_FILE" 2>/dev/null || true
+}
+
+if [ "${VINTA_SANDBOX:-}" = "off" ]; then
+  echo "sandbox-run: VINTA_SANDBOX=off — running UNSANDBOXED (no main-checkout protection)" >&2
+  record_tier none
+  exec "${CMD[@]}"
+fi
+
+# ---- macOS: sandbox-exec -----------------------------------------------------
+if command -v sandbox-exec >/dev/null 2>&1; then
+  # Explicit XXXXXX template (portable across BSD mktemp on stock macOS and GNU
+  # mktemp from coreutils — `mktemp -t prefix` is not portable between them).
+  profile=$(mktemp "${TMPDIR:-/tmp}/vinta-sandbox.XXXXXX") || die "mktemp failed"
+  trap 'rm -f "$profile"' EXIT
+  {
+    echo '(version 1)'
+    echo '(allow default)'
+    for p in "${DENY_C[@]}";  do echo "(deny file-write* (subpath \"$p\"))"; done
+    for p in "${ALLOW_C[@]}"; do echo "(allow file-write* (subpath \"$p\"))"; done
+  } > "$profile"
+  record_tier enforced
+  exec sandbox-exec -f "$profile" "${CMD[@]}"
+fi
+
+# ---- Linux: bubblewrap -------------------------------------------------------
+if command -v bwrap >/dev/null 2>&1; then
+  args=(--bind / /)
+  for p in "${DENY_C[@]}";  do args+=(--ro-bind "$p" "$p"); done   # main → read-only
+  for p in "${ALLOW_C[@]}"; do args+=(--bind    "$p" "$p"); done   # worktree → writable (overrides ro)
+  args+=(--dev /dev --proc /proc)
+  record_tier enforced
+  exec bwrap "${args[@]}" -- "${CMD[@]}"
+fi
+
+# ---- No sandbox tool: best-effort fallback -----------------------------------
+echo "sandbox-run: no sandbox tool (sandbox-exec / bwrap) found — running UNSANDBOXED." >&2
+echo "sandbox-run: main-checkout writes are NOT blocked; rely on the post-run stray-write check." >&2
+record_tier none
+exec "${CMD[@]}"