feat(delegation): surface ready dependencies before the next decision

[Xipong]

Important

This is the final behavior layer of a three-PR stack. It is cumulative over #76228 and #76229 because a fork branch cannot be used as the base of an upstream PR. The behavior owned by this PR is implemented by 9a6293b89 plus the review-hardening fix dd5a4aef3; the stack map below separates the review boundaries.

What this improves

Hermes can already run background subagents in parallel, but parallel execution is only useful when the result arrives while it can still affect the work that depends on it. Today, a reviewer, auditor, or prerequisite can finish during a long foreground turn yet remain invisible until that turn is over. By then the parent may already have made the edit, committed the change, or produced the final answer the child was meant to check.

This PR makes an explicitly dependent result visible at the next existing safe continuation boundary, while the parent still has an opportunity to use it. It turns background review from a post-hoc notification into actionable feedback without making the parent wait.

A concrete sequence is:

1. the parent delegates a review or prerequisite and marks that delegation inject;
2. the parent continues reversible discovery or tool work instead of blocking on the child;
3. the child finishes before a later provider continuation;
4. its marked evidence is included in that continuation;
5. the parent can change the next tool call, avoid a bad edit, or investigate a blocker before finalizing.

Under after_turn, step 4 happens only after the foreground workflow has ended. The bytes may eventually be identical, but their causal value is not: an audit received after the decision can only trigger rework, while the same audit received before the next decision can prevent the mistake.

The practical benefits are:

• useful parallelism: the parent does not have to choose between waiting for a reviewer and making the reviewer irrelevant;
• less avoidable rework: a ready blocker can stop or redirect unfinished work instead of reopening it in a later turn;
• lower end-to-end latency: the result uses a continuation the agent was already going to make, rather than requiring a manufactured reconciliation call;
• better delegation UX: the parent can choose whether a result is time-sensitive or simply useful after the turn, without learning a new workflow;
• larger gains on long agentic turns: the more tool calls and reversible decisions occur before finalization, the more valuable an already-ready dependency becomes.

Zero-setup dependency awareness

Most delegated dependencies in Hermes are ad hoc: review this edit, verify this assumption, inspect this failure, or check this plan. They are too small to justify user-managed project state or a separate orchestration setup, but timing still matters because the answer may invalidate what the parent is doing now.

Without a lightweight timing signal, the parent has two bad choices:

• wait for the child and give up background parallelism; or
• keep working and accept that the child may become useful only as a post-mortem.

This PR removes that false choice inside the existing delegate_task UX. The parent marks the result as time-sensitive where it creates the work; Hermes then uses the existing delivery machinery to expose it at a useful boundary when possible. There is no new user-facing system to configure, no separate queue to operate, and no persistent planning workflow to maintain.

The contract is bounded best effort, not a barrier:

If an opted-in result is ready at an existing safe continuation boundary, expose it before the next decision. Otherwise do not wait; preserve ordinary after-turn delivery.

Why this is a net improvement across model quality

Using timely evidence does not require a perfect planner; reacting to new tool evidence is already a core part of an agentic continuation. Straightforward results such as “this API assumption is false,” “the test fails at this boundary,” or “this edit violates the requested scope” can help any model that can use ordinary tool output. More capable models gain even more because they can synthesize nuanced independent review into their next decision instead of merely reading a post-mortem.

The upside is concrete:

• when the parent uses the evidence well, it can prevent an incorrect edit, commit, tool call, or final answer before the cost is incurred;
• when the evidence would not help, after_turn remains the default and the parent need not opt in;
• if the safe boundary never appears, Hermes adds no wait or extra iteration and falls back to the existing path;
• the child report is clearly marked and arrives alongside tool evidence that the model already has to interpret on that continuation.

A weaker model may still over-focus on injected evidence, spend effort reconciling an unimportant detail, or drift toward the child's framing. That is a quality-of-reasoning risk around one explicitly selected dependency, not a failure of delivery, history, or recovery. The downside is bounded by opt-in use and an unchanged default; the upside can avoid work that has already become wrong.

In other words, this PR adds a missing causal opportunity; it does not guarantee model judgment. Keeping all results after-turn because some models may use feedback poorly would also prevent stronger models—and weaker models in straightforward cases—from using timely, correct feedback at all. The safe policy is therefore opt-in current-turn eligibility with an unchanged default and durable fallback, not removing the opportunity globally.

Safe continuation shape

A ready dependent result is carried on the last new, unsent tool result of a complete tool-call batch. It is attached before that tail is first persisted. The next request therefore keeps the ordinary continuation shape:

assistant(tool_calls) → tool(tool output + clearly marked background evidence) → assistant

