# Evolution: task-to-agent-migration -- Claude Code v2.1.63 Breaking Change Adaptation

**Project**: nWave DES (Deterministic Execution System)
**Feature**: task-to-agent-migration -- adapt DES hooks to Task->Agent tool rename
**Date**: 2026-03-05
**Type**: Bug fix (breaking change adaptation)
**Status**: Complete
**Commits**: `3b4a669` (implementation), `8f2b51c` (docs)

---

## What Was Done

Claude Code v2.1.63 introduced two breaking changes that silently broke DES hooks:

1. **Tool renamed**: `Task` -> `Agent`. Hook matchers with `"matcher": "Task"` stopped firing entirely.
2. **`max_turns` removed**: Parameter removed from tool invocation schema. `MaxTurnsPolicy` always returned `MISSING_MAX_TURNS`, blocking every agent invocation.

### Code Changes

- Removed `MaxTurnsPolicy` and all `max_turns` validation from the DES pipeline
- Updated hook matchers from `"Task"` to `"Agent"` in the DES plugin and installer
- Added matcher migration logic: plugin detects stale `"Task"` matchers on reinstall and replaces them
- Removed `get_max_turns_default()` from `ConfigPort` and all adapter implementations
- Removed `max_turns` field from `PreToolUseInput`
- Deleted obsolete `test_max_turns_validation.py` (418 lines)
- Added 10 regression tests covering the migration
- Updated 7 agent definitions, CLAUDE.md architecture diagram, and DES messages table

### Turn Limit Enforcement

Turn limits moved from DES runtime validation (`max_turns` in tool invocation) to declarative configuration (`maxTurns` in agent YAML frontmatter). All 23 nWave agents already had `maxTurns` configured.

---

## Key Decisions

| Decision | Rationale |
|----------|-----------|
| Remove MaxTurnsPolicy entirely | Claude Code removed `max_turns` from the schema. Validating a nonexistent field would block all invocations. |
| Move turn limits to agent frontmatter | Declarative > imperative. Each agent declares its own limit. Claude Code reads `maxTurns` natively. |
| Add matcher migration in plugin | Existing installations have stale `"Task"` matchers. Plugin detects and replaces on reinstall. |
| SubagentStop hook unchanged | No tool-name matcher (fires for all agent stops). Rename did not affect it. |

---

## User Action Required

Users must run `nwave install` to update hook configuration (matchers `"Task"` -> `"Agent"`).
