subagent-cli 0.1.2__tar.gz → 0.1.3__tar.gz

subagent_cli-0.1.3/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: subagent-cli
+Version: 0.1.3
+Summary: Protocol-agnostic worker orchestration CLI
+Author: niitsuma-t
+License: MIT License
+        
+        Copyright (c) 2026 niitsuma-t
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: acp,agent,automation,cli,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# subagent-cli
+
+[![PyPI version](https://img.shields.io/pypi/v/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![License](https://img.shields.io/github/license/otakumesi/subagent-cli)](LICENSE)
+[![Publish to PyPI](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml/badge.svg)](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml)
+[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/subagent-cli/)
+
+Orchestrate worker agents from a parent controller, cleanly and safely.  
+`subagent-cli` gives manager agents (for example Codex or Claude Code) a practical control plane for starting workers, sending turns, handling approvals, and continuing handoffs. 🤖
+
+The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
+
+## Why subagent-cli? 🚀
+- Run multi-agent workflows from one place (`worker start` to `worker continue`).
+- Keep control explicit with strict approval operations and structured event flow.
+- Recover cleanly with runtime restart + session resume (`session/load`).
+- Stay local-first and scriptable with a single CLI surface.
+
+## Current Scope 🧭
+- Alpha (`v0.1.x`)
+- Local single-host focused
+- Python 3.11+
+
+## Features ✨
+- Worker lifecycle: `start`, `list`, `show`, `inspect`, `stop`
+- Turn operations: `send`, `watch`, `wait`, `approve`, `cancel`
+- Handoff workflow: `worker handoff` and `worker continue`
+- Strict approval flow with structured events
+- ACP runtime integration (`acp-stdio`)
+
+## Install 📦
+With `uv` (recommended):
+```bash
+uv tool install subagent-cli
+```
+
+From PyPI:
+```bash
+pip install subagent-cli
+```
+
+From local artifacts:
+```bash
+pip install dist/subagent_cli-*.whl
+```
+
+## Quick Start ⚡
+1. Bootstrap your local config.
+```bash
+subagent config init --scope user
+```
+
+2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
+
+3. Initialize a controller in your workspace.
+```bash
+subagent controller init --cwd .
+```
+
+4. Render manager guidance.
+```bash
+subagent prompt render --target manager
+```
+
+5. Hand off from here to your manager agent (Codex / Claude Code).  
+Use this instruction template:
+
+```text
+Act as the project manager for this repository.
+Use subagent-cli as the control plane and progress this task by delegating to worker agents.
+
+Required workflow:
+1) Read and follow the output of `subagent prompt render --target manager`.
+2) Check command help before execution (for example `subagent worker --help`, `subagent send --help`, `subagent approve --help`).
+3) Break the task into small executable chunks.
+4) Start/coordinate workers with subagent-cli.
+5) Use send/watch/wait/approve to drive each turn.
+6) Use handoff/continue when context gets large.
+7) Verify results (tests or checks) before reporting completion.
+
+Task to execute:
+<your task here>
+```
+
+After handoff, the manager agent is expected to run the normal CLI lifecycle:
+`worker start` -> `send` -> `watch` -> `approve` -> `handoff` -> `continue`
+
+For local simulation/testing without a real ACP launcher:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Troubleshooting 🛠️
+- Ensure the runtime has the permissions required by your launcher (some launchers need outbound network access).
+- Preflight launcher availability:
+```bash
+subagent launcher probe <launcher-name> --json
+```
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `~/.local/share/subagent/runtimes/` (or `$SUBAGENT_STATE_DIR/runtimes/` when overridden).
+- For cut-down local testing without backend connectivity:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Configuration ⚙️
+- Resolution order: `--config` > `SUBAGENT_CONFIG` > nearest `<cwd-or-parent>/.subagent/config.yaml` > `~/.config/subagent/config.yaml`
+- Generate user config: `subagent config init --scope user`
+- Generate project config: `subagent config init --scope project --cwd .`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+
+## State 💾
+- Default state DB: `~/.local/share/subagent/state.db`
+- Project hint file: `<workspace>/.subagent/controller.json`
+
+## Documentation 📚
+- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Examples: [docs/examples](docs/examples)
+- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+MIT ([LICENSE](LICENSE))

subagent_cli-0.1.3/README.md

@@ -0,0 +1,123 @@
+# subagent-cli
+
+[![PyPI version](https://img.shields.io/pypi/v/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/subagent-cli)](https://pypi.org/project/subagent-cli/)
+[![License](https://img.shields.io/github/license/otakumesi/subagent-cli)](LICENSE)
+[![Publish to PyPI](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml/badge.svg)](https://github.com/otakumesi/subagent-cli/actions/workflows/publish-pypi.yml)
+[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/subagent-cli/)
+
+Orchestrate worker agents from a parent controller, cleanly and safely.  
+`subagent-cli` gives manager agents (for example Codex or Claude Code) a practical control plane for starting workers, sending turns, handling approvals, and continuing handoffs. 🤖
+
+The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
+
+## Why subagent-cli? 🚀
+- Run multi-agent workflows from one place (`worker start` to `worker continue`).
+- Keep control explicit with strict approval operations and structured event flow.
+- Recover cleanly with runtime restart + session resume (`session/load`).
+- Stay local-first and scriptable with a single CLI surface.
+
+## Current Scope 🧭
+- Alpha (`v0.1.x`)
+- Local single-host focused
+- Python 3.11+
+
+## Features ✨
+- Worker lifecycle: `start`, `list`, `show`, `inspect`, `stop`
+- Turn operations: `send`, `watch`, `wait`, `approve`, `cancel`
+- Handoff workflow: `worker handoff` and `worker continue`
+- Strict approval flow with structured events
+- ACP runtime integration (`acp-stdio`)
+
+## Install 📦
+With `uv` (recommended):
+```bash
+uv tool install subagent-cli
+```
+
+From PyPI:
+```bash
+pip install subagent-cli
+```
+
+From local artifacts:
+```bash
+pip install dist/subagent_cli-*.whl
+```
+
+## Quick Start ⚡
+1. Bootstrap your local config.
+```bash
+subagent config init --scope user
+```
+
+2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
+
+3. Initialize a controller in your workspace.
+```bash
+subagent controller init --cwd .
+```
+
+4. Render manager guidance.
+```bash
+subagent prompt render --target manager
+```
+
+5. Hand off from here to your manager agent (Codex / Claude Code).  
+Use this instruction template:
+
+```text
+Act as the project manager for this repository.
+Use subagent-cli as the control plane and progress this task by delegating to worker agents.
+
+Required workflow:
+1) Read and follow the output of `subagent prompt render --target manager`.
+2) Check command help before execution (for example `subagent worker --help`, `subagent send --help`, `subagent approve --help`).
+3) Break the task into small executable chunks.
+4) Start/coordinate workers with subagent-cli.
+5) Use send/watch/wait/approve to drive each turn.
+6) Use handoff/continue when context gets large.
+7) Verify results (tests or checks) before reporting completion.
+
+Task to execute:
+<your task here>
+```
+
+After handoff, the manager agent is expected to run the normal CLI lifecycle:
+`worker start` -> `send` -> `watch` -> `approve` -> `handoff` -> `continue`
+
+For local simulation/testing without a real ACP launcher:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Troubleshooting 🛠️
+- Ensure the runtime has the permissions required by your launcher (some launchers need outbound network access).
+- Preflight launcher availability:
+```bash
+subagent launcher probe <launcher-name> --json
+```
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `~/.local/share/subagent/runtimes/` (or `$SUBAGENT_STATE_DIR/runtimes/` when overridden).
+- For cut-down local testing without backend connectivity:
+```bash
+subagent worker start --cwd . --debug-mode
+```
+
+## Configuration ⚙️
+- Resolution order: `--config` > `SUBAGENT_CONFIG` > nearest `<cwd-or-parent>/.subagent/config.yaml` > `~/.config/subagent/config.yaml`
+- Generate user config: `subagent config init --scope user`
+- Generate project config: `subagent config init --scope project --cwd .`
+- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
+- Example config: [config.example.yaml](config.example.yaml)
+
+## State 💾
+- Default state DB: `~/.local/share/subagent/state.db`
+- Project hint file: `<workspace>/.subagent/controller.json`
+
+## Documentation 📚
+- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Examples: [docs/examples](docs/examples)
+- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+MIT ([LICENSE](LICENSE))

{subagent_cli-0.1.2 → subagent_cli-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subagent-cli"
-version = "0.1.2"
+version = "0.1.3"
 description = "Protocol-agnostic worker orchestration CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{subagent_cli-0.1.2 → subagent_cli-0.1.3}/src/subagent/__init__.py

@@ -2,6 +2,6 @@
 
 from .constants import SCHEMA_VERSION
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = ["SCHEMA_VERSION", "__version__"]

{subagent_cli-0.1.2 → subagent_cli-0.1.3}/src/subagent/cli.py

@@ -10,6 +10,7 @@ import click
 import typer
 
 from .config import SubagentConfig, load_config
+from .constants import PROJECT_HINT_DIRNAME
 from .controller_service import (
     attach_controller,
     init_controller,
@@ -31,7 +32,7 @@ from .input_contract import (
 )
 from .launcher_service import probe_launcher
 from .output import emit_error_and_exit, emit_json, ok_envelope
-from .paths import resolve_workspace_path
+from .paths import resolve_config_path, resolve_workspace_path
 from .prompt_service import render_prompt
 from .state import StateStore
 from .turn_service import approve_request, cancel_turn, send_message, wait_for_event, watch_events
@@ -40,12 +41,17 @@ from .worker_service import inspect_worker, list_workers, show_worker, start_wor
 app = typer.Typer(
     help=(
         "subagent: protocol-agnostic worker orchestration CLI\n"
-        "If you are a manager agent, start with: `subagent prompt render --target manager`"
+        "If you were instructed to use this tool as a manager agent, "
+        "start with: `subagent prompt render --target manager`\n"
+        "Tip: `subagent worker start`, `subagent send`, `subagent wait`, and "
+        "`subagent watch` may require running outside your sandbox "
+        "or with elevated permissions, depending on launcher/runtime policy."
     )
 )
 launcher_app = typer.Typer(help="Manage launcher registry from config")
 profile_app = typer.Typer(help="Manage profile registry from config")
 pack_app = typer.Typer(help="Manage pack registry from config")
+config_app = typer.Typer(help="Manage config files")
 prompt_app = typer.Typer(help="Render manager/worker prompts")
 controller_app = typer.Typer(help="Manage controller ownership")
 worker_app = typer.Typer(help="Manage worker lifecycle")
@@ -53,6 +59,7 @@ worker_app = typer.Typer(help="Manage worker lifecycle")
 app.add_typer(launcher_app, name="launcher")
 app.add_typer(profile_app, name="profile")
 app.add_typer(pack_app, name="pack")
+app.add_typer(config_app, name="config")
 app.add_typer(prompt_app, name="prompt")
 app.add_typer(controller_app, name="controller")
 app.add_typer(worker_app, name="worker")
@@ -65,6 +72,121 @@ def _load_config_or_exit(config_path: Path | None, *, json_output: bool) -> Suba
         emit_error_and_exit(error, json_output=json_output)
 
 
+_DEFAULT_CONFIG_TEMPLATE = """launchers:
+  codex:
+    backend:
+      kind: acp-stdio
+    command: codex-acp
+    args: []
+    env: {}
+
+  claude-code:
+    backend:
+      kind: acp-stdio
+    command: claude-code-acp
+    args: []
+    env: {}
+
+profiles:
+  worker-default:
+    promptLanguage: en
+    responseLanguage: same_as_manager
+    autoHandoff: turn_end
+    policyPreset: safe-default
+    defaultPacks:
+      - repo-conventions
+    bootstrap: |
+      You are a worker subagent.
+      Use STATUS:, ASK:, BLOCKED:, and DONE: prefixes when helpful.
+      Keep messages concise and actionable.
+
+packs:
+  repo-conventions:
+    description: Follow repository coding conventions and keep diffs small.
+    prompt: |
+      Read existing conventions before editing.
+      Prefer minimal, explicit changes.
+
+  python-test-fix:
+    description: Fix flaky Python tests with minimal change scope.
+    prompt: |
+      Reproduce failing tests first.
+      Add regression coverage where practical.
+
+policyPresets:
+  safe-default:
+    filesystem: workspace-write
+    network: ask
+    dangerousCommands: deny
+
+defaults:
+  launcher: codex
+  profile: worker-default
+  packs:
+    - repo-conventions
+"""
+
+
+def _default_project_config_path(cwd: Path) -> Path:
+    return resolve_workspace_path(cwd) / PROJECT_HINT_DIRNAME / "config.yaml"
+
+
+@config_app.command("init")
+def config_init(
+    scope: str = typer.Option(
+        "user",
+        "--scope",
+        help="Config target scope: user or project.",
+    ),
+    cwd: Path = typer.Option(Path("."), "--cwd", help="Workspace root for project scope"),
+    path: Path | None = typer.Option(None, "--path", help="Explicit output path override"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing file"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON envelope."),
+) -> None:
+    normalized_scope = scope.strip().lower()
+    if normalized_scope not in {"user", "project"}:
+        emit_error_and_exit(
+            SubagentError(
+                code="INVALID_ARGUMENT",
+                message="`--scope` must be one of: user, project",
+                details={"scope": scope},
+            ),
+            json_output=json_output,
+        )
+
+    if path is not None:
+        target_path = path.expanduser().resolve()
+    elif normalized_scope == "project":
+        target_path = _default_project_config_path(cwd)
+    else:
+        target_path = resolve_config_path(prefer_project=False)
+
+    existed = target_path.exists()
+    if existed and not force:
+        emit_error_and_exit(
+            SubagentError(
+                code="CONFIG_ALREADY_EXISTS",
+                message=f"Config already exists: {target_path}",
+                details={"path": str(target_path)},
+            ),
+            json_output=json_output,
+        )
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_text(_DEFAULT_CONFIG_TEMPLATE, encoding="utf-8")
+
+    payload = {
+        "path": str(target_path),
+        "scope": normalized_scope,
+        "overwritten": existed,
+    }
+    if json_output:
+        emit_json(ok_envelope("config.initialized", payload))
+    else:
+        typer.echo(f"configPath: {target_path}")
+        typer.echo(f"scope: {normalized_scope}")
+
+
 def _store() -> StateStore:
     store = StateStore()
     store.bootstrap()
@@ -550,7 +672,13 @@ def controller_release(
         typer.echo(f"released: {payload['released']}")
 
 
-@app.command("send")
+@app.command(
+    "send",
+    help=(
+        "Send a turn to a worker. "
+        "In sandboxed manager environments, this may need outside-sandbox execution."
+    ),
+)
 def send(
     ctx: typer.Context,
     worker_id: str | None = typer.Option(None, "--worker", help="Worker ID"),
@@ -637,7 +765,13 @@ def send(
         typer.echo(f"state: {payload['state']}")
 
 
-@app.command("watch")
+@app.command(
+    "watch",
+    help=(
+        "Watch worker events. "
+        "In sandboxed manager environments, this may need outside-sandbox execution."
+    ),
+)
 def watch(
     worker_id: str = typer.Option(..., "--worker", help="Worker ID"),
     from_event_id: str | None = typer.Option(None, "--from-event-id", help="Cursor event ID"),
@@ -693,7 +827,13 @@ def watch(
         return
 
 
-@app.command("wait")
+@app.command(
+    "wait",
+    help=(
+        "Wait for a worker event. "
+        "In sandboxed manager environments, this may need outside-sandbox execution."
+    ),
+)
 def wait(
     ctx: typer.Context,
     worker_id: str | None = typer.Option(None, "--worker", help="Worker ID"),
@@ -869,7 +1009,8 @@ def cancel(
     help=(
         "Start a worker runtime. "
         "Tip: run `subagent launcher probe <launcher-name> --json` first and ensure "
-        "launcher-required permissions (including network access) are available."
+        "launcher-required permissions (including network access) are available. "
+        "In sandboxed manager environments, this may need outside-sandbox execution."
     ),
 )
 def worker_start(

{subagent_cli-0.1.2 → subagent_cli-0.1.3}/src/subagent/paths.py

@@ -21,12 +21,25 @@ def resolve_workspace_path(cwd: Path | None = None) -> Path:
     return (cwd or Path.cwd()).expanduser().resolve()
 
 
-def resolve_config_path(config_path: Path | None = None) -> Path:
+def _discover_project_config_path(cwd: Path | None = None) -> Path | None:
+    start = resolve_workspace_path(cwd)
+    for current in [start, *start.parents]:
+        candidate = current / PROJECT_HINT_DIRNAME / "config.yaml"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def resolve_config_path(config_path: Path | None = None, *, prefer_project: bool = True) -> Path:
     if config_path is not None:
         return config_path.expanduser().resolve()
     env_value = os.environ.get(ENV_CONFIG_PATH)
     if env_value:
         return Path(env_value).expanduser().resolve()
+    if prefer_project:
+        discovered = _discover_project_config_path()
+        if discovered is not None:
+            return discovered
     return DEFAULT_CONFIG_PATH
 
 

{subagent_cli-0.1.2 → subagent_cli-0.1.3}/tests/test_cli_phase1.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import tempfile
 import unittest
 from pathlib import Path
@@ -89,10 +90,90 @@ class CLIPhase1Tests(unittest.TestCase):
         self.assertEqual(pack_payload["type"], "pack.listed")
         self.assertEqual(pack_payload["data"]["count"], 1)
 
+    def test_config_init_creates_file_and_requires_force_to_overwrite(self) -> None:
+        config_out = self.root / "generated" / "config.yaml"
+
+        first = self.invoke(
+            ["config", "init", "--path", str(config_out), "--json"],
+        )
+        self.assertEqual(first.exit_code, 0)
+        first_payload = json.loads(first.stdout)
+        self.assertEqual(first_payload["type"], "config.initialized")
+        self.assertEqual(Path(first_payload["data"]["path"]).resolve(), config_out.resolve())
+        self.assertEqual(first_payload["data"]["scope"], "user")
+        self.assertFalse(first_payload["data"]["overwritten"])
+        self.assertTrue(config_out.exists())
+        generated = config_out.read_text(encoding="utf-8")
+        self.assertIn("launchers:", generated)
+        self.assertIn("profiles:", generated)
+        self.assertIn("defaults:", generated)
+
+        second = self.invoke(
+            ["config", "init", "--path", str(config_out), "--json"],
+        )
+        self.assertEqual(second.exit_code, 1)
+        second_payload = json.loads(second.stdout)
+        self.assertEqual(second_payload["error"]["code"], "CONFIG_ALREADY_EXISTS")
+
+        third = self.invoke(
+            ["config", "init", "--path", str(config_out), "--force", "--json"],
+        )
+        self.assertEqual(third.exit_code, 0)
+        third_payload = json.loads(third.stdout)
+        self.assertTrue(third_payload["data"]["overwritten"])
+
+    def test_config_init_project_scope_writes_under_workspace(self) -> None:
+        result = self.invoke(
+            ["config", "init", "--scope", "project", "--cwd", str(self.workspace), "--json"],
+        )
+        self.assertEqual(result.exit_code, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["type"], "config.initialized")
+        expected = self.workspace / ".subagent" / "config.yaml"
+        self.assertEqual(Path(payload["data"]["path"]).resolve(), expected.resolve())
+        self.assertEqual(payload["data"]["scope"], "project")
+        self.assertTrue(expected.exists())
+
     def test_root_help_mentions_manager_prompt_bootstrap(self) -> None:
         result = self.invoke(["--help"])
         self.assertEqual(result.exit_code, 0)
-        self.assertIn("prompt render --target manager", result.stdout)
+        self.assertIn("instructed to", result.stdout)
+        self.assertIn("use this tool as a manager agent", result.stdout)
+        self.assertIn("subagent prompt render --target", result.stdout)
+        self.assertIn("outside your sandbox", result.stdout)
+        self.assertIn("or with elevated", result.stdout)
+        self.assertIn("permissions, depending on launcher/runtime policy", result.stdout)
+
+    def test_worker_start_help_mentions_sandbox_permissions(self) -> None:
+        result = self.invoke(["worker", "start", "--help"])
+        self.assertEqual(result.exit_code, 0)
+        self.assertIn("outside-sandbox execution", result.stdout)
+
+    def test_send_wait_watch_help_mentions_sandbox_permissions(self) -> None:
+        for args in (["send", "--help"], ["wait", "--help"], ["watch", "--help"]):
+            result = self.invoke(args)
+            self.assertEqual(result.exit_code, 0)
+            self.assertIn("outside-sandbox execution", result.stdout)
+
+    def test_project_config_is_auto_discovered_from_workspace(self) -> None:
+        project_config = self.workspace / ".subagent" / "config.yaml"
+        project_config.parent.mkdir(parents=True, exist_ok=True)
+        project_config.write_text(
+            SAMPLE_CONFIG.replace("codex-acp", "project-codex-acp").strip() + "\n",
+            encoding="utf-8",
+        )
+
+        original_cwd = Path.cwd()
+        os.chdir(self.workspace)
+        try:
+            result = self.invoke(["launcher", "show", "codex", "--json"], env={"SUBAGENT_CONFIG": ""})
+        finally:
+            os.chdir(original_cwd)
+
+        self.assertEqual(result.exit_code, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["type"], "launcher.shown")
+        self.assertEqual(payload["data"]["command"], "project-codex-acp")
 
     def test_controller_init_and_status_with_valid_env_handle(self) -> None:
         init_result = self.invoke(

subagent_cli-0.1.2/PKG-INFO

@@ -1,107 +0,0 @@
-Metadata-Version: 2.4
-Name: subagent-cli
-Version: 0.1.2
-Summary: Protocol-agnostic worker orchestration CLI
-Author: niitsuma-t
-License: MIT License
-        
-        Copyright (c) 2026 niitsuma-t
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Keywords: acp,agent,automation,cli,orchestration
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Utilities
-Requires-Python: >=3.11
-Requires-Dist: typer>=0.24.1
-Description-Content-Type: text/markdown
-
-# subagent-cli
-
-`subagent-cli` is a protocol-agnostic CLI for orchestrating worker agents from a parent controller.
-In practice, it is a control-plane CLI that a manager agent (for example Codex or Claude Code) can use to launch and coordinate other worker agents.
-The CLI surface is protocol-agnostic, while the current runtime implementation is ACP-based (`acp-stdio`).
-
-## Status
-- Alpha (`v0.1.x`)
-- Local single-host focused
-- Python 3.11+
-
-## Features
-- Worker lifecycle: start, list, show, inspect, stop
-- Turn operations: send, watch, wait, approve, cancel
-- Handoff workflow: `worker handoff` and `worker continue`
-- Strict approval flow with structured events
-- ACP runtime integration (`acp-stdio`) with runtime restart + session resume (`session/load`)
-
-## Install
-- From PyPI:
-`pip install subagent-cli`
-- From local artifacts:
-`pip install dist/subagent_cli-*.whl`
-
-## Quick Start
-1. Prepare config:
-`mkdir -p ~/.config/subagent && cp config.example.yaml ~/.config/subagent/config.yaml`
-2. Initialize a controller in your workspace:
-`subagent controller init --cwd .`
-3. Start a worker:
-`subagent worker start --cwd .`
-4. Send an instruction:
-`subagent send --worker <worker-id> --text "Investigate failing tests"`
-5. Watch events:
-`subagent watch --worker <worker-id> --ndjson`
-
-For local simulation/testing without a real ACP launcher:
-`subagent worker start --cwd . --debug-mode`
-
-## Troubleshooting
-- Ensure the runtime has the permissions required by your launcher. Some launchers need outbound network access.
-- Preflight launcher availability:
-`subagent launcher probe <launcher-name> --json`
-- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under:
-`~/.local/share/subagent/runtimes/` (or `$SUBAGENT_STATE_DIR/runtimes/` when overridden)
-- For local cut-down testing without backend connectivity, use:
-`subagent worker start --cwd . --debug-mode`
-
-## Configuration
-- Default config path: `~/.config/subagent/config.yaml`
-- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
-- Example config: [config.example.yaml](config.example.yaml)
-
-## State
-- Default state DB: `~/.local/share/subagent/state.db`
-- Project hint file: `<workspace>/.subagent/controller.json`
-
-## Documentation
-- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-- Examples: [docs/examples](docs/examples)
-- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
-
-## License
-MIT ([LICENSE](LICENSE))

subagent_cli-0.1.2/README.md

@@ -1,64 +0,0 @@
-# subagent-cli
-
-`subagent-cli` is a protocol-agnostic CLI for orchestrating worker agents from a parent controller.
-In practice, it is a control-plane CLI that a manager agent (for example Codex or Claude Code) can use to launch and coordinate other worker agents.
-The CLI surface is protocol-agnostic, while the current runtime implementation is ACP-based (`acp-stdio`).
-
-## Status
-- Alpha (`v0.1.x`)
-- Local single-host focused
-- Python 3.11+
-
-## Features
-- Worker lifecycle: start, list, show, inspect, stop
-- Turn operations: send, watch, wait, approve, cancel
-- Handoff workflow: `worker handoff` and `worker continue`
-- Strict approval flow with structured events
-- ACP runtime integration (`acp-stdio`) with runtime restart + session resume (`session/load`)
-
-## Install
-- From PyPI:
-`pip install subagent-cli`
-- From local artifacts:
-`pip install dist/subagent_cli-*.whl`
-
-## Quick Start
-1. Prepare config:
-`mkdir -p ~/.config/subagent && cp config.example.yaml ~/.config/subagent/config.yaml`
-2. Initialize a controller in your workspace:
-`subagent controller init --cwd .`
-3. Start a worker:
-`subagent worker start --cwd .`
-4. Send an instruction:
-`subagent send --worker <worker-id> --text "Investigate failing tests"`
-5. Watch events:
-`subagent watch --worker <worker-id> --ndjson`
-
-For local simulation/testing without a real ACP launcher:
-`subagent worker start --cwd . --debug-mode`
-
-## Troubleshooting
-- Ensure the runtime has the permissions required by your launcher. Some launchers need outbound network access.
-- Preflight launcher availability:
-`subagent launcher probe <launcher-name> --json`
-- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under:
-`~/.local/share/subagent/runtimes/` (or `$SUBAGENT_STATE_DIR/runtimes/` when overridden)
-- For local cut-down testing without backend connectivity, use:
-`subagent worker start --cwd . --debug-mode`
-
-## Configuration
-- Default config path: `~/.config/subagent/config.yaml`
-- Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
-- Example config: [config.example.yaml](config.example.yaml)
-
-## State
-- Default state DB: `~/.local/share/subagent/state.db`
-- Project hint file: `<workspace>/.subagent/controller.json`
-
-## Documentation
-- Architecture note: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-- Examples: [docs/examples](docs/examples)
-- Contributing and release process: [CONTRIBUTING.md](CONTRIBUTING.md)
-
-## License
-MIT ([LICENSE](LICENSE))