@phuetz/code-buddy 1.2.0 → 1.3.1

package/dist/agent/self-improvement/tool-engine.js

@@ -0,0 +1,101 @@
+/**
+ * ToolImprovementEngine — the tool sibling of SelfImprovementEngine. One cycle:
+ *   pick an uncovered tool scenario → propose (redacted view) → tool gate
+ *   (static scan → visible → held-out) → keep+archive (auto-apply) or report.
+ *
+ * Autonomy is the same fail-safe toggle: 'propose-only' (default) validates and
+ * reports; 'auto-apply' (CODEBUDDY_SELF_IMPROVE=true) keeps only tools that pass
+ * the behavioural held-out gate, and archives them (reversible — un-registerable).
+ *
+ * @module agent/self-improvement/tool-engine
+ */
+import { EvolutionaryArchive } from './evolutionary-archive.js';
+import { resolveAutonomy } from './engine.js';
+import { validateToolProposal } from './tool-gate.js';
+import { LiveToolMutator } from './tool-skill-mutator.js';
+import { toProposerView } from './tool-proposer.js';
+export class ToolImprovementEngine {
+    scenarios;
+    proposer;
+    mutator;
+    archive;
+    autonomy;
+    now;
+    /** Scenario ids already satisfied this run (coverage is per-scenario, not per tool name). */
+    covered = new Set();
+    constructor(options) {
+        this.scenarios = options.scenarios;
+        this.proposer = options.proposer;
+        this.mutator = options.mutator ?? new LiveToolMutator();
+        this.archive = options.archive ?? new EvolutionaryArchive();
+        this.autonomy = options.autonomy ?? resolveAutonomy();
+        this.now = options.now ?? (() => new Date());
+    }
+    /** Run exactly one tool-improvement cycle. */
+    async runCycle() {
+        const startedAt = this.now().toISOString();
+        const base = { kind: 'tool_improvement_cycle', startedAt, autonomy: this.autonomy };
+        for (const scenario of this.scenarios) {
+            // Coverage is per-scenario: once a tool has satisfied this scenario's gate,
+            // don't re-author it (even if the model would pick a different name).
+            if (this.covered.has(scenario.id))
+                continue;
+            const proposal = await this.proposer.propose(toProposerView(scenario));
+            if (!proposal)
+                continue;
+            // A tool with this exact name already exists — skip (avoid dup-register).
+            if (this.mutator.has(proposal.spec.name)) {
+                this.covered.add(scenario.id);
+                continue;
+            }
+            const gate = await validateToolProposal(proposal, scenario, this.mutator, {
+                keepOnAccept: this.autonomy === 'auto-apply',
+            });
+            const applied = gate.accepted && !!gate.appliedRef;
+            if (applied) {
+                this.covered.add(scenario.id);
+                this.archive.append({
+                    proposalId: proposal.id,
+                    kind: 'tool',
+                    targetScenarioId: scenario.id,
+                    experienceId: proposal.experienceId,
+                    delta: 1,
+                    scoreAfter: gate.visiblePassed + gate.heldOutPassed,
+                    appliedRef: gate.appliedRef,
+                });
+            }
+            return {
+                ...base,
+                selectedScenarioId: scenario.id,
+                proposalId: proposal.id,
+                gate,
+                applied,
+                notes: gate.reasons,
+            };
+        }
+        return {
+            ...base,
+            selectedScenarioId: null,
+            proposalId: null,
+            gate: null,
+            applied: false,
+            notes: ['no uncovered tool scenario with an available proposal'],
+        };
+    }
+    /** Run cycles until nothing new is applied (or maxCycles). */
+    async runLoop(maxCycles) {
+        const cap = Math.max(1, maxCycles ?? this.scenarios.length + 1);
+        const results = [];
+        for (let i = 0; i < cap; i++) {
+            const r = await this.runCycle();
+            results.push(r);
+            if (!r.applied)
+                break;
+        }
+        return results;
+    }
+    status() {
+        return { autonomy: this.autonomy, scenarios: this.scenarios.length, archive: this.archive.summary() };
+    }
+}
+//# sourceMappingURL=tool-engine.js.map

