NousResearch/hermes-agent · error · SubagentLifecycleError

working_directory is not supported because Hermes delegates

Error message

working_directory is not supported because Hermes delegates use isolated task environments.

What it means

Validation error from SubagentLifecycleManager._validate_request(): working_directory is intentionally unsupported because Hermes delegate children run in isolated task environments, not in a caller-chosen directory. Any non-None working_directory on the launch request is rejected before a child is built.

Source

Thrown at agent/subagent_lifecycle.py:511

        ):
            raise SubagentLifecycleError(
                "goal must be a non-empty string of at most 16000 characters."
            )
        if request.context is not None and (
            not isinstance(request.context, str)
            or len(request.context) > _MAX_CONTEXT_CHARS
        ):
            raise SubagentLifecycleError(
                "context must be a string of at most 32000 characters."
            )
        if request.role not in {"leaf", "orchestrator"}:
            raise SubagentLifecycleError("role must be 'leaf' or 'orchestrator'.")
        if request.timeout_seconds is not None:
            raise SubagentLifecycleError(
                "Per-launch timeout is not supported; configure delegation timeout explicitly."
            )
        if request.working_directory is not None:
            raise SubagentLifecycleError(
                "working_directory is not supported because Hermes delegates use isolated task environments."
            )
        if request.blocked_tools:
            raise SubagentLifecycleError(
                "Per-tool blocking is not supported; use allowed_toolsets. Hermes always blocks unsafe child tools."
            )
        try:
            metadata_bytes = len(
                json.dumps(dict(request.metadata), sort_keys=True).encode()
            )
        except (TypeError, ValueError) as exc:
            raise SubagentLifecycleError("metadata must be JSON-serializable.") from exc
        if metadata_bytes > _MAX_METADATA_BYTES:
            raise SubagentLifecycleError("metadata exceeds 8192 bytes.")
        if request.allowed_toolsets:
            from toolsets import TOOLSETS

            unknown = set(request.allowed_toolsets) - set(TOOLSETS)

View on GitHub (pinned to c896c09c42)

Solutions

Drop working_directory (None) and put the directory path in the goal or context text so the child cds/reads there itself.
If children consistently need a project cwd, configure the delegation environment (terminal.cwd in config.yaml for messaging contexts) rather than per-launch.
Normalize empty strings to None when building requests from loose input: working_directory=wd or None.

Example fix

# before
request = SubagentLaunchRequest(goal="run tests", working_directory="/src/app")

# after
request = SubagentLaunchRequest(
    goal="run the test suite in /src/app and report failures",
)

Defensive patterns

Strategy: validation

Validate before calling

request = SubagentLaunchRequest(
    goal=f"{goal} (work in /src/app)",
    working_directory=None,  # never set this field
)

Try / catch

try:
    manager.launch(request)
except SubagentLifecycleError as exc:
    if "working_directory is not supported" in str(exc):
        request = dataclasses.replace(
            request,
            working_directory=None,
            goal=f"{request.goal} (work in {request.working_directory})",
        )
        manager.launch(request)
    else:
        raise

Prevention

Children run in isolated environments — express location in goal/context text.
Normalize optional string fields to None (not "") when building requests from loose input.
Set persistent working directories via terminal.cwd in config.yaml.

When it happens

Trigger: Setting SubagentLaunchRequest(working_directory="/repo") to make the child operate on a specific checkout; porting code from agent frameworks where cwd is a standard launch parameter; serializers that emit "" instead of None for unset strings.

Common situations: Wanting a subagent to work inside the current project directory; multi-repo workflows trying to pin each child to a repo; form/UI code defaulting optional strings to empty string rather than None.

Related errors

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