Sub-Agent Patterns

The Task tool spawns a sub-agent — a separate Claude instance that runs independently, performs a scoped task, and returns only its output to the main session. The sub-agent does not see your conversation history. It does not have your accumulated context. It gets a fresh context window with a specific instruction and produces a result. This isolation is both the power and the limitation. It is powerful because the sub-agent gets a clean, focused context for its task. It is limiting because it cannot reference decisions made earlier in your main session.

The right tasks for sub-agents are atomic and independent. Architecture audits: "Scan the src/ directory and report any files over 500 lines." Code scanning: "Search for all uses of deprecated API calls." Documentation generation: "Read the public API surface and generate JSDoc stubs." Dependency analysis: "List all packages in package.json that have major version updates available." Each of these is self-contained — the sub-agent does not need to know what feature you are building or what decisions you made this session. It just needs to scan, analyze, and report.

The wrong tasks for sub-agents are anything context-dependent. "Write the tests for the feature I just built" fails because the sub-agent does not know what you built. "Refactor the auth module using the pattern we discussed" fails because the sub-agent was not part of the discussion. "Fix the remaining issues" fails because the sub-agent does not know what issues exist. If a task requires knowledge from the current conversation, keep it in the main session. Sub-agents are scouts — send them on reconnaissance missions, not on tasks that require institutional knowledge.