There is no additional conversation message, no claimed user authorship, no rewritten history, and no manufactured model iteration. If that existing boundary does not occur before the foreground turn ends, the same durable event remains pending for the normal after_turn path.

One delivery rail, better result timing

This is a UX improvement to the existing delegate_task flow, not a new task-management abstraction. result_delivery only records whether a delegation result is time-sensitive for the active work or can wait for the normal between-turn delivery:

active dependency/review  → eligible at the next safe current-turn boundary
independent work          → eligible at the normal between-turn boundary

Both use the same:

• subagent execution;
• durable child-event identity;
• completion queue;
• claim and lease protocol;
• formatting;
• crash recovery;
• parent session/turn binding;
• exactly-once settlement;
• late-delivery path.

The state machine remains shared:

pending → claimed → delivered
             ↘ released → pending

For an inject event, the active loop merely gets the first bounded opportunity to claim it. If that opportunity is absent, late, lost, or rolled back, the event is still the same pending row consumed by after_turn. There is no second queue, ledger, recovery scanner, or settlement protocol.

Synthetic user vs. tool-boundary carrier

The old #74378 implementation did this after a tool block:

append a new message:
    role = user
    content = delegation result

Even where a provider accepts tool → user → assistant, that representation is wrong for Hermes: the user did not send the message, and the active turn did not end. It also forced the loop to handle a synthetic turn, provisional finalization, reconciliation grace, and provider-specific tail behavior.

This PR does something narrower:

1. wait for a complete tool-call batch that already requires another model continuation;

2. inspect only the new, not-yet-persisted tool-result tail;

3. append a clearly delimited block beginning with:

   [DELEGATION RESULT READY — background evidence for the current task;
   not a new user request]
   

4. persist that tool tail;

5. acknowledge the durable child row only after the transcript commit succeeds.

The provider necessarily receives the evidence inside tool-result content. The marker explicitly distinguishes that framework-added evidence from the bytes produced by the invoked tool and identifies its purpose. This reuses the same deliberate Hermes boundary as /steer, which already appends clearly marked external input to the last tool result so the next assistant continuation can observe it without inserting a role. Tool output in Hermes can already contain framework-added truncation, guardrail, and steering context; this adds another explicitly identified framework block at that established seam.

The restriction is intentional: if there is no complete tool batch, this PR does not fabricate a carrier. The event stays on after_turn.

How this addresses the #74378 close review

The close review identified real problems in that implementation. This redesign does not ask maintainers to relax those invariants.

Close-review concern	What is true after this redesign
synthetic role:"user" inside an active turn	eliminated; no delegation message is created
provider-dependent handling of a new user role after tool results	no such transition exists; the provider sees its ordinary tool continuation
prompt-cache integrity	no system or previously sent message is modified; no new synthetic user segment is added; only an unsent tail is finalized before its first request
roughly ten hooks plus provisional-final/grace lifecycle	provisional finalization and grace calls are gone; active-loop work is localized to the existing post-tool persistence checkpoint plus common rollback
TUI/active-loop competition	#76229 gives all consumers one routing reservation and the same durable claim API
the existing queue “already delivers the benefit”	it delivers the output, but only after the decision; it does not preserve the already-available review/dependency window

The provider/cache concerns around the old shape were compatibility risks, not evidence that every major provider necessarily rejected it or that an already-cached prefix was rewritten. The decisive issue was Hermes' own turn/authorship invariant. The new carrier removes that issue rather than arguing for an exception.

The remaining product question is therefore precise:

Should a completed, explicitly dependent child be allowed to affect unfinished parent work at an already-existing safe tool boundary?

It is no longer a question about permitting synthetic user turns.

Bounded semantic risk and unchanged baseline

The model-quality risk is deliberately contained at the policy surface:

• after_turn remains the default and the interpretation of legacy or missing values;
• inject is explicit delegation metadata, chosen only when the result may change unfinished work;
• missed boundaries automatically preserve after_turn delivery;
• Hermes does not wait, poll, add a grace call, or extend the iteration budget;
• this PR adds no model-strength presets, user settings, mandatory /goal, or routing heuristics.

Existing goals, tool limits, iteration limits, compaction, and persistence still shape long-running agents, but they are surrounding capabilities—not scope added by this PR.

Bounded carrier storage

Delegation evidence uses the existing tool-result budget instead of bypassing it:

• the final provider-visible text on the carrier is limited by the smaller of the configured default per-result cap and aggregate turn budget;
• if the full formatted child report does not fit, maybe_persist_tool_result(...) stores that report in the active environment and the carrier receives the ordinary <persisted-output> path plus bounded preview;
• if full-report storage is unavailable or cannot fit its pointer safely, the event is not claimed or truncated: it remains pending with its delivery-attempt count unchanged for the normal after_turn rail.