package/dist/agent/self-improvement/tool-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool gate — the empirical, anti-gaming validator for an authored-tool proposal.
+ * Ordered, blocking, fail-closed:
+ *   G1 static scan (authored-artifact-gate, no execution)
+ *   G3 VISIBLE behavioural cases must all pass (the tool actually works)
+ *   G4 HELD-OUT behavioural cases must all pass (fresh inputs the proposer never
+ *      saw — a tool that hardcodes the visible outputs fails here → rejected).
+ * A scenario with no held-out cases is rejected (anti-gaming is then undefined).
+ *
+ * Scoring never registers the tool; registration happens only on accept+keep.
+ *
+ * @module agent/self-improvement/tool-gate
+ */
+import type { ToolMutatorPort } from './tool-skill-mutator.js';
+import type { ToolBenchmarkScenario, ToolGateOutcome, ToolProposal } from './tool-types.js';
+export interface ValidateToolOptions {
+    /** auto-apply: keep (register) an accepted tool. propose-only: report only. */
+    keepOnAccept: boolean;
+}
+export declare function validateToolProposal(proposal: ToolProposal, scenario: ToolBenchmarkScenario, mutator: ToolMutatorPort, options: ValidateToolOptions): Promise<ToolGateOutcome>;

package/dist/agent/self-improvement/tool-gate.js

@@ -0,0 +1,78 @@
+/**
+ * Tool gate — the empirical, anti-gaming validator for an authored-tool proposal.
+ * Ordered, blocking, fail-closed:
+ *   G1 static scan (authored-artifact-gate, no execution)
+ *   G3 VISIBLE behavioural cases must all pass (the tool actually works)
+ *   G4 HELD-OUT behavioural cases must all pass (fresh inputs the proposer never
+ *      saw — a tool that hardcodes the visible outputs fails here → rejected).
+ * A scenario with no held-out cases is rejected (anti-gaming is then undefined).
+ *
+ * Scoring never registers the tool; registration happens only on accept+keep.
+ *
+ * @module agent/self-improvement/tool-gate
+ */
+import { inspectAuthoredCode } from './authored-artifact-gate.js';
+import { scoreToolCases } from './sandbox-scorer.js';
+export async function validateToolProposal(proposal, scenario, mutator, options) {
+    const zero = {
+        proposalId: proposal.id,
+        scenarioId: scenario.id,
+        visiblePassed: 0,
+        visibleTotal: scenario.visibleCases.length,
+        heldOutPassed: 0,
+        heldOutTotal: scenario.heldOutCases.length,
+    };
+    // G1 — static scan (no execution).
+    const scan = inspectAuthoredCode(proposal.spec.code, 'code');
+    if (!scan.ok) {
+        return { ...zero, accepted: false, rejectionReason: 'static-scan', reasons: scan.reasons };
+    }
+    // Fail-closed: a scenario with no held-out cases can't defend against gaming.
+    if (scenario.heldOutCases.length === 0) {
+        return {
+            ...zero,
+            accepted: false,
+            rejectionReason: 'heldout-fail',
+            reasons: ['scenario has no held-out cases — anti-gaming is undefined, refusing'],
+        };
+    }
+    // G3 — visible behavioural cases (the tool must actually work).
+    const visible = await scoreToolCases(proposal.spec, scenario.visibleCases);
+    if (visible.passed < visible.total) {
+        return {
+            ...zero,
+            accepted: false,
+            visiblePassed: visible.passed,
+            rejectionReason: 'visible-fail',
+            reasons: visible.failures,
+        };
+    }
+    // G4 — held-out cases on FRESH inputs (catches hardcoded-output gaming).
+    const heldOut = await scoreToolCases(proposal.spec, scenario.heldOutCases);
+    if (heldOut.passed < heldOut.total) {
+        return {
+            ...zero,
+            accepted: false,
+            visiblePassed: visible.passed,
+            heldOutPassed: heldOut.passed,
+            rejectionReason: 'heldout-fail',
+            reasons: ['held-out cases failed — likely gamed/overfit visible outputs', ...heldOut.failures],
+        };
+    }
+    // Accepted. Keep (auto-apply) or just report (propose-only).
+    let appliedRef;
+    if (options.keepOnAccept) {
+        appliedRef = mutator.register(proposal.spec).name;
+    }
+    return {
+        ...zero,
+        accepted: true,
+        visiblePassed: visible.passed,
+        heldOutPassed: heldOut.passed,
+        reasons: options.keepOnAccept
+            ? ['accepted and kept (auto-apply): passed visible + held-out, statically clean']
+            : ['accepted (propose-only): passed visible + held-out, not persisted'],
+        ...(appliedRef ? { appliedRef } : {}),
+    };
+}
+//# sourceMappingURL=tool-gate.js.map

