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

{subagent_cli-0.1.3 → subagent_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subagent-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: Protocol-agnostic worker orchestration CLI
 Author: niitsuma-t
 License: MIT License
@@ -49,8 +49,8 @@ Description-Content-Type: text/markdown
 [![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. 🤖
+Orchestrate coding agents from another coding agent, cleanly and safely.  
+`subagent-cli` turns a manager coding agent (for example Codex or Claude Code) into a practical control plane for starting worker coding agents, sending turns, handling approvals, and continuing handoffs. 🤖
 
 The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
 
@@ -96,38 +96,52 @@ subagent config init --scope user
 
 2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
 
-3. Initialize a controller in your workspace.
+3. Initialize a controller in your workspace (run once per workspace, by you or your manager agent).
 ```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).  
+4. Hand off from here to your manager agent (Codex / Claude Code).  
+Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
 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.
+If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
 
 Required workflow:
-1) Read and follow the output of `subagent prompt render --target manager`.
+1) First, run `subagent prompt render --target manager` and follow that output.
 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.
+5) Use `send` as the default turn driver (`send` waits by default).
+6) If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
+7) Use `watch` only when detailed event streaming/debugging is needed.
+8) Use handoff/continue when context gets large.
+9) 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`
+After handoff, the manager agent's standard lifecycle is:
+`worker start` -> `send` -> (`approve` -> `send` as needed) -> `handoff` -> `continue`
+
+For a single command that sends and waits for terminal-or-approval events:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --json
+```
+
+Opt out of waiting when needed:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+```
+
+Manual wait mode (advanced cursor control) still exists:
+```bash
+subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+```
 
 For local simulation/testing without a real ACP launcher:
 ```bash
@@ -135,12 +149,14 @@ subagent worker start --cwd . --debug-mode
 ```
 
 ## Troubleshooting 🛠️
-- Ensure the runtime has the permissions required by your launcher (some launchers need outbound network access).
+- Ensure both the runtime and your manager/worker agent sandbox allow what your launcher needs.
+- Some launchers require outbound network access, but agent sandbox policies can block network even when the host machine itself has connectivity.
+- If state path resolution fails, run commands from inside your workspace root (or set `SUBAGENT_STATE_DIR` explicitly).
 - 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).
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
 - For cut-down local testing without backend connectivity:
 ```bash
 subagent worker start --cwd . --debug-mode
@@ -150,11 +166,15 @@ subagent worker start --cwd . --debug-mode
 - 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 .`
+- `config init` defaults: `codex` -> `npx -y @zed-industries/codex-acp`, `claude-code` -> `npx -y @zed-industries/claude-agent-acp`
 - Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
 - Example config: [config.example.yaml](config.example.yaml)
+- Launchers support either split style (`command: npx`, `args: ["-y", "..."]`) or inline style (`command: "npx -y ..."`) for probe/start/restart.
 
 ## State 💾
-- Default state DB: `~/.local/share/subagent/state.db`
+- Default state DB: `<workspace>/.subagent/state/state.db`
+- Override state dir: `SUBAGENT_STATE_DIR=/path/to/state-dir`
+- If workspace root cannot be detected and no override is set, commands fail with `WORKSPACE_ROOT_NOT_FOUND`
 - Project hint file: `<workspace>/.subagent/controller.json`
 
 ## Documentation 📚

{subagent_cli-0.1.3 → subagent_cli-0.1.4}/README.md

@@ -6,8 +6,8 @@
 [![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. 🤖
+Orchestrate coding agents from another coding agent, cleanly and safely.  
+`subagent-cli` turns a manager coding agent (for example Codex or Claude Code) into a practical control plane for starting worker coding agents, sending turns, handling approvals, and continuing handoffs. 🤖
 
 The command interface is protocol-agnostic, and the current runtime backend is ACP-based (`acp-stdio`).
 
@@ -53,38 +53,52 @@ subagent config init --scope user
 
 2. Set launcher command/args/env in `~/.config/subagent/config.yaml`.
 
-3. Initialize a controller in your workspace.
+3. Initialize a controller in your workspace (run once per workspace, by you or your manager agent).
 ```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).  
+4. Hand off from here to your manager agent (Codex / Claude Code).  
+Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
 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.
+If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
 
 Required workflow:
-1) Read and follow the output of `subagent prompt render --target manager`.
+1) First, run `subagent prompt render --target manager` and follow that output.
 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.
+5) Use `send` as the default turn driver (`send` waits by default).
+6) If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
+7) Use `watch` only when detailed event streaming/debugging is needed.
+8) Use handoff/continue when context gets large.
+9) 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`
+After handoff, the manager agent's standard lifecycle is:
+`worker start` -> `send` -> (`approve` -> `send` as needed) -> `handoff` -> `continue`
+
+For a single command that sends and waits for terminal-or-approval events:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --json
+```
+
+Opt out of waiting when needed:
+```bash
+subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+```
+
+Manual wait mode (advanced cursor control) still exists:
+```bash
+subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+```
 
 For local simulation/testing without a real ACP launcher:
 ```bash
@@ -92,12 +106,14 @@ subagent worker start --cwd . --debug-mode
 ```
 
 ## Troubleshooting 🛠️
-- Ensure the runtime has the permissions required by your launcher (some launchers need outbound network access).
+- Ensure both the runtime and your manager/worker agent sandbox allow what your launcher needs.
+- Some launchers require outbound network access, but agent sandbox policies can block network even when the host machine itself has connectivity.
+- If state path resolution fails, run commands from inside your workspace root (or set `SUBAGENT_STATE_DIR` explicitly).
 - 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).
+- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
 - For cut-down local testing without backend connectivity:
 ```bash
 subagent worker start --cwd . --debug-mode
@@ -107,11 +123,15 @@ subagent worker start --cwd . --debug-mode
 - 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 .`
+- `config init` defaults: `codex` -> `npx -y @zed-industries/codex-acp`, `claude-code` -> `npx -y @zed-industries/claude-agent-acp`
 - Override config path: `SUBAGENT_CONFIG=/path/to/config.yaml`
 - Example config: [config.example.yaml](config.example.yaml)
+- Launchers support either split style (`command: npx`, `args: ["-y", "..."]`) or inline style (`command: "npx -y ..."`) for probe/start/restart.
 
 ## State 💾
-- Default state DB: `~/.local/share/subagent/state.db`
+- Default state DB: `<workspace>/.subagent/state/state.db`
+- Override state dir: `SUBAGENT_STATE_DIR=/path/to/state-dir`
+- If workspace root cannot be detected and no override is set, commands fail with `WORKSPACE_ROOT_NOT_FOUND`
 - Project hint file: `<workspace>/.subagent/controller.json`
 
 ## Documentation 📚

{subagent_cli-0.1.3 → subagent_cli-0.1.4}/config.example.yaml

@@ -2,15 +2,19 @@ launchers:
   codex:
     backend:
       kind: acp-stdio
-    command: codex-acp
-    args: []
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/codex-acp"
     env: {}
 
   claude-code:
     backend:
       kind: acp-stdio
-    command: claude-code-acp
-    args: []
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/claude-agent-acp"
     env: {}
 
 profiles:

{subagent_cli-0.1.3 → subagent_cli-0.1.4}/docs/ARCHITECTURE.md

@@ -25,6 +25,7 @@
 - handoff store with `handoff.md` + `checkpoint.json`
 - `--input` JSON contract (major commands) with duplicate-field rejection
 - owner handle model: `controllerId + epoch + token`
+- workspace-scoped runtime state by default: `<workspace-root>/.subagent/state` (or `SUBAGENT_STATE_DIR` override)
 - project-local hint: `<workspace>/.subagent/controller.json`
 - versioned envelope for JSON responses
 
@@ -32,3 +33,4 @@
 - local single-host control plane only (`subagentd` is minimal bootstrap/status)
 - no queued turn execution; `send` is rejected while worker is busy
 - resume strategy is handoff-first (no bit-perfect backend session resurrection)
+- commands that need implicit state path fail with `WORKSPACE_ROOT_NOT_FOUND` when workspace root cannot be inferred

subagent_cli-0.1.4/docs/examples/checkpoint.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "v1",
+  "workerId": "w_123",
+  "controllerId": "ctl_abc123",
+  "launcher": "codex",
+  "profile": "worker-default",
+  "packs": ["repo-conventions"],
+  "cwd": "/path/to/workspace",
+  "state": "handoff_ready",
+  "sourceTurnId": "turn_07",
+  "handoffPath": "/path/to/workspace/.subagent/state/handoffs/w_123/hs_abc123/handoff.md",
+  "artifacts": ["/path/to/workspace/.subagent/state/handoffs/w_123/hs_abc123/handoff.md"],
+  "filesChanged": []
+}

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

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

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

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