claude-dev-env 8.14.0 → 8.15.0

package/.agents/skills/everything-search/SKILL.md

@@ -42,7 +42,7 @@ Path and operator searches run when the registry file is missing. Malformed regi
 **Path (WSL):** `/mnt/c/Program\ Files/Everything/es.exe`
 **Path (Windows):** `"C:/Program Files/Everything/es.exe"`
 
-**CRITICAL:**
+Syntax:
 - Search terms are SPACE-SEPARATED, not quoted together
 - When searching a path, use backslashes inside quotes: `"Y:\\path\\to\\folder"`
 

package/.agents/skills/second-account-workers/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/second-account-workers/AGENTS.md

@@ -0,0 +1 @@
+

package/.agents/skills/second-account-workers/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: second-account-workers
+description: >-
+  Run local headless Claude workers through the second-account picker.
+  Triggers: spawn a worker on the second account, offload a worker,
+  claude-ev worker, save main account usage.
+---
+
+# Second Account Workers
+
+Use this skill when a task needs a local Claude worker and the session should
+save main account usage.
+
+## Choose a worker
+
+Keep the Agent tool for small, fast lookups. For any worker that edits code,
+researches at length, or runs long, give it its own Git worktree, write a
+standalone brief to a file, and launch the account worker in the background.
+
+```bash
+python "$HOME/.claude/scripts/claude_account_worker.py" \
+  --prompt-file "<brief>" \
+  --cwd "<worktree>" \
+  --report-file "<report>" \
+  >"<worker-log>" 2>&1 &
+worker_pid=$!
+wait "$worker_pid"
+worker_exit=$?
+cat "<report>"
+```
+
+Read the JSON report and worker log after the process ends. The JSON fields are
+`account`, `reason`, `exit_code`, `duration_seconds`, `result`, and `is_error`.
+The runner writes one summary line with the selected account, exit code, and
+report path.
+
+When the command exits 3 and the report has `"account": "wait"`, both accounts
+are out of room. Report the picker's reason and reset time. Do not fall back to
+the Agent tool. Claude can also return exit 3 after a worker starts. When the
+report account is `main` or `second`, report the child's exit code and result.
+
+Workers never commit, push, or call `gh`. The calling session reviews each
+worktree diff and owns every Git step.
+
+## Write a standalone brief
+
+When pstack is installed, the first brief line is `/pstack:poteto-mode`.
+Otherwise, begin with the worker role. Include every detail needed to finish
+without the calling session's conversation.
+
+```text
+/pstack:poteto-mode
+Role: <one worker duty>
+Owned files: <exact paths this worker may edit>
+Acceptance checks:
+- <observable behavior>
+- <commands to run and expected result>
+Report:
+Changed: <files and reason>
+Proof: <checks run and last result lines>
+Blocked: <open issue, or none>
+```
+
+Keep the owned file list closed. Name the worktree path with `--cwd` and use a
+separate brief and report path for each worker.

package/bin/ever-shipped-skills.mjs

@@ -90,6 +90,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'reviewer-gates',
     'reviews',
     'run-claude-dev-env',
+    'second-account-workers',
     'session-continuity',
     'session-log',
     'session-tidy',

package/bin/install.prompt-context.test.mjs

