# Research: Claude Code Task-to-Agent Tool Rename -- Breaking Changes for DES

**Date**: 2026-03-05 | **Researcher**: nw-researcher (Nova) | **Confidence**: High | **Sources**: 7

## Executive Summary

Claude Code v2.1.63 renamed the internal `Task` tool to `Agent`. This is a confirmed breaking change that affects DES hook payloads, matcher behavior, and the `max_turns` parameter. The `tool_name` field in PreToolUse and PostToolUse hook input JSON changed from `"Task"` to `"Agent"`, silently breaking hook scripts that filter on tool name. The `max_turns` parameter was removed from the Agent tool's invocation-time parameters and relocated to the subagent definition layer (`maxTurns` frontmatter field). Settings-level tool filters (e.g., `permissions.deny`) retain backward compatibility -- `"Task"` still works as an alias. Hook payload `tool_name` values do not.

The impact on DES is severe: our `PreToolUse` hooks with `"matcher": "Task"` no longer fire for Agent tool calls, and our `MaxTurnsPolicy` validation always receives `None` because `max_turns` is no longer in `tool_input`. Both failures are silent -- no errors, no warnings.

## Research Methodology

**Search Strategy**: Official Claude Code documentation (code.claude.com), GitHub issues (anthropics/claude-code), community changelog trackers (Piebald-AI/claude-code-system-prompts, claudefast, claudelog), and local codebase inspection.
**Source Selection**: Types: official docs, GitHub issues, community trackers | Reputation: High to Medium-High | Verification: cross-referencing across 3+ independent sources per major claim.
**Quality Standards**: Min 3 sources/claim | All major claims cross-referenced | Avg reputation: 0.85

## Findings

### Finding 1: Tool Renamed from Task to Agent in v2.1.63

