brainclaw 0.28.0 → 1.5.3

package/dist/core/agent-integrations.js

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getInstalledBrainclawVersion } from './brainclaw-version.js';
+import { getAgentCapabilityProfile } from './agent-capability.js';
 const SUPPORTED_AGENT_INTEGRATION_NAMES = new Set([
     'github-copilot',
     'claude-code',
@@ -12,6 +15,7 @@ const SUPPORTED_AGENT_INTEGRATION_NAMES = new Set([
     'antigravity',
     'continue',
     'roo',
+    'kilocode',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
@@ -21,49 +25,69 @@ const SUPPORTED_AGENT_INTEGRATION_NAMES = new Set([
 const DEFAULT_SURFACES = {
     'github-copilot': [
         { kind: 'instructions', location: 'workspace', path: '.github/copilot-instructions.md' },
+        { kind: 'hook', location: 'workspace', path: '.github/copilot/hooks.json' },
+        { kind: 'mcp', location: 'workspace', path: '.vscode/settings.json' },
         { kind: 'skill', location: 'workspace', path: '.github/skills/brainclaw-context/SKILL.md' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'claude-code': [
         { kind: 'instructions', location: 'workspace', path: 'CLAUDE.md' },
+        { kind: 'hook', location: 'machine', path: '.claude/settings.local.json' },
         { kind: 'mcp', location: 'workspace', path: '.mcp.json' },
         { kind: 'skill', location: 'workspace', path: '.claude/commands/brainclaw.md' },
     ],
     'cursor': [
         { kind: 'instructions', location: 'workspace', path: '.cursor/rules/brainclaw.md' },
         { kind: 'rule', location: 'workspace', path: '.cursor/rules/brainclaw-mcp-shim.mdc' },
+        { kind: 'hook', location: 'workspace', path: '.cursor/hooks.json' },
         { kind: 'mcp', location: 'machine', path: '.cursor/mcp.json' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'windsurf': [
         { kind: 'instructions', location: 'workspace', path: '.windsurfrules' },
         { kind: 'hook', location: 'workspace', path: '.windsurfrules' },
         { kind: 'mcp', location: 'machine', path: '.codeium/windsurf/mcp_config.json' },
+        { kind: 'rule', location: 'workspace', path: '.windsurf/rules/brainclaw.md' },
     ],
     'cline': [
         { kind: 'instructions', location: 'workspace', path: '.clinerules/brainclaw.md' },
+        { kind: 'hook', location: 'workspace', path: '.clinerules/brainclaw.md' },
         { kind: 'mcp', location: 'workspace', path: '.vscode/cline_mcp_settings.json' },
     ],
     'codex': [
         { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
+        { kind: 'hook', location: 'workspace', path: 'AGENTS.md' },
         { kind: 'mcp', location: 'machine', path: '.codex/config.toml' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'opencode': [
         { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
         { kind: 'mcp', location: 'workspace', path: 'opencode.json' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'antigravity': [
         { kind: 'instructions', location: 'workspace', path: 'GEMINI.md' },
         { kind: 'mcp', location: 'machine', path: '.gemini/antigravity/mcp_config.json' },
+        { kind: 'hook', location: 'machine', path: '.gemini/antigravity/hooks.json' },
     ],
     'continue': [
         { kind: 'instructions', location: 'workspace', path: '.continue/rules/brainclaw.md' },
         { kind: 'mcp', location: 'workspace', path: '.continue/config.json' },
+        { kind: 'permissions', location: 'machine', path: '.continue/permissions.yaml' },
     ],
     'roo': [
         { kind: 'instructions', location: 'workspace', path: '.roo/rules/brainclaw.md' },
         { kind: 'mcp', location: 'workspace', path: '.roo/mcp.json' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
+    ],
+    'kilocode': [
+        { kind: 'instructions', location: 'workspace', path: '.kilo/rules/brainclaw.md' },
+        { kind: 'mcp', location: 'workspace', path: '.kilo/mcp.json' },
+        { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'openclaw': [
         { kind: 'skill', location: 'machine', path: '.openclaw/workspace/skills/brainclaw/SKILL.md' },
+        { kind: 'mcp', location: 'machine', path: '.openclaw/mcp.json' },
     ],
     'nanoclaw': [
         { kind: 'skill', location: 'workspace', path: 'skills/nanoclaw/SKILL.md' },
@@ -100,6 +124,10 @@ export function buildAgentIntegrationDeclaration(agentName, declarationSource =
 export function isAgentIntegrationName(value) {
     return SUPPORTED_AGENT_INTEGRATION_NAMES.has(value);
 }
+let commandVersionProbeForTests;
+export function setCommandVersionProbeForTests(probe) {
+    commandVersionProbeForTests = probe;
+}
 function resolveDeclaredSurfacePath(surface, cwd, env) {
     if (!surface.path) {
         return undefined;
@@ -110,24 +138,151 @@ function resolveDeclaredSurfacePath(surface, cwd, env) {
     const homeDir = env.HOME?.trim() || env.USERPROFILE?.trim() || os.homedir();
     return path.join(homeDir, surface.path);
 }
-function surfaceExists(surface, cwd, env) {
+export function extractMcpCommandVal(agentName, expectedPath) {
+    let content;
+    try {
+        content = fs.readFileSync(expectedPath, 'utf-8');
+    }
+    catch {
+        return { is_valid: false };
+    }
+    if (expectedPath.endsWith('.toml')) {
+        const cmdMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)command\s*=\s*(["'])(.+?)\1/is);
+        const argsMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)args\s*=\s*\[(.+?)\]/is);
+        let args;
+        if (argsMatch) {
+            args = argsMatch[1]
+                .split(',')
+                .map(s => s.trim().replace(/^["']|["']$/g, '').replace(/\\\\/g, '\\'));
+        }
+        return {
+            command: cmdMatch ? cmdMatch[2].replace(/\\\\/g, '\\') : undefined,
+            args,
+            is_valid: true,
+        };
+    }
+    try {
+        const j = JSON.parse(content);
+        let cmd;
+        let args;
+        if (agentName === 'github-copilot') {
+            const mcpServers = j['github.copilot.chat.mcpServers'];
+            cmd = mcpServers?.brainclaw?.command;
+            args = mcpServers?.brainclaw?.args;
+        }
+        else if (agentName === 'continue') {
+            const servers = Array.isArray(j.mcpServers) ? j.mcpServers : [];
+            const bc = servers.find((s) => s && s.name === 'brainclaw');
+            cmd = bc?.command;
+            args = bc?.args;
+        }
+        else {
+            cmd = j.mcpServers?.brainclaw?.command;
+            args = j.mcpServers?.brainclaw?.args;
+        }
+        return {
+            command: typeof cmd === 'string' ? cmd : undefined,
+            args: Array.isArray(args) ? args.filter(a => typeof a === 'string') : undefined,
+            is_valid: true
+        };
+    }
+    catch {
+        return { is_valid: false };
+    }
+}
+function getCommandVersion(cmdPath, args) {
+    if (commandVersionProbeForTests) {
+        return commandVersionProbeForTests(cmdPath, args);
+    }
+    if (cmdPath === 'npx')
+        return null; // dynamic
+    try {
+        const isNode = cmdPath.endsWith('node') || cmdPath.endsWith('node.exe');
+        const spawnArgs = isNode && args && args[0] ? [args[0], '--version'] : ['--version'];
+        const res = spawnSync(cmdPath, spawnArgs, { encoding: 'utf-8', timeout: 2000 });
+        if (res.status === 0 && res.stdout) {
+            return res.stdout.trim();
+        }
+    }
+    catch { }
+    return null;
+}
+function surfaceExists(surface, cwd, env, agentName) {
     const expectedPath = resolveDeclaredSurfacePath(surface, cwd, env);
-    return {
+    const exists = expectedPath ? fs.existsSync(expectedPath) : false;
+    const result = {
         ...surface,
         expected_path: expectedPath,
-        exists: expectedPath ? fs.existsSync(expectedPath) : false,
+        exists,
     };
+    if (surface.kind === 'mcp' && exists && agentName && expectedPath) {
+        const { command, args, is_valid } = extractMcpCommandVal(agentName, expectedPath);
+        if (!is_valid) {
+            result.drift_message = `MCP config file is invalid JSON/TOML`;
+        }
+        else if (!command) {
+            result.drift_message = `MCP config file is missing 'brainclaw' command`;
+        }
+        else {
+            if (command !== 'npx' && !fs.existsSync(command) && !['brainclaw', 'node'].includes(path.basename(command).replace(/\.exe$/, ''))) {
+                result.drift_message = `MCP command points to a non-existent file: ${command}`;
+            }
+            else {
+                const expectedVersion = getInstalledBrainclawVersion();
+                const cmdVersion = getCommandVersion(command, args);
+                if (cmdVersion && cmdVersion !== expectedVersion) {
+                    result.drift_message = `MCP command version drift (found ${cmdVersion}, expected ${expectedVersion})`;
+                }
+            }
+        }
+    }
+    return result;
 }
 export function assessAgentIntegrationReadiness(config, cwd, env = process.env) {
     return (config.agent_integrations?.declarations ?? []).map((declaration) => {
-        const surfaces = declaration.surfaces.map((surface) => surfaceExists(surface, cwd, env));
+        const surfaces = declaration.surfaces.map((surface) => surfaceExists(surface, cwd, env, declaration.agent_name));
         const missingSurfaces = surfaces.filter((surface) => !surface.exists);
+        const driftingSurfaces = surfaces.filter((surface) => surface.drift_message != null);
+        let effectiveTier = 'tier-b';
+        const selfHealingGuidance = [];
+        const hasMissingMcpOrHook = missingSurfaces.some((s) => s.kind === 'mcp' || s.kind === 'hook');
+        const hasDriftingMcp = driftingSurfaces.some((s) => s.kind === 'mcp');
+        const profile = getAgentCapabilityProfile(declaration.agent_name);
+        if (!profile) {
+            effectiveTier = 'tier-c';
+            selfHealingGuidance.push(`Agent ${declaration.agent_name} lacks a known capability profile. Defaulting to Tier C.`);
+        }
+        else {
+            const isPrimaryTierA = profile.templateTier === 'A';
+            if (isPrimaryTierA) {
+                if (hasMissingMcpOrHook || hasDriftingMcp) {
+                    effectiveTier = 'tier-b';
+                    selfHealingGuidance.push(`Agent ${declaration.agent_name} is degraded to Tier B because MCP or hooks are missing/drifting. Run 'brainclaw doctor --fix' or check integrations.`);
+                }
+                else {
+                    effectiveTier = 'tier-a';
+                }
+            }
+            else {
+                effectiveTier = 'tier-b'; // Inherently Tier B because context relies on native rules
+                if (hasMissingMcpOrHook || hasDriftingMcp) {
+                    selfHealingGuidance.push(`Agent ${declaration.agent_name} is missing or drifting MCP or hook configurations. Run 'brainclaw doctor --fix'.`);
+                }
+            }
+        }
+        if (missingSurfaces.length === surfaces.length && surfaces.length > 0) {
+            effectiveTier = 'tier-c';
+            selfHealingGuidance.push(`Agent ${declaration.agent_name} has no configured surfaces and is falling back to compact Tier C behavior.`);
+        }
         return {
             agent_name: declaration.agent_name,
             declaration_source: declaration.declaration_source,
-            ready: missingSurfaces.length === 0,
+            ready: missingSurfaces.length === 0 && driftingSurfaces.length === 0,
             missing_surfaces: missingSurfaces,
+            drifting_surfaces: driftingSurfaces,
             surfaces,
+            effective_tier: effectiveTier,
+            self_healing_guidance: selfHealingGuidance,
         };
     });
 }

package/dist/core/agent-inventory.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { MEMORY_DIR } from './io.js';
+import { detectHostExecutionProfile, } from './execution-profile.js';
 function tryCommand(command, args, timeout = 5000) {
     try {
         const r = spawnSync(command, args, { encoding: 'utf-8', timeout, windowsHide: true });
@@ -327,6 +328,7 @@ export function buildAgentInventory(homeDir = os.homedir(), env = process.env) {
         schema_version: 1,
         generated_at: new Date().toISOString(),
         agents,
+        host_execution_profile: detectHostExecutionProfile({ env, platform: process.platform }),
     };
 }
 /**

package/dist/core/agent-profiles.js

@@ -0,0 +1,93 @@
+/**
+ * Agent profile system — load, list, and save reusable agent profiles.
+ *
+ * Profiles are YAML files in .brainclaw/agents/profiles/{name}.yaml
+ * that define a reusable agent invocation: prompt, invoke template,
+ * trust level, trigger mode, and optional scope.
+ *
+ * Built-in default profiles ship with the package in default-profiles/
+ * and are merged with user profiles (user overrides defaults).
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'yaml';
+import { AgentProfileSchema } from './schema.js';
+import { memoryDir } from './io.js';
+const PROFILES_DIR = path.join('agents', 'profiles');
+/** Directory containing built-in default profiles shipped with the package. */
+const DEFAULT_PROFILES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'default-profiles');
+/** Resolve the user profiles directory for a given cwd. */
+function profilesDir(cwd) {
+    return path.join(memoryDir(cwd), PROFILES_DIR);
+}
+/** Resolve the path to a specific user profile YAML file. */
+function profilePath(name, cwd) {
+    return path.join(profilesDir(cwd), `${name}.yaml`);
+}
+/** Read and validate all .yaml profiles from a directory. */
+function readProfilesFromDir(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter(f => f.endsWith('.yaml'))
+        .sort()
+        .map(f => {
+        const raw = fs.readFileSync(path.join(dir, f), 'utf-8');
+        const parsed = yaml.parse(raw);
+        return AgentProfileSchema.safeParse(parsed);
+    })
+        .filter(r => r.success)
+        .map(r => r.data);
+}
+/**
+ * Load a single agent profile by name.
+ * Checks user profiles first, then built-in defaults.
+ * Throws if the profile does not exist or fails validation.
+ */
+export function loadProfile(name, cwd = process.cwd()) {
+    // User profile takes priority
+    const userPath = profilePath(name, cwd);
+    if (fs.existsSync(userPath)) {
+        const raw = fs.readFileSync(userPath, 'utf-8');
+        return AgentProfileSchema.parse(yaml.parse(raw));
+    }
+    // Fall back to built-in default
+    const defaultPath = path.join(DEFAULT_PROFILES_DIR, `${name}.yaml`);
+    if (fs.existsSync(defaultPath)) {
+        const raw = fs.readFileSync(defaultPath, 'utf-8');
+        return AgentProfileSchema.parse(yaml.parse(raw));
+    }
+    throw new Error(`Profile not found: ${name} (checked ${userPath} and built-in defaults)`);
+}
+/**
+ * List all available agent profiles.
+ * Merges built-in defaults with user profiles. User profiles override defaults
+ * with the same name.
+ */
+export function listProfiles(cwd = process.cwd()) {
+    const defaults = readProfilesFromDir(DEFAULT_PROFILES_DIR);
+    const user = readProfilesFromDir(profilesDir(cwd));
+    // Index by name — user profiles override defaults
+    const merged = new Map();
+    for (const p of defaults)
+        merged.set(p.name, p);
+    for (const p of user)
+        merged.set(p.name, p);
+    return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Save an agent profile to disk.
+ * Creates the profiles directory if it doesn't exist.
+ */
+export function saveProfile(profile, cwd = process.cwd()) {
+    const validated = AgentProfileSchema.parse(profile);
+    const dir = profilesDir(cwd);
+    fs.mkdirSync(dir, { recursive: true });
+    const filepath = profilePath(validated.name, cwd);
+    fs.writeFileSync(filepath, yaml.stringify(validated), 'utf-8');
+    return filepath;
+}
+//# sourceMappingURL=agent-profiles.js.map

package/dist/core/agent-registry.js

@@ -2,10 +2,11 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isKnownAgent, getCapabilityProfile } from './agent-capability.js';
 import { detectAiAgent } from './ai-agent-detection.js';
 import { loadConfig, saveConfig } from './config.js';
 import { nowISO } from './ids.js';
-import { MEMORY_DIR, resolveEntityDir } from './io.js';
+import { MEMORY_DIR, memoryExists, resolveEntityDir } from './io.js';
 import { JsonStore } from './json-store.js';
 import { AgentIdentityDocumentSchema, } from './schema.js';
 import { logger } from './logger.js';
@@ -54,7 +55,7 @@ function agentStore(cwd, preferredDirName) {
         sort: (a, b) => a.created_at.localeCompare(b.created_at) || a.agent_name.localeCompare(b.agent_name),
     });
 }
-function normalizeAgentName(agentName) {
+export function normalizeAgentName(agentName) {
     return agentName.trim().toLowerCase();
 }
 function normalizeCapability(capability) {
@@ -168,6 +169,9 @@ export function registerAgentIdentity(input) {
         else if (normalizedCapabilities.length > 0) {
             updated = { ...updated, capabilities: mergeCapabilities(existing.capabilities ?? [], normalizedCapabilities) };
         }
+        if (input.contextProfile && existing.context_profile !== input.contextProfile) {
+            updated = { ...updated, context_profile: input.contextProfile };
+        }
         if (input.generateFingerprint) {
             updated = withIdentityKey(updated, input.env, true);
         }
@@ -180,11 +184,12 @@ export function registerAgentIdentity(input) {
         schema_version: 2,
         version: 1,
         agent_id: generateAgentId(),
-        agent_name: input.agentName.trim(),
+        agent_name: normalizeAgentName(input.agentName),
         created_at: nowISO(),
         kind: input.kind ?? 'unknown',
         trust_level: input.trustLevel ?? 'contributor',
         capabilities: normalizedCapabilities,
+        ...(input.contextProfile ? { context_profile: input.contextProfile } : {}),
     };
     if (input.generateFingerprint) {
         created = withIdentityKey(created, input.env, true);
@@ -192,7 +197,7 @@ export function registerAgentIdentity(input) {
     saveAgentIdentity(created, input.cwd, input.preferredDirName);
     return created;
 }
-export function resolveCurrentAgentIdentity(cwd, preferredDirName) {
+export function resolveCurrentAgentIdentity(cwd, preferredDirName, homeDir) {
     // env var takes priority over config — allows AI agent to self-identify
     const envAgentId = (process.env.BRAINCLAW_AGENT_ID ?? '').trim();
     const envAgentName = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT ?? '').trim();
@@ -206,25 +211,41 @@ export function resolveCurrentAgentIdentity(cwd, preferredDirName) {
         if (byEnvName)
             return byEnvName;
     }
-    // Auto-detect from native agent env vars (e.g. CLAUDECODE, CURSOR_TRACE_ID).
-    // Falls through to config if the detected agent is not registered.
-    const detected = detectAiAgent();
+    // Auto-detect from native agent env vars (e.g. CLAUDECODE, CURSOR_TRACE_ID, CODEX_THREAD_ID).
+    // If detected agent is not registered, auto-register it as trusted agent.
+    // This is the primary identification path for MCP servers and CLI hooks.
+    const detected = detectAiAgent(process.env, homeDir);
     if (detected) {
+        // If the detected name matches an explicit env var that was already tried
+        // and not found, don't auto-register — the caller expects a "not registered" error.
+        if (normalizeAgentName(detected.name) === normalizeAgentName(envAgentName)) {
+            return undefined;
+        }
         const byDetected = findAgentIdentityByName(detected.name, cwd, preferredDirName);
         if (byDetected)
             return byDetected;
-    }
-    // Config fallback (last resort — may not reflect the actual calling agent)
-    const config = loadConfig(cwd, preferredDirName);
-    if (config.current_agent_id) {
-        const byId = findAgentIdentityById(config.current_agent_id, cwd, preferredDirName);
-        if (byId) {
-            return byId;
+        // Auto-register detected agent so it's immediately usable.
+        // This avoids the "not registered" error for agents detected for the first time.
+        try {
+            const autoRegistered = registerAgentIdentity({
+                agentName: normalizeAgentName(detected.name),
+                kind: detected.kind,
+                trustLevel: detected.trust_level,
+                cwd,
+                preferredDirName,
+            });
+            logger.debug(`Auto-registered detected agent: ${detected.name} (${autoRegistered.agent_id})`);
+            return autoRegistered;
+        }
+        catch {
+            // Non-fatal: registration may fail if store is read-only
         }
     }
-    if (config.current_agent) {
-        return findAgentIdentityByName(config.current_agent, cwd, preferredDirName);
-    }
+    // config.current_agent is NOT used for identity resolution — it's a singleton global
+    // that gets overwritten by whichever agent last ran register-agent --set-current.
+    // 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.
     return undefined;
 }
 export function resolveRegisteredAgentIdentity(options = {}) {
@@ -285,13 +306,24 @@ export function requireRegisteredAgentIdentity(options = {}) {
     }
     if (agentName) {
         const resolved = findAgentIdentityByName(agentName, cwd, preferredDirName);
-        if (!resolved) {
-            throw new AgentIdentityResolutionError(`Agent '${agentName}' is not registered. Run \`brainclaw register-agent ${agentName}\`.`, { agent_name: agentName });
+        if (resolved)
+            return resolved;
+        // Auto-register if the agent is a known brainclaw-supported agent or declared in agent_integrations
+        const normalizedName = normalizeAgentName(agentName);
+        if (isKnownAgent(normalizedName) || isAgentDeclaredInIntegrations(normalizedName, cwd)) {
+            const autoRegistered = registerAgentIdentity({
+                agentName: normalizedName,
+                kind: 'agent',
+                trustLevel: 'contributor',
+                cwd,
+                preferredDirName,
+            });
+            return autoRegistered;
         }
-        return resolved;
+        throw new AgentIdentityResolutionError(`Agent '${normalizedName}' is not registered. Run \`brainclaw register-agent ${normalizedName}\`.`, { agent_name: normalizedName });
     }
     const current = options.allowCurrent !== false
-        ? resolveCurrentAgentIdentity(cwd, preferredDirName)
+        ? resolveCurrentAgentIdentity(cwd, preferredDirName, options.homeDir)
         : undefined;
     if (current) {
         return current;
@@ -300,14 +332,111 @@ export function requireRegisteredAgentIdentity(options = {}) {
         const envAgent = resolveEnvAgentName(env);
         if (envAgent) {
             const resolved = findAgentIdentityByName(envAgent, cwd, preferredDirName);
-            if (!resolved) {
-                throw new AgentIdentityResolutionError(`Environment agent '${envAgent}' is not registered.`, { agent_name: envAgent });
+            if (resolved)
+                return resolved;
+            // Auto-register env-declared agent if known or declared in agent_integrations
+            const normalizedEnv = normalizeAgentName(envAgent);
+            if (isKnownAgent(normalizedEnv) || isAgentDeclaredInIntegrations(normalizedEnv, cwd)) {
+                return registerAgentIdentity({
+                    agentName: normalizedEnv,
+                    kind: 'agent',
+                    trustLevel: 'contributor',
+                    cwd,
+                    preferredDirName,
+                });
             }
-            return resolved;
+            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`.');
 }
+/**
+ * Resolve agent identity for session start, returning both the resolved identity and whether
+ * it was auto-registered (did not exist before this call).
+ *
+ * Unlike `requireRegisteredAgentIdentity`, this never throws for unknown agents — it will
+ * auto-register any resolvable name (from args or env) with contributor trust level.
+ * This implements the "separate known agent from current agent" principle: starting a session
+ * never requires prior registration.
+ *
+ * Throws only when no agent name can be derived at all.
+ */
+export function resolveOrAutoRegisterAgentIdentity(options = {}) {
+    const existingBefore = resolveRegisteredAgentIdentity(options);
+    try {
+        const identity = requireRegisteredAgentIdentity(options);
+        return { identity, auto_registered: !existingBefore };
+    }
+    catch (err) {
+        if (!(err instanceof AgentIdentityResolutionError))
+            throw err;
+        // Last-resort: derive a name from explicit arg or env and auto-register.
+        // This allows session_start to succeed even for agents not yet registered.
+        const candidateName = options.agentName?.trim()
+            || (options.allowEnv !== false ? resolveEnvAgentName(options.env ?? process.env) : undefined);
+        if (!candidateName)
+            throw err;
+        const normalizedName = normalizeAgentName(candidateName);
+        const registered = registerAgentIdentity({
+            agentName: normalizedName,
+            kind: 'agent',
+            trustLevel: 'contributor',
+            cwd: options.cwd,
+            preferredDirName: options.preferredDirName,
+        });
+        return { identity: registered, auto_registered: true };
+    }
+}
+/**
+ * Ensure that a target agent is registered in the current project before dispatch.
+ *
+ * If the agent is already registered, returns the existing identity.
+ * If not registered but has a known capability profile with canBeSpawnedCli=true,
+ * auto-registers it as a contributor agent with source='dispatch-auto-register'.
+ *
+ * Returns the identity, or undefined if the agent is unknown/not spawnable.
+ */
+export function ensureAgentRegisteredForDispatch(agentName, cwd) {
+    const normalized = normalizeAgentName(agentName);
+    // Already registered? Return as-is.
+    const existing = findAgentIdentityByName(normalized, cwd);
+    if (existing)
+        return existing;
+    // Check capability profile — only auto-register agents we know about
+    const profile = getCapabilityProfile(normalized);
+    if (!profile || !profile.runtime.canBeSpawnedCli)
+        return undefined;
+    // Auto-register with contributor trust
+    try {
+        const registered = registerAgentIdentity({
+            agentName: normalized,
+            kind: 'agent',
+            trustLevel: 'contributor',
+            capabilities: profile.role_capabilities ?? [],
+            cwd,
+        });
+        logger.debug(`Auto-registered agent for dispatch: ${normalized} (${registered.agent_id})`);
+        return registered;
+    }
+    catch {
+        // Non-fatal: store may be read-only
+        return undefined;
+    }
+}
+/**
+ * Check whether an agent name is declared in the project's agent_integrations config.
+ */
+function isAgentDeclaredInIntegrations(normalizedName, cwd) {
+    if (!memoryExists(cwd))
+        return false;
+    try {
+        const cfg = loadConfig(cwd);
+        return (cfg.agent_integrations?.declarations ?? []).some((d) => normalizeAgentName(d.agent_name) === normalizedName);
+    }
+    catch {
+        return false;
+    }
+}
 export function resolveAgentScope(agentName, cwd, preferredDirName) {
     const explicit = agentName?.trim();
     if (explicit) {
@@ -331,17 +460,20 @@ export function resolveCurrentModel(cwd) {
 /**
  * Returns the name of the current agent, with priority:
  *  1. $BRAINCLAW_AGENT_NAME env var  (AI agent self-declaration)
- *  2. $BRAINCLAW_AGENT      env var  (legacy alias)
- *  3. config.current_agent           (project owner / human default)
+ *  2. $BRAINCLAW_AGENT      env var  (legacy alias / relay model)
+ *  3. detectAiAgent()                (auto-detection from process env vars)
  *  4. OS user                        (last-resort fallback)
+ *
+ * Note: config.current_agent is intentionally NOT used here — it's a singleton
+ * global that causes cross-agent confusion in multi-agent setups.
  */
-export function resolveCurrentAgentName(cwd) {
+export function resolveCurrentAgentName(cwd, homeDir) {
     const fromEnv = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT)?.trim();
     if (fromEnv)
         return fromEnv;
-    const fromConfig = loadConfig(cwd).current_agent?.trim();
-    if (fromConfig)
-        return fromConfig;
+    const detected = detectAiAgent(process.env, homeDir);
+    if (detected)
+        return detected.name;
     return process.env.USER ?? process.env.USERNAME ?? 'unknown';
 }
 export function requireOperationalAgentIdentity(agentName, cwd, preferredDirName) {