docs(jsonl): add comprehensive Claude JSONL session log reference
Create authoritative documentation suite for Claude Code JSONL session log processing, synthesized from codebase analysis, official Anthropic documentation, and community tooling research. Documentation structure (docs/claude-jsonl-reference/): 01-format-specification.md (214 lines): - Complete message envelope structure with all fields - Content block types (text, thinking, tool_use, tool_result) - Usage object for token reporting - Model identifiers and version history - Conversation DAG structure via parentUuid 02-message-types.md (346 lines): - Every message type with concrete JSON examples - User messages (string content vs array for tool results) - Assistant messages with all content block variants - Progress events (hooks, bash, MCP) - System, summary, and file-history-snapshot types - Codex format differences (response_item, function_call) 03-tool-lifecycle.md (341 lines): - Complete tool invocation to result flow - Hook input/output formats (PreToolUse, PostToolUse) - Parallel tool call handling - Tool-to-result pairing algorithm - Missing result edge cases - Codex tool format differences 04-subagent-teams.md (363 lines): - Task tool invocation and input fields - Subagent transcript locations and format - Team coordination (TeamCreate, SendMessage) - Hook events (SubagentStart, SubagentStop) - AMC spawn tracking with pending spawn registry - Worktree isolation for subagents 05-edge-cases.md (475 lines): - Parsing edge cases (invalid JSON, type ambiguity) - Type coercion gotchas (bool vs int in Python) - Session state edge cases (orphans, dead detection) - Tool call edge cases (missing results, parallel ordering) - Codex-specific quirks (content injection, buffering) - File system safety (path traversal, permissions) - Cache invalidation strategies 06-quick-reference.md (238 lines): - File locations cheat sheet - jq recipes for common queries - Python parsing snippets - Common gotchas table - Useful constants - Debugging commands Also adds CLAUDE.md at project root linking to documentation and providing project overview for agents working on AMC. Sources include Claude Code hooks.md, headless.md, Anthropic Messages API reference, and community tools (claude-code-log, claude-JSONL-browser). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
teernisse
363
docs/claude-jsonl-reference/04-subagent-teams.md
Normal file
363
docs/claude-jsonl-reference/04-subagent-teams.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 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."
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user