brainclaw 1.26.0 → 1.26.2

package/dist/core/io.js

@@ -1,4 +1,6 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
 export { mutate } from './mutation-pipeline.js';
@@ -121,6 +123,90 @@ export function entityRecordDirs(subdir, cwd = process.cwd(), preferredDirName)
 export function entityRecordPaths(subdir, id, cwd, preferredDirName) {
     return entityRecordDirs(subdir, cwd ?? process.cwd(), preferredDirName).map((d) => path.join(d, `${id}.json`));
 }
+/**
+ * The id grammar every session record filename is built from (pln#672).
+ *
+ * A session id arrives from the ENVIRONMENT (BRAINCLAW_SESSION_ID and the
+ * per-agent variants read by resolveExplicitSessionId) and is interpolated
+ * straight into a filename: `<id>.json` / `<id>.snapshot.json`. Unvalidated,
+ * `../../../ESCAPED` walks out of the store — reproduced on disk on
+ * 2026-08-18: saveCurrentSession wrote outside the store root, and the same
+ * path feeds loadSessionById (read) and clearCurrentSession (unlink).
+ *
+ * Allowed: a leading alphanumeric, then alphanumerics, `.`, `_`, `-`, up to
+ * 128 chars — covers brainclaw's own `sess_<hex>` and the UUID-shaped ids
+ * some agents export. Refused by construction: path separators, `..`, drive
+ * letters and absolute paths, empty ids, and any id starting with a dot.
+ * The `.snapshot` suffix stays separately refused for current_session ids
+ * (pln#670) — that is a type-collision rule, not a path-safety one.
+ */
+const SAFE_SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/**
+ * Win32 device namespace (pln#672 review P2, reproduced on a Windows host):
+ * `CON`, `NUL`, `COM1`… are not directory entries — `CON.json` opens the
+ * console device, `stat` reports a file, and the sessions directory stays
+ * empty. A record "written" there is silently lost. The reservation applies
+ * to the basename BEFORE the first dot, case-insensitively, so `con.json`
+ * and `Con.anything` are covered too. Refused on every platform: the grammar
+ * is shared, and an id must mean the same thing on all of them.
+ */
+const WIN32_RESERVED_BASENAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+export function isSafeSessionId(sessionId) {
+    if (!SAFE_SESSION_ID_RE.test(sessionId))
+        return false;
+    return !WIN32_RESERVED_BASENAME_RE.test(sessionId.split('.')[0]);
+}
+/** Throwing variant for the filename builders — a traversal must be loud, never silent. */
+export function assertSafeSessionId(sessionId) {
+    if (!isSafeSessionId(sessionId)) {
+        throw new Error(`session id '${sessionId}' is not a valid record identifier: only [A-Za-z0-9._-] (starting with an alphanumeric, max 128 chars) may become a session filename`);
+    }
+}
+/**
+ * Normalize an agent name into ONE filesystem path segment (pln#673).
+ *
+ * The agent name arrives from the environment (BRAINCLAW_AGENT_NAME, read by
+ * resolveCurrentAgentName) and became a DIRECTORY name unvalidated: proved on
+ * disk on 2026-08-18 that `'../../../../outside/PWNED'` made saveRuntimeNote
+ * create the directory and write the note ENTIRELY OUTSIDE the store.
+ *
+ * This is deliberately the SAME normalization the inbox has always used
+ * (`agentInboxDir`, messaging.ts) rather than a new convention: lower-case,
+ * then every character outside [a-z0-9_-] becomes `_`. Separators and dots
+ * cannot survive it, so no traversal can. When that replacement (or a length
+ * cap) would collapse distinct raw names, a stable hash suffix keeps their
+ * runtime directories separate. It remains IDENTITY for every normal agent
+ * name brainclaw produces (claude-code, codex, github-copilot, …) — verified
+ * against the real store — so existing normal directories do not move.
+ * Readers still probe a contained raw legacy name as a fallback (see
+ * runtime.ts) so a non-canonical legacy directory never becomes invisible.
+ *
+ * Alias resolution is deliberately NOT applied here: mapping `copilot` to
+ * `github-copilot` would relocate notes, which is a product decision, not a
+ * path-safety one.
+ */
+const AGENT_SEGMENT_UNSAFE_RE = /[^a-z0-9_-]/g;
+const WIN32_RESERVED_BASENAME_FOR_SEGMENT_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+// 128 leaves ample room for the record id and works below the 255-byte
+// component limit even when an agent name contains non-BMP characters (which
+// normalize to ASCII underscores). The hash makes truncation collision-safe.
+const MAX_AGENT_PATH_SEGMENT_LENGTH = 128;
+export function sanitizeAgentPathSegment(agent) {
+    const source = agent.trim().toLowerCase();
+    let normalized = source.replace(AGENT_SEGMENT_UNSAFE_RE, '_');
+    if (normalized.length === 0)
+        return 'unknown-agent';
+    // A Win32 device name is not a usable directory either (mkdir CON fails).
+    if (WIN32_RESERVED_BASENAME_FOR_SEGMENT_RE.test(normalized))
+        normalized = `${normalized}_`;
+    // A replacement would otherwise merge distinct identities (`a.b` and `a_b`)
+    // into one runtime directory. Preserve safe canonical names exactly, but add
+    // a deterministic discriminator to every lossy or length-capped segment.
+    if (source === normalized && normalized.length <= MAX_AGENT_PATH_SEGMENT_LENGTH)
+        return normalized;
+    const suffix = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
+    return `${normalized.slice(0, MAX_AGENT_PATH_SEGMENT_LENGTH - suffix.length - 1)}_${suffix}`;
+}
 export const SESSION_SNAPSHOT_FILENAME_SUFFIX = '.snapshot.json';
 /**
  * Filesystem type discriminator for session snapshots (codex review, pln#670).
@@ -142,6 +228,9 @@ export function isSessionSnapshotRecordFilename(filename) {
  * before the split; readers must schema-validate every candidate.
  */
 export function sessionSnapshotRecordPaths(sessionId, cwd, preferredDirName) {
+    // pln#672 — the id becomes a filename here too: refuse a traversal loudly
+    // rather than build a path that escapes the store.
+    assertSafeSessionId(sessionId);
     const dirs = entityRecordDirs('sessions', cwd ?? process.cwd(), preferredDirName);
     return [
         ...dirs.map((d) => path.join(d, `${sessionId}.snapshot.json`)),
@@ -151,6 +240,82 @@ export function sessionSnapshotRecordPaths(sessionId, cwd, preferredDirName) {
 export function memoryDir(cwd = process.cwd(), preferredDirName) {
     return path.join(cwd, preferredDirName ?? MEMORY_DIR);
 }
+/**
+ * Walk UP from a directory and return the outermost .brainclaw/ root found.
+ * Bypasses resolveEffectiveCwd / active project entirely — the answer depends
+ * only on the filesystem, which is what makes it safe for identity-level state
+ * that must NOT follow the active project (pln#648: a session record anchored
+ * on the effective cwd moved with every switch, out of the resolver's reach).
+ *
+ * Lives HERE, in a leaf module: identity.ts needs it, and store-resolution.ts
+ * imports identity.ts — the import cycle that blocked pln#648's first attempt.
+ * store-resolution re-exports it for its existing callers.
+ *
+ * Stops at the filesystem root, at $HOME (a user-level store is never a
+ * workspace root), and never climbs ABOVE BRAINCLAW_STORE_BOUNDARY when set —
+ * the containment contract tests and agent shells rely on (a leaked parent
+ * store must not widen the walk into the host machine).
+ */
+export function findOutermostBrainclawRoot(startDir) {
+    let dir = path.resolve(startDir);
+    const root = path.parse(dir).root;
+    const home = os.homedir();
+    const boundaryRaw = process.env.BRAINCLAW_STORE_BOUNDARY?.trim();
+    const boundary = boundaryRaw ? path.resolve(boundaryRaw) : undefined;
+    let outermost;
+    while (dir !== root && dir !== home) {
+        if (fs.existsSync(path.join(dir, MEMORY_DIR, 'config.yaml'))) {
+            outermost = dir;
+        }
+        if (boundary && dir === boundary)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
+/**
+ * The workspace anchor for identity-level state (pln#648 review P1): walking
+ * UP, the NEAREST store declaring `store_type: workspace` wins; only when no
+ * workspace is declared does the outermost store answer. Without the role
+ * check, two sibling declared workspaces under a common parent store would
+ * anchor to that parent and see each other's sessions — breaking exactly the
+ * isolation `resolveWorkspaceRoot` (chain-based, role-aware) guarantees.
+ * The role is read from the raw YAML — the same convention the store-chain
+ * walk uses (`store_type` is not part of the typed Config surface) — so this
+ * stays a leaf-module fs answer with no config.ts dependency.
+ * Same stops as the outermost walk: filesystem root, $HOME, and never above
+ * BRAINCLAW_STORE_BOUNDARY.
+ */
+export function findSessionAnchorRoot(startDir) {
+    let dir = path.resolve(startDir);
+    const root = path.parse(dir).root;
+    const home = os.homedir();
+    const boundaryRaw = process.env.BRAINCLAW_STORE_BOUNDARY?.trim();
+    const boundary = boundaryRaw ? path.resolve(boundaryRaw) : undefined;
+    let outermost;
+    while (dir !== root && dir !== home) {
+        const configPath = path.join(dir, MEMORY_DIR, 'config.yaml');
+        if (fs.existsSync(configPath)) {
+            outermost = dir;
+            try {
+                if (/^store_type:\s*workspace\b/m.test(fs.readFileSync(configPath, 'utf-8'))) {
+                    return dir;
+                }
+            }
+            catch { /* unreadable config — treat as a plain store */ }
+        }
+        if (boundary && dir === boundary)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
 export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }

package/dist/core/protocol-tool-policy.js

@@ -86,6 +86,50 @@ export const MCP_CANONICAL_GRAMMAR_TOOL_NAMES = [
     'bclaw_update',
     'bclaw_transition',
 ];
+/**
+ * Curated MCP workflow surface for Hermes. Hermes receives the shared Tier B
+ * instructions, which prescribe session/claim closure, inbox coordination,
+ * step updates, and Code Map discovery in addition to the canonical memory
+ * grammar. Keep this list aligned with that instruction contract; it is an
+ * advertised-tool policy, not a headless auto-approval policy.
+ */
+export const MCP_HERMES_WORKFLOW_TOOL_NAMES = [
+    ...MCP_CANONICAL_GRAMMAR_TOOL_NAMES,
+    'bclaw_remove',
+    'bclaw_move',
+    'bclaw_session_start',
+    'bclaw_session_end',
+    'bclaw_claim',
+    'bclaw_release_claim',
+    'bclaw_add_step',
+    'bclaw_complete_step',
+    'bclaw_update_step',
+    'bclaw_delete_step',
+    'bclaw_list_sequences',
+    'bclaw_create_sequence',
+    'bclaw_update_sequence',
+    'bclaw_delete_sequence',
+    'bclaw_read_inbox',
+    'bclaw_ack_message',
+    'bclaw_send_message',
+    'bclaw_correct_handoff',
+    'bclaw_write_note',
+    'bclaw_quick_capture',
+    'bclaw_search',
+    'bclaw_setup',
+    'bclaw_bootstrap',
+    'bclaw_switch',
+    'bclaw_release_notes',
+    'bclaw_coordinate',
+    'bclaw_dispatch',
+    'bclaw_loop',
+    'bclaw_dispatch_status',
+    'bclaw_assignment_update',
+    'bclaw_code_find',
+    'bclaw_code_brief',
+    'bclaw_code_status',
+    'bclaw_code_refresh',
+];
 /**
  * Tools removed from the MCP surface at the v1.0 cut (Phase 3 slice 3i).
  * Hidden from every `tools/list` response; direct `tools/call` still works

package/dist/core/runtime.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, sanitizeAgentPathSegment } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
@@ -19,14 +19,60 @@ function privateRuntimeDir(cwd, mode = 'read') {
     return resolveEntityDir('runtime-private', cwd ?? process.cwd(), mode);
 }
 function sharedAgentDir(agent, cwd, mode = 'read') {
-    return path.join(sharedRuntimeDir(cwd, mode), agent);
+    // pln#673 — the agent name is env-controlled and becomes a path segment:
+    // normalize it so a traversal cannot be expressed at all.
+    return path.join(sharedRuntimeDir(cwd, mode), sanitizeAgentPathSegment(agent));
+}
+/**
+ * Return a pre-normalization directory only when it is provably one direct
+ * child of `baseDir`. Compatibility reads must not reintroduce the traversal
+ * the normalized write path closes: the agent name is still env-controlled.
+ *
+ * Dots inside a segment are retained for existing names such as
+ * `Legacy.Agent`; separators, Win32 aliases (including trailing dots/spaces),
+ * and platform-invalid components are not legacy data we can safely probe.
+ */
+const UNSAFE_LEGACY_AGENT_SEGMENT_RE = /[<>:"/\\|?*\u0000-\u001F]/;
+const WIN32_RESERVED_LEGACY_AGENT_BASENAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+function legacyAgentDir(baseDir, agent) {
+    if (agent.length === 0
+        || agent !== agent.trim()
+        || agent.endsWith('.')
+        || UNSAFE_LEGACY_AGENT_SEGMENT_RE.test(agent)
+        || WIN32_RESERVED_LEGACY_AGENT_BASENAME_RE.test(agent.split('.')[0]))
+        return undefined;
+    const base = path.resolve(baseDir);
+    const candidate = path.resolve(path.join(base, agent));
+    return path.dirname(candidate) === base ? candidate : undefined;
+}
+/**
+ * Both directories an agent's notes can occupy, canonical first (pln#673).
+ * Writes always use the normalized segment; reads also probe the RAW name so
+ * notes written before the normalization stay visible — the dual-read pattern
+ * pln#648/pln#670 already use for relocated records. Deduped when the name is
+ * already canonical, which is the case for every agent brainclaw produces.
+ */
+function agentDirCandidates(baseDir, agent) {
+    const canonical = path.join(baseDir, sanitizeAgentPathSegment(agent));
+    const raw = legacyAgentDir(baseDir, agent);
+    return raw && canonical !== raw ? [canonical, raw] : [canonical];
 }
 function hostRootDir(visibility, hostId, cwd, mode = 'read') {
     const baseDir = visibility === 'machine' ? machineRuntimeDir(cwd, mode) : privateRuntimeDir(cwd, mode);
     return path.join(baseDir, sanitizeHostId(hostId));
 }
 function hostAgentDir(visibility, hostId, agent, cwd, mode = 'read') {
-    return path.join(hostRootDir(visibility, hostId, cwd, mode), agent);
+    // pln#673 — same normalization as the shared tree; the host segment was
+    // already sanitized (sanitizeHostId), the agent segment was not.
+    return path.join(hostRootDir(visibility, hostId, cwd, mode), sanitizeAgentPathSegment(agent));
+}
+/** A contained raw path that can be retired after an update reaches its canonical location. */
+function legacyRuntimeNotePath(note, visibility, hostId, cwd) {
+    const base = visibility === 'shared'
+        ? sharedRuntimeDir(cwd, 'write')
+        : hostRootDir(visibility, hostId, cwd, 'write');
+    const legacyDir = legacyAgentDir(base, note.agent);
+    return legacyDir ? path.join(legacyDir, `${note.id}.json`) : undefined;
 }
 export function ensureRuntimeDir(agent, cwd, visibility = 'shared', hostId) {
     const dir = visibility === 'shared'
@@ -57,6 +103,13 @@ export function saveRuntimeNote(note, cwd) {
             registryFaultPoint('after_registry_journal');
         }
         saveVersionedJsonFile('runtime_note', filepath, parsed);
+        // An update to a pre-normalization record must not leave two physical
+        // copies with the same id. Retire only the verified-contained raw path,
+        // and only after the canonical write succeeds.
+        const legacyPath = legacyRuntimeNotePath(note, visibility, hostId, cwd);
+        if (legacyPath && legacyPath !== filepath && fs.existsSync(legacyPath)) {
+            fs.unlinkSync(legacyPath);
+        }
         appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
         commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
     });
@@ -64,9 +117,16 @@ export function saveRuntimeNote(note, cwd) {
 export function runtimeNotePath(note, cwd) {
     const visibility = note.visibility ?? 'shared';
     const hostId = sanitizeHostId(note.host_id ?? resolveCurrentHostId());
-    return visibility === 'shared'
-        ? path.join(sharedAgentDir(note.agent, cwd), `${note.id}.json`)
-        : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
+    // pln#673 — the canonical (normalized) location, plus the RAW-name fallback
+    // for notes written before the normalization: this function answers "where is
+    // THIS note", and a record must not become invisible (nor undeletable)
+    // because its directory predates the fix. Canonical first; the raw candidate
+    // only wins when it actually holds the file.
+    const base = visibility === 'shared'
+        ? sharedRuntimeDir(cwd)
+        : hostRootDir(visibility, hostId, cwd);
+    const candidates = agentDirCandidates(base, note.agent).map((dir) => path.join(dir, `${note.id}.json`));
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
 }
 /**
  * Park one runtime note's raw record under `.brainclaw/gc-backups/` — the same
@@ -141,12 +201,17 @@ export function listSharedJournaledRuntimeNotes(cwd) {
 function readAgentNotes(dir, agent) {
     if (!fs.existsSync(dir))
         return [];
-    const agents = agent
-        ? [agent]
-        : fs.readdirSync(dir).filter((entry) => fs.statSync(path.join(dir, entry)).isDirectory());
+    // pln#673 — a filtered read probes BOTH the normalized directory and the raw
+    // name (a pre-normalization directory must stay readable); an unfiltered read
+    // enumerates whatever is on disk, which covers both by construction. The
+    // candidates are absolute, so the join below must not prepend `dir` again.
+    const agentDirectories = agent
+        ? agentDirCandidates(dir, agent)
+        : fs.readdirSync(dir)
+            .filter((entry) => fs.statSync(path.join(dir, entry)).isDirectory())
+            .map((entry) => path.join(dir, entry));
     const notes = [];
-    for (const a of agents) {
-        const agentDirectory = path.join(dir, a);
+    for (const agentDirectory of agentDirectories) {
         if (!fs.existsSync(agentDirectory))
             continue;
         const files = fs.readdirSync(agentDirectory).filter((file) => file.endsWith('.json'));

package/dist/core/store-resolution.js

@@ -4,7 +4,11 @@ import path from 'node:path';
 import { loadActiveProject } from './active-project.js';
 import { loadConfig } from './config.js';
 import { loadCurrentSession, loadSessionById, resolveExplicitSessionId } from './identity.js';
-import { MEMORY_DIR } from './io.js';
+import { findOutermostBrainclawRoot, MEMORY_DIR } from './io.js';
+// pln#648 — the walk moved to io.ts (leaf) so identity.ts can anchor session
+// records on it without importing this module (which imports identity.ts).
+// Re-exported here to keep the existing API surface.
+export { findOutermostBrainclawRoot } from './io.js';
 import { summarizeWorkspaceProjects } from './workspace-projects.js';
 /**
  * Walk up the filesystem from `cwd`, collecting every `.brainclaw/` directory
@@ -423,26 +427,6 @@ export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
     }
     return undefined;
 }
-/**
- * Walk UP from a directory and return the outermost .brainclaw/ root found.
- * This bypasses resolveEffectiveCwd / active project to find the true workspace root.
- */
-export function findOutermostBrainclawRoot(startDir) {
-    let dir = path.resolve(startDir);
-    const root = path.parse(dir).root;
-    const home = os.homedir();
-    let outermost;
-    while (dir !== root && dir !== home) {
-        if (fs.existsSync(path.join(dir, MEMORY_DIR, 'config.yaml'))) {
-            outermost = dir;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return outermost;
-}
 /**
  * Resolve the most specific child store that should answer a context request.
  *

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.26.0 on 2026-08-16T20:27:49.404Z
+// Source: brainclaw v1.26.2 on 2026-08-22T12:18:05.969Z
 export const FACTS = {
-  "version": "1.26.0",
-  "generated_at": "2026-08-16T20:27:49.404Z",
+  "version": "1.26.2",
+  "generated_at": "2026-08-22T12:18:05.969Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -477,7 +477,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-16T20:27:47.271Z",
+    "generated_at": "2026-08-22T12:18:03.871Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -486,7 +486,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 75,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,7 +494,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 132,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.26.0",
-  "generated_at": "2026-08-16T20:27:49.404Z",
+  "version": "1.26.2",
+  "generated_at": "2026-08-22T12:18:05.969Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -475,7 +475,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-16T20:27:47.271Z",
+    "generated_at": "2026-08-22T12:18:03.871Z",
     "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -484,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 75,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -492,7 +492,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 132,
+        "duration_ms_median": 123,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/docs/PROTOCOL.md

@@ -92,9 +92,11 @@ surface stays small; richer ergonomic helpers are facades on top.
 The reference implementation surfaces these as MCP tools named
 `bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_create`,
 `bclaw_update`, `bclaw_transition`. The same names appear in
-`src/commands/mcp.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES` and are derived from
-the tool catalog, not hand-curated. Hermes and other narrow-surface agents
-include exactly this set in their MCP `tools.include`.
+`src/core/protocol-tool-policy.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES`; the
+catalog derivation is checked against that static core policy in tests. This is
+the minimum grammar, not a universal agent allowlist. Hermes receives the
+broader `MCP_HERMES_WORKFLOW_TOOL_NAMES` surface because its generated
+instructions also require lifecycle, inbox, coordination, and Code Map tools.
 
 ### 4.1 Coordination verbs (experimental — protocol v0.2 candidates)
 
@@ -197,7 +199,7 @@ the wire format for cross-project signaling.
 | Protocol concept              | Reference implementation in brainclaw                                 |
 |-------------------------------|-----------------------------------------------------------------------|
 | Entity schemas                | [`src/core/schema.ts`](../src/core/schema.ts)                          |
-| Canonical grammar tool set    | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
+| Canonical grammar tool set    | [`src/core/protocol-tool-policy.ts`](../src/core/protocol-tool-policy.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
 | MCP tool catalog              | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `ALL_TOOLS`          |
 | Per-agent writer wiring       | [`src/core/agent-files.ts`](../src/core/agent-files.ts) — `AGENT_WIRING_REGISTRY` |
 | Capability profiles           | [`src/core/agent-capability.ts`](../src/core/agent-capability.ts)       |

package/docs/cli.md

@@ -1984,7 +1984,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`; implementation loops add `bind` to dispatch the linked sequence and `verify` to run the opener-configured `command_green` check). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Open, inspect, or drive a multi-turn loop. The public lifecycle is `open`, `get`, `list`, `turn`, `complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`; implementation loops also add `bind` and `verify`, and any kind may use `request_input` / `provide_input`. `bclaw_coordinate` / `bclaw_dispatch` remain the ergonomic review and ideation shortcuts. A direct `open` must include `allow_orphan: true` to acknowledge that the caller will dispatch or drive it. |
 
 **Sequences**: