When a Subagent Returns Partial Work: Accept or Fail Loudly

Accept partial work when all three conditions hold.

1. The missing steps are not on the critical path for the caller's next action. If the parent needs field X to write a record, and the child never reached the table containing X, a partial return is worthless to the parent even if it contains twenty other tables. If the parent is compiling a research brief and the child covered four of five subtopics, the gap is survivable.
2. The partial output can be checked mechanically or with a quick human glance. A diff that passes tests, a list of file paths that exist, a table of numbers that reconciles: these can be confirmed. A judge of a prose quality cannot. When verification costs more than re-running the task, accept nothing.
3. The return carries a complete list of what was and was not done. Not a hedge ("I mostly finished"), but an inventory with identifiers.

If any one fails, fail loudly. Loudly means an error object that names the budget limit, the step where it was hit, and any results already gathered.

The reason to be strict about condition three is the observability gap. A subagent's failure typically reaches the orchestrator as a thin string, with no record of what it accomplished, why it failed, how far it got, or whether a retry will hit the same wall (issue 25818). If the schema itself does not force a complete inventory, the parent will guess, and guessing is where fabricated results come from.

There is a fourth, subtler test: would the reviewer act on this return without knowing it was partial? If a reader could mistake the output for a complete answer, the child must mark it. Coverage annotations are the cheapest fix: a synthesis that says "section on brick costs is limited because the merchant price list was unavailable" is far better than a silent omission (the error propagation guide).

Encode the decision in the contract so that neither the child nor the parent has to interpret prose. A minimal schema carries status, reason, the budget limit that was hit, an inventory, the payload, and the suggested next step.

{
  "status": "partial",
  "reason": "budget_exhausted",
  "limit": { "type": "output_tokens", "value": 40000 },
  "stopped_at_step": "cross-check prices against last quarter invoices",
  "completed_steps": [
    "pulled all 12 supplier price rows",
    "normalized currency for 11 of 12 (missing GBP rate)"
  ],
  "missing_steps": [
    "cross-check against invoices",
    "flag outliers above 8 percent variance"
  ],
  "payload": { "prices": [ "..." ] },
  "verification": { "type": "row_count", "expected": 12, "found": 11 },
  "suggestions": [
    "rerun only the invoice cross-check with a fresh 20k budget",
    "accept the 11 rows and mark the GBP row unknown"
  ]
}

Three details matter more than the field names.

Use three statuses, not two. success, partial, and failed are distinct. Collapsing partial into success is silent suppression, the worst anti-pattern, because the coordinator believes the search ran and found nothing and will not retry (the error propagation guide). Collapsing it into failed is the other extreme: one slow worker kills a pipeline and throws away four finished lookups.

Distinguish access failure from a valid empty result. A tool that times out did not reach the data. A query that returned zero rows did reach it. Concrete error objects should carry a retryable boolean and the timeout or permission message, separate from a successful result with an empty list. Conflating the two either triggers pointless retries or skips retries that were needed.

Make the schema fail closed. A structured delegation that returns a non-conforming payload must not report itself as completed. One agent framework shipped exactly this bug: delegate_task could report status = "completed" alongside schema_valid = false, so downstream automation treated an invalid structured response as a success and gated code review on it (the Hermes issue). If the caller asked for a schema, an invalid payload is a failure, whatever the status string says.

The distinction between rows two and three is the heart of the rule, and it is the one most teams get wrong. The child often cannot know which steps are on the parent's critical path, so the delegation prompt must state the caller's next action. "I need the supplier list by country" tells the child that a missing country is fatal. "I need whatever you can find on supplier pricing" tells it that a gap is tolerable. One sentence in the briefing removes most ambiguous partials.

The two outcomes read very differently downstream, and the gap explains why "fail loudly" usually wins ties.

A partial return hands a human a judgment task. The reviewer must read the payload, read the inventory, decide whether the gap matters for the decision at hand, and then decide whether to trust the verification evidence. That is real work, and it is exactly the kind of work that oversight design keeps getting wrong. Industry guidelines tell users to audit and double-check outputs, but the mechanisms users would need to do this effectively are largely absent, and extended reliance on automation degrades the judgment oversight depends on (the oversight paper). A partial return with no coverage annotation quietly shifts workload onto the reviewer and offers no scaffold for it.

