fix(code): keep server hook state out of task results

[Mason Daugherty (mdrxy)]

Parallel task completions no longer crash parent agent turns when server hooks are active.

---

ServerHooksMiddleware keeps two pieces of per-agent bookkeeping in graph state: a snapshot of PreToolUse verdicts keyed by tool-call id, and a Stop-hook continuation count. Both were declared as ordinary state fields, so a finished subagent copied them into the update it returned to its parent.

_after_model writes the verdict snapshot on every pass — including an empty dict when no hooks are configured — so every subagent emits that key regardless of hook setup. When two task calls completed in the same graph step, LangGraph received two writes for one single-value channel and raised InvalidUpdateError, failing the parent turn. With a single task there was no error, but the subagent's snapshot silently replaced the parent's.

Marking both fields PrivateStateAttr keeps them inside the agent that owns them. SubAgentMiddleware already filters private keys out of subagent results, and create_deep_agent derives that key set from each middleware's state_schema, so no extra wiring is required.

This does not change how hook decisions reach the code that enforces them. PrivateStateAttr is OmitFromSchema(input=True, output=True) — it removes the fields from the graph's input and output schemas only. The channels stay ordinary checkpointed LastValue channels, and every node still runs against the full state schema. A deny written in after_model still reaches wrap_tool_call, and the continuation count still survives interrupt/resume. PreToolUse allow, deny, and ask behavior is unchanged.

One consequence worth knowing: because input=True is also omitted, these keys can no longer be seeded through graph input. Nothing does that today, and update_state still writes them.

Tests

test_parallel_tasks_do_not_merge_subagent_server_hook_state runs two task calls that complete in one step, parametrized over both subagent shapes. The compiled case is a bare CompiledSubAgent that writes the keys directly, which exercises SubAgentMiddleware's explicit key strip — the only layer protecting that shape. The real case is a declarative subagent carrying its own ServerHooksMiddleware, matching how subagents are built in create_cli_agent; it reproduces the crash through the unconditional snapshot write. Without the fix the two cases fail on different keys (_hooks_stop_continuation_count and _hooks_pre_tool_outcomes). Both assert the tool messages come back intact and that neither key lands in the parent's checkpointed state, so swapping in a reducer instead of privacy would not satisfy them.

test_task_omits_private_server_hook_state_from_subagent_update covers the single-task case, which cannot trip InvalidUpdateError and so would otherwise regress silently. It is built through create_deep_agent so the private-key derivation is exercised rather than reimplemented.

test_pretool_deny_blocks_tool_through_real_graph drives a deny through a compiled graph and asserts the tool never executes, with and without a resume round trip. The other deny tests call the middleware hooks directly and copy state between them by hand, so none of them can detect an outcome that fails to cross the node boundary.

test_server_hook_state_fields_are_private asserts through the production detector, so it also catches the case where annotation resolution degrades and silently yields an empty key set.

Types and documentation

ServerHooksState now documents why the fields are private, that the channels remain checkpointed, and that the verdict dict is a per-turn snapshot rather than an accumulator — every _after_model replaces it wholesale, so stale tool-call ids cannot survive into a later turn. It also records that a future reducer on either field must be placed after PrivateStateAttr in the Annotated metadata: LangGraph inspects only the last metadata entry when detecting reducers, so one added before the marker is ignored without error.

_PreToolState becomes a discriminated union of a denied and a passed variant, making a denial without a reason unrepresentable at the three sites that construct one.

pre_tool_behavior becomes hook_decided_permission, returning a bool. It previously returned one of four values while both call sites only asked whether a hook had settled permission, leaving "hook expressed no opinion" and "no outcome recorded" indistinguishable to every caller.