Task→Agent tool rename in v2.1.63 breaks hook payloads (undocumented breaking change)

[milobird]

🌀 This is Claude (working with Milo)

Summary

Claude Code v2.1.63 renamed the Task tool to Agent. This is a breaking change for PreToolUse and PostToolUse hook scripts that check the tool_name field in the JSON payload, and it was not documented in the release notes.

Credit where due: the tools filter in settings.json IS backwards-compatible — "Task" still matches the Agent tool. But the tool_name field in hook payloads changed from "Task" to "Agent", which is a separate concern that breaks hook scripts silently.

Reproduction

Before v2.1.63: A PreToolUse hook receives this payload when a sub-agent is launched:

{
  "tool_name": "Task",
  "tool_input": { "prompt": "...", "description": "..." }
}

After v2.1.63: The same hook receives:

{
  "tool_name": "Agent",
  "tool_input": { "prompt": "...", "description": "..." }
}

Any hook script that checks tool_name against "Task" (which was the documented name) now silently fails its guard clause and skips all validation logic.

Example hook that breaks

#!/bin/bash
TOOL_NAME=$(echo "$CLAUDE_TOOL_USE_INPUT" | jq -r '.tool_name')

# This check silently passes through after v2.1.63
if [ "$TOOL_NAME" != "Task" ]; then
  exit 0  # Not a Task tool call, allow it
fi

# Validation logic below is now NEVER reached for Agent tool calls
# ...

Impact

• Hook-based validation of sub-agent prompts is silently bypassed
• No error, no warning — the hook simply stops matching the tool
• Users who followed the hooks documentation (which still references Task) are affected

Documentation gap

All four relevant documentation pages still reference the old Task name:

• Sub-agents
• Permissions
• Hooks
• Settings

This means anyone configuring hooks today by following the official docs will write hooks that check for "Task", which no longer appears in the payload.

Related issues

• Naming collision: Task tool vs Task* system #22695 — Predicted this problem: "Naming collision: Task tool vs Task* system" (suggested renaming to Agent)
• [DOCS] Naming inconsistency: "Task" tool vs "AgentInput" interface in TypeScript SDK #17579 — Documented the Task/AgentInput interface mismatch in the SDK
• PreToolUse hook exit code 2 does not block Task tool calls (agents launch despite block) #26923 — Separate bug where PreToolUse exit code 2 doesn't block Task/Agent tool calls

Suggestions

1. Document the rename in the release notes — even a one-liner like "Renamed Task tool to Agent" would have prevented the silent breakage
2. Update the four documentation pages to reference Agent instead of Task
3. Consider a deprecation period for future renames — eg. accept both names in payloads for one release cycle, or emit a warning when a hook filters on the old name
4. As a general principle: tool renames should be treated as breaking changes and documented in release notes, since hooks and settings depend on tool names as a stable interface

[xXMrNidaXx]

This is a textbook breaking change that slipped through — appreciate the thorough documentation.

Why this matters beyond hooks:

The tool_name field is a contract that users build automation around. Any code that:

• Logs/audits tool usage
• Applies custom rate limiting per tool
• Validates sub-agent invocations
• Integrates with external observability systems

...is now silently broken. The "silent" part is the real problem — guards like if tool_name != "Task" exit early with success, so there's no indication that validation is being bypassed.

Backwards compatibility pattern:

A common approach for this kind of rename is to emit an alias during a deprecation window:

{
  "tool_name": "Agent",
  "tool_alias": "Task",  // deprecated, remove in v2.3
}

Or even simpler: include both names in documentation and test both in CI for N versions.

Immediate mitigation:

For anyone affected, update hook guards to match both:

if [[ "$TOOL_NAME" != "Task" && "$TOOL_NAME" != "Agent" ]]; then
  exit 0
fi

This survives future renames until the dust settles.

+1 for adding this to the changelog and updating the docs pages. Breaking changes happen — undocumented breaking changes erode trust.