claude-dev-env 2.2.1 → 2.4.0

package/skills/prototype/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prototype
+description: >-
+  Isolated hookless worktree sandbox for zero-friction proof-of-concept builds, then a clean-room re-verification that promotes a successful POC into a real deploy. Triggers: prototype, /prototype, proof of concept, POC, spike, throwaway build, build without hooks, sandbox this idea, hookless worktree, prototype then ship, promote the prototype.
+---
+
+# Prototype
+
+## Principle
+
+Give a build the freedom to move fast, then make it earn the right to ship. Two phases, one hard wall between them:
+
+- **Sandbox** — an isolated worktree where an agent runs under `claude --bare`, so none of the standards gates (TDD, code rules, verified-commit, plain-language, stage) fire. The agent builds a proof-of-concept with zero friction.
+- **Promotion** — back in the normal, fully-hooked session, the successful POC goes through a clean-room re-verification before it becomes a commit and a pull request. Nothing from the sandbox rides along un-checked.
+
+Two safety gates stay live even in the sandbox: personal-data blocking and destructive-command blocking. A worktree shares the real repo's `.git` store and `rm` reaches the whole disk, so these are containment, not the "delays" the sandbox is meant to shed.
+
+## Gotchas
+
+Highest-signal content. Append a bullet each time a run fails in a new way.
+
+- A `--settings` file's hooks still load under `--bare` (the file is passed explicitly). That is the mechanism for keeping the two safety gates, not a bug.
+- The two safety hooks must point at the real installed scripts and import their `*_constants` packages at runtime. `scripts/build_sandbox_settings.py` resolves each hook's command from the live `~/.claude/settings.json` and registers it on the matchers the sandbox needs — personal-data on Write, Edit, MultiEdit, and Bash; destructive-command on Bash — so the paths stay correct on any machine and both gates cover the write surface. Do not hand-write the hook paths or matchers, and do not inherit whatever matcher the live config happens to use (a personal-data gate wired only to a narrow tool leaves disk writes ungated).
+- Under `--dangerously-skip-permissions` an `ask` decision is auto-resolved, so only a hard `deny` blocks a destructive command. The settings file carries an `env` block that sets `CLAUDE_DESTRUCTIVE_DENY_MODE`, which turns the destructive gate's terminal `ask` into a `deny`. The probe runs the gate under that env block and passes only on the hard deny.
+
+**Refusal cases — first match wins:**
+
+- **Not in a git repository.** Respond: `Prototype needs a git repo to branch a worktree from. Run this from inside one.`
+- **The `fresh-branch` skill is not installed.** Respond: `Prototype composes fresh-branch to make the sandbox worktree, and it is not installed. Install claude-dev-env first.`
+- **The `claude` CLI is not on PATH.** Respond: `The sandbox launches a headless claude session, and the claude CLI is not on PATH.`
+
+## Process
+
+Two phases. Run the sandbox phase first; run the promotion phase only when the POC succeeds and the user wants it shipped.
+
+### Phase 1 — Sandbox
+
+Follow `workflows/sandbox.md`. In short:
+
+1. Invoke the `fresh-branch` skill to create an isolated worktree off `origin/main`. Keep its returned `worktree_path` and `base_commit`.
+2. Run `scripts/build_sandbox_settings.py` to emit the minimal safety settings (personal-data and destructive-command gates only).
+3. Run `scripts/probe_sandbox_safety.py --settings <path>` and confirm both gates block. Do not continue on a non-zero exit.
+4. Run `scripts/launch_sandbox.py` to start the hookless `claude -p --bare` session in the worktree with those settings and the POC task.
+5. Read what the sandbox built. Decide whether the POC proves the idea.
+
+### Phase 2 — Promotion
+
+Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, `code-verifier` in a fresh context, then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
+
+## Task seeding
+
+At the start of Phase 2, register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence. Do not track promotion as a markdown checklist.
+
+## Sub-skills
+
+| Skill / agent | When | Produces | If missing |
+|---|---|---|---|
+| `fresh-branch` | Sandbox step 1; Promotion step 2 | isolated worktree JSON (`worktree_path`, `base_commit`, `repo_root`) | Refuse — see refusal cases |
+| `privacy-hygiene` | Promotion step 5 | personal-data and secret sweep of the diff | Warn; do a manual review before continuing |
+| `code-verifier` (agent) | Promotion step 6 | fresh-context verdict against the real diff; mints the commit-gate verdict | Stop; the commit gate will block anyway |
+| `/commit` (command) | Promotion step 7 | conventional commit + push | Commit and push by hand per `git-workflow` |
+| `autoconverge` (default; `pr-converge` or `bugteam` as alternatives) | Promotion step 9 | the PR converged to ready | Stop after the draft PR; tell the user to converge manually |
+
+## Degree of freedom
+
+Low on the skill's own mechanics — the launch flags and the promotion order are fragile with cliffs, so they live in scripts and a fixed task list, not in prose the agent reconstructs. High inside the sandbox — the sandboxed agent's build freedom is the whole point.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This hub — principle, gotchas, when-applies, process, sub-skills, file index |
+| `workflows/sandbox.md` | Phase 1 steps: worktree, safety settings, probe, hookless launch |
+| `workflows/promotion.md` | Phase 2 steps: the clean-room re-verification that drives the promotion task seeds |
+| `reference/promotion-tasks.md` | Task-seed catalog for the clean-room protocol (register via the task tool) |
+| `reference/honest-limitations.md` | The two fixed statements to make on every promotion |
+| `scripts/build_sandbox_settings.py` | Emit the minimal safety `--settings`: resolve each hook's command from live settings, register it on the required matchers |
+| `scripts/launch_sandbox.py` | Launch the hookless `claude -p --bare` sandbox session in the worktree |
+| `scripts/probe_sandbox_safety.py` | Prove both safety gates block before trusting the sandbox |
+
+## Folder map
+
+- `SKILL.md` — hub.
+- `workflows/` — the two phase workflows.
+- `reference/` — promotion task seeds and the honest-limitation statements.
+- `scripts/` — the settings builder, the launcher, the safety probe, their `prototype_scripts_constants` package, and paired tests.