A loud failure hands the reviewer a simpler task: pick one of a short list of recovery moves, each of which the error names. Retry with a narrower scope, raise the budget, fix the precondition, or escalate. That is recoverable in a single exchange. Structured error context should carry four elements for exactly this reason: the failure type, what was attempted, partial results gathered before failure, and alternative approaches (the error propagation guide). The bricklaying example in that guide is a good scale model: five subagents look up brick prices, mortar and sand prices, the calendar, past jobs and order history; the brick price subagent times out; the coordinator uses the three prices it got and retries the rest rather than either failing the quote or shipping it without a brick cost.

Audit evidence pushes the same way. An auditor sampling a sensitive action wants to see the policy that applied, the approver, the timestamp, and the outcome of the side effect, tied together by correlation IDs, not just a tool trace (the audit trail guide). A partial return whose gap is invisible in the record is worse than no record, because it looks like evidence. A failure with a reason code and a correlation ID is at least honest.

For a quick reviewer-facing checklist:

• Does the return state the caller's next action was unblocked or blocked?
• Is there a count or checksum that can be confirmed in seconds?
• Does every "done" item have an identifier (path, row, ID) a person can open?
• Does every "not done" item name the step, not just express regret?
• Could a reader mistake this output for a complete answer? If yes, the annotation is missing.

If any answer is no, the honest move is to fail and say why.

Most partial returns exist because nobody told the child where the edge was. A subagent with no budget awareness consumes context until it crashes, and the parent then has no idea how close it got (issue 25817 referenced alongside 25818). Frameworks are moving toward explicit budgets: one harness exposes a shared budget object where hitting the ceiling blocks new spawns while agents already running are allowed to finish, and skipped items come back with a budget_exceeded status instead of vanishing (the gptme subagent docs). Claude Code added a --max-budget-usd flag and had to fix it so that reaching the cap actually halts background subagents rather than letting them spend past the limit (the guardrails summary).

Three practices make the split decision uncommon:

Stash checkpoints before the last expensive step. If the child writes its findings incrementally, then running out of budget produces a real partial rather than a lose-everything crash. The parent gets usable state and a clean gap.

Give every child a reserve for the return. A subagent that spends its entire budget on tool calls has nothing left to write the summary. Reserve some fraction for the final message and the inventory.

State the caller's next action in the delegation prompt. This is the single highest-leverage change. The child cannot rank its own subtasks against an invisible critical path, and one line of context fixes that.

Teams running many delegations across providers face a related cost problem: the same context gets re-billed at every hop, and budgets set per agent miss the interactions between them (the cost analysis). A single API for every model type, with prepaid pricing in dollars, makes the budget side of planning simpler and keeps the ceiling legible: Quanta Inference (https://quantaintelligence.ai/inference) exposes text, image, video, audio and embedding models through one OpenAI-compatible key.

The return contract is code, so test it like code. A small fixture suite catches most regressions:

def test_budget_exhaustion_with_gap_off_critical_path():
    result = run_child(task="list 12 suppliers by country", budget=2000,
                       caller_next_action="draft a supplier email")
    assert result["status"] == "partial"
    assert result["reason"] == "budget_exhausted"
    assert result["verification"]["found"] < result["verification"]["expected"]
    assert "missing_steps" in result and result["missing_steps"]

def test_budget_exhaustion_on_critical_path_fails():
    result = run_child(task="fetch GBP exchange rate", budget=10,
                       caller_next_action="price the GBP order")
    assert result["status"] == "failed"
    assert result["stopped_at_step"]

def test_schema_violation_never_reports_success():
    result = run_child(task="review this diff", output_schema=REVIEW_SCHEMA,
                       force_invalid_response=True)
    assert result["status"] == "failed"
    assert result["schema_valid"] is False

def test_empty_result_is_not_an_access_failure():
    result = run_child(task="find orders placed tomorrow")
    assert result["status"] == "success"
    assert result["payload"] == []
    assert result.get("retryable", False) is False

Four tests, and each one corresponds to a failure mode that has been observed in the wild: runaway delegation, blind retry, schema-invalid success, and conflated empty results.

If your review of subagent returns turns into a larger program of work, the reviewers and auditors who own the acceptance decision are the people Quanta Experts (https://quantaintelligence.ai/agents) is built for: each expert reads the context, does the work, and hands back a finished deliverable rather than raw tool output.