Epic: Subagent State Handoff & Context Boundary Resilience

[riatzukiza]

Epic: Subagent State Handoff & Context Boundary Resilience

Overview

This epic addresses the fundamental architectural weakness in how OpenCode handles context boundaries between parent agents and subagents, as well as during session compaction. Currently, when context transfers occur between different execution scopes, critical information can be lost, leading to silent failures, stuck states, and incomplete recovery.

Problem Statement

Context Boundary Fragility: Both subagent delegation and session compaction represent context transfers where:

1. State Loss: Critical working context, rules, and progress can be lost
2. Failure Visibility: Parents cannot detect when subagents fail or get stuck
3. Recovery Failure: Insufficient information for agents to continue work after context reset
4. Permission Blindness: Parent agents cannot see subagent permission requests

Related Issues

Subagent State Handoff Issues

• Subagent results not always properly handled anomalyco/opencode#3173 - Subagent results not always properly handled
• Feature request: let subagents inherit context anomalyco/opencode#2588 - Feature request: let subagents inherit context
• Sub-agent's request for permission is not shown in the primary agent's view anomalyco/opencode#4078 - Sub-agent's request for permission is not shown in primary agent's view
• Feature: Subagents should support auto compaction anomalyco/opencode#3153 - Feature: Subagents should support auto compaction
• [FEATURE]: Improve Subagent Invocation Documentation anomalyco/opencode#3715 - Improve Subagent Invocation Documentation

Compaction Context Issues

• Agent no follow rules after compact session anomalyco/opencode#3099 - Agent no follow rules after compact session
• Model in BUILD mode does not have enough context to continue after compaction anomalyco/opencode#3031 - Model in BUILD mode does not have enough context to continue after compaction
• Session automatically compacted, destroying the entire working context anomalyco/opencode#2945 - Session automatically compacted, destroying the entire working context

Solution Areas

1. Enhanced State Handoff Protocol

• Bidirectional State Sync: Continuous state synchronization between parent and subagent
• Progress Indicators: Real-time visibility into subagent execution state
• Failure Detection: Parent agents can detect when subagents are stuck or failed
• Recovery State: Sufficient context for agents to recover and continue work

2. Context Inheritance & Preservation

• Context Forking: Subagents inherit relevant parent context (configurable)
• Rule Persistence: Agent rules and AGENTS.md survive context transfers
• Working State: Current task state, file changes, and progress preserved
• Selective Context: Intelligent filtering of what context to inherit

3. Permission & Notification Bridge

• Permission Forwarding: Subagent permission requests visible to parent
• Status Broadcasting: Real-time status updates across context boundaries
• Error Propagation: Clear error communication between contexts
• Progress Events: Detailed progress information for long-running tasks

4. Resilient Recovery Mechanisms

• Handoff Documents: AI-generated context handoff documents for recovery
• State Snapshots: Periodic state snapshots for recovery points
• Rollback Capability: Ability to rollback to known good states
• Continuation Prompts: Rich context for agents to continue work

Success Criteria

1. No Silent Failures: Parents always know subagent status (working, stuck, failed, completed)
2. Complete Context Recovery: Agents can fully recover work after any context transfer
3. Permission Transparency: All permission requests visible to appropriate users
4. Rule Persistence: Agent rules survive all context boundaries
5. State Continuity: Working state preserved across compaction and subagent calls

---

This epic represents a fundamental improvement to OpenCode's reliability and user experience when dealing with long-running, complex tasks that span multiple context boundaries.

[riatzukiza]

Related Issues & Context

This Subagent State Handoff epic is fundamentally related to the Compaction Update epic (#46) because both address the same core architectural problem: context boundary fragility.

Direct Relationship:

• Subagent failures (sst/opencode issues Subagent results not always properly handled anomalyco/opencode#3173, Feature request: let subagents inherit context anomalyco/opencode#2588, Sub-agent's request for permission is not shown in the primary agent's view anomalyco/opencode#4078, Feature: Subagents should support auto compaction anomalyco/opencode#3153) = Context transfer between different agents
• Compaction failures (Compaction: Preserve rules/constraints across compaction #48, Compaction: Structured BUILD-mode handoff summary prompt #49, Compaction: Smarter boundary selection and cross-session guard #47, Compaction: Pruning/soft compaction and selective tool-output deletion #50, Compaction: Telemetry and /status for context + decisions #52, Compaction: Concurrency/locking robustness and retries #53, Compaction: Provider options flow and accurate usage accounting #51, Compaction: Tests – boundary, rules, pruning, integration #54, Compaction: Configurable preserved turns and prune thresholds #55) = Context transfer within same agent across time

Shared Technical Solutions:

The compaction improvements will directly benefit subagent state handoff:

1. Rules Preservation (Compaction: Preserve rules/constraints across compaction #48) → Subagent Rules Inheritance

   • Same mechanism for preserving AGENTS.md and user constraints across boundaries
   • Both need rules to survive context transfer

2. Structured Handoff Documents (Compaction: Structured BUILD-mode handoff summary prompt #49) → Subagent State Snapshots

   • BUILD-mode handoff format can be adapted for subagent recovery
   • Both need rich context for work continuation

3. Boundary Selection (Compaction: Smarter boundary selection and cross-session guard #47) → Context Inheritance Logic

   • Smart context filtering principles apply to both scenarios
   • Configurable preserved turns become configurable inherited context

4. Telemetry/Observability (Compaction: Telemetry and /status for context + decisions #52) → Subagent Monitoring

   • Same visibility into what context was kept/dropped
   • Essential for debugging both compaction and subagent failures

Implementation Dependencies:

• Concurrency Safety (Compaction: Concurrency/locking robustness and retries #53) required for both compaction and subagent communication
• Usage Accounting (Compaction: Provider options flow and accurate usage accounting #51) needed for cost tracking across both contexts
• Config Options (Compaction: Configurable preserved turns and prune thresholds #55) can expose subagent knobs alongside compaction settings
• Test Framework (Compaction: Tests – boundary, rules, pruning, integration #54) validates both compaction and subagent boundary behavior

Strategic Impact:

Fixing compaction provides the infrastructure foundation for robust subagent state handoff. The context transfer mechanisms, persistence strategies, and observability systems will serve both problem domains.