feat(delegation): add parent-scoped live controls

[0xbWy]

Fixes #76508

Implementation and adversarial review were completed locally before the issue was opened; the issue records the product and security contract this PR implements.

Summary

• Add one parent-scoped delegate_control surface with list, cancel, and steer actions for live asynchronous delegations.
• Preserve authority across genuine context-compression continuations while rejecting foreign profiles, branches, delegate/subagent/tool sessions, siblings, ambiguous lineage, cycles, and malformed handles.
• Keep the capability deferred in the existing delegation toolset, outside _HERMES_CORE_TOOLS, with leaf-agent exclusion.
• Preserve native terminal-result delivery and existing async-delegation lifecycle behavior.

Design

Trusted parent authority

Dispatch records capture a trusted compound owner:

(canonical profile namespace, compression-only parent-conversation root)

The new read-only SessionDB resolver follows only proven compression edges. It fails closed for missing or malformed state, non-compression ancestry, ambiguous continuations, cycles, explicit branch/delegate markers, and delegate/subagent/tool sources. Model arguments and discovery cursors never establish authority.

Complete deleg_<8 lowercase hex> IDs remain useful user-facing handles, but possession is not authorization. Malformed, foreign, missing, terminal, and inaccessible targets all return opaque not_found.

Bounded live chooser

list returns newest-first pages containing only:

• complete delegation ID;
• live status;
• batch flag;
• dispatch time;
• bounded goal preview;
• bounded role preview.

It exposes total_live, truncated, and next_cursor rather than silently truncating. It does not expose prompts, context, results, errors, routes, models, ownership/session fields, callbacks, credentials, or completion-delivery internals.

Race-safe cancellation and steering

• Control callbacks execute outside the global registry lock and batch child-lifecycle lock.
• Per-record control serialization prevents cancel/steer dual acceptance.
• Cancellation is cooperative and reports pending, accepted, or stable non-retriable indeterminate states truthfully.
• A callback exception after interruption begins cannot re-enable steering or trigger a blind retry.
• Batch steering targets active children only and commits acceptance only while those children remain steerable.
• Session shutdown, /stop, and stale-lifecycle cancellation supersede an overlapping steer and cannot miss a child temporarily marked as steering.
• Steering has runtime per-message and cumulative bounds.

Narrow-waist integration

delegate_control is registered in the existing delegation toolset and remains absent from _HERMES_CORE_TOOLS. Normal progressive disclosure discovers it through tool_search; eager exposure remains possible when tool search is disabled but delegation is enabled. Existing child toolset policy keeps it unavailable to leaf agents.

No parallel registry, persistence schema, configuration key, dependency, service, or migration is introduced.

Verification

Final frozen patch:

base:   d7c24f264631d48bd4018a1c1023d02837bf27f7
sha256: 2cdcadcdf11fa7e95ea04bebb1640cb49b4781e602e8deeb857b4a5222eee908
size:   56,703 bytes
scope:  5 maintained files, +1,231 / -44 lines

Executed evidence:

• 301/301 broader affected SessionDB/delegation/model-tool/gateway/lifecycle tests passed in the final security review.
• 66/66 adversarial authority cases passed, including normalized delegate/subagent/tool sources, malformed marker values, valid parent roots, multi-hop compression, ambiguous ancestry, foreign profiles, and real control-owner resolution.
• 3/3 lifecycle overlap regressions passed.
• Ruff lint and focused formatting checks passed.
• Changed Python files compile successfully.
• git diff --check passed.
• No introduced changed-line typing diagnostic was found; the sole reported changed-line diagnostic reproduces on the untouched base.
• Disposable temporary-HERMES_HOME model-tool integration exercised dispatch, listing, pagination, steering, cancellation, compression continuity, and foreign-profile opacity.

The repository-wide runner was also executed on the preceding frozen candidate. It completed with 34 test failures across 22 files plus 14 collection/import failures in known untouched-base optional-dependency/environment categories; no changed delegation-control test failed. After the final localized authority/lifecycle deltas, the focused and broader affected suites above were rerun on the exact final bytes. This PR does not claim repository-wide baseline health.

Related work

