brain-v42

Overview Schema Source Related Servers Discussions Admin

brain_session_relay

DestructiveIdempotent

Hand over an open session to a successor: capture knowledge, write a handover, end the old session, and open a new one atomically.

Instructions

Relay an open session onto its slot, or its project base: capture, end, restart.

One transaction: the named knowledge_ids are captured into the old session, the handover is written under a compare-and-swap, the old session ends, and a successor opens under new_client_key; its briefing follows. Two forms, and exactly one revision per call.

Bound session: send expected_slot_revision; the handover (at most 4,000 characters) becomes the slot body and the successor stays on the slot. A closed slot or a stale revision changes nothing and leaves the session open.

Unbound session: send expected_focus_revision, the BASE revision; the handover becomes the project's whole base focus and the successor is unbound. A stale revision (focus_revision_conflict) changes nothing and leaves the session open, unlike end, which closes anyway. SHRINK GUARD: a handover under 70% of the current base focus is refused (base_focus_shrink, both lengths in the message), because it REPLACES the whole base: carry the durable content over. Only an operator relay may pass allow_focus_shrink = true; a guard mod never can.

An equal replay returns the same successor with replayed = true; any other payload on an ended session is terminal_conflict. The successor's next end or relay sends result.slot.revision (bound: the SLOT revision, from bind, resume, or relay) or result.focus_revision (unbound: the new BASE revision), never started_focus_revision for a bound one.

A guard mod the operator explicitly enabled may make this call as a standing user command, and only this one (Amendment — slot relay (ADR #34)); with initiator = 'guard_mod' it is refused while BRAIN_SESSION_RELAY_GUARD_MOD_ENABLED is false.

An agent tracer is the only session the server opens or closes on its own; no hook and no auto-close may invoke this lifecycle boundary.

Input Schema

TableJSON Schema

Name	Required	Description
`summary`	Yes
`handover`	Yes
`initiator`	Yes
`session_id`	Yes
`knowledge_ids`	No
`new_client_key`	Yes	Stable identity for one intended session. Reuse it for every retry of that session; use a distinct stable key for each parallel session.
`allow_focus_shrink`	No
`expected_client_key`	Yes	Client identity expected for the addressed session UUID. The pair must match before any session mutation. This is an isolation guard, not authentication.
`expected_slot_revision`	No
`expected_focus_revision`	No
`nothing_to_capture_reason`	No

Output Schema

TableJSON Schema

Name	Required	Description
`slot`	No
`session`	Yes	Persistent state of one explicitly controlled concurrent session.
`briefing`	No
`replayed`	Yes
`focus_revision`	No
`ended_session_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.6.7Oct 5, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply the safety profile (destructive, idempotent); the description adds the substantive behavior: single-transaction CAS semantics, that stale revisions or a closed slot change nothing and leave the session open, the 70% shrink guard and its refusal code, the replayed/terminal_conflict outcomes, and the guard-mod environment gate. This is far beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but front-loaded, with labeled cases (Bound/Unbound/Shrink Guard) that let an agent scan rather than parse prose. Most sentences carry operational payload, though the trailing paragraph about the agent tracer is loosely tied to the call itself.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, 11-parameter lifecycle tool with an output schema, it covers transaction shape, guarded failure modes, and revision hand-off to the successor's next call. Remaining gaps: no explanation of `summary` or `nothing_to_capture_reason`, and the handover length figure differs from the schema constraint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 18% across 11 parameters, so the description must compensate, and it does for the critical ones: `expected_slot_revision` vs `expected_focus_revision` (base revision), `handover` content and its replacement semantics, `knowledge_ids` capture, `new_client_key` successor identity, `allow_focus_shrink` operator-only rule, and `initiator`. Gaps remain for `summary` and `nothing_to_capture_reason`, and it states a 4,000-character handover cap that conflicts with the schema's 10,000 maxLength.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('relay an open session onto its slot, or its project base') and unpacks it into the concrete lifecycle it performs: capture, end, restart via a successor. It explicitly distinguishes itself from the sibling `end` ('unlike `end`, which closes anyway'), so an agent can route between them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit branching conditions: bound sessions require `expected_slot_revision`, unbound sessions require `expected_focus_revision`, and it names the failure modes that select differently. It also states when the tool may be invoked by a guard mod (operator-enabled, env flag on). It doesn't frame the choice against alternatives like `brain_session_capture` or `brain_session_resume` beyond the `end` contrast, so not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server