[Bug] Background Agent produces no deliverable when parent session hits usage limit
Bug Description
Claude Code Bug Report — Background Agent + Session Limit
Date: 2026-05-04 Reporter: gmanchaiah@gmail.com Product: Claude Code CLI
Summary
Background Agent tool reports completion but produces no deliverable file when the parent session hits its usage limit mid-run. User loses work and has no way to recover agent output.
Environment
OS: Windows (path C:\Users\giris\...)
Mode: Auto mode active
Plugins: context-mode, aws-serverless, document-skills, anthropic-skills, others
Session usage at 98% when background agent launched
Reproduction
Parent session at 98% usage.
Launch background research agent via Agent tool with run_in_background: true. Prompt instructs agent to Write final report to a specified absolute path.
Receive notification: agent completed.
Verify file at expected path → file does not exist.
Re-launch second background agent with same instructions.
Parent session hits usage limit before second agent completes.
No SendMessage tool available in current toolset to query/resume agent.
Expected
Background agent that completes successfully should leave its Write artifacts on disk.
If agent fails, parent should see error/stderr, not "completed" status.
Parent session should be able to retrieve agent results even after usage limit (e.g. agent output persisted to a known location).
Actual
Agent reports complete; no file written.
No mechanism to inspect agent failure without reading the JSONL transcript (which the harness explicitly forbids — "would overflow your context").
When parent session ends, background agent state and any in-flight work appears lost.
Impact
Silent data loss.
User cannot trust "agent completed" notifications.
Background agents are most valuable precisely when context is tight — but that is exactly when they fail opaquely.
Suggested Fixes
Persist background agent's final tool-call summary (especially Write paths) to a small status file the parent CAN safely read.
Distinguish "agent finished its turn" from "agent achieved its goal" in notifications.
Provide a SendMessage / AgentStatus tool by default so parent can query a completed background agent for its deliverables.
When usage limit nears, surface a warning before background agents are launched so user can decide whether to defer.
Agent IDs (for log lookup)
a93ff8663f50186cc — first run, "completed" but no file written
a66a22198a3656213 — second run, parent hit limit before completion
Environment Info
- Platform: win32
- Terminal: mintty
- Version: 2.1.126
- Feedback ID: eb4bff33-cc96-48e7-89ec-18ec4c04c175
Errors
[]This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