[DOCS] Hooks reference missing TeammateIdle and TaskCompleted hook events

[coygeek]

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

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] Missing PostToolUseFailure event definition in Hooks reference #19372
2. [DOCS] Missing definition and input schema for SubagentStart hook event #19170
3. Docs: hookSpecificOutput schema incomplete - missing SessionStart event #22031

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[coygeek]

Issue #23545 Verification

Title: [DOCS] Hooks reference missing TeammateIdle and TaskCompleted hook events
Issue Date: 2026-02-06
Verification Date: 2026-02-07
Status: RESOLVED

---

Issue Summary

This issue reports that the hooks docs were missing the TeammateIdle and TaskCompleted events in the lifecycle table and reference sections, and that agent-teams docs did not cross-reference those hook events.

---

Verification Results

Claim 1: Hook lifecycle table is missing TeammateIdle and TaskCompleted

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/hooks.md:

• Line 39: TeammateIdle appears in the lifecycle table
• Line 40: TaskCompleted appears in the lifecycle table

Verdict: The lifecycle table now includes both events.

---

Claim 2: Hook reference lacks dedicated sections for both events

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/hooks.md:

• Line 1142: ### TeammateIdle
• Line 1148: #### TeammateIdle input
• Line 1184: ### TaskCompleted
• Line 1190: #### TaskCompleted input

Verdict: Dedicated event sections and input documentation now exist for both events.

---

Claim 3: Agent teams docs do not cross-reference these hooks

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/agent-teams.md:

• Line 189: Link to TeammateIdle
• Line 190: Link to TaskCompleted

Verdict: Agent teams docs now explicitly cross-reference both hook events.

---

Current State

Claim	Status
Lifecycle table includes new events	RESOLVED
Dedicated hook sections for both events	RESOLVED
Agent teams cross-reference to hook events	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/en/hooks

• Lines 39-40 in mirror: Lifecycle table includes TeammateIdle and TaskCompleted

• Lines 1142-1192 in mirror: Dedicated sections and input schemas for both events

• URL: https://code.claude.com/en/agent-teams

• Lines 189-190 in mirror: Direct links to #teammateidle and #taskcompleted

---

Conclusion & Recommendation

Primary Concern: The docs did not describe two multi-agent hook events and where to use them.

Resolution Status: RESOLVED

Recommendation: CLOSE

The missing hook events are now documented in both the hooks reference and agent teams documentation, including lifecycle, event-specific details, and cross-links.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.