langchain-ai/deepagents · error · ValueError

async command hooks are not yet supported.

Error message

async command hooks are not yet supported.

What it means

`_normalize_async` validates the `async_` field of the command hook spec and rejects `True`, because asynchronous command hooks are not implemented in this version of deepagents-code. Only synchronous (blocking) command hooks are supported.

Source

Thrown at libs/code/deepagents_code/hooks/models/config.py:59

    @field_validator("argv", mode="after")
    @classmethod
    def _normalize_argv(cls, value: list[str] | None) -> list[str] | None:
        if value is None:
            return None
        if not value or not all(isinstance(part, str) for part in value):
            msg = "argv must be a non-empty list of strings when provided."
            raise ValueError(msg)
        if not value[0].strip():
            msg = "argv[0] must be a non-empty executable path."
            raise ValueError(msg)
        return value

    @field_validator("async_", mode="after")
    @classmethod
    def _normalize_async(cls, value: bool | None) -> None:
        if value:
            msg = "async command hooks are not yet supported."
            raise ValueError(msg)


# Extension point for future handler kinds, kept as a plain assignment rather
# than a `type` alias: a `type` alias becomes the schema identity and renames
# the generated `$defs` entry from `CommandHandlerSpec` to `HandlerSpec`.
HandlerSpec = CommandHandlerSpec


class MatcherGroup(_ConfigModel):
    """A matcher and its ordered hook handlers."""

    matcher: str | None = None
    hooks: list[HandlerSpec]


class HooksConfig(_ConfigModel):
    """Top-level configuration grouped by hook event."""

View on GitHub (pinned to a1af029e6e)

Solutions

1. Set `async_` to False or omit it (default) so the hook runs synchronously
2. Move long-running work behind the hook command itself (e.g. spawn a daemon and return immediately)
3. Upgrade the library and check the changelog to see if async hook support has landed

Example fix

// before
CommandHandlerSpec(argv=["python", "hook.py"], async_=True)
// after
CommandHandlerSpec(argv=["python", "hook.py"])

if cfg.get("async") is True:
    raise ValueError("async command hooks are not supported; drop the flag")

try:
    spec = CommandHandlerSpec(**cfg)
except ValueError as e:
    if "async" in str(e):
        cfg.pop("async_", None); cfg.pop("async", None)
        spec = CommandHandlerSpec(**cfg)
    else:
        raise

When it happens

Trigger: Setting `async_=True` (or `"async": true` in a hook config file) on a `CommandHandlerSpec` when the config model is validated.

Common situations: Porting hook configs written for other agent CLIs (e.g. Claude Code-style async hooks) into deepagents-code; attempting to define long-running background hooks; speculative use of the field after seeing it in the schema.

Related errors

• argv must be a non-empty list of strings when provided.
• argv[0] must be a non-empty executable path.
• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/eb58c0c3c64798b2. Report an issue: GitHub.