amc/docs/claude-jsonl-reference/04-subagent-teams.md

# Subagent and Team Message Formats

Documentation for spawned agents, team coordination, and inter-agent messaging.

## Subagent Overview

Subagents are spawned via the `Task` tool and run in separate processes with their own transcripts.

### Spawn Relationship

```
Main Session (session-uuid.jsonl)
├── User message
├── Assistant: Task tool_use
├── [Subagent executes in separate process]
├── User message: tool_result with subagent output
└── ...

Subagent Session (session-uuid/subagents/agent-id.jsonl)
├── Subagent receives prompt
├── Subagent works (tool calls, etc.)
└── Subagent returns result
```

## Task Tool Invocation

Spawning a subagent:

```json
{
  "type": "assistant",
  "message": {
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_01TaskSpawn",
        "name": "Task",
        "input": {
          "description": "Research auth patterns",
          "prompt": "Investigate authentication implementations in the codebase. Focus on JWT handling and session management.",
          "subagent_type": "Explore",
          "run_in_background": false
        }
      }
    ]
  }
}
```

### Task Tool Input Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Yes | Short (3-5 word) description |
| `prompt` | string | Yes | Full task instructions |
| `subagent_type` | string | Yes | Agent type (Explore, Plan, etc.) |
| `run_in_background` | boolean | No | Run async without waiting |
| `model` | string | No | Override model (sonnet, opus, haiku) |
| `isolation` | string | No | "worktree" for isolated git copy |
| `team_name` | string | No | Team to join |
| `name` | string | No | Agent display name |

### Subagent Types

| Type | Tools Available | Use Case |
|------|-----------------|----------|
| `Explore` | Read-only tools | Research, search, analyze |
| `Plan` | Read-only tools | Design implementation plans |
| `general-purpose` | All tools | Full implementation |
| `claude-code-guide` | Docs tools | Answer Claude Code questions |
| Custom agents | Defined in `.claude/agents/` | Project-specific |

## Subagent Transcript Location

```
~/.claude/projects/<project-hash>/<session-id>/subagents/agent-<agent-id>.jsonl
```

## Subagent Message Format

Subagent transcripts have additional context fields:

```json
{
  "parentUuid": null,
  "isSidechain": true,
  "userType": "external",
  "cwd": "/Users/dev/myproject",
  "sessionId": "subagent-session-uuid",
  "version": "2.1.20",
  "gitBranch": "main",
  "agentId": "a3fecd5",
  "type": "user",
  "message": {
    "role": "user",
    "content": "Investigate authentication implementations..."
  },
  "uuid": "msg-001",
  "timestamp": "2026-02-27T10:00:00.000Z"
}
```

### Key Differences from Main Session

| Field | Main Session | Subagent Session |
|-------|--------------|------------------|
| `isSidechain` | `false` | `true` |
| `agentId` | absent | present |
| `sessionId` | main session UUID | subagent session UUID |

## Task Result

When subagent completes, result returns to main session:

```json
{
  "type": "user",
  "message": {
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01TaskSpawn",
        "content": "## Authentication Research Findings\n\n### JWT Implementation\n- Located in src/auth/jwt.ts\n- Uses RS256 algorithm\n...\n\nagentId: a3fecd5 (for resuming)"
      }
    ]
  }
}
```

**Note:** Result includes `agentId` for potential resumption.

## Background Tasks

For `run_in_background: true`:

```json
{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "prompt": "Run comprehensive test suite",
    "subagent_type": "general-purpose",
    "run_in_background": true
  }
}
```

Immediate result with task ID:
```json
{
  "type": "tool_result",
  "content": "Background task started.\nTask ID: task-abc123\nUse TaskOutput tool to check status."
}
```

## Team Coordination

Teams enable multiple agents working together.

### Team Creation (TeamCreate Tool)

```json
{
  "type": "tool_use",
  "name": "TeamCreate",
  "input": {
    "team_name": "auth-refactor",
    "description": "Refactoring authentication system"
  }
}
```

### Team Config File

Created at `~/.claude/teams/<team-name>/config.json`:

```json
{
  "team_name": "auth-refactor",
  "description": "Refactoring authentication system",
  "created_at": "2026-02-27T10:00:00.000Z",
  "members": [
    {
      "name": "team-lead",
      "agentId": "agent-lead-123",
      "agentType": "general-purpose"
    },
    {
      "name": "researcher",
      "agentId": "agent-research-456",
      "agentType": "Explore"
    }
  ]
}
```

### Spawning Team Members

```json
{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "prompt": "Research existing auth implementations",
    "subagent_type": "Explore",
    "team_name": "auth-refactor",
    "name": "researcher"
  }
}
```

## Inter-Agent Messaging (SendMessage)

### Direct Message
```json
{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "message",
    "recipient": "researcher",
    "content": "Please focus on JWT refresh token handling",
    "summary": "JWT refresh priority"
  }
}
```

### Broadcast to Team
```json
{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "broadcast",
    "content": "Critical: Found security vulnerability in token validation",
    "summary": "Security alert"
  }
}
```

### Shutdown Request
```json
{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "shutdown_request",
    "recipient": "researcher",
    "content": "Task complete, please wrap up"
  }
}
```

### Shutdown Response
```json
{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "shutdown_response",
    "request_id": "req-abc123",
    "approve": true
  }
}
```

## Hook Events for Subagents

### SubagentStart Hook Input
```json
{
  "session_id": "main-session-uuid",
  "transcript_path": "/path/to/main/session.jsonl",
  "hook_event_name": "SubagentStart",
  "agent_id": "a3fecd5",
  "agent_type": "Explore"
}
```

### SubagentStop Hook Input
```json
{
  "session_id": "main-session-uuid",
  "hook_event_name": "SubagentStop",
  "agent_id": "a3fecd5",
  "agent_type": "Explore",
  "agent_transcript_path": "/path/to/subagent/agent-a3fecd5.jsonl",
  "last_assistant_message": "Research complete. Found 3 auth patterns..."
}
```

## AMC Spawn Tracking

AMC tracks spawned agents through:

### Pending Spawn Record
```json
// ~/.local/share/amc/pending_spawns/<spawn-id>.json
{
  "spawn_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_path": "/Users/dev/myproject",
  "agent_type": "claude",
  "timestamp": 1708872000.123
}
```

### Session State with Spawn ID
```json
// ~/.local/share/amc/sessions/<session-id>.json
{
  "session_id": "session-uuid",
  "agent": "claude",
  "project": "myproject",
  "spawn_id": "550e8400-e29b-41d4-a716-446655440000",
  "zellij_session": "main",
  "zellij_pane": "3"
}
```

## Resuming Subagents

Subagents can be resumed using their agent ID:

```json
{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "description": "Continue auth research",
    "prompt": "Continue where you left off",
    "subagent_type": "Explore",
    "resume": "a3fecd5"
  }
}
```

The resumed agent receives full previous context.

## Worktree Isolation

For isolated code changes:

```json
{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "prompt": "Refactor auth module",
    "subagent_type": "general-purpose",
    "isolation": "worktree"
  }
}
```

Creates temporary git worktree at `.claude/worktrees/<name>/`.

Result includes worktree info:
```json
{
  "type": "tool_result",
  "content": "Refactoring complete.\n\nWorktree: .claude/worktrees/auth-refactor\nBranch: claude/auth-refactor-abc123\n\nChanges made - worktree preserved for review."
}
```