brainclaw 1.17.0 → 1.19.0

package/dist/commands/install-hooks.js

@@ -36,48 +36,205 @@ export function runInstallHooks(options = {}) {
     if (!fs.existsSync(claudeHookPath) || options.force) {
         fs.writeFileSync(claudeHookPath, generateClaudePreToolScript(), { encoding: 'utf-8', mode: 0o755 });
         console.log(`✔ Claude Code preToolUse hook generated at ${claudeHookPath}`);
-        console.log('  To activate, add to .claude/settings.json hooks: { "PreToolUse": ".git/hooks/claude-pre-tool.sh" }');
     }
+    // pln#636 C1 second half (review F2) — GENERATION IS NOT ACTIVATION. This step
+    // used to only print instructions, which is why the hook was dead even for
+    // operators who ran the command: a repaired script nobody wires up is still
+    // dead. The Codex writer has owned `.codex/hooks.json` since v1.17.0; this
+    // brings the Claude surface to the same standard.
+    const activation = activateClaudePreToolHook(gitRoot, claudeHookPath);
+    switch (activation.status) {
+        case 'activated':
+            console.log(`✔ PreToolUse hook activated in ${activation.settingsPath}`);
+            console.log('  Advisory-only (never blocks): it adds context, it cannot deny a write.');
+            break;
+        case 'already_active':
+            console.log(`✔ PreToolUse hook already active in ${activation.settingsPath}`);
+            break;
+        case 'failed':
+            console.log(`⚠ Could not activate the PreToolUse hook automatically: ${activation.reason}`);
+            console.log('  Add this to .claude/settings.json by hand:');
+            console.log('    { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit|NotebookEdit",');
+            console.log(`        "hooks": [ { "type": "command", "command": "${toPosixPath(claudeHookPath)}" } ] } ] } }`);
+            break;
+    }
+}
+/** Hook scripts are invoked through a shell, so the command is always POSIX-style. */
+function toPosixPath(p) {
+    return p.split('\\').join('/');
 }
