agent-cli 0.84.2__tar.gz → 0.86.0__tar.gz

{agent_cli-0.84.2/agent_cli/dev/skill → agent_cli-0.86.0/.claude/skills/agent-cli-dev}/SKILL.md

@@ -56,7 +56,7 @@ agent-cli dev new <branch-name> --from HEAD --agent --prompt-file path/to/prompt
 This creates:
 1. A new git worktree with its own branch
 2. Runs project setup (installs dependencies)
-3. Saves your prompt to `.claude/TASK.md` in the worktree (for reference)
+3. Saves your prompt to a unique task file in `.claude/` in the worktree (for reference)
 4. Opens a new terminal tab with an AI coding agent
 5. Passes your prompt to the agent
 
@@ -144,11 +144,12 @@ agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
+- Use `dev agent -a <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
 - Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
 - Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
 - If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
-- Do not rely on `.claude/TASK.md` as per-agent state in shared worktrees; later launches overwrite it
+- Each agent launch gets its own unique task file in `.claude/` (e.g., `TASK-{timestamp}-{hex}.md`), so parallel launches do not overwrite each other
 
 ### Prompt guidance for shared worktrees
 
@@ -174,7 +175,7 @@ agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
   --prompt-file .claude/validation-a.md
 ```
 
-This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command.
+This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
 
 ## Example: Multi-feature implementation
 

{agent_cli-0.84.2 → agent_cli-0.86.0}/.claude/skills/agent-cli-dev/examples.md

@@ -585,7 +585,7 @@ Write findings to .claude/REPORT-tests-$run_id.md:
 - If you rerun the same prompt often, include a timestamp or run id in the filename so reports do not get replaced
 - `-m tmux` works even when the caller is not already inside tmux
 - All three agents land in the same deterministic tmux session for that repo
-- `.claude/TASK.md` is shared state and may be overwritten by later launches, so keep prompt files outside that convention
+- Each agent launch gets its own unique task file in `.claude/`, so parallel launches do not conflict
 
 ## Scenario 7: Parallel test validation
 

{agent_cli-0.84.2/.claude → agent_cli-0.86.0/.claude-plugin}/skills/agent-cli-dev/SKILL.md

@@ -56,7 +56,7 @@ agent-cli dev new <branch-name> --from HEAD --agent --prompt-file path/to/prompt
 This creates:
 1. A new git worktree with its own branch
 2. Runs project setup (installs dependencies)
-3. Saves your prompt to `.claude/TASK.md` in the worktree (for reference)
+3. Saves your prompt to a unique task file in `.claude/` in the worktree (for reference)
 4. Opens a new terminal tab with an AI coding agent
 5. Passes your prompt to the agent
 
@@ -144,11 +144,12 @@ agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
 
 Key rules for same-worktree launches:
 - Use `dev agent`, not `dev new`, after the worktree already exists
+- Use `dev agent -a <agent>` to select a specific agent for an existing worktree; `--with-agent` remains a deprecated alias on this subcommand
 - Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
 - Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
 - Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
 - If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
-- Do not rely on `.claude/TASK.md` as per-agent state in shared worktrees; later launches overwrite it
+- Each agent launch gets its own unique task file in `.claude/` (e.g., `TASK-{timestamp}-{hex}.md`), so parallel launches do not overwrite each other
 
 ### Prompt guidance for shared worktrees
 
