feat(plugins): add public subagent lifecycle API

[asimons81]

Summary

Expose a typed, plugin-safe subagent lifecycle service through PluginContext.subagent_lifecycle. Plugins can launch, monitor, cancel, and retrieve results from fresh Hermes child sessions without importing private delegation internals, gateway state, or TUI components.

• Add agent/subagent_lifecycle.py -- SubagentLifecycleService with launch, status, bounded wait, cooperative cancellation, immutable terminal-result retrieval, and reconnect diagnostics
• Add PluginContext.subagent_lifecycle property (hermes_cli/plugins.py, +17 lines) with lazy initialization and a parent-agent resolver lambda
• Add tests/agent/test_subagent_lifecycle.py -- 98 lines of contract/security tests
• Add website/docs/developer-guide/subagent-lifecycle-api.md -- public API documentation

Public API

The service is obtained from PluginContext:

service = ctx.subagent_lifecycle
handle = service.launch(SubagentLaunchRequest(goal="..."))
status = service.status(handle)
terminal = service.wait(handle, timeout_seconds=30)
result = service.result(handle)
cancel_result = service.cancel(handle, reason="...")
reconnect_result = service.reconnect(handle)

SubagentHandle is fully serializable (to_dict() / from_dict()) and carries a versioned, opaque HMAC capability. Malformed or forged handles return UNKNOWN / UNKNOWN_HANDLE and cannot access a child.

Key request fields:

Field	Type	Limit
goal	str	16 000 chars
context	Optional[str]	32 000 chars
metadata	Mapping[str, Any]	8192 bytes JSON
allowed_toolsets	Optional[tuple[str, ...]]	Must be subset of parent toolsets
correlation_id	Optional[str]	Unique per parent session

Lifecycle semantics

States: PENDING -> STARTING -> RUNNING -> SUCCEEDED / FAILED / INTERRUPTED, with CANCEL_REQUESTED as a transient during cooperative cancellation. UNKNOWN is returned for unrecognized or forged handles.

• cancel() is cooperative: it calls agent.interrupt() and returns CANCEL_REQUESTED. The state only transitions to CANCELLED after terminal confirmation from the child loop.
• wait() blocks on the child's Future with an optional timeout and returns SubagentTerminalState.
• result() returns an immutable SubagentResult with a result_hash (SHA-256 of serialized payload). Repeated calls return the same instance.
• reconnect() returns connected=True for in-process handles that are still in the registry. After a process restart it returns connected=False, diagnostic="RECONNECT_UNAVAILABLE".

Plugin usage

from agent.subagent_lifecycle import SubagentLaunchRequest

def register(ctx):
    svc = ctx.subagent_lifecycle
    handle = svc.launch(SubagentLaunchRequest(
        goal="Audit this config for security regressions.",
        context="Only inspect the supplied file tree.",
        role="leaf",
        correlation_id="audit-7",
        allowed_toolsets=("file",),
    ))
    svc.wait(handle, timeout_seconds=60)
    return svc.result(handle)

Compatibility

Existing delegate_task, batch delegation, child tool restrictions, and TUI/gateway active-child display are unchanged. The service shares the internal child construction and execution path. It does not expose live agent objects, transcripts, or hidden reasoning.

Security

• All requests are fail-closed. Malformed inputs, oversized metadata, unknown toolsets, parent-broadening toolsets, forged handles, and cross-parent access are all rejected with SubagentLifecycleError or UNKNOWN state.
• Each handle carries an HMAC-SHA256 capability derived from a per-process secret, the subagent ID, parent session, and creation timestamp. Forged capabilities produce UNKNOWN state.
• Cross-parent access is blocked by comparing the caller's resolved parent session ID against the handle's parent_session_id.
• Terminal results are bounded to 32 000 characters and exclude transcripts, prompts, and hidden reasoning.
• Per-tool blocking, working-directory override, and per-launch timeout are explicitly rejected until Hermes can support them without weakening isolation. Use allowed_toolsets to narrow a child.

Validation