This keeps the child goal/context/summary available without allowing a large formatter result to inflate the next provider request after ordinary tool-output budgeting has already run.

Failure ordering

Carrier settlement is deliberately persistence-first:

1. format the ready report and fit it inline or spill the complete formatter output through bounded tool-result storage;
2. claim the ready child row;
3. append evidence only to the new complete tool tail and register its pending claim ownership;
4. durably persist that append-only transcript tail;
5. acknowledge the child row.

If any operation after content mutation fails—including pending-claim registration or heartbeat startup—the exact original target structure is restored and every acquired durable claim is released/requeued. If persistence fails, the same rollback path removes the carrier before the event returns to pending. If the carrier was persisted, its durable event identity prevents restart recovery from presenting it twice. Private claim/display metadata is stripped before provider serialization.

Stack and review boundaries

PR	Owned commit	Responsibility	Standalone effect
#76228	778dcaab3	durable child identity and settlement	recovery foundation; visibility unchanged
#76229	b2c9c3e24	ready-set routing at existing between-turn consumers	faster/default after_turn; no active-loop behavior
#76230	9a6293b89 + dd5a4aef3	opt-in tool-boundary eligibility, bounded carrier, and transactional rollback	ready dependencies may affect unfinished work without bypassing tool-result storage

Reviewing the cumulative branch commit-by-commit gives three ownership cuts. After the foundations merge, this PR can be rebased to show only 9a6293b89 and its focused hardening commit dd5a4aef3.

Compatibility

• default and legacy behavior: after_turn;
• /background: unchanged;
• no completed tool batch: no same-turn carrier;
• late/failed/lost carrier opportunity: same durable event remains for after_turn;
• Chat Completions, Anthropic, Gemini, and Responses retain their native tool-result role shape;
• OpenRouter/custom Chat Completions do not require a brand allowlist because no provider-specific message role is introduced;
• no new config or UI surface.

Verification

• review-hardening matrix on dd5a4aef3: 214 passed, 0 failed across carrier/ledger/storage, production compressor, CLI, gateway, TUI lifecycle, and executor paths;
• a 250,000-character child summary is stored through canonical tool-result spill while the final carrier remains within a 10,000-character result budget;
• unavailable spill leaves the full event pending, unmodified, and at delivery attempt 0;
• fault injection after content mutation but before pending-claim ownership proves exact target restoration plus durable release/requeue;
• a bounded carrier is loaded back from SessionDB, processed by the production ContextCompressor, and retained in the sanitized provider payload;
• carrier/ledger/CLI/gateway/TUI affected matrix: 662 passed, 0 failed;
• combined carrier + subagent model/reasoning/provider integration: 814 passed, 0 persistent failures; one unrelated TUI concurrent-write flake passed the full-file retry and a fresh targeted rerun;
• provider contract tests cover Chat Completions, Anthropic, Gemini, and Responses tool-result serialization;
• tests prove no synthetic delegation-user message and no mutation of prior message/system-prompt bytes;
• private carrier/claim metadata is absent from provider payloads;
• full GitHub CI on dd5a4aef3: 28 successful, 9 skipped, 1 neutral, 0 failures; PR mergeable_state: clean;
• Ruff, py_compile, and git diff --check: passed;
• current head (rebased): dd5a4aef3f7ae7cfb6473869c5f16c12b2a0e839.

Related

• Supersedes the carrier representation in feat(delegation): add same-turn background result injection #74378 without reopening or force-pushing the maintainer-closed PR.
• refactor(delegation): persist child-scoped delivery state #76228 and feat(delegation): route ready children between turns #76229 are the independently reviewable foundations requested in the close review.

Coordination graph

• Issue interlock: Fixes Delegation timing: let a ready dependency affect unfinished parent work #85648
• Stack siblings: refactor(delegation): persist child-scoped delivery state #76228 and feat(delegation): route ready children between turns #76229
• Dependency edges: depends on both foundations; no PR depends on this optional final layer
• Collision constraints: fix(gateway): persist async task origins across restart #75117, fix(delegation): preserve redacted output on timeout #65824, fix(tui): isolate background notifications by UI session #61719/fix(gateway): route plain background live output to its spawn-time UI owner (#61719 residual) #73351, feat(tui): async delegation view — docked agents panel + live steering #70899, and fix(slack): preserve interactive context and surface delegated profiles #82519 overlap parts of delegation/gateway/TUI routing. This PR owns only opt-in current-turn eligibility and bounded tool-tail carriage; it does not own origin persistence, timeout redaction, notification ownership, UI observability, or Slack profile context
• Merge order: refactor(delegation): persist child-scoped delivery state #76228 → feat(delegation): route ready children between turns #76229 → feat(delegation): surface ready dependencies before the next decision #76230. Review the two commits owned by this layer only after the foundations are accepted
• Closed predecessor: supersedes the synthetic-user carrier representation in feat(delegation): add same-turn background result injection #74378 while preserving the maintainer invariants from its close review

Hermes triage dashboard graph

Live dashboard neighbourhood: https://hermes-triage.gottz.de/?node=76230&complex=e394e6179542bacbd5e7dbdc5adc9dfb

flowchart LR
    classDef focus fill:#fef3c7,stroke:#b45309,stroke-width:3px,color:#451a03
    classDef issue fill:#ede9fe,stroke:#6d28d9,color:#2e1065
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    P76230["PR #76230 (open)"]
    I85648(["issue #85648 (open)"])
    P58690["PR #58690 (closed)"]
    P60863["PR #60863 (merged)"]
    P61332["PR #61332 (open)"]
    P62608["PR #62608 (open)"]
    P63866["PR #63866 (closed)"]
    P65860["PR #65860 (open)"]
    P70133["PR #70133 (merged)"]
    P72596["PR #72596 (open)"]
    P74378["PR #74378 (closed)"]
    P76229["PR #76229 (open)"]
    P76230 -->|related| I85648
    P76230 -->|closes| I85648
    P74378 -.->|duplicate of 0.76| P76230
    P76229 -.->|duplicate of 0.67| P76230
    P58690 -.->|duplicate of 0.66| P76230
    P63866 -.->|duplicate of 0.66| P76230
    P60863 -.->|duplicate of 0.66| P76230
    P65860 -.->|duplicate of 0.65| P76230
    P72596 -.->|duplicate of 0.65| P76230
    P61332 -.->|duplicate of 0.65| P76230
    P70133 -.->|duplicate of 0.65| P76230
    P62608 -.->|duplicate of 0.64| P76230
    class P76230 focus
    click P76230 "https://github.com/NousResearch/hermes-agent/pull/76230"
    class I85648 issue
    click I85648 "https://github.com/NousResearch/hermes-agent/issues/85648"
    class P58690 closed
    click P58690 "https://github.com/NousResearch/hermes-agent/pull/58690"
    class P60863 merged
    click P60863 "https://github.com/NousResearch/hermes-agent/pull/60863"
    class P61332 open
    click P61332 "https://github.com/NousResearch/hermes-agent/pull/61332"
    class P62608 open
    click P62608 "https://github.com/NousResearch/hermes-agent/pull/62608"
    class P63866 closed
    click P63866 "https://github.com/NousResearch/hermes-agent/pull/63866"
    class P65860 open
    click P65860 "https://github.com/NousResearch/hermes-agent/pull/65860"
    class P70133 merged
    click P70133 "https://github.com/NousResearch/hermes-agent/pull/70133"
    class P72596 open
    click P72596 "https://github.com/NousResearch/hermes-agent/pull/72596"
    class P74378 closed
    click P74378 "https://github.com/NousResearch/hermes-agent/pull/74378"
    class P76229 open
    click P76229 "https://github.com/NousResearch/hermes-agent/pull/76229"

Loading

Dashboard interpretation:

• solid edges are structural GitHub links (closes / related);
• dashed edges are embedding-discovery candidates and show the dashboard score;
• the fold thresholds reported by the dashboard are embedding 0.88 and file overlap 0.75;
• a dashed duplicate of edge below the fold threshold is a similarity lead for review, not an accepted duplicate or merge-order edge;
• the gold node is this PR; purple nodes are issues; blue/gray nodes are open/closed neighbouring PRs.

This graph is additive to the hand-audited coordination block above: the dashboard supplies discovery neighbourhoods, while the declared dependency, collision, ownership, and merge-order edges remain the reviewed coordination contract.

[teknium1]

Thanks for separating the durable-event, routing, and carrier work into explicit commits.

Problems

• Current main deliberately keeps async completions on a separate idle-turn rail: tools/async_delegation.py:9-21 says they are never spliced into an active tool/assistant sequence, and gateway/run.py:21251-21263 implements that new-turn watcher. This PR changes that contract, so it needs a maintainer design decision rather than review as a stale bug fix.
• adabceae518b is not independently salvageable: its parent is 1d595c0cc7da, which depends on 51174c83b859; current tools/delegate_tool.py:3897-3909 has no result_delivery schema surface.