@@ -0,0 +1,42 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+
+import { mergeHooksIntoSettings } from './install.mjs';
+
+test('reinstall replaces both prompt hooks with one ordered context hook', () => {
+    const hooksConfig = JSON.parse(readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8'));
+    const userCommand = 'python C:/Users/example/hooks/user_hook.py';
+    const settings = {
+        hooks: {
+            UserPromptSubmit: [
+                {
+                    matcher: '',
+                    hooks: [
+                        { type: 'command', command: userCommand },
+                        {
+                            type: 'command',
+                            command: 'python C:/Users/example/.claude/hooks/session/style_reminder_prompt.py',
+                        },
+                        {
+                            type: 'command',
+                            command: 'python C:/Users/example/.claude/hooks/session/skill_loaded_reminder.py',
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
+
+    const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
+    assert.equal(userPromptHooks.length, 2);
+    assert.equal(userPromptHooks[0].command, userCommand);
+    assert.match(userPromptHooks[1].command, /style_reminder_prompt\.py --include-skill-reminder$/);
+    assert.doesNotMatch(userPromptHooks[1].command, /skill_loaded_reminder/);
+
+    const firstMerge = JSON.stringify(settings);
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
+    assert.equal(JSON.stringify(settings), firstMerge);
+});

package/docs/DJANGO_PATTERNS.md

@@ -35,7 +35,7 @@
 
 ## Production Migrations (Post-Launch ONLY)
 
-**CRITICAL:** After launch, model changes MUST be backwards-compatible.
+After launch, keep model changes backwards-compatible.
 
 **Why:** Manual migration takes 2+ minutes. New code runs against old schema during this window.
 
@@ -59,7 +59,7 @@
 
 ## API Contract Changes (Post-Launch)
 
-**CRITICAL:** After launch, API contract changes MUST be backwards-compatible.
+After launch, keep API contract changes backwards-compatible.
 
 **Why:** Users may have old client code cached. Old clients must work with new API.
 

package/docs/TEST_QUALITY.md

@@ -4,19 +4,7 @@
 
 ## Test Infrastructure Anti-Patterns
 
-**CRITICAL: Test helpers get over-engineered MORE than any other code.**
-
-**ALWAYS:**
-- Single file
-- Simple functions
-- Minimal abstractions
-- Pragmatic approach
-
-**NEVER:**
-- Multi-file packages
-- Cache classes
-- Abstractions "for future"
-- Rigid constraints
+Test helpers drift toward over-engineering faster than production code, because nothing reviews them for size. Keep a helper to one file of plain functions with the fewest abstractions the current tests need. Add a package, a cache class, or an abstraction only when a second test needs it today.
 
 **Pre-check (MANDATORY):**
 - [ ] ONE file?

package/docs/second-claude-account.md

@@ -10,6 +10,10 @@ keeps its own sign-in and history.
 |---|---|
 | `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
 | `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
+| `scripts/claude_account_worker.py` | Runs one headless Claude worker using the account chosen by the picker |
+| `scripts/claude_account_worker_process.py` | Launches the worker process, feeds it the brief, and kills it on timeout |
+| `scripts/claude_account_worker_report.py` | Builds and writes the JSON report a worker leaves behind |
+| `scripts/dev_env_scripts_constants/claude_account_worker_constants.py` | The worker's flag names, defaults, exit codes, and report keys |
 | `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
 
 The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to

package/hooks/hooks.json

@@ -69,12 +69,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/style_reminder_prompt.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/style_reminder_prompt.py --include-skill-reminder",
             "timeout": 10
           }
         ]

package/hooks/session/style_reminder_prompt.py

@@ -12,8 +12,8 @@
     the model sees the reminder this turn, and each turn after
 
 Claude Code and Codex CLI both read the same ``additionalContext`` shape on
-their ``UserPromptSubmit`` event. One script serves both. The hook prints
-text and stops.
+their ``UserPromptSubmit`` event. The Claude hook includes the skill reminder
+when its flag is present. The unflagged Codex hook prints style alone.
 """
 
 from __future__ import annotations
@@ -23,15 +23,29 @@ import sys
 
 import _path_setup  # noqa: F401
 
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.style_reminder_prompt_constants import STYLE_REMINDER_PROMPT
+from skill_loaded_reminder import reminder_for
+
+
+def _additional_context_for_prompt() -> str:
+    if "--include-skill-reminder" not in sys.argv[1:]:
+        return STYLE_REMINDER_PROMPT
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return STYLE_REMINDER_PROMPT
+    skill_reminder = reminder_for(hook_input)
+    if skill_reminder is None:
+        return STYLE_REMINDER_PROMPT
+    return STYLE_REMINDER_PROMPT + "\n" + skill_reminder
 
 
 def main() -> None:
-    """Print the style reminder as UserPromptSubmit additionalContext."""
+    """Print ordered UserPromptSubmit additionalContext."""
     payload = {
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
-            "additionalContext": STYLE_REMINDER_PROMPT,
+            "additionalContext": _additional_context_for_prompt(),
         }
     }
     sys.stdout.write(json.dumps(payload) + "\n")

package/hooks/session/test_style_reminder_prompt.py

@@ -13,20 +13,74 @@ for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
         sys.path.insert(0, each_sys_path_entry)
 
 import style_reminder_prompt as reminder
+from hooks_constants.skill_loaded_reminder_constants import NOT_LOADED_REMINDER
 from hooks_constants.style_reminder_prompt_constants import STYLE_REMINDER_PROMPT
 
 
-def _run_main() -> str:
+def _run_main(all_arguments: list[str], hook_input: str) -> str:
     """Return the text main() prints."""
     captured_stdout = StringIO()
-    with patch("sys.stdout", captured_stdout):
+    with (
+        patch("sys.argv", ["style_reminder_prompt.py", *all_arguments]),
+        patch("sys.stdin", StringIO(hook_input)),
+        patch("sys.stdout", captured_stdout),
+    ):
         reminder.main()
     return captured_stdout.getvalue()
 
 
 class TestStyleReminderPrompt:
     def test_main_emits_user_prompt_submit_hook_specific_output(self) -> None:
-        emitted = json.loads(_run_main())
+        emitted = json.loads(_run_main([], ""))
         hook_output = emitted["hookSpecificOutput"]
         assert hook_output["hookEventName"] == "UserPromptSubmit"
         assert hook_output["additionalContext"] == STYLE_REMINDER_PROMPT
+
+    def test_unflagged_invocation_keeps_style_only_with_hook_input(self) -> None:
+        emitted = json.loads(_run_main([], json.dumps({"hook_event_name": "UserPromptSubmit"})))
+        assert emitted["hookSpecificOutput"]["additionalContext"] == STYLE_REMINDER_PROMPT
+
+    def test_flagged_invocation_combines_style_and_missing_skill_reminder(self) -> None:
+        emitted = json.loads(
+            _run_main(
+                ["--include-skill-reminder"],
+                json.dumps({"hook_event_name": "UserPromptSubmit"}),
+            )
+        )
+        assert emitted["hookSpecificOutput"]["additionalContext"] == (
+            STYLE_REMINDER_PROMPT + "\n" + NOT_LOADED_REMINDER
+        )
+
+    def test_flagged_invocation_keeps_style_only_after_skill_load(self, tmp_path: Path) -> None:
+        transcript_path = tmp_path / "session.jsonl"
+        transcript_path.write_text(
+            json.dumps(
+                {
+                    "type": "assistant",
+                    "message": {
+                        "content": [
+                            {
+                                "type": "tool_use",
+                                "name": "Skill",
+                                "input": {"skill": "pstack:poteto-mode"},
+                            }
+                        ]
+                    },
+                }
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+        emitted = json.loads(
+            _run_main(
+                ["--include-skill-reminder"],
+                json.dumps(
+                    {"hook_event_name": "UserPromptSubmit", "transcript_path": str(transcript_path)}
+                ),
+            )
+        )
+        assert emitted["hookSpecificOutput"]["additionalContext"] == STYLE_REMINDER_PROMPT
+
+    def test_flagged_invocation_without_hook_input_keeps_style_only(self) -> None:
+        emitted = json.loads(_run_main(["--include-skill-reminder"], ""))
+        assert emitted["hookSpecificOutput"]["additionalContext"] == STYLE_REMINDER_PROMPT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.14.0",
+    "version": "8.15.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/research-mode.md

@@ -1,6 +1,6 @@
 # Research Mode (Global)
 
-Three anti-hallucination constraints are ALWAYS active.
+Three anti-hallucination constraints are always active.
 
 Source: [Anthropic - Reduce Hallucinations](https://docs.anthropic.com/en/docs/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
 

package/scripts/claude_account_worker.py

@@ -0,0 +1,347 @@
+"""Run a headless Claude worker on the account chosen by the usage picker."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from claude_account_choice import choose_account, decision_payload, read_account_meters
+from claude_account_profile import default_profile_home
+from claude_account_worker_process import WorkerProcess, invoke_worker
+from claude_account_worker_report import (
+    WorkerReport,
+    finalize_report,
+    make_report,
+    pre_launch_failure_report,
+    wait_report,
+)
+from dev_env_scripts_constants.claude_account_worker_constants import (
+    CHOICE_MAIN,
+    CHOICE_SECOND,
+    CHOICE_WAIT,
+    CLAUDE_BINARY_NAME,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    CLI_DESCRIPTION,
+    CREDENTIALS_FILE_NAME,
+    CWD_FLAG,
+    DEFAULT_PERMISSION_MODE,
+    DEFAULT_TIMEOUT_MINUTES,
+    INVALID_TIMEOUT_MESSAGE,
+    JSON_ACCOUNT_KEY,
+    JSON_CONFIG_DIRECTORY_KEY,
+    JSON_REASON_KEY,
+    LAUNCH_FAILURE_EXIT_CODE,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+    MISSING_BINARY_EXIT_CODE,
+    MINIMUM_TIMEOUT_MINUTES,
+    MODEL_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    OUTPUT_FORMAT_JSON,
+    PERMISSION_MODE_FLAG,
+    PROMPT_FILE_FLAG,
+    REPORT_FILE_FLAG,
+    SINGLE_PROMPT_FLAG,
+    TIMEOUT_MINUTES_FLAG,
+    UTF8_ENCODING,
+)
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+
+_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__, all_environment=os.environ
+)
+if str(_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_process_tree_scripts_directory))
+
+_process_tree_kill = importlib.import_module("process_tree_kill")
+_terminate_process_tree = _process_tree_kill.terminate_process_tree
+
+
+@dataclass(frozen=True)
+class AccountSelection:
+    account: str
+    config_dir: Path | None
+    reason: str
+
+
+@dataclass(frozen=True)
+class WorkerDependencies:
+    process_factory: Callable[..., WorkerProcess]
+    all_parent_environment_variables: Mapping[str, str]
+    binary_resolver: Callable[[str], str | None]
+    process_terminator: Callable[[WorkerProcess], None]
+    monotonic_clock: Callable[[], float]
+
+
+def _default_dependencies() -> WorkerDependencies:
+    return WorkerDependencies(
+        process_factory=subprocess.Popen,
+        all_parent_environment_variables=os.environ,
+        binary_resolver=shutil.which,
+        process_terminator=_terminate_process_tree,
+        monotonic_clock=time.monotonic,
+    )
+
+
+def _selection_from_payload(all_selection_payload: Mapping[str, str | None]) -> AccountSelection:
+    account = all_selection_payload[JSON_ACCOUNT_KEY]
+    reason = all_selection_payload[JSON_REASON_KEY]
+    config_dir_text = all_selection_payload[JSON_CONFIG_DIRECTORY_KEY]
+    if account is None or reason is None:
+        raise ValueError("account picker returned an incomplete decision")
+    return AccountSelection(
+        account=account,
+        config_dir=Path(config_dir_text) if config_dir_text is not None else None,
+        reason=reason,
+    )
+
+
+def select_account() -> AccountSelection:
+    """Pick the account this worker runs on and its Claude home directory.
+
+    Returns:
+        The chosen account, its Claude config directory, and the reason.
+
+    Raises:
+        ValueError: When the account picker returns an incomplete decision.
+    """
+    main_config_dir = Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME
+    second_config_dir = default_profile_home()
+    config_directory_by_account = {
+        CHOICE_MAIN: main_config_dir,
+        CHOICE_SECOND: second_config_dir,
+    }
+    main_meters = read_account_meters(main_config_dir / CREDENTIALS_FILE_NAME)
+    second_meters = read_account_meters(second_config_dir / CREDENTIALS_FILE_NAME)
+    decision = choose_account(
+        main_meters=main_meters, second_meters=second_meters, now=datetime.now().astimezone()
+    )
+    selected_config_dir = config_directory_by_account.get(decision.account)
+    payload = decision_payload(decision, config_directory=selected_config_dir)
+    return _selection_from_payload(payload)
+
+
+def _positive_timeout_minutes(candidate_text: str) -> int:
+    timeout_minutes = int(candidate_text)
+    if timeout_minutes < MINIMUM_TIMEOUT_MINUTES:
+        raise argparse.ArgumentTypeError(INVALID_TIMEOUT_MESSAGE)
+    return timeout_minutes
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser for one headless worker invocation.
+
+    Returns:
+        The configured argument parser.
+    """
+    parser = argparse.ArgumentParser(description=CLI_DESCRIPTION)
+    parser.add_argument(PROMPT_FILE_FLAG, type=Path, required=True)
+    parser.add_argument(CWD_FLAG, type=Path, default=Path.cwd())
+    parser.add_argument(REPORT_FILE_FLAG, type=Path, required=True)
+    parser.add_argument(MODEL_FLAG)
+    parser.add_argument(
+        PERMISSION_MODE_FLAG,
+        default=DEFAULT_PERMISSION_MODE,
+    )
+    parser.add_argument(
+        TIMEOUT_MINUTES_FLAG,
+        type=_positive_timeout_minutes,
+        default=DEFAULT_TIMEOUT_MINUTES,
+    )
+    return parser
+
+
+def _child_environment(
+    selection: AccountSelection,
+    all_environment_variables: Mapping[str, str],
+) -> dict[str, str]:
+    if selection.account not in (CHOICE_MAIN, CHOICE_SECOND):
+        raise ValueError(f"unsupported account selection: {selection.account}")
+    all_child_environment_variables = dict(all_environment_variables)
+    if selection.account == CHOICE_MAIN:
+        all_child_environment_variables.pop(CLAUDE_CONFIG_DIR_ENV_VAR, None)
+        return all_child_environment_variables
+    if selection.config_dir is None:
+        raise ValueError("second account selection needs a config directory")
+    all_child_environment_variables[CLAUDE_CONFIG_DIR_ENV_VAR] = str(selection.config_dir)
+    return all_child_environment_variables
+
+
+def _invocation(
+    executable: str,
+    *,
+    model: str | None,
+    permission_mode: str,
+) -> list[str]:
+    all_arguments = [
+        executable,
+        SINGLE_PROMPT_FLAG,
+        OUTPUT_FORMAT_FLAG,
+        OUTPUT_FORMAT_JSON,
+        PERMISSION_MODE_FLAG,
+        permission_mode,
+    ]
+    if model is not None:
+        all_arguments.extend([MODEL_FLAG, model])
+    return all_arguments
+
+
+def _prepared_launch(
+    selection: AccountSelection,
+    prompt_file: Path,
+    dependencies: WorkerDependencies,
+) -> tuple[dict[str, str], str, str] | WorkerReport:
+    try:
+        all_child_environment_variables = _child_environment(
+            selection, dependencies.all_parent_environment_variables
+        )
+        prompt_text = prompt_file.read_text(encoding=UTF8_ENCODING)
+    except (OSError, ValueError):
+        return pre_launch_failure_report(
+            selection.account, selection.reason, LAUNCH_FAILURE_EXIT_CODE
+        )
+    claude_binary = dependencies.binary_resolver(CLAUDE_BINARY_NAME)
+    if claude_binary is None:
+        return pre_launch_failure_report(
+            selection.account, selection.reason, MISSING_BINARY_EXIT_CODE
+        )
+    return all_child_environment_variables, prompt_text, claude_binary
+
+
+def _invoked_report(
+    selection: AccountSelection,
+    *,
+    all_arguments: list[str],
+    cwd: Path,
+    all_child_environment_variables: dict[str, str],
+    prompt_text: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    exit_code, duration_seconds, stdout_text = invoke_worker(
+        all_arguments=all_arguments,
+        cwd=cwd,
+        all_child_environment_variables=all_child_environment_variables,
+        prompt_text=prompt_text,
+        timeout_minutes=timeout_minutes,
+        controls=dependencies,
+    )
+    return make_report(
+        selection.account,
+        selection.reason,
+        exit_code=exit_code,
+        duration_seconds=duration_seconds,
+        stdout_text=stdout_text,
+    )
+
+
+def _worker_report(
+    selection: AccountSelection,
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    prepared = _prepared_launch(selection, prompt_file, dependencies)
+    if isinstance(prepared, WorkerReport):
+        return prepared
+    all_child_environment_variables, prompt_text, claude_binary = prepared
+    all_arguments = _invocation(claude_binary, model=model, permission_mode=permission_mode)
+    return _invoked_report(
+        selection,
+        all_arguments=all_arguments,
+        cwd=cwd,
+        all_child_environment_variables=all_child_environment_variables,
+        prompt_text=prompt_text,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+
+
+def _report_for_selection(
+    selection: AccountSelection,
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    dependencies: WorkerDependencies,
+) -> WorkerReport:
+    if selection.account == CHOICE_WAIT:
+        return wait_report(selection.account, selection.reason)
+    return _worker_report(
+        selection,
+        prompt_file=prompt_file,
+        cwd=cwd,
+        model=model,
+        permission_mode=permission_mode,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+
+
+def run_worker(
+    *,
+    prompt_file: Path,
+    cwd: Path,
+    report_file: Path,
+    model: str | None,
+    permission_mode: str,
+    timeout_minutes: int,
+    decision_selector: Callable[[], AccountSelection],
+    dependencies: WorkerDependencies,
+) -> int:
+    """Pick an account and run one headless Claude worker on it.
+
+    Args:
+        prompt_file, report_file: The prompt and report file paths.
+        decision_selector, dependencies: The picker and process controls.
+    Returns:
+        The exit code: 3 on wait, 124 on timeout, 127 on a missing binary,
+        or the child's own exit code.
+    """
+    report = _report_for_selection(
+        decision_selector(),
+        prompt_file=prompt_file,
+        cwd=cwd,
+        model=model,
+        permission_mode=permission_mode,
+        timeout_minutes=timeout_minutes,
+        dependencies=dependencies,
+    )
+    return finalize_report(report_file, report)
+
+
+def main() -> int:
+    """Parse CLI arguments and run one headless worker.
+
+    Returns:
+        The worker's exit code.
+    """
+    arguments = build_argument_parser().parse_args()
+    return run_worker(
+        prompt_file=arguments.prompt_file,
+        cwd=arguments.cwd,
+        report_file=arguments.report_file,
+        model=arguments.model,
+        permission_mode=arguments.permission_mode,
+        timeout_minutes=arguments.timeout_minutes,
+        decision_selector=select_account,
+        dependencies=_default_dependencies(),
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())