amc/docs/claude-jsonl-reference/03-tool-lifecycle.md

Tool Call Lifecycle

Complete documentation of how tool invocations flow through Claude JSONL logs.

Lifecycle Overview

1. Assistant message with tool_use block
   ↓
2. PreToolUse hook fires (optional)
   ↓
3. Tool executes
   ↓
4. PostToolUse hook fires (optional)
   ↓
5. User message with tool_result block
   ↓
6. Assistant processes result

Phase 1: Tool Invocation

Claude requests a tool via tool_use content block:

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "I'll read that file for you."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ReadFile123",
        "name": "Read",
        "input": {
          "file_path": "/src/auth/login.ts",
          "limit": 200
        }
      }
    ],
    "stop_reason": null
  },
  "uuid": "msg-001"
}

Tool Use Block Structure

Field	Type	Required	Description
type	"tool_use"	Yes	Block type identifier
id	string	Yes	Unique tool call ID (format: toolu_*)
name	string	Yes	Tool name
input	object	Yes	Tool parameters

Common Tool Names

Tool	Purpose	Key Input Fields
Read	Read file	file_path, offset, limit
Edit	Edit file	file_path, old_string, new_string
Write	Create file	file_path, content
Bash	Run command	command, timeout
Glob	Find files	pattern, path
Grep	Search content	pattern, path, type
WebFetch	Fetch URL	url, prompt
WebSearch	Search web	query
Task	Spawn subagent	prompt, subagent_type
AskUserQuestion	Ask user	questions

Phase 2: Hook Execution (Optional)

If hooks are configured, progress events are logged:

PreToolUse Hook Input

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../session.jsonl",
  "cwd": "/Users/dev/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/src/auth/login.ts"
  }
}

Hook Progress Event

{
  "type": "progress",
  "data": {
    "type": "hook_progress",
    "hookEvent": "PreToolUse",
    "hookName": "security_check",
    "status": "running"
  },
  "parentToolUseID": "toolu_01ReadFile123",
  "toolUseID": "toolu_01ReadFile123",
  "uuid": "prog-001"
}

Hook Output (Decision)

{
  "decision": "allow",
  "reason": "File read permitted",
  "additionalContext": "Note: This file was recently modified"
}

Phase 3: Tool Result

Tool output is wrapped in a user message:

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01ReadFile123",
        "content": "1\texport async function login(email: string, password: string) {\n2\t  const user = await db.users.findByEmail(email);\n..."
      }
    ]
  },
  "uuid": "msg-002",
  "parentUuid": "msg-001"
}

Tool Result Block Structure

Field	Type	Required	Description
type	"tool_result"	Yes	Block type identifier
tool_use_id	string	Yes	Matches tool_use.id
content	string	Yes	Tool output
is_error	boolean	No	True if tool failed

Error Results

{
  "type": "tool_result",
  "tool_use_id": "toolu_01ReadFile123",
  "content": "Error: File not found: /src/auth/login.ts",
  "is_error": true
}

Phase 4: Result Processing

Claude processes the result and continues:

{
  "type": "assistant",
  "message": {
    "content": [
      {
        "type": "thinking",
        "thinking": "The login function looks correct. The issue might be in the middleware..."
      },
      {
        "type": "text",
        "text": "I see the login function. Let me check the middleware next."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ReadMiddleware",
        "name": "Read",
        "input": {"file_path": "/src/auth/middleware.ts"}
      }
    ]
  },
  "uuid": "msg-003",
  "parentUuid": "msg-002"
}

Parallel Tool Calls

Multiple tools can be invoked in a single message:

{
  "type": "assistant",
  "message": {
    "content": [
      {"type": "tool_use", "id": "toolu_01A", "name": "Grep", "input": {"pattern": "TODO"}},
      {"type": "tool_use", "id": "toolu_01B", "name": "Grep", "input": {"pattern": "FIXME"}},
      {"type": "tool_use", "id": "toolu_01C", "name": "Glob", "input": {"pattern": "**/*.test.ts"}}
    ]
  }
}

Results come back in the same user message:

{
  "type": "user",
  "message": {
    "content": [
      {"type": "tool_result", "tool_use_id": "toolu_01A", "content": "Found 15 TODOs"},
      {"type": "tool_result", "tool_use_id": "toolu_01B", "content": "Found 3 FIXMEs"},
      {"type": "tool_result", "tool_use_id": "toolu_01C", "content": "tests/auth.test.ts\ntests/api.test.ts"}
    ]
  }
}

Codex Tool Format

Codex uses a different structure:

Function Call

{
  "type": "response_item",
  "payload": {
    "type": "function_call",
    "call_id": "call_abc123",
    "name": "Read",
    "arguments": "{\"file_path\": \"/src/auth/login.ts\"}"
  }
}

Note: arguments is a JSON string that needs parsing.

Function Result

{
  "type": "response_item",
  "payload": {
    "type": "function_call_result",
    "call_id": "call_abc123",
    "result": "File contents..."
  }
}

Tool Call Pairing

To reconstruct tool call history:

1. Find tool_use blocks in assistant messages
2. Match by ID to tool_result blocks in following user messages
3. Handle parallel calls — multiple tool_use can have multiple tool_result

# Example: Pairing tool calls with results
tool_calls = {}

for line in jsonl_file:
    event = json.loads(line)

    if event['type'] == 'assistant':
        for block in event['message']['content']:
            if block['type'] == 'tool_use':
                tool_calls[block['id']] = {
                    'name': block['name'],
                    'input': block['input'],
                    'timestamp': event['timestamp']
                }

    elif event['type'] == 'user':
        content = event['message']['content']
        if isinstance(content, list):
            for block in content:
                if block['type'] == 'tool_result':
                    call_id = block['tool_use_id']
                    if call_id in tool_calls:
                        tool_calls[call_id]['result'] = block['content']
                        tool_calls[call_id]['is_error'] = block.get('is_error', False)

Missing Tool Results

Edge cases where tool results may be absent:

1. Session interrupted — User closed session mid-tool
2. Tool timeout — Long-running tool exceeded limits
3. Hook blocked — PreToolUse hook returned block
4. Permission denied — User denied tool permission

Handle by checking if tool_use has matching tool_result before assuming completion.

Tool-Specific Formats

Bash Tool

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "npm test -- --coverage",
    "timeout": 120000,
    "description": "Run tests with coverage"
  }
}

Result includes exit code context:

{
  "type": "tool_result",
  "content": "PASS src/auth.test.ts\n...\nCoverage: 85%\n\n[Exit code: 0]"
}

Task Tool (Subagent)

{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "description": "Research auth patterns",
    "prompt": "Explore authentication implementations...",
    "subagent_type": "Explore"
  }
}

Result returns subagent output:

{
  "type": "tool_result",
  "content": "## Research Findings\n\n1. JWT patterns...\n\nagentId: agent-abc123"
}