NousResearch/hermes-agent · error · SubagentLifecycleError

Hermes failed to assign a child identity.

Error message

Hermes failed to assign a child identity.

What it means

Raised by SubagentLifecycleManager.launch() when the child agent object constructed via _build_child_preserving_parent_tools has no _subagent_id attribute (or an empty one). Every spawned delegate is expected to receive a subagent identity; an empty one means the delegation internals did not run their normal construction path — an internal invariant violation, not a caller-input error.

Source

Thrown at agent/subagent_lifecycle.py:240

            DEFAULT_MAX_ITERATIONS,
        )

        child = _build_child_preserving_parent_tools(
            task_index=0,
            goal=request.goal,
            context=request.context,
            toolsets=list(request.allowed_toolsets)
            if request.allowed_toolsets
            else None,
            model=request.model,
            max_iterations=DEFAULT_MAX_ITERATIONS,
            task_count=1,
            parent_agent=parent,
            role=request.role,
        )
        subagent_id = str(getattr(child, "_subagent_id", "") or "")
        if not subagent_id:
            raise SubagentLifecycleError("Hermes failed to assign a child identity.")
        created = time.time()
        handle = SubagentHandle(
            PUBLIC_CONTRACT_VERSION,
            subagent_id,
            parent_session_id,
            request.correlation_id,
            created,
            getattr(child, "provider", None),
            getattr(child, "model", None),
            getattr(child, "_delegate_role", request.role),
            int(getattr(child, "_delegate_depth", 1) or 1),
            self._capability(subagent_id, parent_session_id, created),
        )
        record = _Record(handle, SubagentState.PENDING, created, agent=child)
        with _REGISTRY.lock:
            _REGISTRY.records[subagent_id] = record
            if request.correlation_id:
                _REGISTRY.correlations[correlation_key] = subagent_id

View on GitHub (pinned to c896c09c42)

Solutions

1. Update Hermes to a consistent version (pip install -U or git pull) so tools/delegate_tool.py and agent/subagent_lifecycle.py ship from the same release.
2. Remove any monkeypatching of _build_child_preserving_parent_tools or the child-construction path in tests/plugins; construct children through the public delegation API.
3. If it persists on a clean install, capture the child object type and report it as a Hermes core bug with the version pair.

Example fix

# before (test/plugin patching internals)
from tools.delegate_tool import _build_child_preserving_parent_tools
_patched = _build_child_preserving_parent_tools
# ... patch returns a bare agent without _subagent_id

# after: use the public launch API unpatched
handle = manager.launch(SubagentLaunchRequest(goal="summarize repo"))

# not a caller-input error; verify environment consistency first
import hermes_constants, tools.delegate_tool, agent.subagent_lifecycle
# ensure both modules come from the same installed release, e.g.:
# pip show hermes-agent  (single version, no mixed checkout)

try:
    handle = manager.launch(request)
except SubagentLifecycleError as exc:
    if "failed to assign a child identity" in str(exc):
        # restart/update to a consistent Hermes build, then retry once
        log_and_upgrade_or_report(exc)
    else:
        raise

When it happens

Trigger: A Hermes version mismatch where tools/delegate_tool.py no longer sets _subagent_id on children but agent/subagent_lifecycle.py expects it; monkeypatching or wrapping _build_child_preserving_parent_tools in tests/plugins so the attribute is never assigned; a partially-failed child construction that returned a dummy object.

Common situations: Upgrading Hermes where delegate_tool internals changed without a matching subagent_lifecycle update; plugins that patch delegation internals (which the code explicitly discourages); running from a mixed checkout (stale .pyc or worktree with some files updated).

Related errors

• Malformed subagent handle.
• No active Hermes parent session is available.
• parent_session_id does not match the active session.
• Duplicate correlation_id for this parent session.
• goal must be a non-empty string of at most 16000 characters.

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/41baa95e97b592b6. Report an issue: GitHub.