@gracker/smartperfetto 1.0.14 → 1.0.16

package/dist/agentv3/claudeMcpServer.js

@@ -37,6 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_PHASE_SUMMARY_CHARS = exports.MCP_NAME_PREFIX = void 0;
+exports.normalizeOptionalToolString = normalizeOptionalToolString;
 exports.loadLearnedSqlFixPairs = loadLearnedSqlFixPairs;
 exports.createClaudeMcpServer = createClaudeMcpServer;
 const claude_agent_sdk_1 = require("@anthropic-ai/claude-agent-sdk");
@@ -73,6 +74,12 @@ const caseLibrary_1 = require("../services/caseLibrary");
 const scopedKnowledgeStore_1 = require("../services/scopedKnowledgeStore");
 const mcpToolRegistry_1 = require("./mcpToolRegistry");
 const runtimePaths_1 = require("../runtimePaths");
+const defaultCodebaseServices_1 = require("../services/codebase/defaultCodebaseServices");
+const codeLookupLedger_1 = require("../services/codebase/codeLookupLedger");
+const patchProposer_1 = require("../services/codebase/patchProposer");
+const codeAwareFeature_1 = require("../services/codebase/codeAwareFeature");
+const lookupResponseFilter_1 = require("../services/rag/lookupResponseFilter");
+const symbolResolver_1 = require("../services/symbol/symbolResolver");
 /**
  * Process-wide RagStore singleton, lazily initialized on first MCP tool
  * call. Backs the `lookup_blog_knowledge` tool (Plan 55) and will back
@@ -207,6 +214,18 @@ function parseOptionalToolArrayInput(value) {
     }
     return parseToolArrayInput(value);
 }
+function normalizeOptionalToolString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const normalized = trimmed.toLowerCase();
+    if (normalized === 'null' || normalized === 'undefined' || normalized === 'none') {
+        return undefined;
+    }
+    return trimmed;
+}
 function parseToolStringArrayInput(value) {
     if (Array.isArray(value)) {
         return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
@@ -618,6 +637,14 @@ function createClaudeMcpServer(options) {
     const skillNotesBudget = options.skillNotesBudget;
     const outputLanguage = options.outputLanguage ?? outputLanguage_1.DEFAULT_OUTPUT_LANGUAGE;
     const knowledgeScope = options.knowledgeScope;
+    const codeAwareMode = (0, codeAwareFeature_1.normalizeCodeAwareMode)(options.codeAwareMode);
+    const codebaseIds = Array.from(new Set(options.codebaseIds ?? [])).filter(Boolean);
+    const codebaseRegistry = options.codebaseRegistry ?? (0, defaultCodebaseServices_1.getDefaultCodebaseRegistry)();
+    const codeLookupLedger = options.codeLookupLedger ?? (options.sessionId ? codeLookupLedger_1.CodeLookupLedger.restore(options.sessionId, 12000, 2) : undefined);
+    const toolRequestScope = {
+        sessionId: options.sessionId ?? traceId,
+        hasCodebaseAccess: codeAwareMode !== 'off' && codebaseIds.length > 0,
+    };
     /** Normalize skill params: ensure process_name ↔ package are both set. */
     function normalizeSkillParams(params, defaultPackage) {
         const p = { ...params };
@@ -1410,7 +1437,7 @@ function createClaudeMcpServer(options) {
             if (summary && success && rows.length > 0) {
                 const summaryResult = (0, sqlSummarizer_1.summarizeSqlResult)(result.columns, result.rows);
                 if (emitUpdate) {
-                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer);
+                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer, processIdentityWarning);
                 }
                 return {
                     content: [{
@@ -1439,10 +1466,10 @@ function createClaudeMcpServer(options) {
                 };
             }
             if (emitUpdate && success && result.columns.length > 0) {
-                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer);
+                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer, processIdentityWarning);
             }
             else if (emitUpdate && !success) {
-                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer, outputLanguage);
+                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer, processIdentityWarning, outputLanguage);
             }
             return {
                 content: [{
@@ -1476,7 +1503,7 @@ function createClaudeMcpServer(options) {
                 traceId,
                 traceSide: 'current',
             });
-            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, errMsg, sql, undefined, traceProvenance, producer, outputLanguage) : undefined;
+            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, errMsg, sql, undefined, traceProvenance, producer, undefined, outputLanguage) : undefined;
             emitUpdate?.({
                 type: 'progress',
                 content: {
@@ -1588,6 +1615,10 @@ function createClaudeMcpServer(options) {
         try {
             const effectiveParams = normalizeSkillParams(params, packageName);
             const producer = createEvidenceProducerContext('invoke_skill', { skillId, params: effectiveParams }, (0, outputLanguage_1.localize)(outputLanguage, `调用 Skill ${skillId}，收集本阶段结构化证据。`, `Run Skill ${skillId} to collect structured evidence for this phase.`));
+            const skillTraceProvenance = (0, traceProcessorConnectionModel_1.buildTraceProcessorQueryProvenance)({
+                traceId,
+                traceSide: 'current',
+            });
             emitUpdate?.({
                 type: 'progress',
                 content: {
@@ -1622,8 +1653,82 @@ function createClaudeMcpServer(options) {
                 // Persist to disk (fire-and-forget) for cross-session learning
                 logSqlErrorFixPair(errorPair, knowledgeScope).catch(() => { });
             }
+            // Artifact mode stores displayResults before emitting DataEnvelopes so
+            // evidence meta can carry the same artifact ids that the model sees.
+            let artifacts;
+            let diagnosticsArtifactId;
+            let synthesizeArtifacts;
+            const artifactIdsByStepId = new Map();
+            if (artifactStore && result.displayResults?.length) {
+                artifacts = result.displayResults.map(dr => {
+                    const artId = artifactStore.store({
+                        skillId: result.skillId || skillId,
+                        stepId: dr.stepId,
+                        layer: dr.layer,
+                        title: dr.title,
+                        data: dr.data,
+                        diagnostics: undefined,
+                        planPhaseId: producer.planPhaseId,
+                        planPhaseTitle: producer.planPhaseTitle,
+                        planPhaseGoal: producer.planPhaseGoal,
+                        sourceToolCallId: producer.sourceToolCallId,
+                        paramsHash: producer.paramsHash,
+                        identityResolution: result.identityResolution,
+                    });
+                    if (dr.stepId)
+                        artifactIdsByStepId.set(dr.stepId, artId);
+                    const summary = artifactStore.generateCompactSummary(artId);
+                    return summary;
+                }).filter((summary) => Boolean(summary));
+            }
+            // Store diagnostics as a separate artifact if present, even for
+            // diagnostics-only skill results that do not emit displayResults.
+            if (artifactStore && result.diagnostics && Array.isArray(result.diagnostics) && result.diagnostics.length > 0) {
+                diagnosticsArtifactId = artifactStore.store({
+                    skillId: result.skillId || skillId,
+                    stepId: '_diagnostics',
+                    layer: 'diagnosis',
+                    title: `${skillId} diagnostics`,
+                    data: { columns: ['diagnostic'], rows: result.diagnostics.map((d) => [d]) },
+                    diagnostics: result.diagnostics,
+                    planPhaseId: producer.planPhaseId,
+                    planPhaseTitle: producer.planPhaseTitle,
+                    planPhaseGoal: producer.planPhaseGoal,
+                    sourceToolCallId: producer.sourceToolCallId,
+                    paramsHash: producer.paramsHash,
+                    identityResolution: result.identityResolution,
+                });
+            }
+            // Store synthesizeData entries as artifacts too — these contain the
+            // raw step data that would otherwise overflow token limits.
+            if (artifactStore && result.synthesizeData && Array.isArray(result.synthesizeData) && result.synthesizeData.length > 0) {
+                synthesizeArtifacts = result.synthesizeData
+                    .filter((sd) => sd.data && sd.success !== false)
+                    .map((sd) => {
+                    const normalizedData = normalizeSynthesizeDataForStorage(sd.data);
+                    const artId = artifactStore.store({
+                        skillId: result.skillId || skillId,
+                        stepId: sd.stepId,
+                        layer: sd.layer || 'synthesize',
+                        title: sd.stepName || sd.stepId,
+                        data: normalizedData,
+                        planPhaseId: producer.planPhaseId,
+                        planPhaseTitle: producer.planPhaseTitle,
+                        planPhaseGoal: producer.planPhaseGoal,
+                        sourceToolCallId: producer.sourceToolCallId,
+                        paramsHash: producer.paramsHash,
+                        identityResolution: result.identityResolution,
+                    });
+                    return {
+                        artifactId: artId,
+                        stepId: sd.stepId,
+                        rowCount: normalizedData.rows?.length ?? 0,
+                        columns: normalizedData.columns ?? [],
+                    };
+                });
+            }
             if (emitUpdate && result.displayResults?.length) {
-                emitSkillDataEnvelopes(result.displayResults, result.skillId || skillId, emitUpdate, undefined, producer);
+                emitSkillDataEnvelopes(result.displayResults, result.skillId || skillId, emitUpdate, skillTraceProvenance, producer, result.identityResolution, artifactIdsByStepId);
             }
             if (onSkillResult && result.success && result.displayResults?.length) {
                 onSkillResult({ skillId: result.skillId || skillId, displayResults: result.displayResults });
@@ -1661,72 +1766,9 @@ function createClaudeMcpServer(options) {
                     };
                 }
             }
-            // Artifact mode: store displayResults AND synthesizeData as artifacts, return compact references
-            if (artifactStore && result.displayResults?.length) {
-                const artifacts = result.displayResults.map(dr => {
-                    const artId = artifactStore.store({
-                        skillId: result.skillId || skillId,
-                        stepId: dr.stepId,
-                        layer: dr.layer,
-                        title: dr.title,
-                        data: dr.data,
-                        diagnostics: undefined,
-                        planPhaseId: producer.planPhaseId,
-                        planPhaseTitle: producer.planPhaseTitle,
-                        planPhaseGoal: producer.planPhaseGoal,
-                        sourceToolCallId: producer.sourceToolCallId,
-                        paramsHash: producer.paramsHash,
-                    });
-                    const summary = artifactStore.generateCompactSummary(artId);
-                    return summary;
-                });
-                // Store diagnostics as a separate artifact if present
-                let diagnosticsArtifactId;
-                if (result.diagnostics && Array.isArray(result.diagnostics) && result.diagnostics.length > 0) {
-                    diagnosticsArtifactId = artifactStore.store({
-                        skillId: result.skillId || skillId,
-                        stepId: '_diagnostics',
-                        layer: 'diagnosis',
-                        title: `${skillId} diagnostics`,
-                        data: { columns: ['diagnostic'], rows: result.diagnostics.map((d) => [d]) },
-                        diagnostics: result.diagnostics,
-                        planPhaseId: producer.planPhaseId,
-                        planPhaseTitle: producer.planPhaseTitle,
-                        planPhaseGoal: producer.planPhaseGoal,
-                        sourceToolCallId: producer.sourceToolCallId,
-                        paramsHash: producer.paramsHash,
-                    });
-                }
-                // Store synthesizeData entries as artifacts too — these contain the raw step data
-                // (e.g. batch_frame_root_cause with 487 rows) that would otherwise overflow token limits.
-                // Claude can fetch them on demand via fetch_artifact with pagination.
-                let synthesizeArtifacts;
-                if (result.synthesizeData && Array.isArray(result.synthesizeData) && result.synthesizeData.length > 0) {
-                    synthesizeArtifacts = result.synthesizeData
-                        .filter((sd) => sd.data && sd.success !== false)
-                        .map((sd) => {
-                        // synthesizeData entries have data as array-of-objects or { columns, rows }
-                        const normalizedData = normalizeSynthesizeDataForStorage(sd.data);
-                        const artId = artifactStore.store({
-                            skillId: result.skillId || skillId,
-                            stepId: sd.stepId,
-                            layer: sd.layer || 'synthesize',
-                            title: sd.stepName || sd.stepId,
-                            data: normalizedData,
-                            planPhaseId: producer.planPhaseId,
-                            planPhaseTitle: producer.planPhaseTitle,
-                            planPhaseGoal: producer.planPhaseGoal,
-                            sourceToolCallId: producer.sourceToolCallId,
-                            paramsHash: producer.paramsHash,
-                        });
-                        return {
-                            artifactId: artId,
-                            stepId: sd.stepId,
-                            rowCount: normalizedData.rows?.length ?? 0,
-                            columns: normalizedData.columns ?? [],
-                        };
-                    });
-                }
+            // Artifact mode: return compact references whenever any fetchable
+            // artifact was created.
+            if (artifactStore && (artifacts?.length || diagnosticsArtifactId || synthesizeArtifacts?.length)) {
                 return {
                     content: [{
                             type: 'text',
@@ -1735,6 +1777,7 @@ function createClaudeMcpServer(options) {
                                 skillId: result.skillId,
                                 skillName: result.skillName,
                                 ...(result.error ? { error: result.error } : {}),
+                                ...(result.identityResolution ? { identityResolution: result.identityResolution } : {}),
                                 artifacts,
                                 ...(diagnosticsArtifactId ? { diagnosticsArtifactId } : {}),
                                 ...(synthesizeArtifacts && synthesizeArtifacts.length > 0
@@ -1755,6 +1798,7 @@ function createClaudeMcpServer(options) {
                             skillId: result.skillId,
                             skillName: result.skillName,
                             ...(result.error ? { error: result.error } : {}),
+                            ...(result.identityResolution ? { identityResolution: result.identityResolution } : {}),
                             ...(vendorOverrideHint ? { vendorOverride: vendorOverrideHint } : {}),
                             displayResults: result.displayResults?.map(dr => ({
                                 stepId: dr.stepId,
@@ -2045,7 +2089,8 @@ function createClaudeMcpServer(options) {
             success: true,
             detail: effectiveDetail,
             ...result,
-            sourceToolCallId: producer.sourceToolCallId,
+            sourceToolCallId: result?.sourceToolCallId || producer.sourceToolCallId,
+            fetchedByToolCallId: producer.sourceToolCallId,
             paramsHash: producer.paramsHash,
             planPhaseId: producer.planPhaseId,
             planPhaseTitle: producer.planPhaseTitle,
@@ -2295,13 +2340,50 @@ function createClaudeMcpServer(options) {
         'When the result carries `unsupportedReason` (license_blocked, index empty), the agent must say the source is unavailable and must NOT summarize, paraphrase, or invent content.', {
         query: zod_1.z.string().describe('Search query — typically a function or class name, or a behavior description.'),
         top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
-    }, async ({ query, top_k }) => {
+        codebase_id: zod_1.z.string().optional().describe('Optional whitelisted registered AOSP codebase id.'),
+        build_id: zod_1.z.string().optional().describe('Optional native build id filter.'),
+        symbol: zod_1.z.string().optional().describe('Exact symbol filter when known.'),
+        path_prefix: zod_1.z.string().optional().describe('Optional relative source path prefix.'),
+    }, async ({ query, top_k, codebase_id, build_id, symbol, path_prefix }) => {
+        const codebaseId = normalizeOptionalToolString(codebase_id);
+        const buildId = normalizeOptionalToolString(build_id);
+        const symbolExact = normalizeOptionalToolString(symbol);
+        const pathPrefix = normalizeOptionalToolString(path_prefix);
+        if (codebaseId && !codebaseIds.includes(codebaseId)) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Requested codebase is not whitelisted for this session' }) }],
+                isError: true,
+            };
+        }
         const store = getRagStore();
         const result = store.search(query, {
             topK: top_k ?? 5,
             kinds: ['aosp'],
+            ...(codebaseId ? { codebaseIds: [codebaseId] } : {}),
+            ...(buildId ? { buildId } : {}),
+            ...(symbolExact ? { symbolExact } : {}),
+            ...(pathPrefix ? { pathPrefix } : {}),
             scope: knowledgeScope,
         });
+        if (result.results.some(hit => hit.chunk?.registryOrigin === 'codebase_registry')) {
+            const scopedResult = {
+                ...result,
+                results: result.results.filter(hit => hit.chunk?.registryOrigin !== 'codebase_registry' ||
+                    (hit.chunk.codebaseId && codebaseIds.includes(hit.chunk.codebaseId))),
+            };
+            const filtered = await (0, lookupResponseFilter_1.filterRagLookup)(scopedResult, {
+                toolName: 'lookup_aosp_source',
+                turn: 0,
+                codebaseRegistry,
+                ledger: codeLookupLedger,
+                allowProviderSend: codeAwareMode === 'provider_send',
+                sessionId: options.sessionId,
+            });
+            await codeLookupLedger?.flush();
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true, result: filtered }) }],
+            };
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
         };
@@ -2314,17 +2396,254 @@ function createClaudeMcpServer(options) {
         'Read-only over the RagStore. When the result carries `unsupportedReason` (license_blocked, index empty), the agent must say the source is unavailable and must NOT summarize or invent.', {
         query: zod_1.z.string().describe('Search query — typically a tuning concept or vendor-specific knob.'),
         top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
-    }, async ({ query, top_k }) => {
+        codebase_id: zod_1.z.string().optional().describe('Optional whitelisted registered OEM codebase id.'),
+        vendor: zod_1.z.string().optional().describe('Optional vendor filter.'),
+    }, async ({ query, top_k, codebase_id, vendor }) => {
+        const codebaseId = normalizeOptionalToolString(codebase_id);
+        const vendorId = normalizeOptionalToolString(vendor);
+        if (codebaseId && !codebaseIds.includes(codebaseId)) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'Requested codebase is not whitelisted for this session' }) }],
+                isError: true,
+            };
+        }
         const store = getRagStore();
         const result = store.search(query, {
             topK: top_k ?? 5,
             kinds: ['oem_sdk'],
+            ...(codebaseId ? { codebaseIds: [codebaseId] } : {}),
+            ...(vendorId ? { vendor: vendorId } : {}),
             scope: knowledgeScope,
         });
+        if (result.results.some(hit => hit.chunk?.registryOrigin === 'codebase_registry')) {
+            const scopedResult = {
+                ...result,
+                results: result.results.filter(hit => hit.chunk?.registryOrigin !== 'codebase_registry' ||
+                    (hit.chunk.codebaseId && codebaseIds.includes(hit.chunk.codebaseId))),
+            };
+            const filtered = await (0, lookupResponseFilter_1.filterRagLookup)(scopedResult, {
+                toolName: 'lookup_oem_sdk',
+                turn: 0,
+                codebaseRegistry,
+                ledger: codeLookupLedger,
+                allowProviderSend: codeAwareMode === 'provider_send',
+                sessionId: options.sessionId,
+            });
+            await codeLookupLedger?.flush();
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true, result: filtered }) }],
+            };
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
         };
     }, { annotations: { readOnlyHint: true } });
+    const listCodebases = (0, claude_agent_sdk_1.tool)('list_codebases', 'List the app/AOSP/kernel/OEM codebases explicitly whitelisted for this analysis session. ' +
+        'Returns metadata only; it never exposes local root paths.', {}, async () => {
+        const allowed = new Set(codebaseIds);
+        const codebases = codebaseRegistry.list()
+            .filter(ref => allowed.has(ref.codebaseId))
+            .map(ref => ({
+            codebaseId: ref.codebaseId,
+            kind: ref.kind,
+            displayName: ref.displayName,
+            indexGeneration: ref.indexGeneration,
+            chunkCount: ref.chunkCount,
+            eligibleForSendToProvider: ref.eligibleForSendToProvider,
+        }));
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: true, codebases }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    const lookupAppSource = (0, claude_agent_sdk_1.tool)('lookup_app_source', 'Look up registered app source chunks for this analysis session. ' +
+        'Only whitelisted codebase IDs are accepted. In metadata_only mode the result carries file/symbol references without snippets.', {
+        query: zod_1.z.string().describe('Natural-language query, symbol, class, method, or file term.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+        codebase_id: zod_1.z.string().optional().describe('Restrict to one whitelisted codebase id. Defaults to all session codebases.'),
+        symbol: zod_1.z.string().optional().describe('Exact symbol filter when known.'),
+        file_path: zod_1.z.string().optional().describe('Exact source file path relative to the registered root.'),
+        path_prefix: zod_1.z.string().optional().describe('Restrict lookup to a relative path prefix.'),
+    }, async ({ query, top_k, codebase_id, symbol, file_path, path_prefix }) => {
+        const codebaseId = normalizeOptionalToolString(codebase_id);
+        const symbolExact = normalizeOptionalToolString(symbol);
+        const filePath = normalizeOptionalToolString(file_path);
+        const pathPrefix = normalizeOptionalToolString(path_prefix);
+        const requestedIds = codebaseId ? [codebaseId] : codebaseIds;
+        const allowed = requestedIds.filter(id => codebaseIds.includes(id));
+        if (allowed.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: 'No requested codebase is whitelisted for this session' }),
+                    }],
+                isError: true,
+            };
+        }
+        const raw = getRagStore().search(query, {
+            topK: top_k ?? 5,
+            kinds: ['app_source'],
+            codebaseIds: allowed,
+            ...(symbolExact ? { symbolExact } : {}),
+            ...(filePath ? { filePathExact: filePath } : {}),
+            ...(pathPrefix ? { pathPrefix } : {}),
+            scope: knowledgeScope,
+        });
+        const filtered = await (0, lookupResponseFilter_1.filterRagLookup)(raw, {
+            toolName: 'lookup_app_source',
+            turn: 0,
+            codebaseRegistry,
+            ledger: codeLookupLedger,
+            allowProviderSend: codeAwareMode === 'provider_send',
+            sessionId: options.sessionId,
+        });
+        await codeLookupLedger?.flush();
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: true, result: filtered }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    const lookupKernelSource = (0, claude_agent_sdk_1.tool)('lookup_kernel_source', 'Use when kernel/vendor source evidence is needed after trace evidence points at binder, scheduler, mm, io, or a kernel symbol. ' +
+        'Do NOT use for app or AOSP framework code. Prerequisites: a whitelisted kernel_source codebase, vendor or codebase_id, and a path_prefix/subsys. ' +
+        'Budget: top_k is capped at 20 and metadata_only sessions return CodeRef metadata without snippets. Outcomes: source hits, metadata-only hits, or an explicit unsupportedReason.', {
+        query: zod_1.z.string().describe('Kernel symbol, subsystem, or behavior query.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum hits returned (1-20, default 5).'),
+        codebase_id: zod_1.z.string().optional().describe('Restrict to one whitelisted kernel codebase id.'),
+        vendor: zod_1.z.string().optional().describe('Vendor id. Required when multiple kernel codebases are available and codebase_id is omitted.'),
+        symbol: zod_1.z.string().optional().describe('Exact symbol filter when known.'),
+        path_prefix: zod_1.z.string().optional().describe('Required subsystem path prefix, for example drivers/android/binder.'),
+    }, async ({ query, top_k, codebase_id, vendor, symbol, path_prefix }) => {
+        const codebaseId = normalizeOptionalToolString(codebase_id);
+        const vendorId = normalizeOptionalToolString(vendor);
+        const symbolExact = normalizeOptionalToolString(symbol);
+        const pathPrefix = normalizeOptionalToolString(path_prefix);
+        const requestedIds = codebaseId ? [codebaseId] : codebaseIds;
+        const allowed = requestedIds.filter(id => codebaseIds.includes(id));
+        if (allowed.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: 'No requested codebase is whitelisted for this session' }),
+                    }],
+                isError: true,
+            };
+        }
+        const kernelRefs = allowed
+            .map(id => codebaseRegistry.get(id))
+            .filter(ref => ref?.kind === 'kernel_source');
+        const vendors = new Set(kernelRefs.map(ref => ref.vendor).filter(Boolean));
+        if (!codebaseId && !vendorId && vendors.size > 1) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            unsupportedReason: 'vendor_required_for_multi_vendor_kernel_lookup',
+                            vendors: Array.from(vendors).sort(),
+                        }) }],
+                isError: true,
+            };
+        }
+        const raw = getRagStore().search(query, {
+            topK: top_k ?? 5,
+            kinds: ['kernel_source'],
+            codebaseIds: kernelRefs.map(ref => ref.codebaseId),
+            ...(vendorId ? { vendor: vendorId } : {}),
+            ...(symbolExact ? { symbolExact } : {}),
+            ...(pathPrefix ? { pathPrefix } : {}),
+            scope: knowledgeScope,
+        });
+        const filtered = await (0, lookupResponseFilter_1.filterRagLookup)(raw, {
+            toolName: 'lookup_kernel_source',
+            turn: 0,
+            codebaseRegistry,
+            ledger: codeLookupLedger,
+            allowProviderSend: codeAwareMode === 'provider_send',
+            sessionId: options.sessionId,
+        });
+        await codeLookupLedger?.flush();
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: true, result: filtered }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    const resolveSymbol = (0, claude_agent_sdk_1.tool)('resolve_symbol', 'Use when trace frames or obfuscated names must be resolved to CodeRef metadata before source lookup. ' +
+        'Do NOT use to guess file:line when build_id is missing; return the degraded result instead. ' +
+        'Prerequisites: whitelisted codebase ids and indexed source/symbol metadata. Budget: top_k capped at 20. Outcomes: app, native/AOSP, or kernel candidates with degradation reasons.', {
+        symbol: zod_1.z.string().describe('Class, function, or method name to resolve.'),
+        kind: zod_1.z.enum(['app', 'native', 'kernel']).optional().describe('Resolution domain; default app.'),
+        codebase_id: zod_1.z.string().optional().describe('Restrict to one whitelisted codebase id. Defaults to all session codebases.'),
+        file_path: zod_1.z.string().optional().describe('Optional relative source file path for fallback matching.'),
+        build_id: zod_1.z.string().optional().describe('Optional build id. Missing build id returns a degraded result.'),
+        vendor: zod_1.z.string().optional().describe('Vendor id for kernel lookup.'),
+        top_k: zod_1.z.number().int().min(1).max(20).optional().describe('Maximum candidates returned.'),
+    }, async ({ symbol, kind, codebase_id, file_path, build_id, vendor, top_k }) => {
+        const codebaseId = normalizeOptionalToolString(codebase_id);
+        const filePath = normalizeOptionalToolString(file_path);
+        const buildId = normalizeOptionalToolString(build_id);
+        const vendorId = normalizeOptionalToolString(vendor);
+        const requestedIds = codebaseId ? [codebaseId] : codebaseIds;
+        const allowed = requestedIds.filter(id => codebaseIds.includes(id));
+        if (allowed.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: 'No requested codebase is whitelisted for this session' }),
+                    }],
+                isError: true,
+            };
+        }
+        const resolver = new symbolResolver_1.SymbolResolver(getRagStore());
+        const results = allowed.map(id => {
+            const ref = codebaseRegistry.get(id);
+            if (kind === 'kernel' || ref?.kind === 'kernel_source') {
+                return resolver.resolveKernel({
+                    symbol,
+                    codebaseId: id,
+                    vendor: vendorId ?? ref?.vendor,
+                    ...(buildId ? { buildId } : {}),
+                    topK: top_k ?? 5,
+                });
+            }
+            if (kind === 'native' || ref?.kind === 'aosp') {
+                return resolver.resolveNative({
+                    symbol,
+                    codebaseId: id,
+                    ...(buildId ? { buildId } : {}),
+                    topK: top_k ?? 5,
+                });
+            }
+            return resolver.resolveApp({
+                symbol,
+                codebaseId: id,
+                ...(filePath ? { filePath } : {}),
+                ...(buildId ? { buildId } : {}),
+                topK: top_k ?? 5,
+            });
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        success: results.some(result => result.success),
+                        results,
+                    }) }],
+        };
+    }, { annotations: { readOnlyHint: true } });
+    const proposePatch = (0, claude_agent_sdk_1.tool)('propose_patch', 'Use when the user asks for a concrete fix after successful code lookup. Do NOT use before lookup_app_source/lookup_kernel_source/lookup_aosp_source has returned prior contextChunkIds. ' +
+        'Prerequisites: all contextChunkIds must belong to one whitelisted codebase and provider_send consent must be enabled. Budget: patch attempts are capped by the session ledger. Outcomes: verified diff, non-copyable sketch, or unverified rejection.', {
+        context_chunk_ids: zod_1.z.array(zod_1.z.string()).min(1).describe('Chunk ids previously returned by a successful source lookup in this session.'),
+        problem: zod_1.z.string().describe('Performance problem the patch should address.'),
+        proposed_diff: zod_1.z.string().optional().describe('Optional unified diff to validate. Only returned to the user if git apply --check passes.'),
+        patch_sketch: zod_1.z.string().optional().describe('Optional high-level sketch when no verified diff is available.'),
+    }, async ({ context_chunk_ids, problem, proposed_diff, patch_sketch }) => {
+        const proposer = new patchProposer_1.PatchProposer(getRagStore(), codebaseRegistry, codeLookupLedger);
+        const result = proposer.propose({
+            contextChunkIds: context_chunk_ids,
+            problem,
+            ...(proposed_diff ? { proposedDiff: proposed_diff } : {}),
+            ...(patch_sketch ? { patchSketch: patch_sketch } : {}),
+            turn: 0,
+        });
+        await codeLookupLedger?.flush();
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ success: result.patchStatus !== 'unverified', result }) }],
+            ...(result.patchStatus === 'unverified' ? { isError: true } : {}),
+        };
+    }, { annotations: { readOnlyHint: false } });
     // recall_project_memory (Plan 44): pure-read recall over project +
     // world memory entries. Strict invariant: handler MUST NOT cause any
     // disk writes; ProjectMemory.recallProjectMemory() is enforced via
@@ -3251,7 +3570,7 @@ function createClaudeMcpServer(options) {
                 const summaryResult = (0, sqlSummarizer_1.summarizeSqlResult)(result.columns, result.rows);
                 const durationMs = Date.now() - sqlStart;
                 if (emitUpdate) {
-                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer);
+                    emittedEvidence = emitSqlSummaryDataEnvelope(emitUpdate, summaryResult, finalSql, injected, traceProvenance, producer, processIdentityWarning);
                 }
                 const text = JSON.stringify({
                     success: true,
@@ -3275,10 +3594,10 @@ function createClaudeMcpServer(options) {
             }
             const durationMs = Date.now() - sqlStart;
             if (emitUpdate && success && result.columns.length > 0) {
-                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer);
+                emittedEvidence = emitSqlDataEnvelope(emitUpdate, result.columns, rows, finalSql, injected, traceProvenance, producer, processIdentityWarning);
             }
             else if (emitUpdate && !success) {
-                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer);
+                emittedEvidence = emitSqlDiagnosticDataEnvelope(emitUpdate, result.error || (0, outputLanguage_1.localize)(outputLanguage, 'SQL 执行失败', 'SQL execution failed'), finalSql, injected, traceProvenance, producer, processIdentityWarning);
             }
             const text = JSON.stringify({
                 success,
@@ -3308,7 +3627,7 @@ function createClaudeMcpServer(options) {
                 traceId: targetTraceId,
                 traceSide: trace,
             });
-            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, e.message, sql, undefined, traceProvenance, producer, outputLanguage) : undefined;
+            const emittedEvidence = emitUpdate ? emitSqlDiagnosticDataEnvelope(emitUpdate, e.message, sql, undefined, traceProvenance, producer, undefined, outputLanguage) : undefined;
             return {
                 content: [{
                         type: 'text',
@@ -3367,8 +3686,8 @@ function createClaudeMcpServer(options) {
                 traceSide: 'reference',
             });
             const [currentResult, refResult] = await Promise.all([
-                skillExecutor.execute(skillId, traceId, effectiveParams),
-                skillExecutor.execute(skillId, referenceTraceId, refParams),
+                skillExecutor.execute(skillId, traceId, effectiveParams, { __traceSide: 'current' }),
+                skillExecutor.execute(skillId, referenceTraceId, refParams, { __traceSide: 'reference' }),
             ]);
             const compareDuration = Date.now() - compareStart;
             // Schema alignment: check which steps are comparable
@@ -3389,14 +3708,14 @@ function createClaudeMcpServer(options) {
                     ...baseProducer,
                     sourceToolCallId: `${baseProducer.sourceToolCallId}:current`,
                     producerReason: (0, outputLanguage_1.localize)(outputLanguage, `当前 Trace 对比 Skill ${skillId} 结果。`, `Current trace result for comparison Skill ${skillId}.`),
-                });
+                }, currentResult.identityResolution);
             }
             if (emitUpdate && refResult.displayResults?.length) {
                 emitSkillDataEnvelopes(refResult.displayResults, skillId, emitUpdate, referenceTraceProvenance, {
                     ...baseProducer,
                     sourceToolCallId: `${baseProducer.sourceToolCallId}:reference`,
                     producerReason: (0, outputLanguage_1.localize)(outputLanguage, `参考 Trace 对比 Skill ${skillId} 结果。`, `Reference trace result for comparison Skill ${skillId}.`),
-                });
+                }, refResult.identityResolution);
             }
             // Build compact comparison summary for Claude
             const buildStepSummary = (results) => results.map(r => ({
@@ -3416,6 +3735,7 @@ function createClaudeMcpServer(options) {
                     stepCount: currentResult.displayResults?.length || 0,
                     steps: buildStepSummary(currentResult.displayResults || []),
                     diagnosticCount: currentResult.diagnostics?.length || 0,
+                    identityResolution: currentResult.identityResolution,
                     error: currentResult.error,
                 },
                 reference: {
@@ -3426,6 +3746,7 @@ function createClaudeMcpServer(options) {
                     stepCount: refResult.displayResults?.length || 0,
                     steps: buildStepSummary(refResult.displayResults || []),
                     diagnosticCount: refResult.diagnostics?.length || 0,
+                    identityResolution: refResult.identityResolution,
                     error: refResult.error,
                 },
                 alignment: {
@@ -3498,6 +3819,11 @@ function createClaudeMcpServer(options) {
         registry.registerSdk(lookupBlogKnowledge, 'lookup_blog_knowledge', 'public');
         registry.registerSdk(lookupAospSource, 'lookup_aosp_source', 'public');
         registry.registerSdk(lookupOemSdk, 'lookup_oem_sdk', 'public');
+        registry.registerSdk(listCodebases, 'list_codebases', 'requires_codebase_permission');
+        registry.registerSdk(lookupAppSource, 'lookup_app_source', 'requires_codebase_permission');
+        registry.registerSdk(lookupKernelSource, 'lookup_kernel_source', 'requires_codebase_permission');
+        registry.registerSdk(resolveSymbol, 'resolve_symbol', 'requires_codebase_permission');
+        registry.registerSdk(proposePatch, 'propose_patch', 'requires_codebase_permission');
         registry.registerSdk(lookupBaseline, 'lookup_baseline', 'public');
         registry.registerSdk(compareBaselines, 'compare_baselines', 'public');
         registry.registerSdk(recallProjectMemory, 'recall_project_memory', 'public');
@@ -3534,9 +3860,9 @@ function createClaudeMcpServer(options) {
             registry.registerSdk(getComparisonContext, 'get_comparison_context', 'internal');
     }
     return {
-        server: registry.buildSdkServer(),
-        allowedTools: registry.buildAllowedTools(),
-        toolDefinitions: registry.list(),
+        server: registry.buildSdkServer({ scope: toolRequestScope }),
+        allowedTools: registry.buildAllowedTools(toolRequestScope),
+        toolDefinitions: registry.listForRequest(toolRequestScope),
     };
 }
 function evidenceHash(input) {
@@ -3626,7 +3952,7 @@ function producerEnvelopeOptions(producer) {
     };
 }
 /** Emit a DataEnvelope for SQL query results. */
-function emitSqlDataEnvelope(emit, columns, rows, sql, stdlibInjectedModules, traceProvenance, producer) {
+function emitSqlDataEnvelope(emit, columns, rows, sql, stdlibInjectedModules, traceProvenance, producer, processIdentityWarning) {
     const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, columns, rows, traceProvenance, producer);
     const envelope = (0, dataContract_1.createDataEnvelope)({ columns, rows }, {
         type: 'sql_result',
@@ -3643,6 +3969,7 @@ function emitSqlDataEnvelope(emit, columns, rows, sql, stdlibInjectedModules, tr
         traceId: traceProvenance?.traceId,
         queryHash,
         ...producerEnvelopeOptions(producer),
+        processIdentityWarning,
         intent: 'ad_hoc_sql_verification',
     });
     emit({
@@ -3662,7 +3989,7 @@ function emitSqlDataEnvelope(emit, columns, rows, sql, stdlibInjectedModules, tr
     return { evidenceRefId, queryHash };
 }
 /** Emit a DataEnvelope for SQL summary-mode results. */
-function emitSqlSummaryDataEnvelope(emit, summary, sql, stdlibInjectedModules, traceProvenance, producer) {
+function emitSqlSummaryDataEnvelope(emit, summary, sql, stdlibInjectedModules, traceProvenance, producer, processIdentityWarning) {
     const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, summary.columns, summary.sampleRows, traceProvenance, producer, 'summary');
     const envelope = (0, dataContract_1.createDataEnvelope)({
         summary: {
@@ -3681,6 +4008,7 @@ function emitSqlSummaryDataEnvelope(emit, summary, sql, stdlibInjectedModules, t
         traceId: traceProvenance?.traceId,
         queryHash,
         ...producerEnvelopeOptions(producer),
+        processIdentityWarning,
         intent: 'ad_hoc_sql_summary',
     });
     emit({
@@ -3700,7 +4028,7 @@ function emitSqlSummaryDataEnvelope(emit, summary, sql, stdlibInjectedModules, t
     return { evidenceRefId, queryHash };
 }
 /** Emit a diagnostic DataEnvelope for failed SQL so missing tables remain explainable. */
-function emitSqlDiagnosticDataEnvelope(emit, error, sql, stdlibInjectedModules, traceProvenance, producer, outputLanguage = outputLanguage_1.DEFAULT_OUTPUT_LANGUAGE) {
+function emitSqlDiagnosticDataEnvelope(emit, error, sql, stdlibInjectedModules, traceProvenance, producer, processIdentityWarning, outputLanguage = outputLanguage_1.DEFAULT_OUTPUT_LANGUAGE) {
     const { evidenceRefId, queryHash } = stableSqlEvidenceRefId(sql, [], [[error]], traceProvenance, producer, 'diagnostic');
     const envelope = (0, dataContract_1.createDataEnvelope)({
         text: [
@@ -3720,6 +4048,7 @@ function emitSqlDiagnosticDataEnvelope(emit, error, sql, stdlibInjectedModules,
         traceId: traceProvenance?.traceId,
         queryHash,
         ...producerEnvelopeOptions(producer),
+        processIdentityWarning,
         intent: 'ad_hoc_sql_diagnostic',
     });
     emit({
@@ -3751,13 +4080,22 @@ function inferSqlColumnType(col) {
  * Convert skill DisplayResults to DataEnvelopes and emit as SSE 'data' events.
  * This enables interactive tables (clickable timestamps, expandable rows) in the frontend.
  */
-function emitSkillDataEnvelopes(displayResults, skillId, emit, traceProvenance, producer) {
+function emitSkillDataEnvelopes(displayResults, skillId, emit, traceProvenance, producer, identityResolution, artifactIdsByStepId) {
     const envelopes = displayResults
-        .filter(dr => Array.isArray(dr.data?.rows))
+        .filter(dr => Boolean(dr.data))
         .map(dr => {
         const explicitColumns = dr.columnDefinitions;
-        const envelope = (0, dataContract_1.displayResultToEnvelope)(dr, skillId, explicitColumns);
+        const drForEnvelope = {
+            ...dr,
+            metadataConfig: dr.metadataConfig || (Array.isArray(dr.metadataFields)
+                ? { fields: dr.metadataFields }
+                : undefined),
+        };
+        const envelope = (0, dataContract_1.displayResultToEnvelope)(drForEnvelope, skillId, explicitColumns);
         const evidenceRefId = stableSkillEvidenceRefId(skillId, envelope.meta.stepId, envelope.display.title, envelope.data, traceProvenance, producer);
+        const artifactId = envelope.meta.stepId
+            ? artifactIdsByStepId?.get(envelope.meta.stepId)
+            : undefined;
         const withEvidence = {
             ...envelope,
             meta: {
@@ -3765,6 +4103,13 @@ function emitSkillDataEnvelopes(displayResults, skillId, emit, traceProvenance,
                 evidenceRefId,
                 traceSide: traceProvenance?.traceSide,
                 traceId: traceProvenance?.traceId,
+                ...(artifactId ? { artifactId, sourceArtifactId: artifactId } : {}),
+                ...(identityResolution ? {
+                    identityRefId: identityResolution.identityRefId,
+                    identityStatus: identityResolution.status,
+                    identityWarnings: identityResolution.warnings,
+                    identityResolution,
+                } : {}),
                 ...producerEnvelopeOptions(producer),
                 intent: 'skill_structured_result',
             },