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:

{
  "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:

{
  "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:

{
  "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:

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

Immediate result with task ID:

{
  "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)

{
  "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:

{
  "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

{
  "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

{
  "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

{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "broadcast",
    "content": "Critical: Found security vulnerability in token validation",
    "summary": "Security alert"
  }
}

Shutdown Request

{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "shutdown_request",
    "recipient": "researcher",
    "content": "Task complete, please wrap up"
  }
}

Shutdown Response

{
  "type": "tool_use",
  "name": "SendMessage",
  "input": {
    "type": "shutdown_response",
    "request_id": "req-abc123",
    "approve": true
  }
}

Hook Events for Subagents

SubagentStart Hook Input

{
  "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

{
  "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

// ~/.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

// ~/.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:

{
  "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:

{
  "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:

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