package/skills/prototype/reference/honest-limitations.md

@@ -0,0 +1,23 @@
+# Honest limitations of a promoted prototype
+
+State both of these to the user, in these terms, whenever a proof-of-concept is promoted. Do not soften or drop them. They are the price of building without standards gates.
+
+## 1. Write-time code rules never ran on this code
+
+`code_rules_enforcer` is a Write/Edit gate: it checks content as it is written. Prototype code is built under `--bare`, so that gate never fired, and content brought into promotion as a git diff (apply, checkout, cherry-pick) does not pass through it either.
+
+Standards re-engage on promotion through three surfaces that stand in for the write-time hook:
+
+- the `code-verifier` agent, in a fresh context, deriving and running the named gates against the real diff;
+- the `privacy-hygiene` sweep for personal data and secrets;
+- the pull-request review (AGENTS.md criteria and any PR-loop reviewers).
+
+Say plainly: the write-time rule engine did not see this code; the verifier and review are what cover it.
+
+## 2. TDD ordering is waived on promoted prototype lines
+
+The sandbox agent wrote code first and tests, if any, after. Red-green-refactor ordering did not happen. So the honest claim on promoted prototype code is exactly this, and nothing more:
+
+> code-verifier passed, privacy swept, review passed — TDD ordering waived.
+
+Do not claim red-green compliance on these lines. A prototype is a reference build, not a test-first build. Fred Brooks: plan to throw one away. Promotion re-verifies the code and often rewrites it to standard; expect real work in the verifier repair loop, not a rubber stamp.

package/skills/prototype/reference/promotion-tasks.md

