brainclaw 1.12.0 → 1.14.0

package/dist/commands/mcp.js

@@ -9,6 +9,10 @@ import { generatedSchemas } from './mcp-schemas.generated.js';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
 import { resolveCrossProjectLinks, resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate, renderContextBriefing } from '../core/context.js';
+import { ageStaleWarnings, ageWorkflowHints, loadServeRegistry } from '../core/hint-aging.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
+import { sweepAssignmentsAtReadPath, selectReadPathSweepCandidates } from '../core/assignment-sweeper.js';
+import { loadAssignment } from '../core/assignments.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, readDiskBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
@@ -31,13 +35,14 @@ import { rejectCandidate } from './reject.js';
 import { startSession } from './session-start.js';
 import { endSession } from './session-end.js';
 import { applyHandoffUpdates } from './update-handoff.js';
-import { AgentIdentityResolutionError, AgentTrustError, findAgentIdentityById, findAgentIdentityByName, hasMinimumTrustLevel, normalizeAgentName, requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentAgentIdentity, resolveCurrentModel, ensureAgentRegisteredForDispatch, } from '../core/agent-registry.js';
+import { AgentIdentityResolutionError, AgentTrustError, findAgentIdentityById, findAgentIdentityByName, hasMinimumTrustLevel, normalizeAgentName, requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentAgentIdentity, resolveCurrentModel, ensureAgentRegisteredForDispatch, resolveOrAutoRegisterAgentIdentity, } from '../core/agent-registry.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { nowISO, generateId } from '../core/ids.js';
-import { buildOperationalIdentity, loadAllSessions, loadSessionById } from '../core/identity.js';
+import { buildOperationalIdentity, loadAllSessions, loadCurrentSession, loadSessionById, saveCurrentSession } from '../core/identity.js';
 import { validateMcpInput, validateMcpField } from '../core/input-validation.js';
 import { createCapability, createTool as createRegistryTool } from '../core/registries.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
+import { isObserverMode } from '../core/observer-mode.js';
 import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, getDetectedSetupAgentNames, getInstalledAgentNames, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
 import { buildAgentInventory } from '../core/agent-inventory.js';
 import { findOutermostBrainclawRoot, resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
@@ -656,13 +661,17 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_release_claim',
-        description: 'Release a work claim.',
+        description: 'Release a work claim. Callers own their own claims; a trusted+ coordinator releasing another agent\'s claim MUST pass coordinator_override:true (audited).',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 id: { type: 'string', description: 'Claim ID to release.' },
                 planStatus: { type: 'string', description: 'Optional: update linked plan status.' },
+                coordinator_override: {
+                    type: 'boolean',
+                    description: 'Opt-in override for a trusted+ caller releasing a claim they do NOT own (cross-agent teardown, ghost-claim cleanup). Rejected for contributor-level callers; audited when used. trp#928.',
+                },
             },
             required: ['id'],
         },
