brainclaw 1.9.0 → 1.10.0

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

@@ -6,7 +6,7 @@ import { buildContext } from '../core/context.js';
 import { buildExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
 import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
-import { loadAllSessions, loadCurrentSession, saveCurrentSession, gcStaleSessions } from '../core/identity.js';
+import { loadAllSessions, loadCurrentSession, loadSessionById, saveCurrentSession, gcStaleSessions } from '../core/identity.js';
 import { loadState } from '../core/state.js';
 import { listArchivedCandidates, listCandidates, resolvedSource } from '../core/candidates.js';
 import { listClaims, assessClaimLiveness } from '../core/claims.js';
@@ -27,13 +27,13 @@ import { checkPolicy } from '../core/policy.js';
 import { buildGovernanceReport, renderGovernanceMarkdown } from '../core/governance.js';
 import { inferProjectFromTarget, loadInstructions, resolveInstructions } from '../core/instructions.js';
 import { buildReputationSnapshot, toPublicReputationSummary } from '../core/reputation.js';
-import { search } from '../core/search.js';
+import { countLegacySearchMatches, search } from '../core/search.js';
 import { buildEstimationReport } from './estimation-report.js';
 import { runDoctor } from './doctor.js';
 import { buildProjectDiscovery, saveDiscoveryProfile, loadDiscoveryProfile, renderDiscoverySummary } from '../core/project-discovery.js';
 import { listCapabilities, listTools as listRegistryTools } from '../core/registries.js';
-import { listAvailableProjects, switchProject } from './switch.js';
-import { resolveEffectiveCwd } from '../core/store-resolution.js';
+import { listAvailableProjectsForSession, switchProject } from './switch.js';
+import { resolveEffectiveCwdInfo } from '../core/store-resolution.js';
 import { resolveProjectCwd } from '../core/cross-project.js';
 import { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
 import { boundListResult, DEFAULT_FIND_CHAR_BUDGET } from '../core/entity-operations.js';
@@ -100,9 +100,12 @@ function getReviewAssignee(tags) {
 }
 export function handleMcpReadToolCall(name, args = {}, context = {}) {
     const baseCwd = context.cwd ?? process.cwd();
-    let cwd = name === 'bclaw_switch'
-        ? baseCwd
-        : resolveEffectiveCwd({ baseCwd });
+    const effective = name === 'bclaw_switch'
+        ? { cwd: baseCwd, active_source: 'cwd', resolved_project: undefined }
+        : context.effectiveScope ?? resolveEffectiveCwdInfo({ baseCwd, sessionId: context.connectionSessionId });
+    let cwd = effective.cwd;
+    let activeSource = effective.active_source;
+    let resolvedProject = effective.resolved_project;
     // If a project param is provided, resolve it to an actual cwd override.
     // resolveProjectCwd unifies cross_project_links (siblings/peers) AND
     // workspace store-chain children. Throws on unknown project — surfaces
@@ -115,6 +118,14 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     let projectRoutingApplied = false;
     if (targetProjectArg) {
         cwd = resolveProjectCwd(targetProjectArg, cwd);
+        activeSource = 'explicit';
+        try {
+            const config = loadConfig(cwd);
+            resolvedProject = { path: cwd, name: config.project_name };
+        }
+        catch {
+            resolvedProject = { path: cwd };
+        }
         projectRoutingApplied = true;
     }
     if (name === 'bclaw_get_context') {
@@ -631,13 +642,25 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         }
         const offset = Math.max(0, Number(args.offset) || 0);
         const limit = typeof args.limit === 'number' ? args.limit : 10;
+        const includeLegacy = args.includeLegacy === true || (typeof args.filter === 'object' && args.filter?.includeLegacy === true);
         const allResults = search({
             query,
             section: (args.section ?? args.type),
             since: args.since,
-            maxResults: offset + limit,
+            maxResults: Number.MAX_SAFE_INTEGER,
+            includeLegacy,
             cwd,
         });
+        const excludedLegacy = includeLegacy
+            ? 0
+            : countLegacySearchMatches({
+                query,
+                section: (args.section ?? args.type),
+                since: args.since,
+                maxResults: offset + limit,
+                includeLegacy: true,
+                cwd,
+            });
         const total = allResults.length;
         const page = allResults.slice(offset, offset + limit);
         // trp#449 class — bound the page by size (pln#542). budget_tokens tightens
@@ -647,16 +670,34 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         const bounded = boundListResult({ entity: 'search_result', total, items: page }, offset, charBudget);
         const lines = bounded.items.map((result) => `[${result.id}] (${result.section}) score=${result.score.toFixed(2)}: ${result.text.slice(0, 120)}`);
         const nextActions = bounded.has_more
-            ? [{ tool: 'bclaw_search', args: { query, offset: bounded.next_offset, limit }, when: 'to fetch the next page' }]
+            ? [{
+                    tool: 'bclaw_search',
+                    args: {
+                        query,
+                        offset: bounded.next_offset,
+                        limit,
+                        ...(args.project ? { project: args.project } : {}),
+                        ...(args.section ? { section: args.section } : {}),
+                        ...(args.type ? { type: args.type } : {}),
+                        ...(args.since ? { since: args.since } : {}),
+                        ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}),
+                        ...(includeLegacy ? { includeLegacy: true } : {}),
+                    },
+                    when: 'to fetch the next page',
+                }]
             : [];
+        const legacyNote = excludedLegacy > 0 ? ` (${excludedLegacy} legacy result(s) excluded; pass includeLegacy=true to include them)` : '';
         return {
-            content: [{ type: 'text', text: bounded.items.length > 0 ? lines.join('\n') : 'No results found.' }],
+            content: [{ type: 'text', text: bounded.items.length > 0 ? `${lines.join('\n')}${legacyNote}` : `No results found.${legacyNote}` }],
             structuredContent: {
                 total,
                 offset,
                 limit,
                 results: bounded.items,
                 returned: bounded.returned,
+                excluded_legacy: excludedLegacy,
+                resolved_project: resolvedProject ?? { path: cwd },
+                active_source: activeSource,
                 has_more: bounded.has_more,
                 ...(bounded.next_offset !== undefined ? { next_offset: bounded.next_offset } : {}),
                 ...(bounded.omitted_for_size ? { omitted_for_size: bounded.omitted_for_size } : {}),
@@ -1034,7 +1075,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             }
             catch { /* defensive: never block events query on reconcile failure */ }
         }
-        let events = queryRuntimeEvents({
+        const events = queryRuntimeEvents({
             ...(id ? { id } : {}),
             ...(assignmentId ? { assignment_id: assignmentId } : {}),
             ...(runId ? { run_id: runId } : {}),
@@ -1422,7 +1463,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     if (name === 'bclaw_switch') {
         if (args.list === true) {
             try {
-                const result = listAvailableProjects(cwd);
+                const result = listAvailableProjectsForSession(cwd, context.connectionSessionId);
                 const lines = result.projects.map(p => {
                     const marker = p.active ? '→' : ' ';
                     const label = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
@@ -1439,7 +1480,9 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         }
         if (args.clear === true) {
             try {
-                const session = loadCurrentSession(cwd);
+                const session = context.connectionSessionId
+                    ? loadSessionById(context.connectionSessionId, cwd)
+                    : loadCurrentSession(cwd);
                 if (session?.active_project) {
                     const { active_project: _removed, ...rest } = session;
                     saveCurrentSession(rest, cwd);
@@ -1458,7 +1501,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             return createToolErrorResponse('validation_error', 'Missing required argument: project (or use list=true / clear=true)');
         }
         try {
-            const result = switchProject(projectRef, { cwd, sessionOnly: true });
+            const result = switchProject(projectRef, { cwd, sessionOnly: true, sessionId: context.connectionSessionId });
             const text = `✔ Switched to ${result.name ? `"${result.name}"` : result.path} (${result.scope}-scoped)`;
             return {
                 content: [{ type: 'text', text }],

package/dist/commands/mcp.js

@@ -39,7 +39,7 @@ 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, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
+import { resolveEffectiveCwd, resolveEffectiveCwdInfo, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.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';
@@ -48,6 +48,7 @@ import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatc
 import { deleteMemoryItem, updateMemoryItem } from '../core/operations/memory-mutation.js';
 import { assessMemoryPressure, buildCompactionTemplate, applyCompaction } from '../core/gc-semantic.js';
 import { WorkRequestSchema, CoordinateRequestSchema } from '../core/facade-schema.js';
+import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
 import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
@@ -167,6 +168,8 @@ export const MCP_READ_TOOLS = [
                 type: { type: 'string', description: 'Filter by section: decisions, constraints, traps, handoffs, candidates, plans, sequences.' },
                 section: { type: 'string', description: 'Filter by section (state, candidates, runtime).' },
                 since: { type: 'string', description: 'Filter items created after this ISO date.' },
+                project: { type: 'string', description: 'Optional project name/path to search. Defaults to the active project.' },
+                includeLegacy: { type: 'boolean', description: 'Include records with provenance.kind="legacy" (default false). Response reports excluded_legacy when false.' },
                 limit: { type: 'number', description: 'Maximum number of results to return (default 10).' },
                 offset: { type: 'number', description: 'Number of results to skip (for pagination).' },
                 budget_tokens: { type: 'number', description: 'Optional token budget for the result page (~4 chars/token). The page is size-bounded; has_more/next_offset advertise the rest.' },
@@ -447,8 +450,54 @@ export const MCP_READ_TOOLS = [
             required: ['target_id'],
         },
     },
+    {
+        name: 'bclaw_code_status',
+        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'bclaw_code_find',
+        description: 'Search the Code Map symbol index for a query (function/class/component/hook/type names). Returns ranked matches with path + score, plus a freshness_badge from the lazy read-path check. Read-only; never refreshes — a missing_index badge means run bclaw_code_refresh first.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Symbol or token to search for (e.g. "App", "useAuth", "dispatch").' },
+                limit: { type: 'number', description: 'Max matches to return.' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'bclaw_code_brief',
+        description: 'Before editing, ask Code Map what to read: returns a ranked suggested_files_to_read list (cap 12) for a symbol or path, related brainclaw memory (cap 5), and a freshness_badge. Read-only; never refreshes.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or file path to build a reading brief for.' },
+                limit: { type: 'number', description: 'Max suggested files (hard-capped at 12 by the spec).' },
+            },
+            required: ['target'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
+    {
+        name: 'bclaw_code_refresh',
+        description: 'Rebuild the Code Map index for this project (Tree-sitter parse + shards + indexes, behind the per-project lock). scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. A live competing lock fails fast with a clear status — refresh never blocks. Returns the resulting freshness_badge.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['changed', 'all'], description: 'changed (default) reparses changed files only; all does a full refresh with orphan compaction.' },
+            },
+        },
+    },
     {
         name: 'bclaw_dispatch',
         description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening new reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
@@ -1782,6 +1831,32 @@ function explicitSessionIdFromEnv() {
         || process.env.CLAUDE_SESSION_ID?.trim()
         || process.env.COPILOT_SESSION_ID?.trim();
 }
+function projectInfoForCwd(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        return { path: cwd, name: config.project_name };
+    }
+    catch {
+        return { path: cwd };
+    }
+}
+function scopeMetadataForTarget(args, targetCwd, effectiveScope) {
+    const hasExplicitProject = typeof args.project === 'string' && args.project.trim().length > 0;
+    return {
+        resolved_project: projectInfoForCwd(targetCwd),
+        active_source: hasExplicitProject ? 'explicit' : effectiveScope.active_source,
+    };
+}
+function renderProvenanceFilterNote(result) {
+    const parts = [];
+    if ((result.excluded_legacy ?? 0) > 0) {
+        parts.push(`${result.excluded_legacy} legacy item(s) excluded (pass filter.includeLegacy=true to include them)`);
+    }
+    if ((result.excluded_low_confidence_auto_reflect ?? 0) > 0) {
+        parts.push(`${result.excluded_low_confidence_auto_reflect} low-confidence auto_reflect item(s) excluded (lower filter.minAutoReflectConfidence to include them)`);
+    }
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
 export function parseMcpLine(line) {
     let parsed;
     try {
@@ -2557,6 +2632,11 @@ import { handleMcpReadToolCall } from './mcp-read-handlers.js';
 export { handleMcpReadToolCall };
 async function _executeMcpToolCallInner(payload) {
     const { name, args, cwd, connectionSessionId } = payload;
+    const scopeInfo = payload.effectiveScope ?? {
+        cwd,
+        active_source: 'cwd',
+        resolved_project: projectInfoForCwd(cwd),
+    };
     try {
         if (isLegacyMcpToolFacadeDisabled(name)) {
             return { response: createLegacyMcpToolDisabledResponse() };
@@ -2566,9 +2646,62 @@ async function _executeMcpToolCallInner(payload) {
             const { handleCheckSecurity } = await import('./check-security-mcp.js');
             return { response: toolResponse(await handleCheckSecurity(args, cwd)) };
         }
+        // Code Map tools (spec §9). These delegate to the async JsonlBackend, so
+        // they are handled here rather than via the synchronous read-tool path.
+        // status/find/brief are reads; refresh is a write (prompt approval).
+        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_refresh') {
+            const { JsonlBackend } = await import('../core/code-map/backend.js');
+            const be = new JsonlBackend();
+            if (name === 'bclaw_code_status') {
+                const status = await be.status({ cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.status}` }],
+                        structuredContent: { ...status, freshness_badge: status.freshness_badge },
+                    }),
+                };
+            }
+            if (name === 'bclaw_code_refresh') {
+                const scope = args.scope === 'all' ? 'all' : 'changed';
+                const result = await be.refresh({ scope, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.status}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            if (name === 'bclaw_code_find') {
+                const query = typeof args.query === 'string' ? args.query : '';
+                if (!query.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_find requires a non-empty query.') };
+                }
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.find({ query, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_brief
+            const target = typeof args.target === 'string' ? args.target : '';
+            if (!target.trim()) {
+                return { response: createToolErrorResponse('validation_error', 'bclaw_code_brief requires a non-empty target.') };
+            }
+            const limit = typeof args.limit === 'number' ? args.limit : undefined;
+            const result = await be.brief({ target, limit, cwd });
+            return {
+                response: toolResponse({
+                    content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.status}` }],
+                    structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                }),
+            };
+        }
         if (MCP_READ_TOOLS.some((tool) => tool.name === name) || LEGACY_READ_TOOL_HANDLERS.has(name)) {
             return {
-                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd })), name),
+                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name),
             };
         }
         // Resolve model once for all write operations
@@ -4821,6 +4954,26 @@ async function _executeMcpToolCallInner(payload) {
                 nextActions.push({ tool: 'bclaw_context', args: { kind: 'memory' }, when: 'to read the full changed items behind context_diff' });
             }
             nextActions.push({ tool: 'bclaw_quick_capture', args: { text: '<finding>', type: '<decision|trap|constraint|note>' }, when: 'capture decisions/traps as you work' });
+            // Code Map opt-in section (spec §10). Single live seam: returns null
+            // (and does no work) unless the project's Code Map manifest carries
+            // code_map_enabled:true. Never refreshes; bounded ≤2500ms on an active
+            // lock; surfaces a missing_index hint or stale results with the badge.
+            let codeMapSection = null;
+            try {
+                codeMapSection = await codeMapWorkSection(targetCwd, {
+                    query: workReq.scope ?? workReq.contextTarget,
+                });
+            }
+            catch {
+                // Best-effort: Code Map must never break or block bclaw_work.
+            }
+            // Code Map onboarding/freshness nudge (pln#588): promote the actionable
+            // refresh to a first-class next_action so a fresh or stale project's first
+            // bclaw_work TELLS the agent to build/update the index — the passive
+            // missing_index hint alone was easy to skip. Still never refreshes here.
+            for (const action of codeMapRefreshNextActions(codeMapSection)) {
+                nextActions.push(action);
+            }
             const facadeResponse = {
                 status: 'ok',
                 intent: workReq.intent,
@@ -4835,6 +4988,7 @@ async function _executeMcpToolCallInner(payload) {
                 bootstrap_verdict: bootstrapVerdict,
                 next_action: nextAction,
                 next_actions: nextActions,
+                ...(codeMapSection ? { code_map: codeMapSection } : {}),
             };
             const summaryParts = [`✔ bclaw_work [${workReq.intent}] session=${sessionResult.session_id}`];
             if (claimId)
@@ -6214,6 +6368,7 @@ async function _executeMcpToolCallInner(payload) {
             try {
                 const entity = String(args.entity ?? '');
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 // pln#460 follow-up — some MCP clients (notably Claude Code with a
                 // tool schema that declares `filter: { type: 'object' }` without a
                 // sub-property schema) stringify the filter object before shipping
@@ -6269,10 +6424,10 @@ async function _executeMcpToolCallInner(payload) {
                 const bounded = boundListResult(result, offset, charBudget);
                 const warnings = collectLoadValidationWarnings(entity, targetCwd);
                 const nextActions = [
-                    { tool: 'bclaw_get', args: { entity, id: '<id from items>' }, when: 'to read one item in full' },
+                    { tool: 'bclaw_get', args: { entity, id: '<id from items>', ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to read one item in full' },
                 ];
                 if (bounded.has_more) {
-                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset } }, when: 'to fetch the next page' });
+                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset }, ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to fetch the next page' });
                 }
                 // structuredContent is the canonical MCP return channel that clients
                 // (VS Code extension, Codex, etc.) read for machine-parseable data.
@@ -6281,10 +6436,20 @@ async function _executeMcpToolCallInner(payload) {
                 // `result.items` arrived as undefined on the client — the root cause
                 // of the VS Code Backlog section rendering empty.
                 const moreNote = bounded.has_more ? ` (returned ${bounded.returned}; ${result.total - bounded.returned} more — offset ${bounded.next_offset})` : '';
+                const provenanceFilterNote = renderProvenanceFilterNote(result);
+                const legacyNote = provenanceFilterNote
+                    ? `; ${provenanceFilterNote}`
+                    : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}` }],
-                        structuredContent: { ...bounded, warnings, next_actions: nextActions },
+                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}${legacyNote}` }],
+                        structuredContent: {
+                            ...bounded,
+                            warnings,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                            next_actions: nextActions,
+                        },
                     }),
                 };
             }
@@ -6361,6 +6526,7 @@ async function _executeMcpToolCallInner(payload) {
                 }
                 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
                 // GC'd from disk on the next mutation.
@@ -6392,7 +6558,11 @@ async function _executeMcpToolCallInner(payload) {
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ created ${entity} ${result.id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6406,13 +6576,18 @@ async function _executeMcpToolCallInner(payload) {
                 const id = String(args.id ?? '');
                 const patch = (args.patch ?? {});
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = updateEntity(entity, id, patch, targetCwd);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'update', item_id: id, item_type: entity }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ updated ${entity} ${id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6426,13 +6601,18 @@ async function _executeMcpToolCallInner(payload) {
                 const id = String(args.id ?? '');
                 const purge = args.purge === true;
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const targetScope = scopeMetadataForTarget(args, targetCwd, scopeInfo);
                 const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                 const result = removeEntity(entity, id, targetCwd, purge);
                 appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'delete', item_id: id, item_type: entity, reason: purge ? 'purged' : 'archived' }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ removed ${entity} ${id}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6454,13 +6634,18 @@ async function _executeMcpToolCallInner(payload) {
                 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}` }],
-                        structuredContent: { ...result },
+                        structuredContent: {
+                            ...result,
+                            resolved_project: targetScope.resolved_project,
+                            active_source: targetScope.active_source,
+                        },
                     }),
                 };
             }
@@ -6504,9 +6689,10 @@ async function _executeMcpToolCallInner(payload) {
  */
 export async function executeMcpToolCall(payload) {
     const baseCwd = payload.cwd;
-    const cwd = payload.name === 'bclaw_switch'
-        ? baseCwd
-        : resolveEffectiveCwd({ baseCwd });
+    const effective = payload.name === 'bclaw_switch'
+        ? { cwd: baseCwd, active_source: 'cwd', resolved_project: undefined }
+        : resolveEffectiveCwdInfo({ baseCwd, sessionId: payload.connectionSessionId });
+    const cwd = effective.cwd;
     const envClaimId = process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined;
     // ── Auto-session ────────────────────────────────────────────────────────────
     let autoSessionId;
@@ -6564,6 +6750,7 @@ export async function executeMcpToolCall(payload) {
         ...payload,
         cwd,
         connectionSessionId: effectiveConnectionSessionId,
+        effectiveScope: effective,
     });
     // Apply legacy deprecation warning uniformly (Phase 3 slice 3g). Read tools
     // already get it at line 2560; write tools historically did not. This

package/dist/commands/run-profile.js

@@ -37,8 +37,9 @@ export function runRunProfile(profileName, options = {}) {
             console.error(`Unknown agent: ${options.agent}. Using profile invoke template.`);
         }
     }
-    // Replace {prompt} placeholder with the profile prompt
-    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/"/g, '\\"'));
+    // Replace {prompt} placeholder with the profile prompt. Escape backslashes
+    // before quotes so a backslash in the prompt can't break out of the quoting.
+    const command = invoke.replace(/\{prompt\}/g, profile.prompt.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
     if (options.dry) {
         console.log(`[dry-run] Profile: ${profile.name}`);
         console.log(`[dry-run] Command: ${command}`);