package/dist/agent/self-improvement/tool-proposer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tool proposer — authors a candidate tool for a scenario. It receives a REDACTED
+ * view of the scenario (capability + visible cases only); the held-out cases are
+ * never exposed, so a proposer (static or LLM) cannot overfit to them. This is the
+ * structural half of the anti-gaming defence (the gate is the empirical half).
+ *
+ * @module agent/self-improvement/tool-proposer
+ */
+import type { AuthoredToolSpec } from './authored-tool-runtime.js';
+import type { ToolBenchmarkScenario, ToolCase, ToolProposal } from './tool-types.js';
+/** What a proposer is allowed to see — NO held-out cases. */
+export interface ProposerScenarioView {
+    id: string;
+    capability: string;
+    description: string;
+    visibleCases: ToolCase[];
+}
+/** Redact a scenario down to what a proposer may see. */
+export declare function toProposerView(scenario: ToolBenchmarkScenario): ProposerScenarioView;
+export interface ToolProposer {
+    propose(view: ProposerScenarioView): Promise<ToolProposal | null>;
+}
+/**
+ * Deterministic proposer backed by a fixture map (scenarioId → spec). Ships first
+ * (testable, no LLM). The LLM proposer is Phase 3 and uses the same redacted view.
+ */
+export declare class StaticToolProposer implements ToolProposer {
+    private readonly specs;
+    constructor(specs: Map<string, AuthoredToolSpec>);
+    propose(view: ProposerScenarioView): Promise<ToolProposal | null>;
+}

package/dist/agent/self-improvement/tool-proposer.js

@@ -0,0 +1,34 @@
+/**
+ * Tool proposer — authors a candidate tool for a scenario. It receives a REDACTED
+ * view of the scenario (capability + visible cases only); the held-out cases are
+ * never exposed, so a proposer (static or LLM) cannot overfit to them. This is the
+ * structural half of the anti-gaming defence (the gate is the empirical half).
+ *
+ * @module agent/self-improvement/tool-proposer
+ */
+/** Redact a scenario down to what a proposer may see. */
+export function toProposerView(scenario) {
+    return {
+        id: scenario.id,
+        capability: scenario.capability,
+        description: scenario.description,
+        visibleCases: scenario.visibleCases,
+    };
+}
+/**
+ * Deterministic proposer backed by a fixture map (scenarioId → spec). Ships first
+ * (testable, no LLM). The LLM proposer is Phase 3 and uses the same redacted view.
+ */
+export class StaticToolProposer {
+    specs;
+    constructor(specs) {
+        this.specs = specs;
+    }
+    async propose(view) {
+        const spec = this.specs.get(view.id);
+        if (!spec)
+            return null;
+        return { id: `tool-proposal:${view.id}`, targetScenarioId: view.id, spec };
+    }
+}
+//# sourceMappingURL=tool-proposer.js.map

package/dist/agent/self-improvement/tool-skill-mutator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Tool mutator port — applies/reverts an authored tool across BOTH registries
+ * with a proven inverse, so the engine can keep it (auto-apply) or cleanly
+ * un-register it (propose-only / rejection):
+ *   - FormalToolRegistry  → makes it CALLABLE (dispatch reads this),
+ *   - legacy ToolRegistry → makes its schema VISIBLE to the model next turn.
+ *
+ * @module agent/self-improvement/tool-skill-mutator
+ */
+import { type AuthoredToolSpec } from './authored-tool-runtime.js';
+import { AuthoredToolStore } from './authored-tool-store.js';
+export interface ToolMutatorPort {
+    register(spec: AuthoredToolSpec): {
+        name: string;
+    };
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+}
+export interface LiveToolMutatorOptions {
+    /** Persist kept tools to disk so they survive a restart (default true). */
+    persist?: boolean;
+    store?: AuthoredToolStore;
+}
+/** Dual-registry mutator over the live singletons, with optional disk persistence. */
+export declare class LiveToolMutator implements ToolMutatorPort {
+    private readonly persist;
+    private readonly store;
+    constructor(options?: LiveToolMutatorOptions);
+    register(spec: AuthoredToolSpec): {
+        name: string;
+    };
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+}
+/**
+ * Re-register persisted authored tools into both registries at startup. Does NOT
+ * re-persist (it's loading what's already on disk). Returns the names loaded.
+ * Gated by callers on CODEBUDDY_SELF_IMPROVE.
+ */
+export declare function loadAuthoredTools(workDir?: string): string[];

package/dist/agent/self-improvement/tool-skill-mutator.js

@@ -0,0 +1,79 @@
+/**
+ * Tool mutator port — applies/reverts an authored tool across BOTH registries
+ * with a proven inverse, so the engine can keep it (auto-apply) or cleanly
+ * un-register it (propose-only / rejection):
+ *   - FormalToolRegistry  → makes it CALLABLE (dispatch reads this),
+ *   - legacy ToolRegistry → makes its schema VISIBLE to the model next turn.
+ *
+ * @module agent/self-improvement/tool-skill-mutator
+ */
+import { FormalToolRegistry } from '../../tools/registry/tool-registry.js';
+import { getToolRegistry } from '../../tools/registry.js';
+import { buildAuthoredTool } from './authored-tool-runtime.js';
+import { AuthoredToolStore } from './authored-tool-store.js';
+/** Dual-registry mutator over the live singletons, with optional disk persistence. */
+export class LiveToolMutator {
+    persist;
+    store;
+    constructor(options = {}) {
+        this.persist = options.persist ?? true;
+        this.store = options.store ?? new AuthoredToolStore();
+    }
+    register(spec) {
+        const tool = buildAuthoredTool(spec);
+        FormalToolRegistry.getInstance().register(tool, { override: true });
+        const definition = {
+            type: 'function',
+            function: {
+                name: spec.name,
+                description: spec.description,
+                parameters: spec.parameters,
+            },
+        };
+        const metadata = {
+            name: spec.name,
+            category: 'system',
+            keywords: ['authored', 'self-extension', 'tool'],
+            priority: 5,
+            description: spec.description,
+        };
+        getToolRegistry().registerTool(definition, metadata);
+        if (this.persist)
+            this.store.add(spec);
+        return { name: spec.name };
+    }
+    unregister(name) {
+        const a = FormalToolRegistry.getInstance().unregister(name);
+        const b = getToolRegistry().removeTool(name);
+        if (this.persist)
+            this.store.remove(name);
+        return a || b;
+    }
+    has(name) {
+        return FormalToolRegistry.getInstance().has(name) || getToolRegistry().getTool(name) !== undefined;
+    }
+}
+/**
+ * Re-register persisted authored tools into both registries at startup. Does NOT
+ * re-persist (it's loading what's already on disk). Returns the names loaded.
+ * Gated by callers on CODEBUDDY_SELF_IMPROVE.
+ */
+export function loadAuthoredTools(workDir) {
+    const store = new AuthoredToolStore(workDir ? { workDir } : {});
+    const specs = store.list();
+    if (specs.length === 0)
+        return [];
+    const loader = new LiveToolMutator({ persist: false, store });
+    const loaded = [];
+    for (const spec of specs) {
+        try {
+            loader.register(spec);
+            loaded.push(spec.name);
+        }
+        catch {
+            /* skip a malformed persisted spec */
+        }
+    }
+    return loaded;
+}
+//# sourceMappingURL=tool-skill-mutator.js.map

