claude-dev-env 2.3.0 → 2.4.0

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:]))