+/**
+ * The tools whose `tool_input` exposes a concrete file path.
+ *
+ * `Bash` is deliberately absent: a shell command's file footprint is not
+ * statically knowable, so it is `unverifiable`, never a guess. The pre-repair
+ * matcher included it, which was one source of the noise that made the hook
+ * worth ignoring.
+ */
+const CLAUDE_PRE_TOOL_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+/**
+ * Merge the PreToolUse entry into `.claude/settings.json`, additively.
+ *
+ * NON-DESTRUCTIVE BY CONSTRUCTION, which matters more here than anywhere else in
+ * this file: that file holds the operator's own permission allow-list, and
+ * clobbering it would be a far worse outcome than an unactivated advisory. So
+ * every unknown key is preserved, a pre-existing PreToolUse array is appended
+ * to rather than replaced, and anything unparseable is left strictly untouched
+ * with a manual instruction printed instead (trp_5f342186: a hook mechanism may
+ * never be the thing that destroys work).
+ *
+ * Idempotent: re-running finds the existing command and reports `already_active`.
+ */
+export function activateClaudePreToolHook(gitRoot, hookPath) {
+    const settingsPath = path.join(gitRoot, '.claude', 'settings.json');
+    const command = toPosixPath(hookPath);
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { status: 'failed', reason: 'settings.json is not a JSON object', settingsPath };
+            }
+            settings = parsed;
+        }
+        catch (err) {
+            // Refusing to touch a file we cannot parse is the whole point: rewriting it
+            // would silently drop the operator's permission list.
+            return {
+                status: 'failed',
+                reason: `settings.json is not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+                settingsPath,
+            };
+        }
+    }
+    const hooksSection = (typeof settings.hooks === 'object' && settings.hooks !== null && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    const preToolUse = Array.isArray(hooksSection.PreToolUse)
+        ? hooksSection.PreToolUse
+        : [];
+    const alreadyActive = preToolUse.some((entry) => entry?.hooks?.some((h) => typeof h?.command === 'string' && toPosixPath(h.command) === command));
+    if (alreadyActive)
+        return { status: 'already_active', settingsPath };
+    const next = {
+        ...settings,
+        hooks: {
+            ...hooksSection,
+            PreToolUse: [
+                ...preToolUse,
+                { matcher: CLAUDE_PRE_TOOL_MATCHER, hooks: [{ type: 'command', command }] },
+            ],
+        },
+    };
+    try {
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            reason: err instanceof Error ? err.message : String(err),
+            settingsPath,
+        };
+    }
+    return { status: 'activated', settingsPath };
+}
+/**
+ * Claude Code PreToolUse advisory hook (pln#636 C1, mechanism per cst_38effd52).
+ *
+ * THE MECHANISM MATTERS, AND THE PREVIOUS VERSION HAD IT WRONG THREE WAYS:
+ *
+ * 1. It read the tool name from `CLAUDE_TOOL_NAME` in the environment. Claude
+ *    Code delivers a JSON payload on **stdin**; that env var does not exist, so
+ *    the hook exited before doing anything — dead on arrival.
+ * 2. It wrote its advisory to **stderr with exit 0**. Per the documented host
+ *    contract, stderr at exit 0 is NOT surfaced to the model (only exit 2 feeds
+ *    stderr to Claude, and exit 2 BLOCKS the tool — unacceptable for an
+ *    advisory). So even a hook fixed for (1) would have spoken into the void.
+ *    The only non-blocking channel to the model is
+ *    `hookSpecificOutput.additionalContext` on **stdout** with exit 0.
+ * 3. It shelled out to the CLI (`execSync brainclaw claim list`) on every write,
+ *    and deduped through one project-global marker, so one agent's warning
+ *    silenced every other agent.
+ *
+ * Advisory-only is non-negotiable (trp_5f342186 — a hook cascade destroyed
+ * work): `permissionDecision` is always `allow`, the exit code is always 0.
+ *
+ * SCOPE LIMIT, STATED HONESTLY: this version answers "do you hold ANY active
+ * claim of your own?", not "are you writing outside your claim's scope". Real
+ * scope awareness needs the scope grammar (pln#636 C0-a) — 42.4% of real claim
+ * scopes are not path-matchable (cst_22ebb103), so a path comparison written
+ * today would false-accuse on nearly half of them.
+ *
+ * Guarded by tests/unit/guidance-engine-consistency.test.ts.
+ */
 function generateClaudePreToolScript() {
     return `#!/bin/sh
-# brainclaw Claude Code preToolUse hook
+# brainclaw Claude Code PreToolUse hook (advisory-only)
 # Generated by: brainclaw install-hooks
+# Contract: reads a JSON payload on stdin, replies with JSON on stdout, and
+# ALWAYS exits 0. stderr is deliberately unused: Claude Code does not surface it
+# to the model at exit 0 (cst_38effd52).
 exec node -e "
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 
-const toolName = process.env.CLAUDE_TOOL_NAME || process.argv[2] || process.env.TOOL_NAME || '';
-const isWrite = /edit|write|replace|bash|str_replace/i.test(toolName);
+let raw = '';
+try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { process.exit(0); }
 
-if (!isWrite || !toolName) process.exit(0);
+let payload;
+try { payload = JSON.parse(raw); } catch (e) { process.exit(0); }
 
+// Only STRUCTURED writes expose a concrete file path. A shell command's file
+// footprint is not statically knowable, so it stays unverifiable — never guessed.
+const toolName = (payload && payload.tool_name) || '';
+if (['Edit', 'Write', 'NotebookEdit', 'MultiEdit'].indexOf(toolName) === -1) process.exit(0);
+
+// Read the store directly; spawning the CLI per edit was the third defect.
+var active = [];
 try {
-  const BCLAW_CMD = fs.existsSync(path.join(process.cwd(), 'node_modules', '.bin', 'brainclaw')) 
-    ? 'npx brainclaw' : 'brainclaw';
-  const out = execSync(BCLAW_CMD + ' claim list --json', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
-  const claims = JSON.parse(out);
-  if (claims && claims.length > 0) process.exit(0);
-} catch (e) {
-  // ignore if brainclaw not found or fails
-  process.exit(0);
-}
+  var claimsDir = path.join(process.cwd(), '.brainclaw', 'coordination', 'claims');
+  var walk = function (dir) {
+    var entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (var i = 0; i < entries.length; i++) {
+      var full = path.join(dir, entries[i].name);
+      if (entries[i].isDirectory()) { walk(full); continue; }
+      if (entries[i].name.slice(-5) !== '.json') continue;
+      try {
+        var claim = JSON.parse(fs.readFileSync(full, 'utf8'));
+        if (claim && claim.status === 'active') active.push(claim);
+      } catch (e) { /* skip an unreadable claim */ }
+    }
+  };
+  walk(claimsDir);
+} catch (e) { process.exit(0); }
 
-const sessionMark = path.join(process.cwd(), '.brainclaw', 'tmp', 'claude_warned');
-if (!fs.existsSync(path.dirname(sessionMark))) fs.mkdirSync(path.dirname(sessionMark), { recursive: true });
+// Identity-aware: only THIS agent's claims count. Another agent holding a claim
+// says nothing about whether you hold one.
+var me = (process.env.BRAINCLAW_AGENT_ID || process.env.BRAINCLAW_AGENT_NAME || process.env.BRAINCLAW_AGENT || '').trim();
+var mine = me ? active.filter(function (c) { return c.agent_id === me || c.agent === me; }) : active;
+if (mine.length > 0) process.exit(0);
 
-if (fs.existsSync(sessionMark)) {
-  const mtime = fs.statSync(sessionMark).mtimeMs;
-  if (Date.now() - mtime < 2 * 60 * 60 * 1000) {
-    process.exit(0); // already warned this session
-  }
-}
-fs.writeFileSync(sessionMark, Date.now().toString());
+// Dedup PER AGENT, not once per project.
+try {
+  var runtimeDir = path.join(process.cwd(), '.brainclaw', 'coordination', 'runtime');
+  var slug = (me || 'unknown').replace(/[^A-Za-z0-9_.-]/g, '_');
+  var mark = path.join(runtimeDir, 'claim-advisory-' + slug + '.mark');
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  if (fs.existsSync(mark) && Date.now() - fs.statSync(mark).mtimeMs < 2 * 60 * 60 * 1000) process.exit(0);
+  fs.writeFileSync(mark, String(Date.now()));
+} catch (e) { /* dedup is best-effort: speaking twice beats crashing */ }
 
-process.stderr.write('\\n[Brainclaw] ⚠️  WARNING: You are about to use an Edit/Write tool (' + toolName + ') but you have NO active claim.\\n');
-process.stderr.write('[Brainclaw] Consider running \\\`brainclaw claim create <scope>\\\` to lock your work and avoid conflicts.\\n\\n');
-" 2>&1 || exit 0
+// The ONLY non-blocking channel to the model. permissionDecision stays 'allow'.
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'allow',
+    additionalContext: '[brainclaw] Editing without an active claim of your own. Claim the scope so parallel agents do not collide. Advisory only: this write is proceeding.',
+  },
+}));
+process.exit(0);
+"
 `;
 }
 function generatePostMergeScript() {

package/dist/commands/loop.js

@@ -122,14 +122,14 @@ function buildRequest(subcommand, loopId, opts) {
             };
     }
 }
-export function runLoopCommand(subcommand, args, options = {}, cwd) {
+export async function runLoopCommand(subcommand, args, options = {}, cwd) {
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     const loopId = requireLoopId(args, options);
     const request = buildRequest(subcommand, loopId, options);
-    const handled = handleBclawLoop({ args: request, cwd });
+    const handled = await handleBclawLoop({ args: request, cwd });
     if (handled.response.status !== 'ok') {
         const message = handled.response.error ?? handled.summary;
         fail(`bclaw_loop.${String(request.intent)} rejected the call: ${message}`, 2, options);

package/dist/commands/loops-handlers.js

@@ -1,6 +1,9 @@
 import { ZodError } from 'zod';
 import { listAgentRuns } from '../core/agentruns.js';
 import { reconcileAgentRun } from '../core/agentrun-reconciler.js';
+import { findReservationByRunId } from '../core/loops/attempt-reservation.js';
+import { runVerify } from '../core/loops/verify-command.js';
+import { runImplBind } from '../core/loops/impl-bind.js';
 import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, turn, VersionConflictError, withLoopLock, } from '../core/loops/index.js';
 import { BclawLoopRequestSchema, BCLAW_LOOP_INTENTS, } from '../core/loops/facade-schema.js';
 // NextExpectedHint type now lives in src/core/loops/next-expected.ts
@@ -179,7 +182,7 @@ function trySweepLoopTimeouts(loop_id, cwd) {
     }
     catch { /* best-effort: never block facade on sweep errors */ }
 }
-export function handleBclawLoop(options) {
+export async function handleBclawLoop(options) {
     const startMs = Date.now();
     const defaultActor = options.defaultActor ?? 'bclaw_loop';
     const inferredIntent = inferIntent(options.args);
@@ -218,6 +221,7 @@ export function handleBclawLoop(options) {
                         linked: req.linked,
                         stop_condition: req.stop_condition,
                         mode: req.mode,
+                        verify: req.verify,
                         created_by: agentId,
                     }, options.cwd);
                     const newEvents = findNewLoopEvents(loop.id, undefined, options.cwd);
@@ -257,7 +261,20 @@ export function handleBclawLoop(options) {
                             continue;
                         if (slotStatus === 'done' || slotStatus === 'failed' || slotStatus === 'cancelled')
                             continue;
+                        // pln#630 PR2b-c (§13 R6): GET is strictly observational for
+                        // TURN-OWNED slots. A slot carrying current_turn_id reconciles only
+                        // via the dedicated mutating reconcile path (never on a read), so a
+                        // stale/racing read can't phantom-complete its run. Legacy slots
+                        // (no current_turn_id) keep the intentional lazy reconcile
+                        // (trp_fdf3e590) that converges silent-completion on access.
+                        if (slot.current_turn_id)
+                            continue;
                         for (const run of listAgentRuns(options.cwd, { assignment_id: assignmentId })) {
+                            // Belt-and-braces (review PR2b-c #D): skip by ACTUAL ownership too,
+                            // not just the slot pointer — if a run is turn-owned but its slot
+                            // wasn't stamped (write-ordering), GET must still not mutate it.
+                            if (findReservationByRunId(run.id, options.cwd))
+                                continue;
                             reconcileAgentRun(run.id, options.cwd);
                         }
                     }
@@ -426,6 +443,70 @@ export function handleBclawLoop(options) {
                     return successResponse('close', { loop, next_expected: null }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summarizeLoop(loop));
                 });
             }
+            case 'verify': {
+                // pln#632 — run the loop's opener-configured verify command + record a
+                // deterministic verify_report. runVerify manages its OWN two lock scopes (the
+                // spawn runs OUT of the lock), so it is NOT wrapped in withLockedLoopMutation.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('verify', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const result = runVerify({ loop_id: req.loop_id, actor }, options.cwd);
+                const newEvents = findNewLoopEvents(result.thread.id, beforeEvents, options.cwd);
+                const summary = result.unconfigured
+                    ? `verify: loop has no protocol.verify — falling back to an agent-narrated verify_report`
+                    : result.deduped
+                        ? `verify: a verify_report already exists for iteration ${result.thread.iteration_count} (idempotent)`
+                        : `${result.report?.passed ? '✔ verify green' : result.report?.timed_out ? '✖ verify RED (timeout)' : '✖ verify red'}: ${result.report?.command ?? ''}`;
+                return successResponse('verify', {
+                    loop: result.thread,
+                    verify_report: result.report ?? null,
+                    deduped: result.deduped,
+                    unconfigured: result.unconfigured ?? false,
+                    next_expected: computeNextExpected(result.thread),
+                }, [loopArtifactEntry(result.thread.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', result.thread.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summary);
+            }
+            case 'bind': {
+                // pln#632 impl-loop bind — dispatch the loop's linked sequence + advance
+                // bind→execute. runImplBind awaits the async spawn (the advance takes its own
+                // lock via the verb), so it is NOT wrapped in withLockedLoopMutation — it mirrors
+                // coordinate(open_loop)'s async-handler-spawns pattern, not a synchronous verb.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('bind', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                if (existing.kind !== 'implementation') {
+                    return errorResponse('bind', 'validation_error', `bind is only valid for implementation loops (loop ${req.loop_id} is kind='${existing.kind}'); review/ideation loops dispatch via bclaw_coordinate`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const bind = await runImplBind({
+                    loop_id: req.loop_id,
+                    dispatcherAgent: actor,
+                    dispatcherAgentId: agentId,
+                    sessionId: options.sessionId,
+                    dryRun: req.dry_run,
+                    lanes: req.lanes,
+                    autoExecute: req.auto_execute,
+                    model: req.model,
+                    maxAssignments: req.max_assignments,
+                }, options.cwd);
+                const loop = getLoop(req.loop_id, options.cwd);
+                const newEvents = findNewLoopEvents(loop.id, beforeEvents, options.cwd);
+                const sideEffects = bind.action === 'bound'
+                    ? [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)]
+                    : [...loopEventSideEffects(newEvents)];
+                return successResponse('bind', {
+                    loop,
+                    sequence_id: bind.sequence_id,
+                    action: bind.action,
+                    advanced_to: bind.advanced_to ?? null,
+                    auto_closed: bind.auto_closed ?? false,
+                    dispatched: bind.messages_sent,
+                    dispatch: bind.dispatch,
+                    next_expected: computeNextExpected(loop),
+                }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], sideEffects, bind.dispatch?.warnings ?? [], Date.now() - startMs, bind.reason);
+            }
         }
     }
     catch (err) {

package/dist/commands/mcp-catalog.js

@@ -360,19 +360,22 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_read_inbox',
-        description: 'Read messages from an agent inbox. Returns pending messages by default. Use markAsRead to auto-mark pending messages as read. Supports filtering by status, type, and thread_id.',
+        description: 'Read messages from an agent inbox, newest-first. By default returns only ACTIONABLE messages (pending + read) and hides acknowledged/archived — pass includeAll=true, or a specific status, to widen. Message bodies are previewed (~500 chars) unless full=true; the page is size-bounded by budget_tokens so a read can never blow the token budget. Use markAsRead to auto-mark pending messages as read.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 agent: { type: 'string', description: 'Agent name whose inbox to read. Defaults to calling agent.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
-                status: { type: 'string', description: 'Filter by status: pending, read, acknowledged, archived.' },
+                status: { type: 'string', description: 'Filter by an exact status: pending, read, acknowledged, archived. Overrides the actionable default.' },
+                includeAll: { type: 'boolean', description: 'Return every status (including acknowledged + archived), disabling the actionable default. Default: false.' },
                 type: { type: 'string', description: 'Filter by message type: assign, review, rfc, info, reply.' },
                 thread_id: { type: 'string', description: 'Filter by thread ID to see a conversation.' },
+                full: { type: 'boolean', description: 'Return complete message bodies instead of ~500-char previews. Each previewed message reports text_length + truncated:true. Default: false.' },
                 markAsRead: { type: 'boolean', description: 'Mark pending messages as read. Default: false.' },
                 limit: { type: 'number', description: 'Maximum messages to return (default: 20).' },
                 offset: { type: 'number', description: 'Skip N messages for pagination.' },
+                budget_tokens: { type: 'number', description: 'Cap the returned page size (~4 chars/token). Messages are trimmed until the payload fits; has_more/next_offset let you page the rest.' },
             },
         },
     },
@@ -1028,8 +1031,8 @@ const MCP_WRITE_TOOLS = [
                     // created a loop structure without dispatching the first turn, so
                     // nothing ever ran. Loops are opened via
                     // bclaw_coordinate(intent='review', open_loop=true) or intent='ideate'.
-                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close'],
-                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. See docs/concepts/loop-engine.md.',
+                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close', 'bind'],
+                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. `bind` (implementation loops only) dispatches the loop\'s linked sequence and advances bind→execute — the engine action for the `bind` phase. See docs/concepts/loop-engine.md.',
                 },
                 loop_id: { type: 'string', description: 'Target loop id (lop_…). Required for every intent except open and list.' },
                 kind: { type: 'string', enum: ['review', 'ideation', 'implementation', 'research', 'debug'], description: 'Loop kind for open / list filter.' },
@@ -1052,6 +1055,11 @@ const MCP_WRITE_TOOLS = [
                 outcome: { type: 'string', enum: ['done', 'failed', 'cancelled'], description: 'complete_turn outcome (default done).' },
                 failure_reason: { type: 'string', description: 'complete_turn: optional failure/cancel reason.' },
                 artifact: { type: 'object', description: 'complete_turn / add_artifact payload: { phase, type, body?, produced_by?, ref? }.' },
+                dry_run: { type: 'boolean', description: 'bind: analyze + report what would dispatch; no spawn, no advance.' },
+                lanes: { type: 'array', items: { type: 'string' }, description: 'bind: restrict the dispatch to specific sequence lanes.' },
+                auto_execute: { type: 'boolean', description: 'bind: deliver briefs without spawning (→ manual launch commands).' },
+                model: { type: 'string', description: 'bind: model override for the dispatched agents.' },
+                max_assignments: { type: 'number', description: 'bind: cap assignments made in this bind.' },
                 to_phase: { type: 'string', description: 'advance: explicit target phase (otherwise the next phase).' },
                 force: { type: 'boolean', description: 'advance: allow going backwards (increments iteration_count).' },
                 reason: { type: 'string', description: 'advance / pause / close: optional reason string.' },

package/dist/commands/mcp-read-handlers.js

@@ -149,6 +149,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     let agentNameCache;
     return dispatchReadTool(name, args, {
         cwd,
+        sourceCwd: effective.cwd,
         activeSource,
         resolvedProject,
         projectRoutingApplied,
@@ -1803,6 +1804,8 @@ function dispatchReadTool(name, args, ctx) {
     if (name === 'bclaw_read_inbox') {
         const agentName = args.agent ?? ctx.getAgentName();
         const markAsRead = args.markAsRead === true; // default: false — reading doesn't imply processing
+        const includeAll = args.includeAll === true; // pln#627 Phase A — widen past the actionable default
+        const full = args.full === true; // pln#627 Phase A — return whole bodies, not previews
         const result = readInbox({
             agent: agentName,
             status: args.status,
@@ -1810,21 +1813,77 @@ function dispatchReadTool(name, args, ctx) {
             thread_id: args.thread_id,
             limit: args.limit,
             offset: args.offset,
+            includeAll,
             markAsRead,
         }, cwd);
-        const lines = [`Inbox for ${agentName} — ${result.total} message(s):`];
-        for (const msg of result.messages) {
+        // pln#627 Phase A — bound the payload so a single inbox read can never blow
+        // the MCP token budget (root cause: persona/CoDev dumps persisted as inbox
+        // messages, one at 960 KB). Two independent guards:
+        //   1. per-message: preview each body to INBOX_PREVIEW_CHARS unless full=true;
+        //      the whole body stays available via full=true (bclaw_get(inbox_message)
+        //      is per-agent-scoped and cannot serve one message by id).
+        //   2. whole-page: boundListResult trims messages until the JSON fits the
+        //      char budget, the same way bclaw_find / bclaw_search do (~4 chars/token).
+        const INBOX_PREVIEW_CHARS = 500;
+        const projected = result.messages.map((msg) => {
+            const textLength = msg.text.length;
+            const truncated = !full && textLength > INBOX_PREVIEW_CHARS;
+            return {
+                ...msg,
+                text: truncated ? msg.text.slice(0, INBOX_PREVIEW_CHARS) : msg.text,
+                text_length: textLength,
+                truncated,
+            };
+        });
+        const budgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+        const charBudget = budgetTokens ? Math.min(budgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+        const bounded = boundListResult({ entity: 'inbox_message', total: result.total, items: projected }, result.offset, charBudget);
+        const scopeNote = includeAll || args.status ? '' : ' actionable (pending+read); pass includeAll=true for acknowledged/archived';
+        const lines = [`Inbox for ${agentName} — ${result.total} message(s)${scopeNote}:`];
+        for (const msg of bounded.items) {
             const ack = msg.requires_ack ? ' [ACK required]' : '';
             const thread = msg.thread_id ? ` thread:${msg.thread_id}` : '';
             lines.push(`  [${msg.short_label ?? msg.id}] ${msg.type} from ${msg.from} (${msg.status})${ack}${thread}`);
-            lines.push(`    ${msg.text.slice(0, 200)}${msg.text.length > 200 ? '...' : ''}`);
-        }
-        if (result.messages.length === 0) {
+            const preview = msg.text.slice(0, 200);
+            const more = msg.truncated || msg.text_length > 200;
+            const moreNote = more
+                ? `… (${msg.text_length} chars${msg.truncated ? '; pass full=true for the whole body' : ''})`
+                : '';
+            lines.push(`    ${preview}${moreNote}`);
+        }
+        if (bounded.items.length === 0) {
             lines.push('  (no messages)');
         }
+        if (bounded.hint)
+            lines.push('', bounded.hint);
+        const nextActions = bounded.has_more
+            ? [{
+                    tool: 'bclaw_read_inbox',
+                    args: {
+                        ...(args.agent ? { agent: args.agent } : {}),
+                        offset: bounded.next_offset,
+                        ...(args.limit ? { limit: args.limit } : {}),
+                        ...(args.status ? { status: args.status } : {}),
+                        ...(includeAll ? { includeAll: true } : {}),
+                    },
+                    when: 'to fetch the next page',
+                }]
+            : [];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...result, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                total: result.total,
+                offset: result.offset,
+                limit: result.limit,
+                messages: bounded.items,
+                returned: bounded.returned,
+                has_more: bounded.has_more,
+                ...(bounded.next_offset !== undefined ? { next_offset: bounded.next_offset } : {}),
+                ...(bounded.omitted_for_size ? { omitted_for_size: bounded.omitted_for_size } : {}),
+                ...(bounded.hint ? { hint: bounded.hint } : {}),
+                ...(nextActions.length ? { next_actions: nextActions } : {}),
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     if (name === 'bclaw_context') {
@@ -1915,9 +1974,33 @@ function dispatchReadTool(name, args, ctx) {
             `  stderr: ${status.runtime.log_files.stderr?.exists ? `${status.runtime.log_files.stderr.size_bytes}B` : 'absent'}`,
             `  git: commits_ahead=${status.runtime.commits_ahead ?? 'n/a'} dirty_tracked=${status.runtime.dirty_tracked ?? 'n/a'}`,
         ];
+        // pln#521 P1 (B4) — routing echo. Operators debugging a dispatch need to see
+        // which project this status was read from, and WHY that project won, without
+        // reverse-engineering cwd + store state. The decision (project_name/
+        // project_cwd) is a first-class field; the reasoning is the `_resolution_trace`
+        // sibling, which by design ships here and nowhere else. Deliberately cheap:
+        // no candidate/nested-store scan on a hot read path. source_cwd is the
+        // PRE-routing cwd (ctx.sourceCwd) — using the routed cwd would make the two
+        // ends identical exactly when a `project` arg hopped stores, i.e. the one
+        // case the trace exists to show.
+        const projectCwd = resolvedProject?.path ?? cwd;
+        const projectName = resolvedProject?.name;
+        const resolutionTrace = {
+            source_cwd: ctx.sourceCwd,
+            effective_cwd: projectCwd,
+            active_source: activeSource,
+            ...(projectRoutingApplied && typeof args.project === 'string' ? { project_arg: args.project } : {}),
+        };
+        lines.push('', `Project: ${projectName ?? '(unnamed)'} — ${projectCwd} (via ${activeSource})`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...status, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                ...status,
+                project_cwd: projectCwd,
+                ...(projectName ? { project_name: projectName } : {}),
+                _resolution_trace: resolutionTrace,
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     throw new Error(`Unknown read tool: ${name}`);

package/dist/commands/mcp-schemas.generated.js

@@ -291,6 +291,9 @@ export const generatedSchemas = {
                     "failed",
                     "cancelled"
                 ]
+            },
+            "current_turn_id": {
+                "type": "string"
             }
         },
         "required": [