TeammateIdle

Runs when an agent team teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

TeammateIdle hooks don't support matchers and fire on every occurrence.

TeammateIdle input

In addition to the common input fields, TeammateIdle hooks receive teammate_name and team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

Field	Description
teammate_name	Name of the teammate that is about to go idle
team_name	Deprecated. Session-derived team name; will be removed in a future release

TeammateIdle decision control

TeammateIdle hooks support two ways to control teammate behavior:

• Exit code 2: the teammate receives the stderr message as feedback and continues working instead of going idle.
• JSON \{"continue": false, "stopReason": "..."\}: stops the teammate entirely, matching Stop hook behavior. The stopReason is shown to the user.

This example checks that a build artifact exists before allowing a teammate to go idle:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0