@@ -0,0 +1,23 @@
+# Promotion task seeds (clean-room protocol)
+
+Register every numbered item below as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool) at the start of the promotion phase. Work only from the task list. Mark each complete only with evidence — a command result, a path, a verdict, or a skill's return. This is not a checkbox board; it is a seed catalog for the task tool.
+
+Promotion runs in the **normal, fully-hooked session** — never inside the `--bare` sandbox. Nothing from the sandbox history is carried; only its file content is re-applied and re-verified.
+
+1. **Confirm the prototype is worth promoting.** The sandbox build works and the user (or the standing goal) wants it shipped. Evidence: the working behavior observed, one sentence on what the POC proves.
+
+2. **Fresh branch off live upstream.** Re-fetch `origin/main` and branch from it via the `fresh-branch` skill. Evidence: the returned `base_commit` matches current `origin/main`. This starts clean history and keeps the work based on live upstream.
+
+3. **Bring prototype content as an uncommitted working-tree diff, by allowlist.** Take the sandbox diff against its `base_commit` and copy only the product files you intend to ship into the fresh branch's working tree. Do NOT cherry-pick or merge the sandbox commits, and do NOT bulk-copy the worktree. Exclude the sandbox settings file (`.prototype-sandbox-settings.json`) and every scratch, debug, or artifact file the POC produced — name the files you are bringing, not the ones you are dropping. Evidence: the allowlist of copied paths; `git status` shows only those unstaged; `git log` shows no sandbox commits.
+
+4. **Cleanup pass.** Remove every scratch file, debug dump, and temp helper the prototype created (see the `cleanup-temp-files` rule). Evidence: the removed paths, or a stated "none created".
+
+5. **Privacy sweep.** Run the `privacy-hygiene` skill over the full applied working tree, not only the diff — a POC that pulled live data can leave a secret in a file the diff view hides. Evidence: its clean report, or the leak it found and how it was removed. If the skill is missing, do a manual PII and secret review and say so.
+
+6. **Verify in a fresh context.** Spawn the `code-verifier` agent against the real diff. Expect findings and a repair loop — the code was un-TDD'd. Evidence: the verifier's clean verdict, and a note of what it made you fix. Do not skip this on the belief that the sandbox agent already tested it.
+
+7. **Commit and open a draft PR.** Only on a clean verdict, run `/commit` (which mints the commit-gate verdict and pushes), then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
+
+8. **State the honest limitations.** Post the two statements from `reference/honest-limitations.md` — write-time rules never ran; TDD ordering waived — in the PR body or to the user. Evidence: the text was included.
+
+9. **Hand to a PR-loop skill.** Hand the PR to `autoconverge` by default — one autonomous run to ready. Reach for `pr-converge` when paced ticks fit better, or `bugteam` for an open-loop audit-fix. Evidence: the skill was invoked, or the user chose to converge manually.