**Evidence**: Official documentation states: "In version 2.1.63, the Task tool was renamed to Agent. Existing Task(...) references in settings and agent definitions still work as aliases."
**Source**: [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [GitHub Issue #29677](https://github.com/anthropics/claude-code/issues/29677), [Piebald-AI System Prompt Changelog](https://github.com/Piebald-AI/claude-code-system-prompts/blob/main/CHANGELOG.md), [Claude Code Changelog on X (@ClaudeCodeLog)](https://x.com/ClaudeCodeLog/status/2027594456237527237)
**Analysis**: The rename is confirmed by the official documentation note embedded in the sub-agents page. The GitHub issue #29677 explicitly documents this as an "undocumented breaking change" that affects hook payloads. The Piebald-AI changelog independently confirms the rename occurred in v2.1.63 across tool tables and code examples.

### Finding 2: Hook Payload tool_name Changed -- Matchers Break Silently

**Evidence**: The `tool_name` field in PreToolUse/PostToolUse JSON input changed from `"Task"` to `"Agent"`. Hook matchers configured with `"Task"` no longer match Agent tool calls.
**Source**: [GitHub Issue #29677 - Task to Agent rename breaks hook payloads](https://github.com/anthropics/claude-code/issues/29677) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks) (matchers filter on `tool_name`), [GitHub Issue #26923](https://github.com/anthropics/claude-code/issues/26923) (references #29677 as related)
**Analysis**: The hooks reference documentation confirms matchers for PreToolUse/PostToolUse filter on `tool_name`. Since `tool_name` is now `"Agent"`, any matcher regex that only matches `"Task"` silently passes through. This is the most critical DES impact: our PreToolUse hooks with `"matcher": "Task"` and PostToolUse hooks with `"matcher": "Task"` no longer fire at all.

**Before v2.1.63**:
```json
{ "tool_name": "Task", "tool_input": { "prompt": "...", "description": "...", "max_turns": 30 } }
```

**After v2.1.63**:
```json
{ "tool_name": "Agent", "tool_input": { "prompt": "...", "description": "..." } }
```

### Finding 3: Settings-Level Backward Compatibility Preserved

**Evidence**: The `tools` filter in `settings.json` still accepts `"Task"` as a matcher and correctly identifies the Agent tool. `permissions.deny` entries like `"Task(Explore)"` still work.
**Source**: [GitHub Issue #29677](https://github.com/anthropics/claude-code/issues/29677) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents) ("Existing Task(...) references still work as aliases"), [Claude Code Permissions Documentation](https://code.claude.com/docs/en/permissions)
**Analysis**: There is a critical inconsistency: settings-level aliases work, but hook-level payloads do not. This means the `"matcher": "Task"` field in hook configuration may or may not work depending on whether Claude Code resolves aliases at the matcher level (unclear from documentation). The `tool_name` in the JSON payload sent to hook scripts is definitively `"Agent"`.

### Finding 4: max_turns Removed from Tool Invocation Parameters

**Evidence**: The Agent tool accepts these parameters: `description` (required), `prompt` (required), `subagent_type` (required), `resume` (optional), `run_in_background` (optional), `isolation` (optional: "worktree"). The `max_turns` parameter is absent from the tool schema.
**Source**: Local tool schema inspection (verified from current Claude Code installation) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents) (`maxTurns` is now a subagent frontmatter field), [Claude Code CLI Reference](https://code.claude.com/docs/en/sub-agents) (`--agents` JSON flag accepts `maxTurns`)
**Analysis**: `max_turns` was relocated from an invocation-time parameter to a subagent definition-time field (`maxTurns` in YAML frontmatter or `--agents` JSON). This is architecturally significant: the caller no longer controls turn limits per-invocation. Instead, turn limits are defined by the subagent definition itself. For DES, this means `tool_input.get("max_turns")` always returns `None`, causing `MaxTurnsPolicy.validate()` to always produce `MISSING_MAX_TURNS` and block every DES task.

### Finding 5: SubagentStop and SubagentStart Hooks Unaffected

**Evidence**: SubagentStop and SubagentStart hooks match on `agent_type` (the subagent name), not on `tool_name`. They were never matching on "Task".
**Source**: [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents) (hook events table), local DES codebase inspection
**Analysis**: SubagentStart matcher examples show values like `"Bash"`, `"Explore"`, `"Plan"`, or custom agent names. SubagentStop uses the same values. These are agent type names, not tool names, so the Task-to-Agent rename does not affect them. Our SubagentStop hook (which has no matcher) continues to fire for all subagent completions.

### Finding 6: maxTurns Now a Subagent Definition Field

**Evidence**: The official subagent frontmatter documentation lists `maxTurns` as an optional field: "Maximum number of agentic turns before the subagent stops."
**Source**: [Claude Code Sub-agents Documentation](https://code.claude.com/docs/en/sub-agents) - Accessed 2026-03-05
**Confidence**: High
**Verification**: [Claude Code CLI Reference](https://code.claude.com/docs/en/sub-agents) (`--agents` JSON flag includes `maxTurns`), [Community documentation](https://deepwiki.com/shanraisshan/claude-code-best-practice/3.2-agents-and-subagents)
**Analysis**: The `maxTurns` field moved from the tool call to the subagent definition. This means turn limits are now set when defining a subagent (in `.claude/agents/*.md` frontmatter or `--agents` JSON), not when invoking it. For nWave agents, this means adding `maxTurns` to each agent definition file in `nWave/agents/`.

## Source Analysis

| Source | Domain | Reputation | Type | Access Date | Cross-verified |
|--------|--------|------------|------|-------------|----------------|
| Claude Code Sub-agents Docs | code.claude.com | High (1.0) | Official | 2026-03-05 | Y |
| Claude Code Hooks Reference | code.claude.com | High (1.0) | Official | 2026-03-05 | Y |
| GitHub Issue #29677 | github.com/anthropics | High (1.0) | Official (bug tracker) | 2026-03-05 | Y |
| GitHub Issue #26923 | github.com/anthropics | High (1.0) | Official (bug tracker) | 2026-03-05 | Y |
| Piebald-AI System Prompts | github.com/Piebald-AI | Medium-High (0.8) | Community tracker | 2026-03-05 | Y |
| ClaudeCodeLog on X | x.com/ClaudeCodeLog | Medium (0.6) | Community tracker | 2026-03-05 | Y |
| Local tool schema | Local installation | High (1.0) | Direct observation | 2026-03-05 | N/A |

Reputation: High: 5 (71%) | Medium-high: 1 (14%) | Medium: 1 (14%) | Avg: 0.91

## Impact Analysis for DES

### Critical Breakages

| Component | File | Impact | Severity |
|-----------|------|--------|----------|
| PreToolUse hook matcher | `scripts/install/plugins/des_plugin.py:555` | `"matcher": "Task"` no longer matches `tool_name: "Agent"` | **CRITICAL** |
| PostToolUse hook matcher | `scripts/install/plugins/des_plugin.py:562` | `"matcher": "Task"` no longer matches `tool_name: "Agent"` | **CRITICAL** |
| max_turns extraction | `src/des/adapters/.../claude_code_hook_adapter.py:567` | `tool_input.get("max_turns")` always returns `None` | **CRITICAL** |
| MaxTurnsPolicy | `src/des/domain/max_turns_policy.py:59` | Always returns `MISSING_MAX_TURNS`, blocks all DES tasks | **CRITICAL** |
| Hook installer | `scripts/install/install_des_hooks.py:22,41` | Installs hooks with stale `"Task"` matcher | **HIGH** |
| Test fixtures | `tests/bugs/.../conftest.py:148,152,194,228` | Tests use `"Task"` matcher -- tests pass but don't reflect reality | **MEDIUM** |
| Test assertions | `tests/plugins/.../test_des_plugin.py:179,375` | Assert `"Task"` matcher -- tests pass but verify wrong behavior | **MEDIUM** |
| Adapter comment | `src/des/adapters/.../claude_code_hook_adapter.py:565` | Comment says "Task" but tool is now "Agent" | **LOW** |

### Files Requiring Changes

1. **`scripts/install/plugins/des_plugin.py`** -- Change `"matcher": "Task"` to `"matcher": "Agent"` (lines 555, 562)
2. **`scripts/install/install_des_hooks.py`** -- Change `"matcher": "Task"` to `"matcher": "Agent"` (lines 22, 41)
3. **`src/des/adapters/drivers/hooks/claude_code_hook_adapter.py`** -- Update comment at line 565; decide strategy for `max_turns` extraction (line 567)
4. **`src/des/domain/max_turns_policy.py`** -- Rethink validation strategy: `max_turns` is no longer in `tool_input`
5. **`src/des/application/pre_tool_use_service.py`** -- Adjust validation flow for absent `max_turns`
6. **nWave agent definition files** -- Add `maxTurns` frontmatter field to all 23 agent definitions
7. **All test files** referencing `"Task"` matcher -- Update to `"Agent"`

## Knowledge Gaps

### Gap 1: Matcher Alias Resolution at Hook Level

**Issue**: It is unclear whether Claude Code resolves the `"Task"` matcher alias to match `"Agent"` tool_name in hook configurations. The official docs confirm settings-level aliases work, but do not explicitly state whether hook-level matchers support the alias.
**Attempted**: Official hooks reference, GitHub issues, sub-agents documentation.
**Recommendation**: Test empirically by checking if a hook with `"matcher": "Task"` fires when the Agent tool is invoked. If it does, the matcher change is not urgent but should still be updated for clarity. If it does not (more likely based on #29677), matcher changes are critical and immediate.

### Gap 2: Exact Version of max_turns Removal

**Issue**: We cannot pinpoint the exact version when `max_turns` was removed from the tool parameters. It may have been removed in v2.1.63 alongside the rename, or in an earlier version.
**Attempted**: Changelogs, GitHub issues, system prompt diffs.
**Recommendation**: Compare system prompt snapshots across versions in Piebald-AI repository.

### Gap 3: Deprecation Timeline

**Issue**: No deprecation window was provided. The rename was described as "undocumented" in GitHub issue #29677. There is no indication of when/if `"Task"` aliases will be removed entirely.
**Attempted**: Official documentation, GitHub issues, release notes.
**Recommendation**: Monitor GitHub issue #29677 for Anthropic's response.

## Conflicting Information

### Conflict 1: Matcher Backward Compatibility

**Position A**: Settings-level tool filters accept `"Task"` as an alias for `"Agent"` -- confirmed by official docs.
**Position B**: Hook payload `tool_name` is definitively `"Agent"`, not `"Task"` -- confirmed by GitHub issue #29677.
**Assessment**: Both positions are correct but apply to different layers. Settings-level and hook-level operate differently. The matcher field in hook configuration may or may not resolve aliases -- this is the key unknown (see Knowledge Gap 1). The safest approach is to update matchers to `"Agent"`.

## Migration Recommendations

### Immediate (Before Next Release)

1. **Update hook matchers**: Change all `"matcher": "Task"` to `"matcher": "Agent"` in `des_plugin.py` and `install_des_hooks.py`. Consider using `"matcher": "Task|Agent"` for transitional safety.

2. **Rethink MaxTurnsPolicy**: Since `max_turns` is no longer in `tool_input`, the policy has three options:
   - **Option A**: Remove the policy entirely (max_turns is now the subagent definition's responsibility)
   - **Option B**: Add `maxTurns` to nWave agent frontmatter and trust the definition
   - **Option C**: Extract max_turns from the DES step file/prompt instead of tool_input

3. **Add maxTurns to agent definitions**: Add `maxTurns: <value>` to all 23 nWave agent definition files in `nWave/agents/`. Use the values from the existing CLAUDE.md defaults table.

4. **Update all test fixtures**: Replace `"Task"` with `"Agent"` in test matchers and assertions.

### Medium-Term

5. **Update CLAUDE.md instructions**: The Task Tool Safety section references `max_turns` as a Task tool parameter. Update to reflect Agent tool and `maxTurns` frontmatter.

6. **Update PreToolUseService**: Remove or make optional the max_turns validation step for DES tasks, since turn limits are now enforced at the subagent definition level.

7. **Audit hook_input extraction**: Review all `tool_input.get(...)` calls to ensure they reference parameters that exist in the Agent tool schema.

## Full Citations

[1] Anthropic. "Create custom subagents". Claude Code Documentation. 2026. https://code.claude.com/docs/en/sub-agents. Accessed 2026-03-05.
[2] Anthropic. "Hooks reference". Claude Code Documentation. 2026. https://code.claude.com/docs/en/hooks. Accessed 2026-03-05.
[3] Community. "Task to Agent tool rename in v2.1.63 breaks hook payloads (undocumented breaking change)". GitHub Issue #29677. 2026. https://github.com/anthropics/claude-code/issues/29677. Accessed 2026-03-05.
[4] Community. "PreToolUse hook exit code 2 does not block Task tool calls". GitHub Issue #26923. 2026. https://github.com/anthropics/claude-code/issues/26923. Accessed 2026-03-05.
[5] Piebald-AI. "Claude Code System Prompts Changelog". GitHub. 2026. https://github.com/Piebald-AI/claude-code-system-prompts/blob/main/CHANGELOG.md. Accessed 2026-03-05.
[6] ClaudeCodeLog. "Claude Code 2.1.63 system prompt updates". X (Twitter). 2026. https://x.com/ClaudeCodeLog/status/2027594456237527237. Accessed 2026-03-05.
[7] claudefast. "Claude Code Changelog: Complete Version History". 2026. https://claudefa.st/blog/guide/changelog. Accessed 2026-03-05.

## Research Metadata

Duration: ~25 min | Examined: 14 sources | Cited: 7 | Cross-refs: 12 | Confidence: High 83%, Medium 17%, Low 0% | Output: docs/research/claude-code-task-to-agent-migration.md