• Related/adjacent: feat(tui): async delegation view — docked agents panel + live steering #70899 — TUI Mission Control visibility and steering. This PR does not adopt possession-as-authority; it adds strict parent-scoped model-facing control and can reuse accepted shared steering seams.
• Separate informational surface: feat(telegram): show bounded async delegation activity #76390 — Telegram-only bounded delegation activity. This PR does not modify it.

Non-goals

• No TUI or transport-specific UI.
• No internal-subagent model API.
• No hard thread kill, pause/resume scheduler, or result-history API.
• No persistence, restart resurrection, schema migration, config key, dependency, service, or runtime activation.

[alt-glitch]

This was generated by AI during triage.

Related to #66046: both expose live delegation controls, but this PR adds a deferred delegate_control tool with compression-lineage ownership while #66046 uses a different argument/overlay model. Maintainer contract selection is needed; this is not marked duplicate.

[teknium1]

Thanks for the security-focused live-control proposal.

Current main still lacks the requested model-facing surface: delegate_task accepts only spawn inputs at tools/delegate_tool.py:2778-2786, its schema has no control action fields at tools/delegate_tool.py:3850-3911, and AIAgent._dispatch_delegate_task forwards only spawn inputs at run_agent.py:7053-7060.

Suggested changes

• Preserve and reconcile post-base delegation fixes during salvage. The branch diverged from merge base d7c24f264631d48bd4018a1c1023d02837bf27f7; current main has subsequent lifecycle work in tools/delegate_tool.py and tools/async_delegation.py, including 0af8fb05bfd6, 3d30232eba80, and 92914e9b09d6.

This is an automated hermes-sweeper review.

[GottZ]

This was generated by AI during triage.

Summary

One PR directly addresses #76508. #76512 adds the missing model-facing list, cancel, and steer controls, with authority derived from the canonical profile and compression-only parent lineage while retaining the existing async registry and terminal-result delivery path.

Related pull requests

• feat(delegation): add parent-scoped live controls #76512 best fix — (+1231/-44) — addresses the reported control gap but requires salvage against current main: the diff adds a deferred delegate_control tool, opaque owner-scoped lookup, bounded listing and steering, serialized cancellation, lifecycle integration, documentation, and adversarial tests. Consistent with the automated keep_open review, the implementation remains relevant because current main lacks this surface, but it must reconcile lifecycle changes after merge base d7c24f264631d48bd4018a1c1023d02837bf27f7, including 0af8fb05bfd6, 3d30232eba80, and 92914e9b09d6, and resolve the contributor-documented contract choice versus feat(delegation): add live subagent control #66046.

Duplicates

No duplicates among the listed PRs. #66046 is related, but its argument/overlay model differs from #76512's deferred delegate_control and compression-lineage ownership model; the contributor explicitly did not classify them as duplicates.

Suggested consolidation

Keep #76512 open with a salvage path: resolve the documented contract choice against #66046, then rebase onto main or split out the viable portion while preserving the parent-scoped authority resolver, bounded control API, callback serialization, lifecycle-race handling, and adversarial tests, and reconciling the cited post-base lifecycle commits. There are no listed duplicate PRs to close.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I76508(["issue #76508 (open)"])
    P76512["PR #76512 (open)"]
    P76512 -->|best fix| I76508
    class I76508 open
    class P76512 open
    class P76512 best
    class P76512 target
    click I76508 "https://github.com/NousResearch/hermes-agent/issues/76508"
    click P76512 "https://github.com/NousResearch/hermes-agent/pull/76512"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 57 kB of PR diffs, 12 kB of issue/PR text, <1 kB of discussion (1 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[teknium1]

Thanks for building this, @0xbWy — you were ahead of us on the exact user story here, and the three-verb surface you designed (list / cancel / steer, parent-scoped) is precisely the shape that just landed.

Live subagent orchestration merged in #85232, folded into delegate_task itself via an action parameter (list / steer / stop) rather than a separate delegate_control tool — a maintainer call to keep the model-facing tool count flat, since every tool ships on every API call. Ownership is enforced by an in-process parent weakref chain on the live registry instead of the SessionDB lineage resolver, which kept the surface small while preserving the same guarantee (a conversation can only control its own spawn tree; foreign/unknown/finished targets are refused).

Closing this as superseded by the merged implementation. The adversarial-testing mindset in your branch is genuinely appreciated — if you spot ownership or lifecycle gaps in what shipped, a focused follow-up PR against current main would be very welcome.