brainclaw 1.11.0 → 1.11.1

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/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.11.1 on 2026-06-24T13:31:04.040Z
 export const FACTS = {
-  "version": "1.11.0",
-  "generated_at": "2026-06-24T07:26:01.488Z",
+  "version": "1.11.1",
+  "generated_at": "2026-06-24T13:31:04.040Z",
   "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.11.1",
+  "generated_at": "2026-06-24T13:31:04.040Z",
   "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.11.1",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {