This document covers the Task Tool in Amp, a specialized sub-agent delegation mechanism for executing heavy, multi-file implementations. The Task Tool operates as a "fire-and-forget" executor for well-defined work packages that don't require interactive decision-making. For planning and architectural guidance, see Oracle AI Advisor Architecture. For code discovery, see Codebase Search Agent and Code Navigation.
The Task Tool functions as a productive junior engineer that executes detailed instructions without the ability to ask follow-up questions once started. It is designed for bulk execution work where the scope and approach are already determined.
Sources: Amp/gpt-5.yaml220-253 Amp/claude-4-sonnet.yaml200-208
The Task Tool should be used for:
| Use Case | Description | Example |
|---|---|---|
| Feature scaffolding | Creating boilerplate structure across multiple files | Generating CRUD endpoints with models, controllers, routes |
| Cross-layer refactors | Systematic changes that touch multiple architectural layers | Renaming a service across API, business logic, and data layers |
| Mass migrations | Repetitive transformations across many files | Converting class components to functional components |
| Boilerplate generation | Creating repetitive code structures | Adding test files for multiple modules |
| Anti-Pattern | Why It Fails | Use Instead |
|---|---|---|
| Exploratory work | Task Tool cannot discover or investigate | Codebase Search Agent + Main Agent |
| Architectural decisions | Cannot make judgment calls or design choices | Oracle Tool for planning |
| Debugging analysis | Cannot interactively test hypotheses | Oracle Tool + Main Agent iteration |
| Ambiguous requirements | Cannot ask clarifying questions | Main Agent should clarify first |
Sources: Amp/gpt-5.yaml236-246
Sources: Amp/gpt-5.yaml220-232
The Task Tool supports parallel execution when write targets are disjoint. Multiple Task Tool instances can run simultaneously if they don't conflict.
| Condition | Action | Example |
|---|---|---|
| Disjoint files | Parallel execution | Three test files, each modified by separate Task |
| Disjoint directories | Parallel execution | UI components + backend logs |
| Same file(s) | Serialize | Two refactors touching types.ts |
| Shared contract | Serialize | Changes to DB schema + API types |
| Chained transforms | Serialize | Step B requires artifacts from Step A |
Sources: Amp/gpt-5.yaml72-121 Amp/claude-4-sonnet.yaml200-208
A well-formed Task Tool invocation must include:
Bad Prompt (Insufficient):
Make the authentication system better
Good Prompt (Complete):
Goal: Add JWT token validation to all API endpoints
Deliverables:
- middleware/auth.js with validateToken function
- Updated routes in routes/*.js to use middleware
- Test file test/auth.test.js with token validation tests
Steps:
1. Create middleware/auth.js with JWT library
2. Implement validateToken() that checks token expiry and signature
3. Add middleware to each route in routes/ directory
4. Write tests covering valid/invalid/expired tokens
Validation:
- Run npm test to verify all tests pass
- Run npm run typecheck to ensure no type errors
Constraints:
- Use existing jsonwebtoken library (already in package.json)
- Follow error handling pattern from middleware/logging.js
- Use same test structure as test/user.test.js
Context:
[Attach relevant code snippets from existing middleware]
Sources: Amp/gpt-5.yaml247-253
The recommended workflow integrates all three sub-agent types:
| Principle | Implementation | Rationale |
|---|---|---|
| Oracle → Codebase Search → Task | Planning first, discovery second, execution last | Ensures informed execution |
| Scope constraints | Directories, file patterns, acceptance criteria | Prevents unbounded work |
| Many small requests | Multiple focused Task invocations | Better than one giant ambiguous task |
| Explicit prompts | Detailed instructions with examples | Compensates for no follow-up ability |
Sources: Amp/gpt-5.yaml289-298
Sources: Amp/claude-4-sonnet.yaml200-208
The Task Tool operates with no feedback loop during execution:
| Limitation | Impact | Mitigation |
|---|---|---|
| Cannot ask clarifications | May misinterpret ambiguous instructions | Provide extremely detailed prompts |
| Cannot adapt to discoveries | May continue down wrong path | Use Oracle/Main Agent for exploration first |
| Cannot make judgment calls | May implement suboptimal solution | Pre-decide all design choices |
| Cannot handle blockers | May fail silently | Test commands and acceptance criteria in prompt |
Sources: Amp/gpt-5.yaml96-107
The Task Tool serves as a delegation mechanism for bulk execution work in Amp:
The Task Tool's "fire-and-forget" nature makes it powerful for well-scoped work but requires comprehensive upfront specification since it cannot ask follow-up questions during execution.
Sources: Amp/gpt-5.yaml220-298 Amp/claude-4-sonnet.yaml200-208 Amp/README.md1-21
Refresh this wiki