package/dist/agent/self-improvement/tool-types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for the TOOL self-improvement path (sibling to the lesson path). A tool
+ * "covers" a scenario only BEHAVIORALLY: it must run on fixed inputs and produce
+ * asserted outputs (a presence predicate would be trivially gamed).
+ *
+ * @module agent/self-improvement/tool-types
+ */
+import type { AuthoredToolSpec } from './authored-tool-runtime.js';
+/** One behavioural assertion: run the tool on `input`, output must contain ALL of `expectIncludes`. */
+export interface ToolCase {
+    input: Record<string, unknown>;
+    expectIncludes: string[];
+}
+/**
+ * A behavioural benchmark for an authored tool. `visibleCases` describe the
+ * capability (and may be shown to the proposer); `heldOutCases` use fresh inputs
+ * and are NEVER shown to the proposer — a tool that hardcodes the visible
+ * outputs passes visible but fails held-out (the anti-reward-hacking defence).
+ */
+export interface ToolBenchmarkScenario {
+    id: string;
+    /** Human capability description (safe to show the proposer). */
+    capability: string;
+    description: string;
+    visibleCases: ToolCase[];
+    heldOutCases: ToolCase[];
+}
+/** A candidate authored tool, motivated by a scenario. The spec must be produced WITHOUT seeing heldOutCases. */
+export interface ToolProposal {
+    id: string;
+    targetScenarioId: string;
+    experienceId?: string;
+    spec: AuthoredToolSpec;
+}
+export type ToolGateRejection = 'static-scan' | 'visible-fail' | 'heldout-fail';
+export interface ToolGateOutcome {
+    accepted: boolean;
+    proposalId: string;
+    scenarioId: string;
+    visiblePassed: number;
+    visibleTotal: number;
+    heldOutPassed: number;
+    heldOutTotal: number;
+    rejectionReason?: ToolGateRejection;
+    reasons: string[];
+    /** Name of the tool left registered (only when accepted AND kept). */
+    appliedRef?: string;
+}

package/dist/agent/self-improvement/tool-types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the TOOL self-improvement path (sibling to the lesson path). A tool
+ * "covers" a scenario only BEHAVIORALLY: it must run on fixed inputs and produce
+ * asserted outputs (a presence predicate would be trivially gamed).
+ *
+ * @module agent/self-improvement/tool-types
+ */
+export {};
+//# sourceMappingURL=tool-types.js.map

package/dist/agent/self-improvement/types.d.ts

@@ -97,13 +97,15 @@ export interface GateOutcome {
 /** One accepted improvement, kept as an evolutionary stepping stone (DGM). */
 export interface ArchiveEntry {
     proposalId: string;
-    kind: ImprovementProposal['kind'];
+    kind: ImprovementProposal['kind'] | 'tool' | 'skill';
     targetScenarioId: string;
     experienceId?: string;
     delta: number;
     scoreAfter: number;
     /** Id of the applied lesson (so it can be traced/rolled back later). */
     appliedRef?: string;
+    /** For consolidation: the umbrella skill an archived sibling was absorbed into. */
+    absorbedInto?: string;
     createdAt: string;
     /** Sentinel for auditability, mirrors the learning-loop convention. */
     reviewedBy: string;

package/dist/agent/tool-handler.js

@@ -17,6 +17,7 @@
  */
 import { TextEditorTool, MorphEditorTool, ImageTool, BashTool, } from "../tools/index.js";
 import { getFormalToolRegistry, createTextEditorTools, createBashTools, createLsTools, createSearchTools, createWebTools, createTodoTools, createCronjobTools, createDockerTools, createKubernetesTools, createGitTools, createMiscTools, createBrowserTools, createProcessTools, createVisionTools, createScriptTools, createPlanTools, createKnowledgeTools, createRelationshipIntelligenceTools, createInternetScoutTools, createLeadScoutTools, createBrowserOperatorTools, createWindowsTools, createMemoryTools, createParallelTools, createAttentionTools, createSkillsInspectionTools, createLessonsTools, createUserModelTools, createAliasTools, createMultimodalTools, createAdvancedTools, createCanvasTools, createLspTools, createMergeConflictTools, createVulnScannerTools, createCodebaseReplaceTools, createAdvisorTools, createFleetTools, createAskUserQuestionTools, createExitPlanModeTools, createGuiTools, createSessionTools, createGitNexusTools, createScreenpipeTools, } from "../tools/registry/index.js";
+import { createRegisterToolTool } from "../tools/register-tool-handler.js";
 import { getMCPManager } from "../codebuddy/tools.js";
 import { getErrorMessage } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
@@ -239,6 +240,8 @@ export class ToolHandler {
             ...createSessionTools(),
             ...createGitNexusTools(),
             ...createScreenpipeTools(),
+            // Self-improvement: the agent can author its own tools (opt-in only).
+            ...(process.env.CODEBUDDY_SELF_IMPROVE === 'true' ? [createRegisterToolTool()] : []),
         ];
         // Register canonical-prefix alias tools (shell_exec→bash, file_read→view_file, etc.)
         const aliasTools = createAliasTools(allTools);

package/dist/codebuddy/providers/provider-chatgpt-responses.js

@@ -459,6 +459,11 @@ export async function* parseSseStream(body, model, onReasoningItem, idleTimeoutM
     const decoder = new TextDecoder();
     let buffer = '';
     let chunkIndex = 0;
+    // Monotonic index per function_call so the downstream message-reducer keeps
+    // parallel tool calls in separate slots. Hardcoding 0 made every parallel
+    // call merge into one — names/call_ids/arguments concatenated — producing a
+    // 100+ char call_id the Responses backend rejects (max 64) on the next turn.
+    let functionCallIndex = 0;
     const makeChunk = (delta, finishReason) => ({
         id: `chatcmpl-codex-${chunkIndex++}`,
         object: 'chat.completion.chunk',
@@ -547,7 +552,7 @@ export async function* parseSseStream(body, model, onReasoningItem, idleTimeoutM
                     if (item.name && item.call_id) {
                         yield makeChunk({
                             tool_calls: [{
-                                    index: 0,
+                                    index: functionCallIndex++,
                                     id: item.call_id,
                                     type: 'function',
                                     function: {

package/dist/codebuddy/tools.d.ts

@@ -26,6 +26,13 @@ export declare function getBuiltinToolNames(): string[];
  */
 export declare function initializeToolRegistry(): void;
 export declare function getMCPManager(): MCPManager;
+/**
+ * True when the Code Explorer (gitnexus) MCP tools are connected — i.e. at least
+ * one `mcp__gitnexus__*` tool is registered. Used to conditionally steer the
+ * agent toward Code Explorer for relationship/impact questions. Returns false
+ * (no behavior change) whenever Code Explorer is not installed.
+ */
+export declare function isCodeExplorerAvailable(): boolean;
 export declare function initializeMCPServers(): Promise<void>;
 export declare function convertMCPToolToCodeBuddyTool(mcpTool: MCPTool): CodeBuddyTool;
 /**

package/dist/codebuddy/tools.js

@@ -9,6 +9,8 @@ import { loadMCPConfig } from "../mcp/config.js";
 import { getToolSelector, selectRelevantTools } from "../tools/tool-selector.js";
 import { logger } from "../utils/logger.js";
 import { getToolRegistry } from "../tools/registry.js";
+import { createRegisterToolTool } from "../tools/register-tool-handler.js";
+import { loadAuthoredTools } from "../agent/self-improvement/tool-skill-mutator.js";
 import { applyToolFilter } from "../utils/tool-filter.js";
 import { TOOL_METADATA } from "../tools/metadata.js";
 import { getPluginMarketplace } from "../plugins/marketplace.js";
@@ -89,6 +91,18 @@ export function initializeToolRegistry() {
         description: 'High-speed file editing with Morph'
     };
     registry.registerTool(MORPH_EDIT_TOOL, morphMetadata, isMorphEnabled);
+    // Self-improvement: expose `register_tool` + reload persisted authored tools,
+    // only when opted in.
+    if (process.env.CODEBUDDY_SELF_IMPROVE === 'true') {
+        const schema = createRegisterToolTool().getSchema();
+        registry.registerTool({ type: 'function', function: { name: schema.name, description: schema.description, parameters: schema.parameters } }, { name: schema.name, category: 'system', keywords: ['authored', 'self-extension', 'register', 'tool'], priority: 6, description: schema.description });
+        try {
+            const loaded = loadAuthoredTools();
+            if (loaded.length > 0)
+                logger.info(`[self-improve] reloaded ${loaded.length} authored tool(s): ${loaded.join(', ')}`);
+        }
+        catch { /* persisted store optional */ }
+    }
     registerGroup(SEARCH_TOOLS);
     registerGroup(TODO_TOOLS);
     registerGroup(KANBAN_TOOLS);
@@ -147,6 +161,20 @@ export function getMCPManager() {
     }
     return mcpManager;
 }
+/**
+ * True when the Code Explorer (gitnexus) MCP tools are connected — i.e. at least
+ * one `mcp__gitnexus__*` tool is registered. Used to conditionally steer the
+ * agent toward Code Explorer for relationship/impact questions. Returns false
+ * (no behavior change) whenever Code Explorer is not installed.
+ */
+export function isCodeExplorerAvailable() {
+    try {
+        return getMCPManager().getTools().some((t) => t.name.startsWith('mcp__gitnexus__'));
+    }
+    catch {
+        return false;
+    }
+}
 export async function initializeMCPServers() {
     const manager = getMCPManager();
     const config = loadMCPConfig();
@@ -359,6 +387,18 @@ export async function getAllCodeBuddyTools() {
     }
     // Apply CLI tool filter (--enabled-tools, --disabled-tools, --allowed-tools)
     allTools = applyToolFilter(allTools);
+    // When Code Explorer (gitnexus) is connected, make the built-in graph tools
+    // defer to it at the decision point — its graph is broader / more complete.
+    // Conditional & non-mutating: returns fresh objects only for code_graph /
+    // codebase_map, and only when a gitnexus tool is present (no change otherwise).
+    if (allTools.some((t) => t.function.name.startsWith('mcp__gitnexus__'))) {
+        const DEFER = ' NOTE: Code Explorer (gitnexus) is available — for code-relationship, blast-radius/impact, ' +
+            'dead-code and cycle questions PREFER its MCP tools (`mcp__gitnexus__impact` / `context` / ' +
+            '`query` / `find_cycles`); use this built-in only as a fallback if a gitnexus tool errors.';
+        allTools = allTools.map((t) => t.function.name === 'code_graph' || t.function.name === 'codebase_map'
+            ? { ...t, function: { ...t.function, description: (t.function.description ?? '') + DEFER } }
+            : t);
+    }
     return allTools;
 }
 // ============================================================================