brain-v42

by hawkixs

Overview Schema Source Related Servers Discussions Admin

Python

Local

brain_session_end

DestructiveIdempotent

End a session by capturing a summary and next focus, validating revision and blocking accidental focus shrink.

Instructions

End a session from an explicit user command, on judgement alone.

nothing_to_capture_reason is now OPTIONAL. The old rule — a non-empty ledger XOR a written reason — measured whether the client had DECLARED its work. Derived capture feeds that signal from the server, and a check is hollow the moment the thing it checks can influence its own signal; worse, it made a session whose ledger the server had filled impossible to close. Give a reason if you have one to give; a blank one is still refused, because saying nothing and saying " " are not the same act.

What end still requires is what the server cannot produce for you: a summary and a next focus. It REPORTS unattributed_in_window — artifacts of this project created during the session that belong to no ledger — as a measure, never a gate. It cannot refuse a close, and a session cannot improve it by doing nothing.

For a bound session, expected_focus_revision is the SLOT revision (from bind, resume, or relay's slot.revision), never started_focus_revision.

For an UNBOUND session, next_focus REPLACES the project's whole base focus under a compare-and-swap on expected_focus_revision. SHRINK GUARD: a next_focus under 70% of the current base focus is refused before any write (base_focus_shrink, current, proposed and floor in the message) and the session stays open, so carry the durable content over and call again. A bound end REPLACES the whole slot body and meets the same 70% guard (slot_focus_shrink). allow_focus_shrink = true requires an active /brain-admin elevation for this credential and MCP connection; otherwise focus_shrink_override_refused is raised before any mutation. Shared-token and stdio callers cannot override; an operator relay can. A stale revision is still recorded as a conflict and closes the session, since nothing is written.

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
`next_focus`	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. The override is operator-only: an end requires an active /brain-admin elevation for this credential and MCP connection; an operator relay may also override. Carry all durable judgement and commitments forward, including decisions and deadlines with their reasons. Do not copy measurable state: each briefing recalculates it from its source.
`session_id`	Yes
`allow_focus_shrink`	No	The override is operator-only and requires an active /brain-admin elevation for this credential and MCP connection, checked before any mutation (`focus_shrink_override_refused`). True allows a replacement under 70% of the whole base focus or slot body (`base_focus_shrink` or `slot_focus_shrink`); shared-token and stdio callers cannot override. An operator relay is also permitted.
`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_focus_revision`	Yes
`nothing_to_capture_reason`	No

Output Schema

TableJSON Schema

Name	Required	Description
`session`	Yes	Persistent state of one explicitly controlled concurrent session.
`replayed`	Yes
`focus_diff`	No
`focus_at_end`	Yes
`current_focus`	Yes
`focus_outcome`	Yes	Persisted outcome of the one focus update attempted while ending.
`focus_revision_at_end`	No
`current_focus_revision`	Yes
`unattributed_in_window`	Yes
`remaining_open_session_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.7.0Oct 15, 2026

addedInput schema / properties / allow_focus_shrink

Added value: +{
+  "default": false,
+  "description": "The override is operator-only and requires an active /brain-admin elevation for this credential and MCP connection, checked before any mutation (`focus_shrink_override_refused`). True allows a replacement under 70% of the whole base focus or slot body (`base_focus_shrink` or `slot_focus_shrink`); shared-token and stdio callers cannot override. An operator relay is also permitted.",
+  "type": "boolean"
+}

changedInput schema / properties / next_focus / description

Previous value: -"Jugement et engagements pour la session suivante — ce qui n'est pas dérivable automatiquement (ex : ne pas publier ce brouillon et pourquoi, une échéance et sa raison, une décision opérateur à respecter). N'y recopie pas l'état mesurable (révision de schéma, HEAD git, arbre propre, résultat de suite de tests) : il est déjà recalculé à chaque briefing depuis la source réelle, et une copie manuelle se périme en silence."New value: +"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. The override is operator-only: an end requires an active /brain-admin elevation for this credential and MCP connection; an operator relay may also override. Carry all durable judgement and commitments forward, including decisions and deadlines with their reasons. Do not copy measurable state: each briefing recalculates it from its source."

First observedv0.6.1Sep 23, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Despite rich annotations (destructive, idempotent, openWorld=false), the description adds substantial behavior the annotations cannot convey: the 70% shrink guard, the specific error codes raised (base_focus_shrink, slot_focus_shrink, focus_shrink_override_refused), the CAS on expected_focus_revision, and the fact that a stale revision is recorded as a conflict but still closes the session. It also clarifies that unattributed_in_window is a report and never a gate, and that the nothing_to_capture_reason rule was relaxed.

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

Conciseness3/5

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

The purpose is front-loaded and the prose is dense with actionable detail, but it is well overlong and repeats the shrink-guard logic already present in the parameter descriptions. Passages like the justification of why the ledger XOR reason check was removed are rationale rather than invocation guidance.

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

Completeness5/5

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

For a high-stakes mutation with an output schema available, the description supplies everything an agent needs: required inputs, guard thresholds, override authorization, failure codes, and conflict semantics. Return-value format is correctly left to the output schema.

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?

With schema coverage at 43%, the description does real work: it defines what next_focus replaces for bound vs unbound sessions, distinguishes expected_focus_revision (slot revision) from started_focus_revision, and explains the operator-only nature of allow_focus_shrink. It adds less meaning for summary and nothing_to_capture_reason, which the schema largely covers.

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

Purpose4/5

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

The opening line states a specific verb and resource ("End a session") plus the trigger condition (explicit user command). It also distinguishes this lifecycle boundary from automatic machinery ("no hook and no auto-close may invoke this"). It never names the obvious sibling alternative (brain_session_abandon), so sibling differentiation is only partial.

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?

It gives a clear when-to-use rule (explicit user command, on judgement alone) and an explicit when-not (no hook, no auto-close may call it). It also describes the preconditions for the override path (active /brain-admin elevation) and the compare-and-swap requirements. It stops short of routing the agent between end, abandon, and relay.

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

Deploy Server