Feature: Research skill file-based agent result handoff for Extensive/Deep tiers

[virtualian]

Type

Investigation — Feature or Bug?

Problem Statement

Claude Code agents operate in isolated context windows. When they complete, results flow back to the parent via <task-notification> messages. This raises fundamental architecture questions about how agents should communicate:

1. Agent → Parent: Currently dumps full result text. No truncation. No file-based handoff.
2. Agent → Agent: No direct communication path exists. Agents can't coordinate or share findings.
3. Parent → Agent: Only at spawn time via the prompt parameter. No mid-execution messaging (except via Agent Teams/Swarm which uses SendMessage).

Core question: What are the designed communication patterns for Claude Code agents, and where do PAI's assumptions diverge from the intended design?

Specific Observations

Agent Result Injection

From session 10625351 forensics:

L432  task-notification from agent a55fc65: 15,104 chars injected into parent
L206  task-notification from agent a4d43ba: 20,618 chars injected into parent  
L194  task-notification from agent a45a5c5: 12,644 chars injected into parent

Each of these is the full agent output — not a summary. When 7+ agents complete in quick succession, the parent accumulates 100K+ chars of task-notifications alone.

Auto-Compact Cascade Failure

When context overflows, Claude Code spawns auto-compact agents. But:

• The compact agent receives the full conversation (including all bloated task-notifications) as its input
• If the conversation is already too large, the compact agent's prompt is also too large
• Result: 14 compact agents spawned, all failed with "Prompt is too long"
• This is a feedback loop with no exit — the only escape was /exit

Agent Teams vs. Background Agents

PAI has two agent coordination mechanisms:

• Task tool (run_in_background: true) — isolated agents, results via task-notification
• Agent Teams (TeamCreate + SendMessage) — coordinated agents with shared task lists and direct messaging

Question: Should research workflows use Agent Teams instead of background Task agents to manage context better? Are Agent Teams designed for this use case?

Investigation Questions

1. Is there a max_result_length or truncation parameter for Task tool results?
2. Can agents write to shared files as their output mechanism instead of returning text?
3. What is the designed flow for 5+ parallel agents that each produce 10K+ char results?
4. Should PAI's Research skill use Agent Teams (SendMessage for incremental results) instead of background agents (full result dump)?
5. Is the auto-compact cascade failure a known issue? Is there a circuit breaker?
6. Does Claude Code have context usage metrics accessible to the model (e.g., "you're at 80% context")?

Related

• Depends on findings from: "Investigate: Agent result reporting overflows parent context"

Affected PAI Components

• Research skill architecture
• Algorithm's agent spawning in CAPABILITIES SELECTION
• Delegation system (SYSTEM/THEDELEGATIONSYSTEM.md)
• Agent system (SYSTEM/PAIAGENTSYSTEM.md)

[virtualian]

Status Review (2026-03-01)

Addressed through clear system documentation.

The v4.0.1 codebase explicitly documents two distinct agent communication systems in THEDELEGATIONSYSTEM.md:

1. Custom Agents (Task tool): Fire-and-forget parallel workers. No shared state, no inter-agent messaging. Results collected after completion. Used by Research skill for parallel researcher dispatch.
2. Agent Teams (TeamCreate + SendMessage): Persistent coordinated teams with shared task lists and direct inter-agent messaging. Used for complex multi-step work requiring coordination.

Key findings:

• Research skill intentionally uses pattern Create Diataxis Documentation Pack #1 (parallel agents, not teams) — appropriate for parallelizable one-off work
• The two systems are documented as "COMPLETELY DIFFERENT SYSTEMS" with clear routing rules
• Context boundaries are explicit: custom agents get full prompt at spawn, no mid-execution input; teams communicate via SendMessage

Remaining concern: The context overflow risk from pattern #1 (issue #24) is documented but not mitigated at the platform level. The design decision is to prevent bloat upstream (word limits in prompts) rather than manage it downstream (truncation).

Could close this as documented/by-design, but it's linked to #24's unresolved overflow risk.

[virtualian]

Status Review (2026-03-08) — Cross-Reference with #24

The communication pattern question in this issue IS the root cause of #24's overflow.

Answering the Six Investigation Questions

#	Question	Finding
1	max_result_length or truncation parameter?	No. Claude Code v2.1.71 has no such parameter. Disk persistence at ~50K chars is the only implicit mechanism.
2	Can agents write to shared files as output?	Yes — PAI already does this. Deep Investigation writes to MEMORY/RESEARCH/{slug}/. Telos writes 13 extraction files. Parser writes JSON to disk. Research is the outlier that doesn't.
3	Designed flow for 5+ parallel agents with large results?	Isolated subagent contexts (new in CC) + summarized return. But no explicit large-result pattern. Agent Teams recommended for sustained parallelism.
4	Should Research use Agent Teams?	Not for the overflow problem. Agent Teams solve coordination, not context management. SendMessage results still inject into parent context. Agent Teams make sense when Research needs multi-step coordination across 3+ workstreams, but that's a different problem.
5	Auto-compact cascade failure known?	Yes, confirmed upstream. No circuit breaker. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70 is the workaround (buggy but better than default 95%).
6	Context usage metrics accessible to model?	No API for it. The Algorithm's 60% self-summarization rule (v3.7.0 line 361) is heuristic, not measured. /context shows what's loaded but isn't accessible programmatically.

Current PAI Agent Communication Architecture

PAI has three agent systems with different context implications:

System	Pattern	Context Impact	Used By
Task tool (fire-and-forget)	Agents return inline	Full result injected into parent	Research (Standard, Extensive), Custom Agents
Agent Teams (TeamCreate)	Persistent teams, SendMessage	Messages still inject, but targeted	Delegation skill (3+ workstreams)
File artifacts (disk-based)	Agents write files, parent reads later	Zero context injection	Deep Investigation, Telos extraction, Parser

Research currently uses only Pattern 1 — the most overflow-prone approach. Pattern 3 already exists and is production-proven in the same codebase.

The Fix

For Extensive/Deep Research: Adopt Deep Investigation's file-based handoff pattern. Each researcher agent writes findings to MEMORY/WORK/{slug}/agent-results/{agent-name}.md, then returns a 1-line summary ("Wrote 3,200 words on market analysis to agent-results/claude-1.md"). Parent reads files for synthesis instead of receiving inline dumps.

For Standard Research (2 agents): No change needed. Two agents returning <1500 words each won't overflow.

Immediate safety net: Set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70 in PAI settings.json.

Recommendation

Keep open but reclassify. This is no longer an investigation — the answers are clear. Convert to a feature request: "Research skill: file-based agent result handoff for Extensive/Deep tiers." Close #24 when that's implemented, since it eliminates the overflow path.

See #24 for the upstream platform analysis and timeline.