{"record":{"id":"c9f49283eb556952","repo":"langchain-ai/deepagents","slug":"subagentstop-requires-a-materialized-agent-transcr","errorCode":null,"errorMessage":"SubagentStop requires a materialized agent transcript path","messagePattern":"SubagentStop requires a materialized agent transcript path","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/hooks/projection.py","lineNumber":304,"sourceCode":"    transcript_path: Path,\n    _agent_transcript_path: Path | None,\n) -> HookWireInput:\n    return SubagentStartWireInput(\n        **_base_fields(invocation, transcript_path, agent=event.agent),\n        hook_event_name=HookEvent.SUBAGENT_START,\n    )\n\n\n@_project_event.register(SubagentStopEvent)\ndef _project_subagent_stop(\n    event: SubagentStopEvent,\n    invocation: HookInvocation,\n    transcript_path: Path,\n    agent_transcript_path: Path | None,\n) -> HookWireInput:\n    if agent_transcript_path is None:\n        msg = \"SubagentStop requires a materialized agent transcript path\"\n        raise ValueError(msg)\n    return SubagentStopWireInput(\n        **_base_fields(invocation, transcript_path, agent=event.agent),\n        hook_event_name=HookEvent.SUBAGENT_STOP,\n        stop_hook_active=event.continuation_count > 0,\n        agent_transcript_path=str(agent_transcript_path),\n        last_assistant_message=event.last_assistant_message,\n        background_tasks=[\n            BackgroundTaskWire.model_validate(task.model_dump())\n            for task in event.background_tasks\n        ],\n        session_crons=[\n            SessionCronWire.model_validate(cron.model_dump())\n            for cron in event.session_crons\n        ],\n    )\n\n\ndef _base_fields(","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/hooks/projection.py#L286-L322","documentation":"`_project_subagent_stop` builds the wire input for SubagentStop hooks and needs the path to the subagent's own transcript file. If `agent_transcript_path` is None — i.e. the subagent transcript was never materialized on disk — it raises `ValueError`, because the external hook process could not be given a transcript to inspect.","triggerScenarios":"Firing a SubagentStop hook projection while the caller (the hook runner/orchestrator) supplied `agent_transcript_path=None`, e.g. when the subagent never wrote a transcript file or the path failed to materialize before the stop event was processed.","commonSituations":"Subagent crashed or was cancelled before persisting its transcript; misconfigured transcript directory; a custom runner that invokes the projection layer without materializing agent transcripts.","solutions":["Ensure the subagent's transcript is materialized to disk before emitting SubagentStop and pass its path as `agent_transcript_path`","Check transcript-directory configuration/permissions so the transcript file can be written","If a subagent produced no transcript, skip projecting the SubagentStop hook rather than passing None"],"exampleFix":"// before\nproject_subagent_stop(event, invocation, transcript_path, None)\n// after\nagent_path = materialize_transcript(event.agent)  # e.g. Path('/tmp/agent-123.jsonl')\nproject_subagent_stop(event, invocation, transcript_path, agent_path)","handlingStrategy":"validation","validationCode":"if agent_transcript_path is None:\n    raise ValueError(\"SubagentStop projection requires a materialized agent transcript\")","typeGuard":"def has_agent_transcript(p: Path | None) -> TypeGuard[Path]:\n    return p is not None and p.exists()","tryCatchPattern":"try:\n    wire = project_subagent_stop(event, invocation, transcript_path, agent_transcript_path)\nexcept ValueError as e:\n    logger.warning(\"skipping SubagentStop hook: %s\", e)","preventionTips":["Materialize the subagent transcript before emitting the stop event","Verify transcript directory exists and is writable","Skip SubagentStop hooks cleanly when a subagent produced no transcript"],"tags":["valueerror","hooks","transcript","subagent"],"backgroundTag":"missing-required-field","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}