[DOCS] Hooks reference missing TeammateIdle and TaskCompleted hook events

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

"Hook lifecycle" event table and "Hook events" reference sections

Current Documentation

The hooks reference lists these events in the lifecycle table:

| Event | When it fires | | SessionStart | When a session begins or resumes | | UserPromptSubmit | When you submit a prompt, before Claude processes it | | PreToolUse | Before a tool call executes. Can block it | | PermissionRequest | When a permission dialog appears | | PostToolUse | After a tool call succeeds | | PostToolUseFailure | After a tool call fails | | Notification | When Claude Code sends a notification | | SubagentStart | When a subagent is spawned | | SubagentStop | When a subagent finishes | | Stop | When Claude finishes responding | | PreCompact | Before context compaction | | SessionEnd | When a session terminates |

TeammateIdle and TaskCompleted are not listed.

What's Wrong or Missing?

Changelog v2.1.33 added two new hook events for multi-agent workflows:

• TeammateIdle — fires when an agent team teammate becomes idle
• TaskCompleted — fires when a task in the shared task list is completed

Neither event appears in the hook lifecycle table, the hook events reference sections, or the agent teams documentation. Users building automations around agent teams (e.g., triggering notifications when teammates finish, auto-assigning follow-up work when tasks complete) cannot discover or configure these hooks.

Suggested Improvement

A. Add to the hook lifecycle table

Add two rows to the event summary table:

| Event | When it fires |
| TeammateIdle | When an agent team teammate becomes idle |
| TaskCompleted | When a shared task list task is completed |

B. Add dedicated hook event sections

Add reference sections for each event under "Hook events", documenting:

• When the event fires
• Matcher support (if any)
• JSON input schema (e.g., teammate name/ID, task ID/subject)
• Decision control options (if any)

C. Cross-reference from agent teams page

Add a note in the agent teams documentation (https://code.claude.com/docs/en/agent-teams) under "How agent teams work" or a new "Hooks" subsection, linking to the hooks reference for these events.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | Hook lifecycle table and Hook events reference sections |
| https://code.claude.com/docs/en/hooks-guide | Quickstart guide — no mention of multi-agent hook events |
| https://code.claude.com/docs/en/agent-teams | Agent teams page — no hook event cross-references |

Total scope: 3 pages affected

Source: Changelog v2.1.33

Added TeammateIdle and TaskCompleted hook events for multi-agent workflows