Check	Result
42 focused tests (lifecycle contract, concurrency, interrupt, guardrails)	Passed
Ruff (enforcement + ty diff)	Passed
Python compilation (compileall)	Passed
Python test slices 1/8 through 8/8	Passed
E2E tests	Passed
Windows footgun check	Passed
OSV scan	Passed
Supply-chain risk scan	Passed
All required checks (GitHub branch protection)	Passed
Docker amd64 build	Passed
Docker arm64 build	In progress (non-blocking)

Known limitations

1. Terminal results are retained in-process for one hour, then evicted.
2. Reconnect is in-process only. After a process restart, reconnect() returns RECONNECT_UNAVAILABLE and never starts a replacement child.
3. Cancellation is cooperative. The state remains CANCEL_REQUESTED until the child thread confirms the interrupt at its next safe boundary.
4. The direct local Windows full test suite could not be collected because an existing test (tests/tools/test_search_hidden_dirs.py) invokes the Unix command which rg.
5. The canonical local shell runner expects the POSIX path venv/bin/python.
6. These local Windows runner limitations are not introduced by this PR.
7. Remote CI results should be treated as authoritative where available.

What reviewers should focus on

• agent/subagent_lifecycle.py -- the entire new module. Check that the public contract is complete, the HMAC capability scheme is correct, the _validate_request gates cover all injection surfaces, and the thread safety of _Registry is sound.
• hermes_cli/plugins.py -- the subagent_lifecycle property. Confirm the lazy-init pattern and parent-agent resolver lambda are correct for the plugin lifecycle.
• tests/agent/test_subagent_lifecycle.py -- verify the contract tests cover launch, wait, result, cancel (cooperative), forged-handle rejection, cross-parent isolation, duplicate correlation IDs, toolset-broadening rejection, and in-process reconnect.
• website/docs/developer-guide/subagent-lifecycle-api.md -- confirm the documentation accurately reflects the implementation.

[teknium1]

Thanks for proposing a typed plugin-facing lifecycle boundary. The API is additive, but its current execution path bypasses delegation invariants that main already centralizes.

Problems

• agent/subagent_lifecycle.py:196 calls _build_child_agent() without the parent tool-name save/restore required by tools/delegate_tool.py:2499-2541; _run_single_child() later restores the child’s saved value (tools/delegate_tool.py:2314-2320). This can leave process-global tool resolution on the child toolset.
• agent/subagent_lifecycle.py:230 directly runs _run_single_child(), skipping the parent-side memory notification, serialized subagent_stop hooks, and cost rollup in tools/delegate_tool.py:2687-2779.
• hermes_cli/plugins.py:375 resolves only through _cli_ref, but website/docs/developer-guide/plugins/index.md:859-862 documents that _cli_ref is absent in gateway, non-interactive, and kanban-worker contexts.

Suggested changes

• Route both public lifecycle calls and delegate_task through one host-owned lifecycle executor that preserves current construction, concurrency, cleanup, aggregation, and hook contracts.
• Define a session-scoped resolver and lifecycle ownership model before exposing this surface across plugin contexts.
• Validate malformed deserialized handle fields before HMAC comparison; current tests cover a forged string capability but not malformed typed fields.

Automated hermes-sweeper review.

[teknium1]

_build_child_agent() mutates model_tools._last_resolved_tool_names. The existing delegate_task() path saves the parent value before construction, stores it on the child, and restores it afterward (tools/delegate_tool.py:2499-2541). Preserve that invariant here or route through a shared constructor/executor; otherwise child construction can corrupt the parent process's resolved tool set.

[teknium1]

Submitting _run_single_child() directly bypasses the parent-side aggregation in delegate_task() that fires subagent_stop, notifies the memory provider, and rolls child cost into the parent (tools/delegate_tool.py:2687-2779). Please use a shared host-owned lifecycle path rather than reproducing only the worker portion.

[teknium1]

This only verifies the dataclass type/version. SubagentHandle.from_dict() accepts arbitrary field types, so malformed capability, subagent_id, or created_at values can raise during HMAC computation/comparison instead of producing the documented UNKNOWN response. Validate all capability-input fields before calling _capability().

[teknium1]