Suggested changes

• Keep the three commits as an ordered salvage unit and obtain an explicit decision on superseding the current after-turn-only delivery contract.

Automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Graph note (no action implied — a maintainer has already reviewed this thread).

Our triage graph places this PR in a complex with 1 related pull request (#74378). They were checked against each other at the diff level and no consolidation is indicated — they address distinct causes.

Full neighbourhood: https://hermes-triage.gottz.de/?node=76230

This note exists so the relationship stays discoverable from the thread itself.

[Xipong]

Rebased onto current main (a8c50eb1d) and re-stacked on the updated #76229.

Conflict in tools/delegate_tool.py resolved: kept upstream's output_schema parameter and the static top-level tool description, added result_delivery documentation; the registry call site now passes both kwargs. Test goals padded to >=10 chars (upstream _MIN_BATCH_GOAL_LEN validation), with result-text assertions updated.

Verification: affected suite (10 files: async_delegation, delegation events, delegation delivery, apiserver background, completion delivery, tui gateway server, process registry, run_agent, cli async delivery, restored ownership) 922 passed / 1 failed. The single failure is upstream test_write_json_serializes_concurrent_writes — a timing-sensitive concurrency test that passes in isolation (3/3) and flakes only under full-suite load. py_compile clean.

[Xipong]

Follow-up after CI: compacted the top-level description back to upstream's exact text (len(desc) = 1900 <= 2200, all required keywords retained). Per the compaction contract, the result_delivery details live in the parameter description instead of the top-level text.

Verification after the fix:

• tests/tools/test_delegate.py 63/63 (incl. test_top_level_description_compact_and_complete);
• full affected suite (14 files, now including test_delegate.py and the delegate schema/validation/cost-footer files): 1022 passed; the 5 test_delegation_delivery failures seen under full-suite load all pass in isolation (5/5), and the only other failure is the known upstream timing-sensitive test_write_json_serializes_concurrent_writes (passes 3/3 alone);
• py_compile clean.

PR description updated to the rebased commit SHAs (64edae26f + 7c73e26bc).

[Xipong]

Final semantic touch per review: the top-level description no longer promises "one consolidated message for a batch" — that phrase became false once children publish individually. The paragraph now reads "Result timing follows the result_delivery parameter", keeping the background/wait-or-poll anchors and the 2200-char compaction ceiling (len(desc) = 1852). Result timing details remain in the parameter description.

Stack re-based onto the latest main (b3aa561); PR description SHAs updated (962bc39d8 / c5c767c89 / 9a2cb3f3a / 3892f7c24).

[Xipong]

Rebase update: the stack is now rebuilt on current main bfff32ae8c6a9c585431997a6cc3d791b6ec9af5 and remains 1 / 2 / 4 functional commits:

• refactor(delegation): persist child-scoped delivery state #76228: 778dcaab35298392b3a1dffd7c5ed17c1ab8930b
• feat(delegation): route ready children between turns #76229: b2c9c3e24dd43d990a4eb62c114df2e8b295be01
• feat(delegation): surface ready dependencies before the next decision #76230: dd5a4aef3f7ae7cfb6473869c5f16c12b2a0e839

There were relevant upstream changes since the previous documented base (b3aa561fa):

• 2a26693e2 added live delegate_task action=list/steer/stop orchestration on the existing delegation control plane. The rebase preserves that upstream surface end-to-end (action, subagent_id, message) alongside this stack's orthogonal result_delivery timing metadata; neither feature replaces the other.
• 21835cc95 documented the frontier-planner / inexpensive-worker split. That is compatible with the same mixed scheduling model here: dependent review/prerequisite dispatches may use inject, while independent worker dispatches stay after_turn.
• 6a7cf1930 fixed dropped idle-session delegation callbacks. The stack keeps that upstream recovery/routing behavior and layers child-scoped ready-set delivery on top of it rather than restoring the older file wholesale.
• 005dfcbfc hardened canonical spill/cache writers against symlink races. The bounded carrier continues using the upstream canonical spill path, so it inherits that hardening.
• Upstream also added live orchestration schema/call-site fields in agent/tool_executor.py, run_agent.py, and tools/delegate_tool.py; the conflict resolution was additive and verified, not an either/or choice.

No upstream commit implemented the same result_delivery policy or tool-boundary carrier. The closest changes strengthen adjacent orchestration, recovery, and storage seams, and the rebased stack now composes with them.

Fresh local verification on this base before the CI refresh: #76228 32 passed; #76229 110 passed, 4 skipped; #76230 156 passed, 4 skipped; combined integration 1035 passed, 4 skipped. New CI runs are attached to the heads above.