@@ -1188,7 +1197,7 @@ const MCP_WRITE_TOOLS = [
             type: 'object',
             properties: {
                 entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | sequence | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
-                filter: { type: 'object', description: 'Filter keys: status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). entity=agent_run also accepts assignment_id, claim_id, message_id.' },
+                filter: { type: 'object', description: 'Filter keys (ANY entity): status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). ENTITY-SCOPED keys (rejected with a validation_error if used with any other entity): assignment_id, claim_id, message_id — ONLY for entity="agent_run". Unknown/mis-scoped keys are rejected loudly.' },
                 project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to query. Defaults to the current project. Only cross_project_links (config.yaml) and workspace store-chain children are accepted — list with `brainclaw link list`.' },
                 budget_tokens: { type: 'number', description: 'Optional token budget for the page payload (~4 chars/token). Tightens the default size cap; pagination metadata (has_more/next_offset) still applies.' },
             },
@@ -1256,7 +1265,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_transition',
-        description: 'Transition an entity to a new status. Validated against EntityRegistry.transitions. Returns the triggered side-effect tags. Pass `project` to transition an entity in a linked project instead of the current one.',
+        description: 'Transition an entity to a new status. Validated against EntityRegistry.transitions. Returns the triggered side-effect tags. Pass `project` to transition an entity in a linked project instead of the current one. For entity="claim": released/stale transitions are ownership-checked — non-owners must pass coordinator_override:true (trusted+ trust level required).',
         annotations: { tier: 'standard', category: 'memory', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
@@ -1266,6 +1275,7 @@ const MCP_WRITE_TOOLS = [
                 to: { type: 'string', description: 'Target status.' },
                 reason: { type: 'string', description: 'Optional free-text reason, audited alongside the transition.' },
                 project: { type: 'string', description: 'Optional: name of a linked project to transition the entity in. Defaults to the current project.' },
+                coordinator_override: { type: 'boolean', description: 'entity="claim" only: opt-in override for a trusted+ caller releasing/staling a claim they do NOT own. Audited when used. trp#928.' },
             },
             required: ['entity', 'id', 'to'],
         },
@@ -1829,10 +1839,22 @@ function ensureTrust(args, fields, level, cwd, sessionId) {
  * missing field — which would then be silently GC'd by the state sync loop
  * (see fix plan pln_5f44426c).
  *
- * pln#562 step 3 — resolution failure is a HARD error. The old fallback to
- * author:'unknown' produced records that passed creation but were schema-
- * invalid on read and silently GC'd: a write that lies about succeeding.
- * Callers map the throw to a validation_error tool response.
+ * pln#562 step 3 — a write that would create a record with a missing/'unknown'
+ * author must never be silent (that produced records that passed creation but
+ * were schema-invalid on read and silently GC'd from disk).
+ *
+ * pln#608 — extended with auto-repair: when the caller has no session but a
+ * derivable agent name (arg / $BRAINCLAW_AGENT_NAME / detected AI agent),
+ * fall through to `resolveOrAutoRegisterAgentIdentity` and materialize the
+ * session via `buildOperationalIdentity({ persistImplicitSession: true })`
+ * (same mechanic as switchProject:86-106 and session-start). The freshly-
+ * created session is tagged `auto_created` so aggressive harvesting can
+ * distinguish it from operator sessions (pln#602). The caller receives
+ * `auto_repair` and surfaces it as a warning — never silent.
+ *
+ * KEEP (still a hard error, doctrine boundary): the identity is ambiguous
+ * (no name in args, no env signal, no detectable agent). We do not invent
+ * an identity — invoke intent is unclear and the write would misattribute.
  */
 function resolveCanonicalAuthor(args, cwd, connectionSessionId) {
     const resolved = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, cwd, connectionSessionId);
@@ -1842,9 +1864,92 @@ function resolveCanonicalAuthor(args, cwd, connectionSessionId) {
             agent_id: resolved.identity.agent_id,
         };
     }
-    const detail = 'error' in resolved && resolved.error ? resolved.error.message : 'no registered agent identity resolved';
-    throw new Error(`cannot resolve mutation author: ${detail} `
-        + 'Start a session (bclaw_session_start) or pass a registered agent before writing.');
+    const strictError = 'error' in resolved && resolved.error ? resolved.error : undefined;
+    // KEEP (doctrine boundary): a pinned principal that rejected the caller args
+    // is a SPOOF/MISMATCH, not an ambiguous first-write. Never auto-repair over
+    // it — silently re-attributing would defeat pln#562 step 3. The strict error
+    // already carries the pointer to a curator override.
+    if (resolveConnectionPrincipal(cwd, connectionSessionId)) {
+        throw new Error(`cannot resolve mutation author: ${strictError?.message ?? 'principal mismatch'}`);
+    }
+    // Observer processes are read-only dashboards/inspectors. Even when an env
+    // variable leaks an agent name into the observer process, canonical writes
+    // must not use the auto-repair path because it can mint identity/session
+    // state as a side effect.
+    if (isObserverMode()) {
+        throw new Error(`cannot resolve mutation author: ${strictError?.message ?? 'observer mode cannot auto-repair identity/session state'}`);
+    }
+    const explicitName = typeof args.agent === 'string' ? args.agent : undefined;
+    const explicitId = typeof args.agentId === 'string' ? args.agentId : undefined;
+    // resolveOrAutoRegisterAgentIdentity's fall-through helper only reads
+    // BRAINCLAW_AGENT / OPENCLAW_AGENT. resolveCurrentAgentIdentity also honors
+    // BRAINCLAW_AGENT_NAME, and dispatched workers set both. Normalize here so
+    // an env-declared name is a first-class signal to the auto-repair path.
+    const envAgentName = explicitName
+        ?? (process.env.BRAINCLAW_AGENT_NAME?.trim() || undefined)
+        ?? (process.env.BRAINCLAW_AGENT?.trim() || undefined);
+    let identity;
+    let autoRegistered;
+    try {
+        const outcome = resolveOrAutoRegisterAgentIdentity({
+            agentName: envAgentName,
+            agentId: explicitId,
+            cwd,
+            allowCurrent: true,
+            allowEnv: true,
+        });
+        identity = outcome.identity;
+        autoRegistered = outcome.auto_registered;
+    }
+    catch (err) {
+        // Genuine ambiguity — no derivable name. Stays a hard error (KEEP: doctrine
+        // boundary is "ambiguous intent → refuse with next_action", not silence).
+        const detail = err instanceof Error ? err.message : (strictError?.message ?? String(err));
+        throw new Error(`cannot resolve mutation author: ${detail} `
+            + 'Pass a registered agent, set $BRAINCLAW_AGENT_NAME, '
+            + 'or register with `brainclaw register-agent <name>` before writing.', { cause: err });
+    }
+    const explicitSessionId = connectionSessionId?.trim() || explicitSessionIdFromEnv();
+    const hadSessionBefore = explicitSessionId
+        ? Boolean(loadSessionById(explicitSessionId, cwd))
+        : Boolean(loadCurrentSession(cwd));
+    let sessionAutoCreated;
+    try {
+        const opIdentity = buildOperationalIdentity(identity.agent_name, cwd, {
+            agentId: identity.agent_id,
+            sessionId: explicitSessionId,
+            persistImplicitSession: true,
+        });
+        if (!hadSessionBefore && opIdentity.session_id) {
+            sessionAutoCreated = opIdentity.session_id;
+            const session = loadSessionById(opIdentity.session_id, cwd);
+            if (session && !session.auto_created) {
+                saveCurrentSession({ ...session, auto_created: true }, cwd);
+            }
+        }
+    }
+    catch { /* best-effort — write can still proceed without a persisted session */ }
+    const autoRepair = (autoRegistered || sessionAutoCreated)
+        ? {
+            ...(autoRegistered ? { agent_auto_registered: true } : {}),
+            ...(sessionAutoCreated ? { session_auto_created: sessionAutoCreated } : {}),
+        }
+        : undefined;
+    return {
+        agent_name: identity.agent_name,
+        agent_id: identity.agent_id,
+        ...(autoRepair ? { auto_repair: autoRepair } : {}),
+    };
+}
+function renderAutoRepairWarning(auto_repair, agent_name) {
+    const parts = [];
+    if (auto_repair.agent_auto_registered) {
+        parts.push(`agent '${agent_name}' auto-registered (first use). Run \`brainclaw register-agent ${agent_name}\` to set capabilities and trust level.`);
+    }
+    if (auto_repair.session_auto_created) {
+        parts.push(`session ${auto_repair.session_auto_created} auto-created for this write.`);
+    }
+    return `⚠️ auto-repair: ${parts.join(' ')}`;
 }
 function explicitSessionIdFromEnv() {
     return process.env.BRAINCLAW_SESSION_ID?.trim()
@@ -3561,18 +3666,43 @@ async function _executeMcpToolCallInner(payload) {
             catch {
                 return { response: createToolErrorResponse('not_found', `Claim not found: ${claimId}`) };
             }
-            // pln#562 step 5 — release is ownership-checked like acquisition and
-            // adoption. The resolved principal must own the claim; trusted+ callers
-            // (coordinators) may release others' claims, with an audit entry.
+            // pln#562 step 5 + trp#928 — release is ownership-checked like acquisition
+            // and adoption. Under the trp#928 tightening the coordinator override is
+            // OPT-IN via coordinator_override:true (implicit "trusted+ = always
+            // override" was too magic — a coordinator releasing a worker's claim
+            // should be a visible act, not a silent side-effect of trust). The
+            // ownership check still enforces:
+            //   - owner-of-claim releases (identity matches): allowed, no override needed
+            //   - non-owner releases without coordinator_override: rejected loudly (the
+            //     error message points the caller at coordinator_override so it is
+            //     executable — pln#607 rule).
+            //   - non-owner releases with coordinator_override:true but not trusted+:
+            //     trust_error (privilege escalation prevention).
+            //   - non-owner releases with coordinator_override:true and trusted+:
+            //     allowed, audited (auditReleaseOverride).
             const releaseIdentity = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, cwd, connectionSessionId);
-            const releaseAuth = 'identity' in releaseIdentity && releaseIdentity.identity
-                ? {
-                    agent: releaseIdentity.identity.agent_name,
-                    agent_id: releaseIdentity.identity.agent_id,
-                    session_id: connectionSessionId,
-                    override: hasMinimumTrustLevel(releaseIdentity.identity.trust_level ?? 'contributor', 'trusted'),
+            if ('error' in releaseIdentity && releaseIdentity.error) {
+                const { kind, message, details } = releaseIdentity.error;
+                return { response: createToolErrorResponse(kind, message, details) };
+            }
+            if (!('identity' in releaseIdentity) || !releaseIdentity.identity) {
+                return { response: createToolErrorResponse('identity_error', 'No registered agent identity resolved for bclaw_release_claim.') };
+            }
+            const coordinatorOverrideRequested = args.coordinator_override === true;
+            if (coordinatorOverrideRequested) {
+                const trustLevel = releaseIdentity.identity.trust_level ?? 'contributor';
+                if (!hasMinimumTrustLevel(trustLevel, 'trusted')) {
+                    return {
+                        response: createToolErrorResponse('trust_error', `coordinator_override:true requires trust_level 'trusted' or higher — caller is '${trustLevel}'. Ask a curator to elevate the agent, or have the claim owner release it.`),
+                    };
                 }
-                : undefined;
+            }
+            const releaseAuth = {
+                agent: releaseIdentity.identity.agent_name,
+                agent_id: releaseIdentity.identity.agent_id,
+                session_id: connectionSessionId,
+                override: coordinatorOverrideRequested,
+            };
             let cascadeResult;
             try {
                 cascadeResult = releaseClaimWithCascade(claimId, {
@@ -4067,6 +4197,39 @@ async function _executeMcpToolCallInner(payload) {
                     actor: callerAgent,
                     actor_id: resolved.identity.agent_id,
                 }, cwd);
+                // trp#928 — cascade-release the assignment's linked claim on completion.
+                // Before this landing an obedient worker had to make TWO calls to close
+                // the loop (bclaw_assignment_update status=completed AND
+                // bclaw_release_claim); dispatch briefs enumerate both, but not every
+                // sandboxed worker gets through both, and the coordinator's harvest path
+                // only releases on --integrate — so contributor-driven completions left
+                // claims active. The worker's own identity owns the claim (session
+                // adoption), so ownership matches and no coordinator_override is needed.
+                // Silent success/failure is unacceptable: log per-claim outcome.
+                if (status === 'completed' && assignment.claim_id) {
+                    try {
+                        const { releaseClaimsCascade, logCascadeReleaseResult } = await import('../core/claims.js');
+                        const cascade = releaseClaimsCascade([assignment.claim_id], {
+                            cwd,
+                            planStatus: 'done',
+                            auth: {
+                                agent: callerAgent,
+                                agent_id: resolved.identity.agent_id,
+                                session_id: effectiveSessionId,
+                                override: false,
+                            },
+                        });
+                        logCascadeReleaseResult({
+                            actor: callerAgent,
+                            trigger: 'assignment_completed',
+                            assignment_id: assignmentId,
+                            claim_id: assignment.claim_id,
+                            cascade,
+                            cwd,
+                        });
+                    }
+                    catch { /* never block the update on cascade release */ }
+                }
                 // When accepted: auto-acknowledge the inbox message (replaces bclaw_ack_message)
                 if (status === 'accepted' && assignment.message_id) {
                     try {
@@ -4936,6 +5099,45 @@ async function _executeMcpToolCallInner(payload) {
                     }
                 }
             }
+            let stalePostAging;
+            let staleAggregate;
+            let hintsPostAging;
+            let hintsAggregate;
+            if (contextResult) {
+                try {
+                    const policy = loadHygienePolicy(targetCwd);
+                    if (!policy.disabled) {
+                        // Filter candidates from the projection (no extra reads) — only
+                        // assignments whose surfaced last_heartbeat_at is old enough to
+                        // possibly cross a family TTL. Zero read overhead when the open
+                        // work is fresh (the common case).
+                        const openAssignments = contextResult.open_work?.active_assignments ?? [];
+                        // Codex PR#48 finding 3 (pln#578 guardrail): select candidate ids
+                        // from the already-surfaced projection — created/terminal rows are
+                        // dropped BEFORE any full loadAssignment, so a healthy store costs
+                        // zero extra file reads. Selection logic is unit-tested in
+                        // selectReadPathSweepCandidates.
+                        const candidateIds = selectReadPathSweepCandidates(openAssignments, policy, Date.now());
+                        if (candidateIds.length > 0) {
+                            const full = candidateIds
+                                .map((id) => loadAssignment(id, targetCwd))
+                                .filter((a) => a !== undefined);
+                            sweepAssignmentsAtReadPath(full, targetCwd, {
+                                actor: 'bclaw_work-readpath',
+                                policy,
+                            });
+                        }
+                        const registry = loadServeRegistry(targetCwd);
+                        const aged = ageStaleWarnings(contextResult.stale_warnings ?? [], targetCwd, { policy, registry });
+                        stalePostAging = aged.warnings;
+                        staleAggregate = aged.aggregate;
+                        const agedHints = ageWorkflowHints(contextResult.workflow_hints ?? [], targetCwd, { policy, registry });
+                        hintsPostAging = agedHints.hints;
+                        hintsAggregate = agedHints.aggregate;
+                    }
+                }
+                catch { /* non-fatal — hygiene must never break bclaw_work */ }
+            }
             // Build the full context result, then compact it if requested.
             // Compact mode (default) strips the heavy ContextResult down to a
             // minimal summary that fits within MCP token limits (~25k chars).
@@ -4951,7 +5153,8 @@ async function _executeMcpToolCallInner(payload) {
                     status: item.extra ?? 'unknown',
                     plan_id: item.plan_id,
                 }));
-                const staleTop3 = (contextResult.stale_warnings ?? []).slice(0, 3).map((w) => ({
+                const stalePool = stalePostAging ?? contextResult.stale_warnings ?? [];
+                const staleTop3 = stalePool.slice(0, 3).map((w) => ({
                     id: w.id,
                     entity: w.entity,
                     text: w.text.slice(0, 80),
@@ -4975,6 +5178,7 @@ async function _executeMcpToolCallInner(payload) {
                             : {}),
                     }
                     : undefined;
+                const hintsPool = hintsPostAging ?? contextResult.workflow_hints ?? [];
                 resultPayload = {
                     context_schema: contextResult.context_schema,
                     profile: contextResult.profile,
@@ -4983,7 +5187,9 @@ async function _executeMcpToolCallInner(payload) {
                     context_diff: trimmedDiff ?? null,
                     plan_summary: planItems,
                     stale_warnings: staleTop3,
-                    workflow_hints: (contextResult.workflow_hints ?? []).slice(0, 3),
+                    ...(staleAggregate ? { stale_warnings_aggregate: staleAggregate } : {}),
+                    workflow_hints: hintsPool.slice(0, 3),
+                    ...(hintsAggregate ? { workflow_hints_aggregate: hintsAggregate } : {}),
                     claim_conflicts: contextResult.claim_conflicts ?? [],
                     open_work: contextResult.open_work ?? null,
                     _compact: true,
@@ -6515,17 +6721,38 @@ async function _executeMcpToolCallInner(payload) {
                 // only checks known keys), letting the caller believe the filter had
                 // applied when it hadn't. Under the new contract, an unknown key is
                 // a validation_error listing the keys actually honored.
+                // trp#928 — the entity-scoping error is now first-class: the doc says
+                // assignment_id/claim_id/message_id are entity='agent_run' only, but
+                // before this the rejection message called them 'unknown', misleading
+                // callers who'd cross-reference the description. Now the message names
+                // the constraint AND the entity that DOES accept the key so the user
+                // can fix the call without hunting through docs. (pln#599 docs-vs-facts.)
                 const KNOWN_FILTER_KEYS = new Set([
                     'status', 'tag', 'tags', 'author', 'plan_id', 'source', 'auto_generated',
                     'assignment_id', 'claim_id', 'message_id',
                     'limit', 'offset', 'includeLegacy', 'minAutoReflectConfidence',
                 ]);
                 const agentRunOnlyFilterKeys = new Set(['assignment_id', 'claim_id', 'message_id']);
-                const unknownKeys = Object.keys(filter).filter((k) => !KNOWN_FILTER_KEYS.has(k) || (agentRunOnlyFilterKeys.has(k) && entity !== 'agent_run'));
-                if (unknownKeys.length > 0) {
+                const providedKeys = Object.keys(filter);
+                const unknownKeys = providedKeys.filter((k) => !KNOWN_FILTER_KEYS.has(k));
+                const misScopedKeys = providedKeys.filter((k) => agentRunOnlyFilterKeys.has(k) && entity !== 'agent_run');
+                if (unknownKeys.length > 0 || misScopedKeys.length > 0) {
+                    const parts = [];
+                    if (unknownKeys.length > 0) {
+                        parts.push(`Unknown filter key(s): ${unknownKeys.map((k) => `"${k}"`).join(', ')}. Accepted keys: ${[...KNOWN_FILTER_KEYS].sort().join(', ')}.`);
+                    }
+                    if (misScopedKeys.length > 0) {
+                        parts.push(`Filter key(s) ${misScopedKeys.map((k) => `"${k}"`).join(', ')} are only valid for entity="agent_run" `
+                            + `(this call used entity="${entity}"). `
+                            + `Retry with entity="agent_run", or drop the ${misScopedKeys.join('/')} filter.`);
+                    }
                     return {
-                        response: createToolErrorResponse('validation_error', `Unknown filter key(s): ${unknownKeys.map((k) => `"${k}"`).join(', ')}. ` +
-                            `Accepted keys: ${[...KNOWN_FILTER_KEYS].sort().join(', ')}.`, { unknown_keys: unknownKeys, accepted_keys: [...KNOWN_FILTER_KEYS].sort() }),
+                        response: createToolErrorResponse('validation_error', parts.join(' '), {
+                            unknown_keys: unknownKeys,
+                            mis_scoped_keys: misScopedKeys,
+                            accepted_keys: [...KNOWN_FILTER_KEYS].sort(),
+                            agent_run_only_keys: [...agentRunOnlyFilterKeys],
+                        }),
                     };
                 }
                 const result = listEntities(entity, targetCwd, filter);
@@ -6664,29 +6891,36 @@ async function _executeMcpToolCallInner(payload) {
                 const data = { ...rawData };
                 let actor = typeof data.author === 'string' ? data.author : undefined;
                 let actorId = typeof data.agent_id === 'string' ? data.agent_id : undefined;
+                let autoRepair;
                 if (data.author === undefined) {
-                    const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
-                    data.author = agent_name;
+                    const author = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                    data.author = author.agent_name;
                     if (data.agent === undefined)
-                        data.agent = agent_name;
-                    if (data.agent_id === undefined && agent_id)
-                        data.agent_id = agent_id;
-                    actor = agent_name;
-                    actorId = agent_id;
+                        data.agent = author.agent_name;
+                    if (data.agent_id === undefined && author.agent_id)
+                        data.agent_id = author.agent_id;
+                    actor = author.agent_name;
+                    actorId = author.agent_id;
+                    autoRepair = author.auto_repair;
                 }
                 else if (data.agent === undefined) {
                     data.agent = data.author;
                 }
                 const result = createEntity(entity, data, targetCwd);
                 appendAuditEntry({ actor: actor ?? 'unknown', ...(actorId ? { actor_id: actorId } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
+                const createText = `✔ created ${entity} ${result.id}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}`;
+                const createContent = autoRepair
+                    ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }]
+                    : [{ type: 'text', text: createText }];
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ created ${entity} ${result.id}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}` }],
+                        content: createContent,
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
                             active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                             ...(autoSwitched ? { auto_switched: true } : {}),
+                            ...(autoRepair ? { auto_repair: autoRepair } : {}),
                         },
                     }),
                 };
@@ -6702,16 +6936,21 @@ async function _executeMcpToolCallInner(payload) {
                 const patch = (args.patch ?? {});
                 const targetCwd = resolveProjectCwd(args.project, cwd);
                 const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
-                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = updateEntity(entity, id, patch, targetCwd);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'update', item_id: id, item_type: entity }, targetCwd);
+                const updateText = `✔ updated ${entity} ${id}`;
+                const updateContent = auto_repair
+                    ? [{ type: 'text', text: updateText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
+                    : [{ type: 'text', text: updateText }];
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ updated ${entity} ${id}` }],
+                        content: updateContent,
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
                             active_source: targetScope.active_source,
+                            ...(auto_repair ? { auto_repair } : {}),
                         },
                     }),
                 };
@@ -6727,16 +6966,21 @@ async function _executeMcpToolCallInner(payload) {
                 const purge = args.purge === true;
                 const targetCwd = resolveProjectCwd(args.project, cwd);
                 const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
-                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = removeEntity(entity, id, targetCwd, purge);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'delete', item_id: id, item_type: entity, reason: purge ? 'purged' : 'archived' }, targetCwd);
+                const removeText = `✔ removed ${entity} ${id}`;
+                const removeContent = auto_repair
+                    ? [{ type: 'text', text: removeText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
+                    : [{ type: 'text', text: removeText }];
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ removed ${entity} ${id}` }],
+                        content: removeContent,
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
                             active_source: targetScope.active_source,
+                            ...(auto_repair ? { auto_repair } : {}),
                         },
                     }),
                 };
@@ -6752,13 +6996,20 @@ async function _executeMcpToolCallInner(payload) {
                 const toProject = String(args.to_project ?? '');
                 const fromProject = typeof args.from_project === 'string' ? args.from_project : undefined;
                 const force = args.force === true;
-                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = relocateEntity({ entity, id, toProject, fromProject, force, cwd, actor: agent_name, actorId: agent_id });
                 const warn = result.warnings.length ? ` (${result.warnings.length} warning(s))` : '';
+                const moveText = `✔ moved ${entity} ${id} → ${result.to}${warn}`;
+                const moveContent = auto_repair
+                    ? [{ type: 'text', text: moveText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
+                    : [{ type: 'text', text: moveText }];
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ moved ${entity} ${id} → ${result.to}${warn}` }],
-                        structuredContent: { ...result },
+                        content: moveContent,
+                        structuredContent: {
+                            ...result,
+                            ...(auto_repair ? { auto_repair } : {}),
+                        },
                     }),
                 };
             }
@@ -6788,17 +7039,48 @@ async function _executeMcpToolCallInner(payload) {
                 const to = String(args.to ?? '');
                 const reason = args.reason;
                 const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
-                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
-                const result = transitionEntity(entity, id, to, targetCwd, reason);
+                const { agent_name, agent_id, auto_repair } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                // trp#928 — claim transitions consume the ReleaseClaimAuth ownership
+                // check (released/stale both mutate a claim owned by SOME agent). Reuse
+                // the same coordinator_override opt-in as bclaw_release_claim so both
+                // paths have identical trust semantics and the same executable error.
+                let transitionAuth;
+                if (entity === 'claim') {
+                    const transitionIdentity = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, targetCwd, connectionSessionId);
+                    const coordinatorOverrideRequested = args.coordinator_override === true;
+                    if (coordinatorOverrideRequested) {
+                        const identity = 'identity' in transitionIdentity ? transitionIdentity.identity : undefined;
+                        const trustLevel = identity?.trust_level ?? 'contributor';
+                        if (!hasMinimumTrustLevel(trustLevel, 'trusted')) {
+                            return {
+                                response: createToolErrorResponse('trust_error', `coordinator_override:true requires trust_level 'trusted' or higher — caller is '${trustLevel}'.`),
+                            };
+                        }
+                    }
+                    transitionAuth = 'identity' in transitionIdentity && transitionIdentity.identity
+                        ? {
+                            agent: transitionIdentity.identity.agent_name,
+                            agent_id: transitionIdentity.identity.agent_id,
+                            session_id: connectionSessionId,
+                            override: coordinatorOverrideRequested,
+                        }
+                        : undefined;
+                }
+                const result = transitionEntity(entity, id, to, targetCwd, reason, transitionAuth);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'update', item_id: id, item_type: entity, reason: `transition ${result.from} → ${to}${reason ? ` (${reason})` : ''}` }, targetCwd);
+                const transitionText = `✔ ${entity} ${id}: ${result.from} → ${to}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}`;
+                const transitionContent = auto_repair
+                    ? [{ type: 'text', text: transitionText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
+                    : [{ type: 'text', text: transitionText }];
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${entity} ${id}: ${result.from} → ${to}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}` }],
+                        content: transitionContent,
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
                             active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                             ...(autoSwitched ? { auto_switched: true } : {}),
+                            ...(auto_repair ? { auto_repair } : {}),
                         },
                     }),
                 };

package/dist/commands/release-claim.js

@@ -3,16 +3,36 @@ import { mutate } from '../core/mutation-pipeline.js';
 import { loadClaim, listClaims, releaseClaim } from '../core/claims.js';
 import { rebuildProjectMd } from '../core/markdown.js';
 import { loadState, mutateState } from '../core/state.js';
+import { requireMinimumTrustLevel, requireRegisteredAgentIdentity } from '../core/agent-registry.js';
 export function runReleaseClaim(id, options = {}) {
     if (!memoryExists(options.cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     try {
+        // Surface split (trp#928 follow-up): the ownership gate lives on the MCP
+        // surface (bclaw_release_claim / bclaw_transition), where agent callers
+        // carry a session-bound identity. The CLI `release-claim <id>` is the
+        // operator/scripting surface and keeps its historic unguarded semantics —
+        // the e2e contract (collaboration.test.ts) has always released cross-agent
+        // claims from an env-identified CLI. Deriving an ambient identity here and
+        // gating on it turned every operator release into a false ownership
+        // mismatch (silent-default anti-pattern, pln#607). `--coordinator-override`
+        // stays available to make a cross-agent release explicit and audited.
+        let releaseAuth;
+        if (options.coordinatorOverride) {
+            const identity = requireRegisteredAgentIdentity({ cwd: options.cwd, allowCurrent: true, allowEnv: true });
+            requireMinimumTrustLevel(identity, 'trusted');
+            releaseAuth = {
+                agent: identity.agent_name,
+                agent_id: identity.agent_id,
+                override: true,
+            };
+        }
         let claim = loadClaim(id, options.cwd);
         mutate({ cwd: options.cwd }, () => {
             const existing = loadClaim(id, options.cwd);
-            claim = releaseClaim(id, options.cwd);
+            claim = releaseClaim(id, options.cwd, releaseAuth);
             if (existing.plan_id) {
                 const updated = mutateState((state) => {
                     const plan = state.plan_items.find((item) => item.id === existing.plan_id);