brainclaw 1.11.0 → 1.12.0

package/README.md

@@ -417,6 +417,14 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.11.1
+
+Agent-identity & session-hook resilience, from a fresh-CLI dogfood on a monorepo:
+
+- **Session hooks no longer spam `UserPromptSubmit hook error` on every prompt.** Root cause was an agent-identity error whose own remediation (`register-agent --set-current`) the resolver ignored, swallowed by `2>/dev/null`. Now: the error hint points at what actually works (`--agent` / `$BRAINCLAW_AGENT_NAME`), a **single registered agent auto-resolves** with no env signal, and `session-start`/`context-diff`/`session-end` run with `--hook` so they degrade to exit 0 + `~/.brainclaw/hook.log` instead of erroring the prompt loop. Multi-agent safety (pln#562) is unchanged.
+- **`brainclaw doctor --fix-hooks`** purges stale/broken/duplicate brainclaw hooks across all Claude Code settings scopes (user + cwd) and rewrites the canonical ones — for the broken hooks that accumulate where `setup`'s git-repo discovery never reached.
+- **`setup` repo discovery recurses** (bounded, skipping `node_modules`/build dirs) so repos nested deep in a workspace are found instead of silently missed, and it registers the detected agent so the hooks it installs can resolve an identity.
+
 ### v1.11.0
 
 Monorepo project-resolution + Code Map, cross-project relocation, and dispatch-worktree hygiene — from a multi-project (monorepo) dogfood:

package/dist/cli.js

@@ -774,6 +774,7 @@ program
     .option('--json', 'Output as JSON dashboard')
     .option('--migration-check', 'Report versioned documents that need schema migration')
     .option('--fix-agent-ignore', 'Add missing .gitignore entries for generated local Brainclaw agent files')
+    .option('--fix-hooks', 'Purge stale/broken/duplicate brainclaw session hooks across all Claude Code settings scopes (user + cwd) and rewrite the canonical ones')
     .option('--fix', 'Fix auto-resolvable issues (e.g. drifting MCP configs)')
     .option('--repair', 'Rebuild dist/ when the MCP runtime is missing or stale')
     .option('--after-migration', 'Run the v1.0 post-migration health check only (exits non-zero on any failure)')
@@ -1435,6 +1436,7 @@ program
     .option('--model <id>', 'Model identifier (e.g. claude-sonnet-4-6)')
     .option('--maintenance-mode <mode>', 'Maintenance mode: full (default) or fast')
     .option('--include-context', 'Output full project context after starting session (replaces separate context call)')
+    .option('--hook', 'Hook mode: degrade to exit 0 + ~/.brainclaw/hook.log on failure (advisory session hooks)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runSessionStart(options);
@@ -1452,6 +1454,7 @@ program
     .option('--dispatch-review', 'When used with --reflect-handoff, auto-dispatch a code review if the handoff is reviewable')
     .option('--reviewer <name>', 'Explicit reviewer to route the reflected handoff review to')
     .option('--no-reflect', 'Suppress the dogfooding reflection prompt (project + your surfaces/skills/tools), shown by default')
+    .option('--hook', 'Hook mode: degrade to exit 0 + ~/.brainclaw/hook.log on failure (advisory Stop hook)')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
     await runSessionEnd({
@@ -1462,6 +1465,7 @@ program
         dispatchReview: options.dispatchReview,
         reviewer: options.reviewer,
         reflect: options.reflect,
+        hook: options.hook,
     });
 });
 // --- whoami ---
@@ -1753,9 +1757,10 @@ program
     .description('Show what changed in memory since last context read, a session start, or a given timestamp')
     .option('--since <date>', 'Show changes since this ISO date')
     .option('--session <id>', 'Show changes since the start of this session')
+    .option('--hook', 'Hook mode: exit 0 silently when there is no diff baseline (advisory session hooks)')
     .option('--json', 'Output as JSON')
     .action((options) => {
-    runContextDiff({ since: options.since, session: options.session, json: options.json });
+    runContextDiff({ since: options.since, session: options.session, json: options.json, hook: options.hook });
 });
 program
     .command('capability <subcommand> [args...]')

package/dist/commands/context-diff.js

@@ -4,18 +4,45 @@ import { loadInstructions, resolveInstructions } from '../core/instructions.js';
 import { memoryExists } from '../core/io.js';
 import { loadState } from '../core/state.js';
 import { isTrapActive } from '../core/traps.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 /**
  * Hybrid context-diff: always includes critical anchors (active claims,
  * top traps, instructions) so the agent stays grounded, plus the memory
  * delta since last context read.
  */
 export function runContextDiff(options = {}) {
+    try {
+        contextDiffBody(options);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory hook (trp#917): any failure past the early guards — e.g. a
+            // corrupt session snapshot / claim / instruction file feeding buildContextDiff
+            // or buildCriticalAnchors — must NOT error the prompt loop. Log + exit 0.
+            logHookDiagnostic(`context-diff skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+function contextDiffBody(options) {
     if (!memoryExists(options.cwd)) {
+        if (options.hook) {
+            logHookDiagnostic('context-diff skipped: .brainclaw/ not found');
+            return;
+        }
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     const resolved = resolveContextDiffSince(options);
     if (!resolved.since) {
+        if (options.hook) {
+            // No diff baseline yet (e.g. first prompt before a session marker exists).
+            // Nothing to surface — exit 0 silently so the hook never errors (trp#917).
+            return;
+        }
         if (options.session) {
             console.error(`Error: session '${options.session}' not found in session snapshots or audit log.`);
             process.exit(1);
@@ -25,6 +52,10 @@ export function runContextDiff(options = {}) {
     }
     const diff = buildContextDiff({ ...options, includeItems: true });
     if (!diff) {
+        if (options.hook) {
+            logHookDiagnostic('context-diff skipped: unable to build diff');
+            return;
+        }
         console.error('Error: unable to build context diff.');
         process.exit(1);
     }

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
@@ -35,7 +36,7 @@ import { assessBrainclawVersion, detectConcurrentInstallations } from '../core/b
 import { resolveStoreChain } from '../core/store-resolution.js';
 import { listWorktrees, detectSharedCheckoutRisk } from '../core/worktree.js';
 import { resolveCrossProjectLinks, detectCrossProjectCycles } from '../core/cross-project.js';
-import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries, patchAllMcpConfigs } from '../core/agent-files.js';
+import { auditLocalAgentWorkspaceFiles, ensureGitignoreEntries, patchAllMcpConfigs, fixClaudeCodeHooksAllScopes } from '../core/agent-files.js';
 import { summarizeWorkspaceProjects } from '../core/workspace-projects.js';
 import { detectStaleness, staleSummary } from '../core/staleness.js';
 import { InboxMessageSchema } from '../core/schema.js';
@@ -654,6 +655,27 @@ export function runDoctor(options = {}) {
             process.exit(report.exit_code);
         return;
     }
+    if (options.fixHooks) {
+        const cwd = options.cwd ?? process.cwd();
+        const results = fixClaudeCodeHooksAllScopes(cwd, os.homedir());
+        const fixed = results.filter((r) => r.changed);
+        if (options.json) {
+            console.log(JSON.stringify({ ok: true, action: 'fix-hooks', results }, null, 2));
+        }
+        else if (fixed.length === 0) {
+            console.log('✔ No stale/broken brainclaw session hooks found across Claude Code settings scopes.');
+        }
+        else {
+            for (const r of fixed) {
+                const suffix = r.collapsed > 0
+                    ? ` (collapsed ${r.collapsed} stale/duplicate entr${r.collapsed === 1 ? 'y' : 'ies'})`
+                    : '';
+                console.log(`✔ Sanitized brainclaw session hooks in ${r.filePath}${suffix}`);
+            }
+            console.log('  → Restart your Claude Code session to pick up the canonical hooks.');
+        }
+        return;
+    }
     if (options.repair) {
         try {
             const result = repairDistRuntime(options);

package/dist/commands/mcp.js

@@ -7,14 +7,14 @@ import { fileURLToPath } from 'node:url';
 import { Worker } from 'node:worker_threads';
 import { generatedSchemas } from './mcp-schemas.generated.js';
 import { getTriggeredItems, renderTriggeredItems } from '../core/lifecycle.js';
-import { resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
+import { resolveCrossProjectLinks, resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate, renderContextBriefing } from '../core/context.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, readDiskBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
 import { collectLoadValidationWarnings, findLoadValidationWarning, loadState, persistState, saveState } from '../core/state.js';
 import { generateIdWithLabel } from '../core/ids.js';
-import { memoryExists } from '../core/io.js';
+import { memoryExists, MEMORY_DIR } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
 import { createEntity, getEntity, listEntities, boundListResult, DEFAULT_FIND_CHAR_BUDGET, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
 import { relocateEntity } from '../core/operations/relocate.js';
@@ -40,7 +40,8 @@ import { createCapability, createTool as createRegistryTool } from '../core/regi
 import { detectAiAgent } from '../core/ai-agent-detection.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 { resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
+import { findOutermostBrainclawRoot, resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
+import { switchProject } from './switch.js';
 import { assessBootstrapNeed, probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview, resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { ensureUserStore, resolveHomeDir } from '../core/setup-state.js';
 import { createPlan, addStep as addStepOp, completeStep as completeStepOp, updateStep as updateStepOp, deleteStep as deleteStepOp, deletePlan as deletePlanOp } from '../core/operations/plan.js';
@@ -2647,6 +2648,100 @@ function blockCrossProjectExecution(entity, args) {
         return createToolErrorResponse('validation_error', error instanceof Error ? error.message : String(error));
     }
 }
+function matchesCrossProjectLink(ref, cwd) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        return false;
+    const linkRoots = new Set([path.resolve(cwd), path.resolve(resolveWorkspaceAnchor(cwd))]);
+    for (const root of linkRoots) {
+        for (const link of resolveCrossProjectLinks(root)) {
+            if (link.projectName === trimmed
+                || link.name === trimmed
+                || link.path === trimmed
+                || link.absolutePath === trimmed
+                || path.basename(link.absolutePath) === trimmed) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Resolve the destination store for an execution-entity write (plan / claim and
+ * their sub-objects: steps).
+ *
+ * The signaling-only boundary (cnd cross_project_signaling_vs_execution) forbids
+ * driving execution entities into ANOTHER project — but that rule is about
+ * FEDERATION (cross_project_links / other machines), not about workspace siblings
+ * in the same monorepo. Switching into a sibling and creating a plan there is a
+ * purely local operation, and the one the agent actually wants.
+ *
+ * So when `project=X` resolves to a workspace store-chain child (resolveProjectRef
+ * hits — it only matches projects reachable WITHIN this workspace, never a
+ * federated link), we AUTO-LOCALIZE: open a session + session-scoped switch into X
+ * (sticky, per-agent — switchProject auto-creates the session if missing), then
+ * write locally in X. Federated links and unknown names stay blocked.
+ *
+ * DGX dogfood 2026-06-27: without this an agent on the /srv monorepo cannot
+ * `bclaw_create(entity=plan, project=<child>)` — it was rejected as cross-project —
+ * so plans silently fell back to the default project instead.
+ */
+function resolveExecutionWriteTarget(entity, args, cwd, connectionSessionId) {
+    const targetProject = getCrossProjectArg(args, 'targetProject', 'target_project', 'crossProject', 'cross_project', 'project');
+    if (!targetProject) {
+        return { targetCwd: cwd, autoSwitched: false };
+    }
+    if (matchesCrossProjectLink(targetProject, cwd)) {
+        const block = blockCrossProjectExecution(entity, args);
+        return {
+            block: block ?? createToolErrorResponse('validation_error', `Cross-project execution write blocked: ${targetProject}`),
+            targetCwd: cwd,
+            autoSwitched: false,
+        };
+    }
+    // Workspace store-chain child (or the workspace root / the current project)?
+    const wsHit = resolveProjectRef(targetProject, cwd);
+    if (wsHit) {
+        // Same-workspace → auto-localize. Switch the session into X (sticky,
+        // session-scoped) so subsequent un-qualified writes follow, and persist the
+        // session under the workspace anchor where resolveEffectiveCwd probes for it
+        // — NOT the effective child cwd, or stickiness would be invisible on the next
+        // call. The switch is best-effort: the write still localizes to wsHit below.
+        let autoSwitched = false;
+        try {
+            const anchor = resolveWorkspaceAnchor(cwd);
+            const sessionId = connectionSessionId ?? explicitSessionIdFromEnv();
+            switchProject(targetProject, { cwd: anchor, sessionOnly: true, sessionId });
+            autoSwitched = true;
+        }
+        catch {
+            /* sticky switch is best-effort */
+        }
+        return { targetCwd: wsHit, autoSwitched, resolvedProject: projectInfoForCwd(wsHit) };
+    }
+    // Not a workspace child → federated link or unknown name. The signaling-only
+    // boundary stands: execution entities never cross a federation boundary.
+    const block = blockCrossProjectExecution(entity, args);
+    return {
+        block: block ?? createToolErrorResponse('validation_error', `Unknown project: ${targetProject}`),
+        targetCwd: cwd,
+        autoSwitched: false,
+    };
+}
+/**
+ * Workspace anchor for persisting a session switch — mirrors resolveEffectiveCwd's
+ * anchor selection (BRAINCLAW_CWD when it is a real store, else the outermost
+ * store walking up from cwd) so an auto-switch is found on the next resolution.
+ */
+function resolveWorkspaceAnchor(cwd) {
+    const env = process.env.BRAINCLAW_CWD?.trim();
+    if (env) {
+        const resolved = path.resolve(env);
+        if (fs.existsSync(path.join(resolved, MEMORY_DIR, 'config.yaml')))
+            return resolved;
+    }
+    return findOutermostBrainclawRoot(cwd) ?? cwd;
+}
 // Read handlers moved to mcp-read-handlers.ts
 import { handleMcpReadToolCall } from './mcp-read-handlers.js';
 export { handleMcpReadToolCall };
@@ -3300,21 +3395,17 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_claim') {
-            const crossProjectError = blockCrossProjectExecution('claim', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
-            }
-            // Resolve project-scoped cwd before store resolution (fixes worktree in wrong project)
-            let effectiveClaimCwd = cwd;
-            const claimProjectArg = args.project;
-            if (claimProjectArg) {
-                const resolvedProject = resolveProjectRef(claimProjectArg, cwd);
-                if (resolvedProject)
-                    effectiveClaimCwd = resolvedProject;
-            }
+            // project=X naming a workspace sibling auto-localizes (session+switch then
+            // claim locally); federated links / unknown names stay blocked.
+            const claimLoc = resolveExecutionWriteTarget('claim', args, cwd, connectionSessionId);
+            if (claimLoc.block) {
+                return { response: claimLoc.block };
+            }
+            const effectiveClaimCwd = claimLoc.targetCwd;
+            const claimAutoSwitched = claimLoc.autoSwitched;
             const storeTarget = args.store ?? 'local';
             const claimCwd = resolveTargetStore(effectiveClaimCwd, storeTarget);
-            const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', claimCwd, connectionSessionId);
+            const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
                 return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
             }
@@ -3329,10 +3420,13 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', descCheck.message) };
             }
             const resolvedIdentity = resolved.identity;
-            const identity = buildOperationalIdentity(resolvedIdentity.agent_name, claimCwd, {
-                agentId: resolvedIdentity.agent_id,
-                sessionId: connectionSessionId,
-            });
+            const identity = {
+                ...buildOperationalIdentity(resolvedIdentity.agent_name, cwd, {
+                    agentId: resolvedIdentity.agent_id,
+                    sessionId: connectionSessionId,
+                }),
+                project_id: loadConfig(claimCwd).project_id,
+            };
             const claimId = generateClaimId();
             let worktreePath;
             let worktreeWarn = '';
@@ -3438,7 +3532,8 @@ async function _executeMcpToolCallInner(payload) {
             const worktreeNote = worktreePath ? `\n  Worktree: ${worktreePath}` : '';
             const expiryNote = claimExpiresAt ? `\n  Expires: ${claimExpiresAt.slice(0, 16).replace('T', ' ')} UTC` : '';
             const handoffNote = handoffMode ? `\n  Handoff: ${handoffMode} (another agent will review and merge)` : '';
-            const claimText = `✔ Claimed scope [${claimId}]${worktreeNote}${expiryNote}${handoffNote}${noPlanWarn}${worktreeWarn}${branchWarn}${staleBranchWarn}${policyWarn}${postClaimText ? `\n${postClaimText}` : ''}`;
+            const autoSwitchNote = claimAutoSwitched ? `\n  Auto-switched → ${projectInfoForCwd(effectiveClaimCwd).name ?? effectiveClaimCwd}` : '';
+            const claimText = `✔ Claimed scope [${claimId}]${worktreeNote}${expiryNote}${handoffNote}${autoSwitchNote}${noPlanWarn}${worktreeWarn}${branchWarn}${staleBranchWarn}${policyWarn}${postClaimText ? `\n${postClaimText}` : ''}`;
             return {
                 response: appendLegacyMcpToolWarning(toolResponse({
                     content: [{ type: 'text', text: claimText }],
@@ -3446,6 +3541,7 @@ async function _executeMcpToolCallInner(payload) {
                     session_id: identity.session_id,
                     worktree_path: worktreePath,
                     triggered_items: postClaimItems,
+                    ...(claimAutoSwitched ? { auto_switched: true, resolved_project: projectInfoForCwd(effectiveClaimCwd) } : {}),
                 }), name),
                 nextConnectionSessionId: explicitSessionIdFromEnv() ? undefined : identity.session_id,
             };
@@ -4232,9 +4328,9 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_add_step') {
-            const crossProjectError = blockCrossProjectExecution('plan', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
+            const stepLoc = resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+            if (stepLoc.block) {
+                return { response: stepLoc.block };
             }
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
@@ -4256,7 +4352,7 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!stepText)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: data.text') };
-            const stepTargetCwd = resolveProjectCwd(args.project, cwd);
+            const stepTargetCwd = stepLoc.targetCwd;
             try {
                 const result = addStepOp({ planId: stepPlanId, text: stepText, assignee: stepAssignee, estimatedEffort: stepEstimated, actualEffort: stepActual }, stepTargetCwd);
                 return {
@@ -4277,9 +4373,9 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_complete_step') {
-            const crossProjectError = blockCrossProjectExecution('plan', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
+            const csLoc = resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+            if (csLoc.block) {
+                return { response: csLoc.block };
             }
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
@@ -4291,7 +4387,7 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!csStepId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
-            const csTargetCwd = resolveProjectCwd(args.project, cwd);
+            const csTargetCwd = csLoc.targetCwd;
             try {
                 const result = completeStepOp({ planId: csPlanId, stepId: csStepId }, csTargetCwd);
                 return {
@@ -4313,9 +4409,9 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_update_step') {
-            const crossProjectError = blockCrossProjectExecution('plan', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
+            const usLoc = resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+            if (usLoc.block) {
+                return { response: usLoc.block };
             }
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
@@ -4331,7 +4427,7 @@ async function _executeMcpToolCallInner(payload) {
             if (args.status && !validStatuses.includes(String(args.status))) {
                 return { response: createToolErrorResponse('validation_error', `Invalid status: ${args.status}. Valid: ${validStatuses.join(', ')}`) };
             }
-            const usTargetCwd = resolveProjectCwd(args.project, cwd);
+            const usTargetCwd = usLoc.targetCwd;
             try {
                 const result = updateStepOp({
                     planId: usPlanId,
@@ -4372,9 +4468,9 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_delete_step') {
-            const crossProjectError = blockCrossProjectExecution('plan', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
+            const dsLoc = resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+            if (dsLoc.block) {
+                return { response: dsLoc.block };
             }
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
@@ -4386,7 +4482,7 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!dsStepId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
-            const dsTargetCwd = resolveProjectCwd(args.project, cwd);
+            const dsTargetCwd = dsLoc.targetCwd;
             try {
                 const result = deleteStepOp({ planId: dsPlanId, stepId: dsStepId }, dsTargetCwd);
                 return {
@@ -4407,10 +4503,11 @@ async function _executeMcpToolCallInner(payload) {
             }
         }
         if (name === 'bclaw_delete_plan') {
-            const crossProjectError = blockCrossProjectExecution('plan', args);
-            if (crossProjectError) {
-                return { response: crossProjectError };
+            const dpLoc = resolveExecutionWriteTarget('plan', args, cwd, connectionSessionId);
+            if (dpLoc.block) {
+                return { response: dpLoc.block };
             }
+            const dpTargetCwd = dpLoc.targetCwd;
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', cwd, connectionSessionId);
             if (resolved.error) {
                 return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
@@ -4419,7 +4516,7 @@ async function _executeMcpToolCallInner(payload) {
             if (!dpId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: id') };
             try {
-                const result = deletePlanOp(dpId, cwd);
+                const result = deletePlanOp(dpId, dpTargetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Plan deleted: [${result.id}] ${result.text.slice(0, 80)}` }],
@@ -6537,15 +6634,22 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_create') {
             try {
                 const entity = String(args.entity ?? '');
-                // Execution entities stay local: the signaling-only cross-project
-                // boundary applies to the canonical verbs too, not just legacy tools.
+                // Execution entities (plan/claim) auto-localize into a workspace sibling
+                // when project=X names one: session+switch then write locally. Only
+                // federated links / unknown names are blocked (signaling-only boundary).
+                let targetCwd;
+                let autoSwitched = false;
                 if (entity === 'claim' || entity === 'plan') {
-                    const crossProjectError = blockCrossProjectExecution(entity, args);
-                    if (crossProjectError)
-                        return { response: crossProjectError };
+                    const loc = resolveExecutionWriteTarget(entity, args, cwd, connectionSessionId);
+                    if (loc.block)
+                        return { response: loc.block };
+                    targetCwd = loc.targetCwd;
+                    autoSwitched = loc.autoSwitched;
+                }
+                else {
+                    targetCwd = resolveProjectCwd(args.project, cwd);
                 }
                 const rawData = (args.data ?? {});
-                const targetCwd = resolveProjectCwd(args.project, cwd);
                 const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 // Auto-fill identity fields. Without this, a caller who omits author/agent
                 // creates a schema-invalid record that is silently dropped on read and
@@ -6577,11 +6681,12 @@ async function _executeMcpToolCallInner(payload) {
                 appendAuditEntry({ actor: actor ?? 'unknown', ...(actorId ? { actor_id: actorId } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ created ${entity} ${result.id}` }],
+                        content: [{ type: 'text', text: `✔ created ${entity} ${result.id}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}` }],
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
-                            active_source: targetScope.active_source,
+                            active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
+                            ...(autoSwitched ? { auto_switched: true } : {}),
                         },
                     }),
                 };
@@ -6664,28 +6769,36 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_transition') {
             try {
                 const entity = String(args.entity ?? '');
-                // Same signaling-only boundary as bclaw_create: no remote lifecycle
-                // driving of execution entities through the canonical grammar.
+                // Same auto-localize as bclaw_create: a workspace sibling named by
+                // project=X is switched into and transitioned locally; only federated
+                // links / unknown names are blocked (signaling-only boundary).
+                let targetCwd;
+                let autoSwitched = false;
                 if (entity === 'claim' || entity === 'plan') {
-                    const crossProjectError = blockCrossProjectExecution(entity, args);
-                    if (crossProjectError)
-                        return { response: crossProjectError };
+                    const loc = resolveExecutionWriteTarget(entity, args, cwd, connectionSessionId);
+                    if (loc.block)
+                        return { response: loc.block };
+                    targetCwd = loc.targetCwd;
+                    autoSwitched = loc.autoSwitched;
+                }
+                else {
+                    targetCwd = resolveProjectCwd(args.project, cwd);
                 }
                 const id = String(args.id ?? '');
                 const to = String(args.to ?? '');
                 const reason = args.reason;
-                const targetCwd = resolveProjectCwd(args.project, cwd);
                 const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = transitionEntity(entity, id, to, targetCwd, reason);
                 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);
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${entity} ${id}: ${result.from} → ${to}` }],
+                        content: [{ type: 'text', text: `✔ ${entity} ${id}: ${result.from} → ${to}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}` }],
                         structuredContent: {
                             ...result,
                             resolved_project: targetScope.resolved_project,
-                            active_source: targetScope.active_source,
+                            active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
+                            ...(autoSwitched ? { auto_switched: true } : {}),
                         },
                     }),
                 };

package/dist/commands/session-end.js

@@ -39,6 +39,7 @@ import { extractFilesFromDiff } from '../commands/handoff.js';
 import { capHandoffDiff } from '../core/handoff-snapshot.js';
 import { suggestCompaction } from '../core/memory-compactor.js';
 import { dispatchReview } from '../core/dispatcher.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 export const REFLECTION_QUESTIONS = [
     'Dogfooding the project — using brainclaw to do real work this session, what friction did you hit (slow reads, confusing surfaces, missing affordances, awkward workflows)? What concrete change to the project would have removed it?',
     'Your surfaces, skills & tools — did your generated surface files (CLAUDE.md / agent surface), skills (SKILL.md), or tools (MCP / CLI) help or get in the way? Name at least one concrete edit that would make them serve you better next time.',
@@ -113,7 +114,13 @@ export async function runSessionEnd(options = {}) {
         }
     }
     catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory Stop hook (trp#917): never fail the prompt loop. Log + exit 0.
+            logHookDiagnostic(`session-end skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
 }

package/dist/commands/session-start.js

@@ -11,6 +11,7 @@ import { writeContextMarker } from '../core/freshness.js';
 import { saveRuntimeNote, generateRuntimeNoteId } from '../core/runtime.js';
 import { nowISO, generateId } from '../core/ids.js';
 import { appendAuditEntry } from '../core/audit.js';
+import { logHookDiagnostic } from '../core/hook-log.js';
 import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
 import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
@@ -93,7 +94,13 @@ export async function runSessionStart(options = {}) {
         }
     }
     catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        const message = e instanceof Error ? e.message : String(e);
+        if (options.hook) {
+            // Advisory hook (trp#917): never fail the prompt loop. Log + exit 0.
+            logHookDiagnostic(`session-start skipped: ${message}`);
+            return;
+        }
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
 }

package/dist/commands/setup.js

@@ -12,6 +12,7 @@ import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursor
 import { MEMORY_DIR, memoryExists } from '../core/io.js';
 import { ensureUserStore, readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
 import { writeDetectedAgentHooks } from './hooks.js';
+import { normalizeAgentName, findAgentIdentityByName, registerAgentIdentity } from '../core/agent-registry.js';
 export { readSetupState } from '../core/setup-state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 export const ALL_KNOWN_AGENTS = [
@@ -83,37 +84,59 @@ export function parseRoots(input, env = process.env) {
     return results;
 }
 // ─── Step 2: Scan repos ───────────────────────────────────────────────────────
-export function scanGitRepos(roots) {
+/** Heavy / generated directories never worth descending into when hunting repos. */
+const SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'dist-test', 'build', 'out', '.next',
+    'coverage', 'vendor', '.venv', 'venv', '__pycache__', '.cache', 'target', '.gradle',
+]);
+/**
+ * Discover git repositories under each root, recursing up to `maxDepth` levels.
+ *
+ * trp#918: the previous scan was depth-1 only (root + immediate children), so in
+ * a workspace like /srv with repos nested at /srv/dev/repos/global/<svc> it found
+ * just the shallow ones and silently missed the rest. This walk descends (skipping
+ * heavy/build/hidden dirs, bounded by `maxDepth`) and surfaces every directory
+ * that contains a `.git`. It keeps descending past a found repo because a
+ * workspace repo can legitimately contain independent child repos (the prior
+ * depth-1 scan already surfaced depth-1 children); the user selects which to init.
+ */
+export function scanGitRepos(roots, maxDepth = 6) {
     const repos = [];
     const seen = new Set();
-    for (const root of roots) {
-        const candidates = [root];
-        try {
-            const entries = fs.readdirSync(root, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory())
-                    continue;
-                candidates.push(path.join(root, entry.name));
-            }
-        }
-        catch {
-            // skip unreadable dirs
-        }
-        for (const candidate of candidates) {
-            const repoPath = path.resolve(candidate);
-            if (seen.has(repoPath))
-                continue;
-            if (isBrainclawInternalPath(repoPath))
-                continue;
-            if (!fs.existsSync(path.join(repoPath, '.git')))
-                continue;
+    const walk = (dir, depth) => {
+        const repoPath = path.resolve(dir);
+        if (seen.has(repoPath))
+            return;
+        if (isBrainclawInternalPath(repoPath))
+            return;
+        if (fs.existsSync(path.join(repoPath, '.git'))) {
             seen.add(repoPath);
             repos.push({
                 path: repoPath,
                 name: path.basename(repoPath) || repoPath,
                 alreadyInitialised: memoryExists(repoPath),
             });
+            // Keep descending — a workspace repo may contain independent child repos.
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(repoPath, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — skip
         }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SCAN_SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            walk(path.join(repoPath, entry.name), depth + 1);
+        }
+    };
+    for (const root of roots) {
+        walk(root, 0);
     }
     return repos;
 }
@@ -309,6 +332,39 @@ export async function initReposAndConfigureAgents(selectedRepos, selectedAgents,
     }
     return { initialisedRepos, configActions };
 }
+/**
+ * Ensure a resolvable session identity exists (pln#596 / trp#917). setup installs
+ * session hooks that need an agent identity; a hook with no identity now degrades
+ * silently (exit 0, logs to ~/.brainclaw/hook.log) but won't inject context. If we
+ * detected the running agent, register it in each selected repo so the hook resolves
+ * immediately. Otherwise emit a clear, actionable note — we don't guess an agent (a
+ * wrong identity is worse than none, and the single-registered-agent fallback wants
+ * exactly one).
+ */
+export function ensureSessionIdentityForRepos(repoPaths, detectedName) {
+    if (detectedName) {
+        const normalized = normalizeAgentName(detectedName);
+        let registered = 0;
+        for (const repoPath of repoPaths) {
+            try {
+                if (!findAgentIdentityByName(normalized, repoPath)) {
+                    registerAgentIdentity({ agentName: normalized, kind: 'agent', trustLevel: 'contributor', cwd: repoPath });
+                    registered++;
+                }
+            }
+            catch {
+                /* best-effort — identity registration must not abort setup */
+            }
+        }
+        if (registered > 0) {
+            console.log(`  ✔ Registered session identity '${normalized}' in ${registered} repo(s) so session hooks resolve immediately.`);
+        }
+        return;
+    }
+    console.log('\n⚠ No agent identity registered yet — session hooks will no-op (exit 0) until one resolves.');
+    console.log('  Set `export BRAINCLAW_AGENT_NAME=<agent>` in your shell, or run `brainclaw register-agent <name>`.');
+    console.log('  (A single registered agent then resolves automatically; running inside a detected agent auto-registers on first session.)');
+}
 // ─── Step 7: Reload reminder ──────────────────────────────────────────────────
 export function printReloadReminder(detectedAgent) {
     console.log('');
@@ -540,6 +596,8 @@ export async function runSetup(options = {}) {
     // Step 6: Init repos + configure agents
     console.log('\n→ Initialising repositories and configuring agents...');
     const { initialisedRepos, configActions } = await initReposAndConfigureAgents(selectedRepos, selectedAgents, env);
+    // Step 6.5: ensure a resolvable session identity for the hooks we just installed.
+    ensureSessionIdentityForRepos(selectedRepos.map((r) => r.path), detectedName);
     // Step 7: VS Code extension
     installVscodeExtension();
     // Save state

package/dist/core/agent-files.js

@@ -1095,6 +1095,98 @@ function replaceBrainclawHooks(entries, canonical) {
     kept.push(canonical);
     return kept;
 }
+/**
+ * Canonical Claude Code session-hook commands.
+ *
+ * `--hook` (pln#596) makes session-start / context-diff / session-end degrade to
+ * exit 0 + ~/.brainclaw/hook.log on failure instead of hard-erroring the prompt
+ * loop (trp#917). `2>/dev/null` is kept to suppress incidental stderr noise —
+ * the actionable diagnostic now goes to hook.log, not stderr, so it survives the
+ * redirect (the bug was the non-zero EXIT, not the stream).
+ */
+function buildClaudeCodeHookCommands(bclawBin) {
+    return {
+        session: `f=.claude/.bclaw-session; if [ ! -f "$f" ]; then touch "$f"; ${bclawBin} session-start --include-context --hook 2>/dev/null; else ${bclawBin} context-diff --hook 2>/dev/null; fi`,
+        stop: `rm -f .claude/.bclaw-session; ${bclawBin} session-end --auto-release --reflect --reflect-handoff --dispatch-review --hook 2>/dev/null`,
+        checkEvents: `${bclawBin} check-events 2>/dev/null`,
+    };
+}
+/**
+ * Sanitize the brainclaw session hooks in ONE Claude Code settings file: collapse
+ * every recognized brainclaw hook (across UserPromptSubmit / Stop / PostToolUse)
+ * to a single canonical entry, repairing stale/broken forms (e.g. the legacy
+ * `node session-start` with the cli.js arg dropped, or dead install paths).
+ *
+ * Only touches events that ALREADY contain a brainclaw hook — it never injects
+ * hooks into a file (or event) that lacked them, so user-scope settings without
+ * brainclaw hooks stay untouched. This is the cross-scope counterpart to
+ * `ensureClaudeCodeSettings`, which only rewrites the cwd project file (pln#596 /
+ * trp#918: setup's git-repo discovery never reaches the launch dir or user scope,
+ * so broken hooks accumulate exactly where the agent executes them).
+ */
+export function fixClaudeCodeHooksInFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return { filePath, existed: false, changed: false, collapsed: 0 };
+    const existing = readJsonObject(filePath); // returns {} for missing, undefined for unparseable
+    if (existing === undefined)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const hooksObj = isJsonObject(existing.hooks) ? existing.hooks : undefined;
+    if (!hooksObj)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const bclawBin = getBclawCliParts().map(quoteShellArg).join(' ');
+    const cmds = buildClaudeCodeHookCommands(bclawBin);
+    const countBrainclawHooks = (arr) => Array.isArray(arr)
+        ? arr.reduce((n, e) => n + (isJsonObject(e) && Array.isArray(e.hooks)
+            ? e.hooks.filter((h) => isJsonObject(h) && typeof h.command === 'string' && isBrainclawHookCommand(h.command)).length
+            : 0), 0)
+        : 0;
+    const events = [
+        ['UserPromptSubmit', buildCommandHookEntry(cmds.session)],
+        ['Stop', buildCommandHookEntry(cmds.stop)],
+        ['PostToolUse', buildMatchedCommandHookEntry('mcp__brainclaw__', cmds.checkEvents)],
+    ];
+    const nextHooks = { ...hooksObj };
+    let collapsed = 0;
+    let touched = false;
+    for (const [event, canonical] of events) {
+        const arr = Array.isArray(hooksObj[event]) ? hooksObj[event] : undefined;
+        if (!arr)
+            continue;
+        const before = countBrainclawHooks(arr);
+        if (before === 0)
+            continue; // never add hooks to an event that had none
+        nextHooks[event] = replaceBrainclawHooks(arr, canonical);
+        collapsed += Math.max(0, before - 1); // N brainclaw entries → 1 canonical
+        touched = true;
+    }
+    if (!touched)
+        return { filePath, existed: true, changed: false, collapsed: 0 };
+    const { updated } = writeJsonFileIfChanged(filePath, { ...existing, hooks: nextHooks });
+    return { filePath, existed: true, changed: updated, collapsed };
+}
+/**
+ * Run `fixClaudeCodeHooksInFile` across every Claude Code settings scope that can
+ * carry brainclaw hooks: user-scope (`~/.claude/settings*.json`) and the cwd
+ * project (`<cwd>/.claude/settings*.json`). Independent of git-repo discovery.
+ */
+export function fixClaudeCodeHooksAllScopes(cwd, homeDir) {
+    const candidates = [
+        path.join(homeDir, '.claude', 'settings.json'),
+        path.join(homeDir, '.claude', 'settings.local.json'),
+        path.join(cwd, '.claude', 'settings.json'),
+        path.join(cwd, '.claude', 'settings.local.json'),
+    ];
+    const seen = new Set();
+    const results = [];
+    for (const candidate of candidates) {
+        const resolved = path.resolve(candidate);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        results.push(fixClaudeCodeHooksInFile(resolved));
+    }
+    return results;
+}
 export function ensureProjectDevDependency(cwd) {
     const filePath = path.join(cwd, 'package.json');
     if (!fs.existsSync(filePath))
@@ -1242,10 +1334,8 @@ export function ensureClaudeCodeSettings(cwd) {
     // binary resolution succeeded (hidden by 2>/dev/null).
     const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
     const bclawBin = getBclawCliParts().map(quoteShellArg).join(' ');
-    const sessionCommand = `f=.claude/.bclaw-session; if [ ! -f "$f" ]; then touch "$f"; ${bclawBin} session-start --include-context 2>/dev/null; else ${bclawBin} context-diff 2>/dev/null; fi`;
-    const stopCommand = `rm -f .claude/.bclaw-session; ${bclawBin} session-end --auto-release --reflect --reflect-handoff --dispatch-review 2>/dev/null`;
     // PostToolUse — check for unseen events after any brainclaw MCP tool call
-    const checkEventsCommand = `${bclawBin} check-events 2>/dev/null`;
+    const { session: sessionCommand, stop: stopCommand, checkEvents: checkEventsCommand } = buildClaudeCodeHookCommands(bclawBin);
     hooks.UserPromptSubmit = replaceBrainclawHooks(Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [], buildCommandHookEntry(sessionCommand));
     hooks.Stop = replaceBrainclawHooks(Array.isArray(hooks.Stop) ? hooks.Stop : [], buildCommandHookEntry(stopCommand));
     hooks.PostToolUse = replaceBrainclawHooks(Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [], buildMatchedCommandHookEntry('mcp__brainclaw__', checkEventsCommand));

package/dist/core/agent-registry.js

@@ -314,6 +314,18 @@ export function resolveCurrentAgentIdentity(cwd, preferredDirName, _homeDir) {
     // In multi-agent setups this always resolves to the wrong agent.
     // The field remains in config for display (status, doctor) and for resolveExistingCurrentAgent
     // which is used during setup/init only.
+    // Single-registered-agent fallback (pln#596). When there is NO identity signal
+    // at all — no env id/name AND no detected native agent — but exactly one agent
+    // is registered in this scope, resolving it is unambiguous. This is the
+    // solo-dev / single-CLI case (a fresh hook with no BRAINCLAW_AGENT_NAME). The
+    // pln#562 guard against config.current_agent only matters at ≥2 agents, so this
+    // preserves multi-agent safety: ≥2 registered → still falls through to undefined.
+    if (!envAgentId && !envAgentName && !detected) {
+        const registered = listAgentIdentities(cwd, preferredDirName);
+        if (registered.length === 1) {
+            return registered[0];
+        }
+    }
     return undefined;
 }
 export function resolveRegisteredAgentIdentity(options = {}) {
@@ -416,7 +428,10 @@ export function requireRegisteredAgentIdentity(options = {}) {
             throw new AgentIdentityResolutionError(`Environment agent '${normalizedEnv}' is not registered.`, { agent_name: normalizedEnv });
         }
     }
-    throw new AgentIdentityResolutionError('No registered agent identity resolved. Use --agent/--agent-id or configure a current agent with `brainclaw register-agent <name> --set-current`.');
+    throw new AgentIdentityResolutionError('No registered agent identity resolved. Pass `--agent <name>` or `--agent-id <id>`, '
+        + 'set $BRAINCLAW_AGENT_NAME, or register an agent with `brainclaw register-agent <name>` '
+        + '— a single registered agent is then resolved automatically. '
+        + '(`--set-current` alone does NOT affect resolution.)');
 }
 /**
  * Resolve agent identity for session start, returning both the resolved identity and whether

package/dist/core/hook-log.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Append a one-line, timestamped diagnostic to ~/.brainclaw/hook.log.
+ *
+ * brainclaw session hooks (UserPromptSubmit / Stop) historically wrapped every
+ * CLI call in `2>/dev/null`, which turned an actionable failure (e.g. "no
+ * registered agent identity resolved") into a contentless "hook error: No
+ * stderr output" on every prompt (trp#917). Hook-mode commands now degrade to
+ * exit 0 and drop a line here instead, so the failure is silent to the agent's
+ * prompt loop but still debuggable.
+ *
+ * Best-effort and never throws — a logging failure must not break a hook.
+ */
+const MAX_LOG_BYTES = 256 * 1024;
+export function hookLogPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.brainclaw', 'hook.log');
+}
+export function logHookDiagnostic(message, homeDir = os.homedir()) {
+    try {
+        const file = hookLogPath(homeDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        // Size-cap: when the log grows past the cap, keep only the tail so it never
+        // balloons unbounded across thousands of prompts.
+        try {
+            const stat = fs.statSync(file);
+            if (stat.size > MAX_LOG_BYTES) {
+                const tail = fs.readFileSync(file, 'utf-8').slice(-Math.floor(MAX_LOG_BYTES / 2));
+                fs.writeFileSync(file, tail, 'utf-8');
+            }
+        }
+        catch {
+            /* no existing file — nothing to truncate */
+        }
+        const line = `${new Date().toISOString()} ${message.replace(/\s+/g, ' ').trim()}\n`;
+        fs.appendFileSync(file, line, 'utf-8');
+    }
+    catch {
+        /* best-effort — never break a hook over logging */
+    }
+}
+//# sourceMappingURL=hook-log.js.map

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.11.0 on 2026-06-24T07:26:01.488Z
+// Source: brainclaw v1.12.0 on 2026-06-27T13:47:04.254Z
 export const FACTS = {
-  "version": "1.11.0",
-  "generated_at": "2026-06-24T07:26:01.488Z",
+  "version": "1.12.0",
+  "generated_at": "2026-06-27T13:47:04.254Z",
   "tools": {
     "count": 67,
     "published_count": 66,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.11.0",
-  "generated_at": "2026-06-24T07:26:01.488Z",
+  "version": "1.12.0",
+  "generated_at": "2026-06-27T13:47:04.254Z",
   "tools": {
     "count": 67,
     "published_count": 66,

package/docs/cli.md

@@ -264,14 +264,18 @@ Run health checks on config, state, and generated views.
 | `--json` | Output as JSON |
 | `--migration-check` | Check for pending migrations |
 | `--fix-agent-ignore` | Add missing `.gitignore` entries for generated local Brainclaw agent files |
+| `--fix-hooks` | Purge stale/broken/duplicate brainclaw session hooks across all Claude Code settings scopes (user + cwd) and rewrite the canonical ones |
 
 ```bash
 brainclaw doctor
 brainclaw doctor --json
 brainclaw doctor --migration-check
 brainclaw doctor --fix-agent-ignore
+brainclaw doctor --fix-hooks
 ```
 
+`--fix-hooks` collapses every recognized brainclaw session hook (across `UserPromptSubmit` / `Stop` / `PostToolUse`) in `~/.claude/settings.json`, `~/.claude/settings.local.json`, `<cwd>/.claude/settings.json`, and `<cwd>/.claude/settings.local.json` down to a single canonical entry, repairing legacy/broken forms. It only touches files (and events) that already contain a brainclaw hook, so user-authored hooks and hook-less scopes are left untouched. Use it when you see repeated `UserPromptSubmit hook error` warnings.
+
 When Brainclaw detects generated local agent files such as `.mcp.json` or `.claude/settings.local.json` inside a Git repo, `doctor` warns if they are not ignored or are still tracked. `--fix-agent-ignore` only updates `.gitignore`; if a file is already tracked you still need to untrack it with `git rm --cached <path>`.
 
 In `multi-project` mode with `projects.strategy: folder`, `doctor` now checks the effective workspace project set, not just `config.projects.known`. That avoids false positives on workspaces that resolve child stores from the filesystem or global project registry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {