{"record":{"id":"eb58c0c3c64798b2","repo":"langchain-ai/deepagents","slug":"async-command-hooks-are-not-yet-supported","errorCode":null,"errorMessage":"async command hooks are not yet supported.","messagePattern":"async command hooks are not yet supported\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/hooks/models/config.py","lineNumber":59,"sourceCode":"    @field_validator(\"argv\", mode=\"after\")\n    @classmethod\n    def _normalize_argv(cls, value: list[str] | None) -> list[str] | None:\n        if value is None:\n            return None\n        if not value or not all(isinstance(part, str) for part in value):\n            msg = \"argv must be a non-empty list of strings when provided.\"\n            raise ValueError(msg)\n        if not value[0].strip():\n            msg = \"argv[0] must be a non-empty executable path.\"\n            raise ValueError(msg)\n        return value\n\n    @field_validator(\"async_\", mode=\"after\")\n    @classmethod\n    def _normalize_async(cls, value: bool | None) -> None:\n        if value:\n            msg = \"async command hooks are not yet supported.\"\n            raise ValueError(msg)\n\n\n# Extension point for future handler kinds, kept as a plain assignment rather\n# than a `type` alias: a `type` alias becomes the schema identity and renames\n# the generated `$defs` entry from `CommandHandlerSpec` to `HandlerSpec`.\nHandlerSpec = CommandHandlerSpec\n\n\nclass MatcherGroup(_ConfigModel):\n    \"\"\"A matcher and its ordered hook handlers.\"\"\"\n\n    matcher: str | None = None\n    hooks: list[HandlerSpec]\n\n\nclass HooksConfig(_ConfigModel):\n    \"\"\"Top-level configuration grouped by hook event.\"\"\"\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/hooks/models/config.py#L41-L77","documentation":"`_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.","triggerScenarios":"Setting `async_=True` (or `\"async\": true` in a hook config file) on a `CommandHandlerSpec` when the config model is validated.","commonSituations":"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.","solutions":["Set `async_` to False or omit it (default) so the hook runs synchronously","Move long-running work behind the hook command itself (e.g. spawn a daemon and return immediately)","Upgrade the library and check the changelog to see if async hook support has landed"],"exampleFix":"// before\nCommandHandlerSpec(argv=[\"python\", \"hook.py\"], async_=True)\n// after\nCommandHandlerSpec(argv=[\"python\", \"hook.py\"])","handlingStrategy":"validation","validationCode":"if cfg.get(\"async\") is True:\n    raise ValueError(\"async command hooks are not supported; drop the flag\")","typeGuard":null,"tryCatchPattern":"try:\n    spec = CommandHandlerSpec(**cfg)\nexcept ValueError as e:\n    if \"async\" in str(e):\n        cfg.pop(\"async_\", None); cfg.pop(\"async\", None)\n        spec = CommandHandlerSpec(**cfg)\n    else:\n        raise","preventionTips":["Never set async_=True until the feature ships","When porting configs from other CLIs, strip unsupported keys like `async`","Feature-check via the package changelog before using experimental fields"],"tags":["validation","unsupported-feature","hooks","config"],"backgroundTag":"unsupported-feature","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}