package/skills/prototype/scripts/build_sandbox_settings.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Emit a minimal ``--settings`` file carrying only the two sandbox safety hooks.
+
+::
+
+    python build_sandbox_settings.py --out sandbox-settings.json
+    sandbox-settings.json -> {"env": {deny-mode override},
+        "hooks": {"PreToolUse": [
+        {"matcher": "Bash",      "hooks": [pii_prevention, destructive_command]},
+        {"matcher": "Edit",      "hooks": [pii_prevention]},
+        {"matcher": "MultiEdit", "hooks": [pii_prevention]},
+        {"matcher": "Write",     "hooks": [pii_prevention]}]}}
+
+The builder resolves each safety hook's command entry from the live settings
+source, which carries the per-machine interpreter, absolute script path, and
+timeout. It then registers each entry on the matchers the sandbox requires.
+The personal-data gate covers every write surface and the command line. The
+destructive-command gate covers the command line, and the emitted ``env`` block
+runs that gate in deny mode so its block holds under
+``--dangerously-skip-permissions``. When either safety hook is absent from the
+source, the builder exits without writing, because a sandbox cannot be
+contained without both.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+from prototype_scripts_constants.config.build_sandbox_settings_constants import (
+    ALL_REQUIRED_MATCHERS_BY_SAFETY_BASENAME,
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES,
+    BUILD_SUCCESS_EXIT_CODE,
+    COMMAND_KEY,
+    DEFAULT_SETTINGS_SOURCE,
+    DESTRUCTIVE_DENY_MODE_ENV_VALUE,
+    DESTRUCTIVE_DENY_MODE_ENV_VAR,
+    ENV_KEY,
+    HOOKS_KEY,
+    JSON_INDENT_SPACES,
+    MATCHER_KEY,
+    MISSING_BASENAMES_JOIN_SEPARATOR,
+    PRE_TOOL_USE_KEY,
+    SETTINGS_MISSING_SAFETY_HOOK_EXIT_CODE,
+    SETTINGS_SOURCE_UNREADABLE_EXIT_CODE,
+)
+from prototype_scripts_constants.config.prototype_common_constants import (
+    LOGGING_FORMAT,
+    TEXT_ENCODING_UTF8,
+)
+
+logger = logging.getLogger("build_sandbox_settings")
+
+
+def read_settings_document(source_path: Path) -> dict:
+    """Load the live settings JSON the sandbox settings are resolved from.
+
+    ::
+
+        ~/.claude/settings.json  ->  parsed dict with hooks.PreToolUse blocks
+    """
+    return json.loads(source_path.read_text(encoding=TEXT_ENCODING_UTF8))
+
+
+def _first_subhook_running(
+    pre_tool_use_block: dict, script_basename: str
+) -> dict | None:
+    """Return the block's first sub-hook whose command runs the named script."""
+    for each_subhook in pre_tool_use_block.get(HOOKS_KEY, []):
+        if script_basename in each_subhook.get(COMMAND_KEY, ""):
+            return each_subhook
+    return None
+
+
+def _first_block_running(
+    all_pre_tool_use_blocks: list[dict], script_basename: str
+) -> dict | None:
+    """Return the first block's sub-hook entry that runs the named safety script."""
+    for each_block in all_pre_tool_use_blocks:
+        resolved_entry = _first_subhook_running(each_block, script_basename)
+        if resolved_entry is not None:
+            return resolved_entry
+    return None
+
+
+def resolve_safety_hook_entries(settings_document: dict) -> dict[str, dict]:
+    """Resolve each safety hook's live sub-hook entry, keyed by script basename.
+
+    ::
+
+        live PreToolUse blocks
+            -> {"pii_prevention_blocker.py": {type, command, timeout},
+                "destructive_command_blocker.py": {type, command, timeout}}
+
+    The captured entry carries the per-machine interpreter, absolute script
+    path, and timeout, so the sandbox settings stay correct on any machine.
+
+    Args:
+        settings_document: the live settings JSON with hooks.PreToolUse blocks.
+
+    Returns:
+        The first matching sub-hook entry per safety basename; a basename with
+        no matching sub-hook is absent from the mapping.
+    """
+    pre_tool_use_blocks = settings_document.get(HOOKS_KEY, {}).get(PRE_TOOL_USE_KEY, [])
+    entry_by_basename: dict[str, dict] = {}
+    for each_basename in ALL_SAFETY_HOOK_SCRIPT_BASENAMES:
+        resolved_entry = _first_block_running(pre_tool_use_blocks, each_basename)
+        if resolved_entry is not None:
+            entry_by_basename[each_basename] = resolved_entry
+    return entry_by_basename
+
+
+def find_unresolved_safety_hook_basenames(
+    entry_by_basename: dict[str, dict],
+) -> list[str]:
+    """List the safety hook basenames the live source resolved no command for.
+
+    ::
+
+        both resolved            -> []
+        destructive unresolved   -> ["destructive_command_blocker.py"]
+
+    Args:
+        entry_by_basename: the resolved sub-hook entry per safety basename.
+
+    Returns:
+        The safety hook basenames absent from the mapping, empty when both
+        resolved.
+    """
+    return [
+        each_basename
+        for each_basename in ALL_SAFETY_HOOK_SCRIPT_BASENAMES
+        if each_basename not in entry_by_basename
+    ]
+
+
+def _build_pre_tool_use_blocks(entry_by_basename: dict[str, dict]) -> list[dict]:
+    """Build one PreToolUse block per required matcher, in sorted matcher order."""
+    entries_by_matcher: dict[str, list[dict]] = {}
+    for each_basename in ALL_REQUIRED_MATCHERS_BY_SAFETY_BASENAME:
+        resolved_entry = entry_by_basename[each_basename]
+        for each_matcher in ALL_REQUIRED_MATCHERS_BY_SAFETY_BASENAME[each_basename]:
+            entries_by_matcher.setdefault(each_matcher, []).append(resolved_entry)
+    return [
+        {MATCHER_KEY: each_matcher, HOOKS_KEY: entries_by_matcher[each_matcher]}
+        for each_matcher in sorted(entries_by_matcher)
+    ]
+
+
+def _build_deny_mode_env_block() -> dict[str, str]:
+    """Build the env block that runs the destructive gate in deny mode.
+
+    The single key is the deny-mode env variable, mapped to its truthy value,
+    so the sandbox session runs the destructive gate with a hard block.
+
+    Returns:
+        The single-key env override the sandbox session applies.
+    """
+    return {DESTRUCTIVE_DENY_MODE_ENV_VAR: DESTRUCTIVE_DENY_MODE_ENV_VALUE}
+
+
+def build_minimal_settings(entry_by_basename: dict[str, dict]) -> dict:
+    """Assemble the minimal settings document from the resolved safety entries.
+
+    ::
+
+        resolved entries -> {"env": {deny-mode override},
+                             "hooks": {"PreToolUse": [required-matcher blocks]}}
+
+    The ``env`` block runs the destructive gate in deny mode, so its block
+    holds under ``--dangerously-skip-permissions``, where an ask decision is
+    auto-resolved.
+
+    Args:
+        entry_by_basename: the resolved sub-hook entry per safety basename.
+
+    Returns:
+        The minimal settings document registering each safety entry on the
+        matchers the sandbox requires, with the deny-mode env override.
+    """
+    return {
+        ENV_KEY: _build_deny_mode_env_block(),
+        HOOKS_KEY: {PRE_TOOL_USE_KEY: _build_pre_tool_use_blocks(entry_by_basename)},
+    }
+
+
+def write_minimal_settings(minimal_settings: dict, out_path: Path) -> None:
+    """Write the minimal settings document to the output path as pretty JSON."""
+    serialized_settings = json.dumps(minimal_settings, indent=JSON_INDENT_SPACES)
+    out_path.write_text(serialized_settings + "\n", encoding=TEXT_ENCODING_UTF8)
+
+
+def _parse_arguments(all_arguments: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--out", required=True, help="where to write the settings")
+    parser.add_argument(
+        "--settings-source",
+        default=DEFAULT_SETTINGS_SOURCE,
+        help="the live settings JSON to resolve the safety hook commands from",
+    )
+    return parser.parse_args(all_arguments)
+
+
+def _load_settings_or_none(source_path: Path) -> dict | None:
+    """Read and parse the settings source, logging and returning None on failure."""
+    try:
+        return read_settings_document(source_path)
+    except (OSError, json.JSONDecodeError) as read_error:
+        logger.error("cannot read settings source %s: %s", source_path, read_error)
+        return None
+
+
+def main(all_arguments: list[str] | None = None) -> int:
+    """Build the minimal safety settings and write them to the output path.
+
+    Args:
+        all_arguments: the command-line arguments, or None to read sys.argv.
+
+    Returns:
+        0 after writing the settings, 2 when the source is unreadable, and 2
+        when either safety hook is unresolved from the source.
+    """
+    logging.basicConfig(format=LOGGING_FORMAT)
+    arguments = _parse_arguments(all_arguments)
+    source_path = Path(arguments.settings_source).expanduser()
+    settings_document = _load_settings_or_none(source_path)
+    if settings_document is None:
+        return SETTINGS_SOURCE_UNREADABLE_EXIT_CODE
+    entry_by_basename = resolve_safety_hook_entries(settings_document)
+    all_unresolved_basenames = find_unresolved_safety_hook_basenames(entry_by_basename)
+    if all_unresolved_basenames:
+        logger.error(
+            "safety hook missing from settings source: %s",
+            MISSING_BASENAMES_JOIN_SEPARATOR.join(all_unresolved_basenames),
+        )
+        return SETTINGS_MISSING_SAFETY_HOOK_EXIT_CODE
+    minimal_settings = build_minimal_settings(entry_by_basename)
+    out_path = Path(arguments.out).expanduser()
+    write_minimal_settings(minimal_settings, out_path)
+    sys.stdout.write(str(out_path) + "\n")
+    return BUILD_SUCCESS_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/prototype/scripts/conftest.py

@@ -0,0 +1,15 @@
+"""Put this worktree's prototype scripts directory on the import path.
+
+The scripts import their ``prototype_scripts_constants`` package by name.
+Inserting this directory lets the tests resolve that package and the
+script modules from the local worktree rather than an installed copy.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))

package/skills/prototype/scripts/launch_sandbox.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Launch the hookless ``claude -p --bare`` sandbox session in a worktree.
+
+::
+
+    python launch_sandbox.py --worktree ./wt --settings ./s.json --task-file ./t.txt
+    {"worktree": "./wt", "settings": "./s.json", "exit_code": 0}
+
+The launcher validates the three paths, reads the proof-of-concept task from
+the task file, and runs a headless ``claude`` session in the worktree under
+the minimal safety settings. The session runs with the standards gates
+stripped, so the two safety hooks in the settings are its only containment.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from prototype_scripts_constants.config.launch_sandbox_constants import (
+    BARE_FLAG,
+    CLAUDE_EXECUTABLE_NAME,
+    DEFAULT_TIMEOUT_SECONDS,
+    LAUNCH_MISSING_PATH_EXIT_CODE,
+    LAUNCH_TIMEOUT_EXIT_CODE,
+    PROMPT_FLAG,
+    SETTINGS_FLAG,
+    SKIP_PERMISSIONS_FLAG,
+    SUMMARY_KEY_EXIT_CODE,
+    SUMMARY_KEY_SETTINGS,
+    SUMMARY_KEY_WORKTREE,
+)
+from prototype_scripts_constants.config.prototype_common_constants import (
+    LOGGING_FORMAT,
+    TEXT_ENCODING_UTF8,
+)
+
+logger = logging.getLogger("launch_sandbox")
+
+SandboxCommandRunner = Callable[[list[str], Path, "int | None"], int]
+
+
+def build_sandbox_command(task_text: str, settings_path: Path) -> list[str]:
+    """Build the exact headless ``claude`` argument vector for the sandbox.
+
+    ::
+
+        "build a spike", settings.json
+            -> ["claude", "-p", "build a spike", "--bare",
+                "--dangerously-skip-permissions", "--settings", "settings.json"]
+
+    Args:
+        task_text: the proof-of-concept task the session builds.
+        settings_path: the minimal safety settings file.
+
+    Returns:
+        The ordered argument vector for the headless claude session.
+    """
+    return [
+        CLAUDE_EXECUTABLE_NAME,
+        PROMPT_FLAG,
+        task_text,
+        BARE_FLAG,
+        SKIP_PERMISSIONS_FLAG,
+        SETTINGS_FLAG,
+        str(settings_path),
+    ]
+
+
+def validate_sandbox_paths(
+    worktree_path: Path, settings_path: Path, task_file_path: Path
+) -> str | None:
+    """Report the first path that does not fit the sandbox launch contract.
+
+    Args:
+        worktree_path: the isolated worktree the session runs in.
+        settings_path: the minimal safety settings file.
+        task_file_path: the file holding the proof-of-concept task text.
+
+    Returns:
+        An error message for the first path that is absent or the wrong
+        kind, or None when the worktree is a directory and both files exist.
+    """
+    if not worktree_path.is_dir():
+        return f"worktree is not a directory: {worktree_path}"
+    if not settings_path.is_file():
+        return f"settings file not found: {settings_path}"
+    if not task_file_path.is_file():
+        return f"task file not found: {task_file_path}"
+    return None
+
+
+def _run_via_subprocess(
+    all_command_tokens: list[str], working_directory: Path, timeout_seconds: int | None
+) -> int:
+    try:
+        completed_process = subprocess.run(
+            all_command_tokens,
+            cwd=working_directory,
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        logger.error(
+            "sandbox session exceeded the %s-second wall-clock limit; terminated",
+            timeout_seconds,
+        )
+        return LAUNCH_TIMEOUT_EXIT_CODE
+    except OSError as launch_error:
+        logger.error(
+            "cannot launch the claude executable %s: %s",
+            all_command_tokens[0],
+            launch_error,
+        )
+        return LAUNCH_MISSING_PATH_EXIT_CODE
+    return completed_process.returncode
+
+
+def run_sandbox(
+    worktree_path: Path,
+    settings_path: Path,
+    task_text: str,
+    timeout_seconds: int | None,
+    command_runner: SandboxCommandRunner,
+) -> int:
+    """Run the headless sandbox command in the worktree and return its code.
+
+    Args:
+        worktree_path: the isolated worktree the session runs in.
+        settings_path: the minimal safety settings file.
+        task_text: the proof-of-concept task the session builds.
+        timeout_seconds: the wall-clock limit, or None for no limit.
+        command_runner: the callable that runs the command vector.
+
+    Returns:
+        The exit code the command runner reports for the session, which is
+        the timeout exit code when the session outran its wall-clock limit.
+    """
+    sandbox_command = build_sandbox_command(task_text, settings_path)
+    return command_runner(sandbox_command, worktree_path, timeout_seconds)
+
+
+def _emit_sandbox_summary(
+    worktree_path: Path, settings_path: Path, exit_code: int
+) -> None:
+    summary = {
+        SUMMARY_KEY_WORKTREE: str(worktree_path),
+        SUMMARY_KEY_SETTINGS: str(settings_path),
+        SUMMARY_KEY_EXIT_CODE: exit_code,
+    }
+    sys.stdout.write(json.dumps(summary) + "\n")
+
+
+def _parse_arguments(all_arguments: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--worktree", required=True, help="the sandbox worktree")
+    parser.add_argument("--settings", required=True, help="the safety settings file")
+    parser.add_argument("--task-file", required=True, help="the task text file")
+    parser.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="the wall-clock limit for the session",
+    )
+    return parser.parse_args(all_arguments)
+
+
+def main(all_arguments: list[str] | None = None) -> int:
+    """Resolve and validate the paths, run the session, and print a summary.
+
+    Args:
+        all_arguments: the command-line arguments, or None to read sys.argv.
+
+    Returns:
+        The sandbox exit code, 2 when a required path is missing, or the
+        timeout exit code when the session outran its wall-clock limit.
+    """
+    logging.basicConfig(format=LOGGING_FORMAT)
+    arguments = _parse_arguments(all_arguments)
+    worktree_path = Path(arguments.worktree).expanduser().resolve()
+    settings_path = Path(arguments.settings).expanduser().resolve()
+    task_file_path = Path(arguments.task_file).expanduser().resolve()
+    path_error = validate_sandbox_paths(worktree_path, settings_path, task_file_path)
+    if path_error is not None:
+        logger.error("%s", path_error)
+        return LAUNCH_MISSING_PATH_EXIT_CODE
+    task_text = task_file_path.read_text(encoding=TEXT_ENCODING_UTF8)
+    exit_code = run_sandbox(
+        worktree_path,
+        settings_path,
+        task_text,
+        arguments.timeout_seconds,
+        _run_via_subprocess,
+    )
+    _emit_sandbox_summary(worktree_path, settings_path, exit_code)
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))