Summary
The background agent handoff pipeline is a pattern for asynchronous AI coding agents to integrate their work into the standard development workflow upon completion. Instead of running silently and potentially losing results, the handoff pipeline ensures that background agents commit changes, push to a remote branch, open a draft pull request, and emit notification events (agent_needs_input, agent_completed). Subagents inherit the parent's model configuration and extended thinking, and when cut off by rate limits, they now return partial work to the parent rather than failing silently. This pattern represents the industry endpoint for agent-to-repo integration, going beyond local worktree commits to full collaborative PR workflows.
Key Points
- Background agents should execute and integrate: commit, push, and open a draft PR on completion.
- Notification hooks (
agent_needs_input,agent_completed) allow orchestration and human-in-the-loop handling. - Subagents inherit the parent's model (capped at Opus) and extended thinking.
- Rate-limit cutoffs no longer cause silent failure — subagents return partial work to the parent.
- This pattern validates the safety commit principle: even leading implementations initially had the lost-partial-work bug.
Concepts
- Background agent: An autonomous agent running asynchronously (e.g., subprocess or task) to perform a subtask.
- Handoff: The transfer of completed or partially completed work from a background agent back to the main workflow via version control and pull request infrastructure.
- Draft PR: A pull request marked as draft, indicating work in progress not ready for review.
agent_needs_inputevent: Notification that the background agent requires human guidance to proceed.agent_completedevent: Notification that the background agent has finished its task.