brain_session_relay
Relay an open agent session in brain-v42 to its slot or project base: capture knowledge, write a handover, end the old session, and open a successor.
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.
briefing defaults to full detail; compact returns counts and IDs in at
most 4,000 characters. Focus text appears only in session.started_focus.
Bound session: send expected_slot_revision; the handover (at most 4,000
characters) REPLACES the whole 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. An operator relay may pass allow_focus_shrink = true
only with an active /brain-admin elevation for this credential and MCP
connection; a guard mod never can.
The same 70% guard applies to a bound slot body (slot_focus_shrink).
The override is enforced before mutation: only initiator='operator' can
pass it, and only with an active /brain-admin elevation for this credential
and MCP connection. A guard_mod relay is refused even if elevated.
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"session_id": "<session_id>",
"expected_client_key": "<expected_client_key>",
"summary": "<summary>",
"handover": "<handover>",
"new_client_key": "<new_client_key>",
"initiator": "<initiator>"
},
"name": "brain_session_relay"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | ||
| briefing | No | full | |
| handover | Yes | REPLACES the whole project base focus for an unbound session, or the whole slot body for a bound session. A replacement under 70% of the current length is refused (`base_focus_shrink` or `slot_focus_shrink`), leaving the session open. Carry all durable content forward. The override is operator-only: an elevated /brain-admin session may override on end, or a relay with initiator='operator' may pass allow_focus_shrink=true. A guard_mod relay cannot override, even with elevation. | |
| 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 | Operator-only override of the 70% guard for the whole base focus or slot body. Requires an active /brain-admin elevation for this credential and MCP connection; guard_mod is refused in code, even with elevation. | |
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| slot | No | ||
| session | Yes | Persistent state of one explicitly controlled concurrent session. | |
| briefing | No | ||
| replayed | Yes | ||
| focus_revision | No | ||
| ended_session_id | Yes |