docs: add agent teams API and CLI notes

.turbo

@@ -0,0 +1 @@
+/home/nathan/sandbox-agent/.turbo

dist

@@ -0,0 +1 @@
+/home/nathan/sandbox-agent/dist

docs/agent-teams.mdx

@@ -0,0 +1,86 @@
+---
+title: "Agent Teams"
+description: "Notes on Claude Code agent teams and a proposed Sandbox Agent API."
+icon: "users"
+---
+
+## Claude Code team model (external)
+
+Claude Code exposes agent teams as an interactive feature, not a public API. Key points from the upstream docs:
+
+- Enablement: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in env or settings.json.
+- Display mode: `--teammate-mode` supports `auto`, `in-process`, `tmux`.
+- Teams are created in natural language by the lead; teammates are independent sessions.
+- Storage:
+  - `~/.claude/teams/{team-name}/config.json`
+  - `~/.claude/tasks/{team-name}/`
+- Team concepts: lead, teammates, shared task list, mailbox for messaging.
+- No documented CLI subcommand or Agent SDK API for team management.
+
+## Current gap in Sandbox Agent
+
+Sandbox Agent controls a single agent session at a time. Claude Code team state and teammate coordination do not surface through the `stream-json` CLI output, so there is no native team lifecycle to convert into the universal schema yet.
+
+## Proposed API shape (new resource)
+
+Add a Team resource and treat a team as a first-class container for multiple sessions:
+
+### Endpoints
+
+- `POST /v1/teams/{team_id}`
+  - Create a team and optionally create a lead session.
+- `GET /v1/teams`
+  - List teams with summary metadata.
+- `GET /v1/teams/{team_id}`
+  - Get team metadata and members.
+- `POST /v1/teams/{team_id}/members`
+  - Spawn a teammate session (agent + mode + model + permission mode).
+- `POST /v1/teams/{team_id}/members/{member_id}/messages`
+  - Send a message to a specific teammate.
+- `POST /v1/teams/{team_id}/messages`
+  - Broadcast a message to all teammates.
+- `POST /v1/teams/{team_id}/tasks`
+  - Create a task in the shared list.
+- `PATCH /v1/teams/{team_id}/tasks/{task_id}`
+  - Update task state (pending/in_progress/completed) or assignment.
+- `POST /v1/teams/{team_id}/terminate`
+  - Stop all sessions and clean up team resources.
+
+### CLI mapping (proposed)
+
+```
+sandbox-agent api teams list
+sandbox-agent api teams create <TEAM_ID> --agent claude --agent-mode code
+sandbox-agent api teams members add <TEAM_ID> --agent claude --model sonnet
+sandbox-agent api teams members message <TEAM_ID> <MEMBER_ID> --message "..."
+sandbox-agent api teams broadcast <TEAM_ID> --message "..."
+sandbox-agent api teams tasks create <TEAM_ID> --title "..."
+sandbox-agent api teams tasks update <TEAM_ID> <TASK_ID> --status completed
+sandbox-agent api teams terminate <TEAM_ID>
+```
+
+### Event extensions (proposed)
+
+Add optional team-aware events to the session transcript schema. These would be emitted by the daemon when it orchestrates teams, and marked `source=daemon` for agents without native team events:
+
+- `team.created` / `team.ended`
+- `team.member.added` / `team.member.removed`
+- `team.message.sent` (for teammate or broadcast messages)
+- `team.task.created` / `team.task.updated`
+
+Each event should include `team_id` and, where relevant, `member_id` or `task_id`.
+
+### Session linkage (minimal change)
+
+Add an optional `team_id` field to `CreateSessionRequest` so existing session endpoints can still be used while associating sessions to a team container.
+
+## Compatibility strategy
+
+- Claude Code: Sandbox Agent would manage the team abstraction itself (multiple CLI sessions), since there is no public team API.
+- Other agents: Teams are supported as a daemon-level orchestration feature; events are synthetic and marked accordingly.
+
+## Open questions
+
+- Should team tasks live in the universal schema or remain a daemon-only construct?
+- Do we need a mailbox API for cross-agent messages, or are per-member messages enough?
+- How should team cleanup interact with per-session termination and resume behavior?

docs/docs.json

@@ -65,6 +65,7 @@
 						"cli",
 						"opencode-compatibility",
 						"inspector",
+						"agent-teams",
 						"session-transcript-schema",
 						"cors",
 					{

node_modules

@@ -0,0 +1 @@
+/home/nathan/sandbox-agent/node_modules

research/agents/claude.md

@@ -65,6 +65,7 @@ claude \
   --output-format stream-json \
   --verbose \
   --dangerously-skip-permissions \
+  [--teammate-mode in-process|tmux|auto] \
   [--resume SESSION_ID] \
   [--model MODEL_ID] \
   [--permission-mode plan] \
@@ -82,6 +83,7 @@ claude \
 | `--resume SESSION_ID` | Resume existing session |
 | `--model MODEL_ID` | Specify model (e.g., `claude-sonnet-4-20250514`) |
 | `--permission-mode plan` | Plan mode (read-only exploration) |
+| `--teammate-mode <MODE>` | Agent teams display mode: `auto`, `in-process`, `tmux` |
 
 ### Environment Variables
 
@@ -196,6 +198,44 @@ Claude supports spawning subagents via the `Task` tool with `subagent_type`:
 - Custom agents defined in config
 - Built-in agents like "Explore", "Plan"
 
+## Agent Teams (Experimental)
+
+Claude Code supports multi-session teams where a lead coordinates multiple teammates. Teams are disabled by default and must be enabled explicitly.
+
+### Enablement
+
+- **Environment flag**: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+- **settings.json**: `{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }`
+
+### CLI additions
+
+- `--teammate-mode` controls display mode for teammates: `auto` (default), `in-process`, `tmux`.
+- Teams are created via natural language in interactive mode; there is no dedicated CLI subcommand.
+
+### Team components and storage
+
+- **Lead**: the session that creates and manages the team.
+- **Teammates**: independent Claude Code instances with their own context.
+- **Task list**: shared task tracker used for coordination.
+- **Mailbox**: internal messaging between teammates and lead.
+
+Claude stores team metadata locally:
+
+- `~/.claude/teams/{team-name}/config.json`
+- `~/.claude/tasks/{team-name}/`
+
+### Known limitations (from docs)
+
+- No session resumption for in-process teammates (`/resume` does not restore them).
+- Task status can lag; teammates may not mark tasks as completed.
+- Shutdown can be slow (teammates finish current requests before exiting).
+- One team per session; no nested teams.
+- Teammate permission mode inherits from the lead at spawn time.
+
+### API surface notes
+
+The public Agent SDK and CLI documentation do not describe a dedicated API for team management. Team coordination appears to be interactive-first, with state persisted locally (paths above). No streaming event types for team lifecycle are documented in the CLI/SDK references.
+
 ### ExitPlanMode (Plan Approval)
 
 When in `plan` permission mode, agent invokes `ExitPlanMode` tool to request execution:

target

@@ -0,0 +1 @@
+/home/nathan/sandbox-agent/target