@@ -174,7 +175,7 @@ agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
   --prompt-file .claude/validation-a.md
 ```
 
-This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command.
+This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command. Launches may also run pre-launch preparation by default; use `--no-hooks` only when you explicitly need to bypass that behavior.
 
 ## Example: Multi-feature implementation
 

{agent_cli-0.84.2 → agent_cli-0.86.0}/.claude-plugin/skills/agent-cli-dev/examples.md

@@ -585,7 +585,7 @@ Write findings to .claude/REPORT-tests-$run_id.md:
 - If you rerun the same prompt often, include a timestamp or run id in the filename so reports do not get replaced
 - `-m tmux` works even when the caller is not already inside tmux
 - All three agents land in the same deterministic tmux session for that repo
-- `.claude/TASK.md` is shared state and may be overwritten by later launches, so keep prompt files outside that convention
+- Each agent launch gets its own unique task file in `.claude/`, so parallel launches do not conflict
 
 ## Scenario 7: Parallel test validation
 

{agent_cli-0.84.2 → agent_cli-0.86.0}/.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.6"
+    rev: "v0.15.7"
     hooks:
       - id: ruff
         args: ["--fix"]

{agent_cli-0.84.2 → agent_cli-0.86.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.84.2
+Version: 0.86.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>

{agent_cli-0.84.2 → agent_cli-0.86.0}/agent_cli/cli.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
 
 import typer
 from rich.table import Table
@@ -93,7 +93,7 @@ def main(
     set_process_title(ctx.invoked_subcommand)
 
 
-def set_config_defaults(ctx: typer.Context, config_file: str | None) -> None:
+def set_config_defaults(ctx: typer.Context, config_file: str | None) -> dict[str, Any]:
     """Set the default values for the CLI based on the config file."""
     config = load_config(config_file)
     wildcard_config = normalize_provider_defaults(config.get("defaults", {}))
@@ -101,7 +101,7 @@ def set_config_defaults(ctx: typer.Context, config_file: str | None) -> None:
     command_key = ctx.command.name or ""
     if not command_key:
         ctx.default_map = wildcard_config
-        return
+        return config
 
     # For nested subcommands (e.g., "memory proxy"), build "memory.proxy"
     if ctx.parent and ctx.parent.command.name and ctx.parent.command.name != "agent-cli":
@@ -109,6 +109,7 @@ def set_config_defaults(ctx: typer.Context, config_file: str | None) -> None:
 
     command_config = normalize_provider_defaults(config.get(command_key, {}))
     ctx.default_map = {**wildcard_config, **command_config}
+    return config
 
 
 # Import commands from other modules to register them

{agent_cli-0.84.2 → agent_cli-0.86.0}/agent_cli/config.py

@@ -264,6 +264,7 @@ class Dev(BaseModel):
 
     editor: bool = False
     agent: bool = False
+    auto_trust: bool = True
     direnv: bool | None = None
     default_agent: str | None = None
     default_editor: str | None = None

agent_cli-0.86.0/agent_cli/dev/_config.py

@@ -0,0 +1,59 @@
+"""Helpers for reading runtime dev configuration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from agent_cli.config import load_config
+
+
+def get_runtime_config() -> dict[str, Any]:
+    """Return the config dict active for the current CLI invocation."""
+    ctx = click.get_current_context(silent=True)
+    while ctx is not None:
+        if isinstance(ctx.obj, dict) and isinstance(ctx.obj.get("config"), dict):
+            return ctx.obj["config"]
+        ctx = ctx.parent
+    return load_config(None)
+
+
+def get_dev_config() -> dict[str, Any]:
+    """Return the `[dev]` config table for the current CLI invocation."""
+    dev_config = get_runtime_config().get("dev", {})
+    return dev_config if isinstance(dev_config, dict) else {}
+
+
+def get_dev_table(name: str) -> dict[str, Any]:
+    """Return a merged `[dev.<name>]` table from nested or flattened config."""
+    result: dict[str, Any] = {}
+
+    nested = get_dev_config().get(name)
+    if isinstance(nested, dict):
+        result.update(nested)
+
+    flat = get_runtime_config().get(f"dev.{name}")
+    if isinstance(flat, dict):
+        result.update(flat)
+
+    return result
+
+
+def get_dev_child_tables(name: str) -> dict[str, dict[str, Any]]:
+    """Return merged `[dev.<name>.<child>]` tables keyed by child name."""
+    result = {
+        child: value for child, value in get_dev_table(name).items() if isinstance(value, dict)
+    }
+
+    prefix = f"dev.{name}."
+    for key, value in get_runtime_config().items():
+        if key.startswith(prefix) and isinstance(value, dict):
+            result[key[len(prefix) :]] = value
+
+    return result
+
+
+def get_dev_child_table(name: str, child: str) -> dict[str, Any]:
+    """Return a single merged `[dev.<name>.<child>]` table."""
+    return get_dev_child_tables(name).get(child, {})

{agent_cli-0.84.2 → agent_cli-0.86.0}/agent_cli/dev/cli.py

@@ -23,6 +23,7 @@ from . import cleanup, coding_agents, editors, terminals, worktree
 from ._branch_name import AGENTS as BRANCH_NAME_AGENTS
 from ._branch_name import generate_ai_branch_name, generate_random_branch_name
 from ._output import error, info, success, warn
+from .hooks import LaunchContext, prepare_agent_launch
 from .launch import (
     get_agent_env,
     launch_agent,
@@ -83,7 +84,11 @@ def dev_callback(
     Creates isolated working directories for each feature branch. Each worktree
     has its own branch, allowing parallel development without stashing changes.
     """
-    set_config_defaults(ctx, config_file)
+    config = set_config_defaults(ctx, config_file)
+    if isinstance(ctx.obj, dict):
+        ctx.obj["config"] = config
+    else:
+        ctx.obj = {"config": config}
 
     # The [dev] section config is intended for `dev new` options.
     # Click expects subcommand defaults under ctx.default_map["new"].
@@ -368,7 +373,7 @@ def new(
         typer.Option(
             "--prompt",
             "-p",
-            help="Initial task for the AI agent. Saved to .claude/TASK.md. Implies --agent. Example: --prompt='Fix the login bug'",
+            help="Initial task for the AI agent. Saved to a unique file in .claude/ to avoid conflicts. Implies --agent. Example: --prompt='Fix the login bug'",
         ),
     ] = None,
     prompt_file: Annotated[
@@ -390,6 +395,13 @@ def new(
             help="Launch the agent in a specific multiplexer. Currently supported: tmux. When started outside tmux, creates or reuses a detached session and reports the pane handle",
         ),
     ] = None,
+    hooks: Annotated[
+        bool,
+        typer.Option(
+            "--hooks/--no-hooks",
+            help="Run built-in agent preparation (like Codex auto-trust) and configured pre-launch hooks before starting the agent",
+        ),
+    ] = True,
     verbose: Annotated[
         bool,
         typer.Option(
@@ -491,6 +503,18 @@ def new(
     if resolved_agent and resolved_agent.is_available():
         merged_args = merge_agent_args(resolved_agent, agent_args)
         agent_env = get_agent_env(resolved_agent)
+        prepare_agent_launch(
+            LaunchContext(
+                agent=resolved_agent,
+                worktree_path=result.path,
+                repo_root=repo_root,
+                branch=result.branch,
+                worktree_name=result.path.name,
+                task_file=task_file,
+                agent_env=agent_env,
+            ),
+            hooks_enabled=hooks,
+        )
         agent_handle = launch_agent(
             result.path,
             resolved_agent,
@@ -752,7 +776,9 @@ def status_cmd(  # noqa: PLR0915
 def remove(
     name: Annotated[
         str,
-        typer.Argument(help="Worktree to remove. Can be branch name or directory name"),
+        typer.Argument(
+            help="Worktree to remove. Can be branch name, directory name, or '.' for current"
+        ),
     ],
     force: Annotated[
         bool,
@@ -816,7 +842,9 @@ def remove(
 def path_cmd(
     name: Annotated[
         str,
-        typer.Argument(help="Worktree to get path for. Can be branch name or directory name"),
+        typer.Argument(
+            help="Worktree to get path for. Can be branch name, directory name, or '.' for current"
+        ),
     ],
 ) -> None:
     """Print the absolute path to a dev environment.
@@ -838,7 +866,9 @@ def path_cmd(
 def open_editor(
     name: Annotated[
         str,
-        typer.Argument(help="Worktree to open. Can be branch name or directory name"),
+        typer.Argument(
+            help="Worktree to open. Can be branch name, directory name, or '.' for current"
+        ),
     ],
     editor_name: Annotated[
         str | None,
@@ -887,7 +917,7 @@ def start_agent(
     name: Annotated[
         str,
         typer.Argument(
-            help="Worktree to start the agent in. Can be branch name or directory name",
+            help="Worktree to start the agent in. Can be branch name, directory name, or '.' for current",
         ),
     ],
     agent_name: Annotated[
@@ -898,6 +928,14 @@ def start_agent(
             help="Which agent: claude, codex, gemini, aider, copilot, cn, opencode, cursor-agent. Auto-detects if omitted",
         ),
     ] = None,
+    agent_name_deprecated: Annotated[
+        str | None,
+        typer.Option(
+            "--with-agent",
+            hidden=True,
+            help="[Deprecated: use --agent/-a] Which agent to start",
+        ),
+    ] = None,
     agent_args: Annotated[
         list[str] | None,
         typer.Option(
@@ -910,7 +948,7 @@ def start_agent(
         typer.Option(
             "--prompt",
             "-p",
-            help="Initial task for the agent. Saved to .claude/TASK.md. Example: --prompt='Add unit tests for auth'",
+            help="Initial task for the agent. Saved to a unique file in .claude/ to avoid conflicts. Example: --prompt='Add unit tests for auth'",
         ),
     ] = None,
     prompt_file: Annotated[
@@ -932,6 +970,13 @@ def start_agent(
             help="Launch the agent in a specific multiplexer instead of the current terminal. Currently supported: tmux",
         ),
     ] = None,
+    hooks: Annotated[
+        bool,
+        typer.Option(
+            "--hooks/--no-hooks",
+            help="Run built-in agent preparation (like Codex auto-trust) and configured pre-launch hooks before starting the agent",
+        ),
+    ] = True,
 ) -> None:
     """Start an AI coding agent in an existing dev environment.
 
@@ -944,6 +989,11 @@ def start_agent(
     - `dev agent my-feature -a claude` — Start Claude specifically
     - `dev agent my-feature -p "Continue the auth refactor"` — Start with a task
     """
+    # Handle deprecated --with-agent alias
+    if agent_name_deprecated is not None:
+        warn("--with-agent is deprecated for 'dev agent', use --agent/-a instead")
+        agent_name = agent_name or agent_name_deprecated
+
     prompt = _resolve_prompt_text(prompt, prompt_file=prompt_file)
 
     repo_root = _ensure_git_repo()
@@ -970,6 +1020,18 @@ def start_agent(
 
     merged_args = merge_agent_args(agent, agent_args)
     agent_env = get_agent_env(agent)
+    prepare_agent_launch(
+        LaunchContext(
+            agent=agent,
+            worktree_path=wt.path,
+            repo_root=repo_root,
+            branch=wt.branch,
+            worktree_name=wt.name,
+            task_file=task_file,
+            agent_env=agent_env,
+        ),
+        hooks_enabled=hooks,
+    )
 
     if multiplexer:
         handle = launch_agent(
@@ -1190,7 +1252,9 @@ def _doctor_check_git() -> None:
 def run_cmd(
     name: Annotated[
         str,
-        typer.Argument(help="Worktree to run command in. Can be branch name or directory name"),
+        typer.Argument(
+            help="Worktree to run command in. Can be branch name, directory name, or '.' for current"
+        ),
     ],
     command: Annotated[
         list[str],

{agent_cli-0.84.2 → agent_cli-0.86.0}/agent_cli/dev/coding_agents/base.py

@@ -117,6 +117,17 @@ class CodingAgent(ABC):
         """Get any additional environment variables needed."""
         return {}
 
+    def prepare_launch(
+        self,
+        worktree_path: Path,  # noqa: ARG002
+        repo_root: Path,  # noqa: ARG002
+    ) -> str | None:
+        """Perform any agent-specific preparation before launch.
+
+        Returns an optional human-readable message describing a change that was made.
+        """
+        return None
+
     def __repr__(self) -> str:  # noqa: D105
         status = "available" if self.is_available() else "not installed"
         return f"<{self.__class__.__name__} {self.name!r} ({status})>"

agent_cli-0.86.0/agent_cli/dev/coding_agents/codex.py

@@ -0,0 +1,92 @@
+"""OpenAI Codex CLI coding agent adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import CodingAgent
+
+CODEX_CONFIG_PATH = Path.home() / ".codex" / "config.toml"
+
+
+def _project_section_header(path: Path) -> str:
+    """Build the TOML section header for a trusted Codex project path."""
+    escaped = str(path).replace("\\", "\\\\").replace('"', '\\"')
+    return f'[projects."{escaped}"]'
+
+
+def _ensure_project_trusted(project_path: Path, config_path: Path | None = None) -> bool:
+    """Ensure Codex trusts the launched project path for headless launches.
+
+    Returns True when the config file was modified.
+    """
+    project_path = project_path.expanduser().resolve()
+    config_path = (config_path or CODEX_CONFIG_PATH).expanduser()
+    header = _project_section_header(project_path)
+    trust_line = 'trust_level = "trusted"'
+
+    if not config_path.exists():
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(f"{header}\n{trust_line}\n", encoding="utf-8")
+        return True
+
+    text = config_path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+
+    for idx, line in enumerate(lines):
+        if line.strip() != header:
+            continue
+
+        end = len(lines)
+        for j in range(idx + 1, len(lines)):
+            if lines[j].strip().startswith("[") and lines[j].strip().endswith("]"):
+                end = j
+                break
+
+        for j in range(idx + 1, end):
+            stripped = lines[j].strip()
+            if not stripped.startswith("trust_level"):
+                continue
+            if stripped == trust_line:
+                return False
+            msg = (
+                f"Codex trust for {project_path} is already configured in {config_path}. "
+                "Update that section or disable [dev].auto_trust."
+            )
+            raise RuntimeError(msg)
+
+        lines.insert(idx + 1, trust_line)
+        config_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return True
+
+    new_text = text.rstrip("\n")
+    if new_text:
+        new_text += "\n\n"
+    new_text += f"{header}\n{trust_line}\n"
+    config_path.write_text(new_text, encoding="utf-8")
+    return True
+
+
+class Codex(CodingAgent):
+    """OpenAI Codex CLI coding agent."""
+
+    name = "codex"
+    command = "codex"
+    install_url = "https://github.com/openai/codex"
+    detect_process_name = "codex"
+
+    def prompt_args(self, prompt: str) -> list[str]:
+        """Return prompt as positional argument.
+
+        Codex accepts prompt as a positional argument:
+        `codex "your prompt here"`
+
+        See: codex --help
+        """
+        return [prompt]
+
+    def prepare_launch(self, worktree_path: Path, repo_root: Path) -> str | None:  # noqa: ARG002
+        """Ensure Codex trusts the repository root before launch."""
+        if _ensure_project_trusted(repo_root, CODEX_CONFIG_PATH):
+            return f"Trusted {repo_root.resolve()} in Codex config"
+        return None

agent_cli-0.86.0/agent_cli/dev/hooks.py

@@ -0,0 +1,138 @@
+"""Launch preparation helpers for `agent-cli dev`."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ._config import get_dev_child_table, get_dev_config, get_dev_table
+from ._output import info
+
+if TYPE_CHECKING:
+    from .coding_agents.base import CodingAgent
+
+
+@dataclass(frozen=True)
+class LaunchContext:
+    """Context provided to built-in preparation and user hooks."""
+
+    agent: CodingAgent
+    worktree_path: Path
+    repo_root: Path
+    branch: str | None
+    worktree_name: str
+    task_file: Path | None
+    agent_env: dict[str, str]
+
+
+def _normalize_hook_commands(value: Any, *, config_key: str) -> list[str]:
+    """Normalize a hook config entry to a list of shell commands."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        msg = f"{config_key} must be a string or list of strings"
+        raise RuntimeError(msg)
+    commands = [item.strip() for item in value if item.strip()]
+    if len(commands) != len(value):
+        msg = f"{config_key} contains an empty command"
+        raise RuntimeError(msg)
+    return commands
+
+
+def _load_dev_hook_settings(agent_name: str) -> tuple[bool, list[str]]:
+    """Load auto-trust and pre-launch hook settings for an agent."""
+    auto_trust = bool(get_dev_config().get("auto_trust", True))
+    global_hooks = get_dev_table("hooks")
+    agent_hooks = get_dev_child_table("hooks", agent_name)
+
+    pre_launch_hooks = _normalize_hook_commands(
+        global_hooks.get("pre_launch"),
+        config_key="[dev.hooks].pre_launch",
+    )
+    pre_launch_hooks.extend(
+        _normalize_hook_commands(
+            agent_hooks.get("pre_launch"),
+            config_key=f"[dev.hooks.{agent_name}].pre_launch",
+        ),
+    )
+    return auto_trust, pre_launch_hooks
+
+
+def _build_hook_env(context: LaunchContext) -> dict[str, str]:
+    """Build the environment passed to pre-launch hooks."""
+    env = os.environ.copy()
+    env.update(context.agent_env)
+    env.update(
+        {
+            "AGENT_CLI_AGENT": context.agent.name,
+            "AGENT_CLI_WORKTREE": str(context.worktree_path),
+            "AGENT_CLI_REPO_ROOT": str(context.repo_root),
+            "AGENT_CLI_BRANCH": context.branch or "",
+            "AGENT_CLI_NAME": context.worktree_name,
+            "AGENT_CLI_TASK_FILE": str(context.task_file or ""),
+            # Keep the proposal name as an alias for compatibility.
+            "AGENT_CLI_PROMPT_FILE": str(context.task_file or ""),
+        },
+    )
+    return env
+
+
+def _resolve_hook_command(command: str) -> list[str]:
+    """Parse a configured hook command into argv."""
+    argv = shlex.split(command)
+    if not argv:
+        msg = "Hook command cannot be empty"
+        raise RuntimeError(msg)
+
+    first = Path(argv[0]).expanduser()
+    if argv[0].startswith("~") or "/" in argv[0]:
+        argv[0] = str(first)
+    return argv
+
+
+def _run_pre_launch_hook(command: str, context: LaunchContext) -> None:
+    """Run a single pre-launch hook."""
+    argv = _resolve_hook_command(command)
+    info(f"Running pre-launch hook: {command}")
+    try:
+        result = subprocess.run(
+            argv,
+            cwd=context.worktree_path,
+            env=_build_hook_env(context),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as e:
+        msg = f"Pre-launch hook not found: {argv[0]}"
+        raise RuntimeError(msg) from e
+
+    if result.returncode == 0:
+        return
+
+    details = (result.stderr or result.stdout).strip()
+    msg = f"Pre-launch hook failed ({result.returncode}): {command}"
+    if details:
+        msg += f"\n{details}"
+    raise RuntimeError(msg)
+
+
+def prepare_agent_launch(context: LaunchContext, *, hooks_enabled: bool = True) -> None:
+    """Run built-in preparation and configured pre-launch hooks."""
+    if not hooks_enabled:
+        return
+
+    auto_trust, pre_launch_hooks = _load_dev_hook_settings(context.agent.name)
+    if auto_trust and (
+        message := context.agent.prepare_launch(context.worktree_path, context.repo_root)
+    ):
+        info(message)
+
+    for command in pre_launch_hooks:
+        _run_pre_launch_hook(command, context)