This resolver is CLI-only: _cli_ref is populated by cli.py:13487-13489, while plugin docs explicitly say it is absent in gateway, non-interactive, and kanban-worker contexts (website/docs/developer-guide/plugins/index.md:859-862). Define a session-scoped resolver for those surfaces or document and enforce a deliberately CLI-only API.

[asimons81]

Implemented the review fixes in 6cb4bb80a:

• Routed public lifecycle construction and completion through shared host-owned delegation helpers. Parent tool resolution is saved/restored, and both delegate_task and the plugin API now share summary budgeting, memory notification, serialized subagent_stop hooks, child-cost rollup, and existing worker cleanup.
• Replaced the CLI-only _cli_ref resolver with a turn-scoped ContextVar bound by AIAgent.run_conversation, covering CLI, gateway, non-interactive, and kanban-worker agent turns while failing closed outside an active turn.
• Added strict type validation for every deserialized handle field before capability/HMAC computation, returning UNKNOWN/UNKNOWN_HANDLE for malformed values.
• Added regression coverage for tool-state restoration, aggregation side effects, non-CLI resolution, malformed handles, and turn-scope cleanup. The tests also exposed and fixed an immediate-cancellation race.

Validation:

• 184 focused lifecycle/delegation/plugin-hook tests passed
• Ruff passed on all changed Python files
• git diff --check passed

I have left the review threads unresolved for reviewer confirmation.

[asimons81]

Rebased onto latest upstream/main (0 behind). All 3 hermes-sweeper concerns were already addressed by the follow-up commit 6cb4bb80a:

1. Tool-name save/restore -- _build_child_preserving_parent_tools() saves/restores model_tools._last_resolved_tool_names around _build_child_agent()
2. Delegation pipeline hooks -- _run_child_lifecycle() routes through _finalize_child_results() which handles memory notification, subagent_stop hook, and cost rollup -- same path delegate_task uses
3. CLI-only resolver -- uses get_active_subagent_parent() via contextvars.ContextVar, set in run_agent.py's run_conversation(), which works across CLI, gateway, and TUI

Additional: malformed handle field validation (type checks on every SubagentHandle field before HMAC comparison) was also added in the same pass.

18/18 lifecycle contract tests pass on the rebased branch. Ready for human review.

[2001Y]

@asimons81 I'm evaluating #65447 for a concrete use case: a Luna parent selectively launching a full Sol child. The current #63359 head appears to provide the missing plugin lifecycle surface, and its CI is green.

Is this still the intended salvage path? If useful, I can validate model selection and shared delegation limits against the current upstream base. I do not want to open a duplicate PR.

[asimons81]

@2001Y -- yes, this is still the intended path for #65447. The branch was rebased onto upstream/main 4 days ago and the review feedback was addressed in a follow-up commit. CI is green and the change is mergable cleanly.

Your Luna/Sol use case is exactly the kind of real validation this needs. The shared delegation limits path (acceptance criterion 3 from #65447) is the obvious thing to validate -- both delegate_task and the plugin API route through the same host-owned lifecycle executor now, so the concurrency cap and depth limit should hit the same counters. Having someone verify that against a profile-parented launch would close the gap between contract tests and real behavior.

Want me to give you push access to the branch, or would you rather work off the current head and open a sibling PR against #65447? Happy to coordinate either way.

[teknium1]

Merged via PR #72501 — thank you for this substantial piece of work! Both your commits were cherry-picked onto current main with your authorship preserved in git history (1865fb5, f60abd6).

During the salvage we resolved conflicts against the delegation work that landed since your branch (live transcripts, progress-based stall detection #72227, inline child API calls #72412) and added two integration follow-ups: the shared _finalize_child_results pipeline now carries the tool_call_history hook field (#72403, which postdated your branch), and the lifecycle executor uses the daemon pool so a wedged child can't block interpreter exit. Your ownership-invariants design — the HMAC handles, tree scoping, and the shared build/finalize helpers — survived intact and is exactly what made the two-doors-one-engine shape safe to land.

Plugins can now launch subagents via ctx.subagent_lifecycle. Docs are live under developer-guide/subagent-lifecycle-api.