@compilr-dev/cli 0.5.2 → 0.5.3

package/dist/commands-v2/handlers/session.js

@@ -356,7 +356,7 @@ export async function loadAndRestoreSession(projectId, agent, mode = 'auto') {
  * @param teamOptions - Optional team switching options
  * @returns Object with switch info, or null if no switch occurred
  */
-export async function handleProjectSwitch(oldProjectId, agent, teamOptions) {
+export async function handleProjectSwitch(oldProjectId, agent, teamOptions, agentOptions) {
     const newProject = getCurrentProject();
     const newProjectId = newProject?.id ?? null;
     // No switch occurred
@@ -427,14 +427,24 @@ export async function handleProjectSwitch(oldProjectId, agent, teamOptions) {
                 messageCount = messages.length;
             }
         }
-        // Update agent's anchors for the new project
-        if (agent?.clearAnchors && agent.addAnchor) {
-            // Clear existing persistent anchors
-            agent.clearAnchors({ scope: 'persistent' });
-            // Add new project's anchors
+    }
+    catch {
+        // Context refresh is best-effort
+    }
+    // Recreate default agent if agentOptions provided — the new agent gets
+    // the fresh system prompt (project name, COMPILR.md, guided context).
+    let newAgent;
+    if (agentOptions) {
+        try {
+            // 1. Update liveProjectState in index.ts so agentFactory reads fresh values
+            await agentOptions.updateProjectState?.(newProjectId);
+            // 2. Create fresh default agent with new project's system prompt
+            newAgent = await agentOptions.agentFactory({});
+            // 3. Transfer anchors to the NEW agent
+            newAgent.clearAnchors({ scope: 'persistent' });
             const newAnchors = await getProjectAnchors(newProjectId);
             for (const anchor of newAnchors) {
-                agent.addAnchor({
+                newAgent.addAnchor({
                     id: anchor.id,
                     content: anchor.content,
                     priority: anchor.priority,
@@ -442,18 +452,45 @@ export async function handleProjectSwitch(oldProjectId, agent, teamOptions) {
                     tags: anchor.tags,
                 });
             }
+            // 4. Set history on the NEW agent (not the old one)
+            if (messages.length > 0) {
+                await newAgent.setHistory(messages, { turnCount: messageCount });
+            }
+        }
+        catch {
+            // If agent recreation fails, fall back to updating the old agent
+            newAgent = undefined;
         }
     }
-    catch {
-        // Context refresh is best-effort
-    }
-    // Set the updated history (with context message if any)
-    if (agent) {
-        if (messages.length > 0) {
-            await agent.setHistory(messages, { turnCount: messageCount });
+    // If no new agent was created, update the old agent as before
+    if (!newAgent) {
+        try {
+            // Update old agent's anchors
+            if (agent?.clearAnchors && agent.addAnchor) {
+                agent.clearAnchors({ scope: 'persistent' });
+                const newAnchors = await getProjectAnchors(newProjectId);
+                for (const anchor of newAnchors) {
+                    agent.addAnchor({
+                        id: anchor.id,
+                        content: anchor.content,
+                        priority: anchor.priority,
+                        scope: anchor.scope,
+                        tags: anchor.tags,
+                    });
+                }
+            }
         }
-        else {
-            agent.clearHistory();
+        catch {
+            // Context refresh is best-effort
+        }
+        // Set the updated history on the old agent
+        if (agent) {
+            if (messages.length > 0) {
+                await agent.setHistory(messages, { turnCount: messageCount });
+            }
+            else {
+                agent.clearHistory();
+            }
         }
     }
     // Handle team switching if team options provided
@@ -496,6 +533,7 @@ export async function handleProjectSwitch(oldProjectId, agent, teamOptions) {
         contextRefreshed,
         contextMessage,
         newTeam,
+        newAgent,
     };
 }
 /**

package/dist/commands-v2/types.d.ts

@@ -43,6 +43,11 @@ export interface CommandContextV2 {
      * Used when switching projects to create new team.
      */
     agentFactory?: (config: Record<string, unknown>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean) => Promise<Agent>;
+    /**
+     * Update live project state so agentFactory creates agents with fresh context.
+     * Called during project switch before recreating the default agent.
+     */
+    updateProjectState?: (projectId: number | null) => Promise<void>;
     /**
      * Replace the current agent with a restored one.
      * Used by /resume command to restore from a saved session.

package/dist/index.js

@@ -11,7 +11,7 @@ process.env.FORCE_COLOR = '3';
 import { perf, flushStartupPerf } from './utils/startup-perf.js';
 perf('imports-start');
 import { createAgent } from './agent.js';
-import { getModelForTier } from './models/index.js';
+import { getModelForTier, getProviderMetadata } from './models/index.js';
 import { ReplV2 } from './repl-v2.js';
 import { AgentTeam, setActiveSharedContext } from './multi-agent/index.js';
 import { getStyles } from './themes/index.js';
@@ -320,34 +320,48 @@ async function main() {
             }
         }
     }
+    // ==========================================================================
+    // Mutable project state — closures read these live so agentFactory
+    // always sees the current project context (not stale startup values).
+    // ==========================================================================
+    const liveProjectState = {
+        dbProject: null,
+        projectContext: undefined,
+        guidedModeContext: undefined,
+    };
     // Load project memory (COMPILR.md or CLAUDE.md)
     perf('project-memory-start');
     const projectMemory = loadProjectMemory();
-    let projectContext;
     if (projectMemory.found && projectMemory.filePath) {
-        projectContext = projectMemory.content;
+        liveProjectState.projectContext = projectMemory.content;
     }
     // ==========================================================================
     // Load guided mode context from database (if project uses guided mode)
     // ==========================================================================
     perf('project-db-start');
-    let guidedModeContext;
     // Determine which project to load based on projectStartup setting
     const projectStartupMode = getProjectStartupMode();
-    let dbProject = null;
     if (projectStartupMode === 'last') {
         // Try to load the last opened project
         const lastProjectId = getLastProjectId();
         if (lastProjectId !== null) {
-            dbProject = projectRepository.getById(lastProjectId);
+            liveProjectState.dbProject = projectRepository.getById(lastProjectId);
             // If last project no longer exists (deleted), don't auto-load any project
         }
         // If no lastProjectId remembered, don't auto-load any project
     }
     // else projectStartupMode === 'off': don't auto-load any project
-    if (dbProject) {
+    if (liveProjectState.dbProject) {
+        const dbProject = liveProjectState.dbProject;
         // Set as active project for tools to use
         setActiveProject({ id: dbProject.id, name: dbProject.name, displayName: dbProject.displayName, path: dbProject.path });
+        // Reload project memory from the DB project's path (not CWD)
+        // The initial loadProjectMemory() above uses process.cwd() which may
+        // load the wrong COMPILR.md/CLAUDE.md (e.g., workspace-level instead of project-specific)
+        if (dbProject.path) {
+            const memory = loadProjectMemory({ cwd: dbProject.path });
+            liveProjectState.projectContext = memory.found ? memory.content : undefined;
+        }
         // If in guided mode, generate context
         if (shouldInjectGuidedContext(dbProject)) {
             // Get work item counts
@@ -376,7 +390,7 @@ async function main() {
                 inProgressCount: statusCounts.in_progress,
                 completedCount: statusCounts.completed,
             };
-            guidedModeContext = getFullGuidedPrompt(contextOptions);
+            liveProjectState.guidedModeContext = getFullGuidedPrompt(contextOptions);
         }
     }
     // ==========================================================================
@@ -386,8 +400,8 @@ async function main() {
     // Load global anchors (always)
     const globalAnchors = getGlobalAnchorManager().getAll({ scope: 'persistent' });
     // Load project-specific anchors (if in a tracked project)
-    const projectAnchors = dbProject
-        ? getAnchorManager(String(dbProject.id)).getAll({ scope: 'persistent' })
+    const projectAnchors = liveProjectState.dbProject
+        ? getAnchorManager(String(liveProjectState.dbProject.id)).getAll({ scope: 'persistent' })
         : [];
     // Combine into persistedAnchors array for agent
     const persistedAnchors = [
@@ -404,7 +418,7 @@ async function main() {
             priority: a.priority,
             scope: a.scope,
             tags: a.tags,
-            projectId: String(dbProject?.id),
+            projectId: String(liveProjectState.dbProject?.id),
         })),
     ];
     // ==========================================================================
@@ -463,8 +477,8 @@ async function main() {
     // ==========================================================================
     perf('mcp-init-fire');
     // Check if there are MCP servers to connect — fire the promise but don't await yet
-    const mcpServerCount = loadMCPConfig(dbProject?.path).length;
-    const mcpInitPromise = mcpServerCount > 0 ? initializeMCP(dbProject?.path) : null;
+    const mcpServerCount = loadMCPConfig(liveProjectState.dbProject?.path).length;
+    const mcpInitPromise = mcpServerCount > 0 ? initializeMCP(liveProjectState.dbProject?.path) : null;
     // Mutable ref for MCP tools — read by team agent factory when creating new agents.
     // Updated when background MCP init completes.
     let mcpToolsRef = [];
@@ -472,9 +486,10 @@ async function main() {
     // Episode Recorder Setup (work history tracking)
     // ==========================================================================
     const createEpisodeRecorder = (agentId) => {
-        if (!dbProject)
+        if (!liveProjectState.dbProject)
             return undefined;
-        const episodesPath = path.join(getSessionsPath(), `project-${String(dbProject.id)}`, 'episodes.json');
+        const projectId = liveProjectState.dbProject.id;
+        const episodesPath = path.join(getSessionsPath(), `project-${String(projectId)}`, 'episodes.json');
         const store = new FileEpisodeStore({ filePath: episodesPath });
         // Set global store for recall_work tool access
         setGlobalEpisodeStore(store);
@@ -486,7 +501,7 @@ async function main() {
             onBatchFlushed: () => {
                 updateWorkSummaryAnchor({
                     store,
-                    projectId: String(dbProject.id),
+                    projectId: String(projectId),
                     getAnchorManager,
                 });
             },
@@ -500,16 +515,16 @@ async function main() {
         model,
         minimal: options.minimal,
         quiet: true,
-        enableMetaTools: !options.minimal, // Use meta-tools for token optimization
+        enableMetaTools: !options.minimal && getProviderMetadata(provider).supportsMetaTools,
         onPermissionRequest,
         onIterationLimitReached,
         onSuggest: (event) => {
             // Store suggestion to be applied after agent finishes
             sharedState.pendingSuggestion = event.action;
         },
-        projectName: dbProject?.displayName,
-        projectContext,
-        guidedModeContext,
+        projectName: liveProjectState.dbProject?.displayName,
+        projectContext: liveProjectState.projectContext,
+        guidedModeContext: liveProjectState.guidedModeContext,
         // Anchors - library handles re-injection on every LLM call
         enableAnchors: true,
         persistedAnchors: persistedAnchors.length > 0 ? persistedAnchors : undefined,
@@ -537,9 +552,11 @@ async function main() {
         episodeRecorder: defaultEpisodeRecorder,
     });
     perf('create-agent-done');
+    // Mutable ref so grantSession and onDefaultAgentSwapped closures track the current default agent
+    let defaultAgentRef = agent;
     // Bind grantSession for the permission handler to use
     sharedState.grantSession = (toolName) => {
-        agent.grantSessionPermission(toolName);
+        defaultAgentRef.grantSessionPermission(toolName);
     };
     // ==========================================================================
     // Create AgentTeam with the default agent (or restore from persistence)
@@ -554,15 +571,15 @@ async function main() {
             provider,
             model: agentModel,
             minimal: options.minimal,
-            enableMetaTools: !options.minimal && !noTools, // Disable meta-tools if noTools is set
+            enableMetaTools: !options.minimal && !noTools && getProviderMetadata(provider).supportsMetaTools,
             onPermissionRequest,
             onIterationLimitReached,
             onSuggest: (event) => {
                 sharedState.pendingSuggestion = event.action;
             },
-            projectName: dbProject?.displayName,
-            projectContext,
-            guidedModeContext,
+            projectName: liveProjectState.dbProject?.displayName,
+            projectContext: liveProjectState.projectContext,
+            guidedModeContext: liveProjectState.guidedModeContext,
             enableAnchors: true,
             persistedAnchors: persistedAnchors.length > 0 ? persistedAnchors : undefined,
             enableGuardrails: true,
@@ -605,11 +622,11 @@ async function main() {
     // Set the active shared context for activity recording
     setActiveSharedContext(team.sharedContext);
     // Populate shared context with actual project info so agents know the project name
-    if (dbProject) {
+    if (liveProjectState.dbProject) {
         team.sharedContext.setProject({
-            id: dbProject.id,
-            name: dbProject.displayName,
-            path: dbProject.path,
+            id: liveProjectState.dbProject.id,
+            name: liveProjectState.dbProject.displayName,
+            path: liveProjectState.dbProject.path,
         });
     }
     // ==========================================================================
@@ -636,7 +653,7 @@ async function main() {
         provider,
         version: VERSION,
         updateAvailable,
-        projectName: dbProject?.displayName ?? process.cwd().split('/').pop(),
+        projectName: liveProjectState.dbProject?.displayName ?? process.cwd().split('/').pop(),
         // Set up V2 permission overlay callback when UI is ready
         onUIReady: (showOverlay) => {
             sharedState.showPermissionOverlayV2 = showOverlay;
@@ -705,6 +722,58 @@ async function main() {
         onTeamReplaced: (newTeam) => {
             sharedState.team = newTeam;
         },
+        // Recreate default agent on project switch — updates liveProjectState
+        // so agentFactory reads fresh project context for the new agent.
+        onProjectStateUpdate: (projectId) => {
+            if (projectId !== null) {
+                liveProjectState.dbProject = projectRepository.getById(projectId);
+                if (liveProjectState.dbProject?.path) {
+                    const memory = loadProjectMemory({ cwd: liveProjectState.dbProject.path });
+                    liveProjectState.projectContext = memory.found ? memory.content : undefined;
+                }
+                else {
+                    liveProjectState.projectContext = undefined;
+                }
+                if (liveProjectState.dbProject && shouldInjectGuidedContext(liveProjectState.dbProject)) {
+                    const statusCounts = workItemRepository.getStatusCounts(liveProjectState.dbProject.id);
+                    let currentItem = null;
+                    if (liveProjectState.dbProject.currentItemId) {
+                        currentItem = workItemRepository.getByItemId(liveProjectState.dbProject.id, liveProjectState.dbProject.currentItemId);
+                    }
+                    else {
+                        const inProgressItems = workItemRepository.query({
+                            project_id: liveProjectState.dbProject.id,
+                            status: 'in_progress',
+                            limit: 1,
+                        });
+                        if (inProgressItems.items.length > 0) {
+                            currentItem = inProgressItems.items[0];
+                        }
+                    }
+                    const contextOptions = {
+                        project: liveProjectState.dbProject,
+                        currentItem,
+                        backlogCount: statusCounts.backlog,
+                        inProgressCount: statusCounts.in_progress,
+                        completedCount: statusCounts.completed,
+                    };
+                    liveProjectState.guidedModeContext = getFullGuidedPrompt(contextOptions);
+                }
+                else {
+                    liveProjectState.guidedModeContext = undefined;
+                }
+            }
+            else {
+                liveProjectState.dbProject = null;
+                liveProjectState.projectContext = undefined;
+                liveProjectState.guidedModeContext = undefined;
+            }
+            return Promise.resolve();
+        },
+        // Keep defaultAgentRef in sync when project switch creates a new default agent
+        onDefaultAgentSwapped: (newAgent) => {
+            defaultAgentRef = newAgent;
+        },
         // Set session prefix for VS Code diff IPC after session registration
         onSessionRegistered: (sessionId) => {
             sharedState.sessionPrefix = sessionId.slice(0, 8);

package/dist/models/providers.d.ts

@@ -9,11 +9,13 @@ import type { ProviderKey } from '../utils/credentials.js';
 import { type ProviderMetadata as SdkProviderMetadata } from '@compilr-dev/sdk';
 export { type OthersProviderModel, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, } from '@compilr-dev/sdk';
 /**
- * CLI-extended provider metadata — adds credentialKey for encrypted storage.
+ * CLI-extended provider metadata — adds credentialKey and capability flags.
  */
 export interface ProviderMetadata extends SdkProviderMetadata {
     /** Credential key for API key storage (CLI-specific) */
     credentialKey: ProviderKey;
+    /** Whether this provider handles the meta-tools indirection pattern well */
+    supportsMetaTools: boolean;
 }
 /**
  * CLI-extended provider metadata registry.

package/dist/models/providers.js

@@ -22,6 +22,14 @@ const CREDENTIAL_KEYS = {
     openrouter: 'openrouter',
     custom: 'openai', // Custom uses openai-compatible format by default
 };
+/**
+ * Meta-tools capability: which providers handle the indirection pattern well.
+ * When false, all tools are registered directly (higher token cost, but reliable).
+ */
+const SUPPORTS_META_TOOLS = {
+    claude: true,
+    gemini: true,
+};
 /**
  * CLI-extended provider metadata registry.
  * Merges SDK metadata with CLI credential keys.
@@ -33,6 +41,7 @@ export const PROVIDER_METADATA = (() => {
         result[providerType] = {
             ...sdkMeta,
             credentialKey: CREDENTIAL_KEYS[providerType],
+            supportsMetaTools: SUPPORTS_META_TOOLS[providerType] ?? false,
         };
     }
     return result;

package/dist/repl-v2.d.ts

@@ -160,6 +160,16 @@ export interface ReplV2Options {
      * see the restored team (with all agents) instead of the initial one.
      */
     onTeamReplaced?: (newTeam: AgentTeam) => void;
+    /**
+     * Callback to update live project state in index.ts before recreating the default agent.
+     * Updates liveProjectState (COMPILR.md, guided context) so agentFactory sees fresh values.
+     */
+    onProjectStateUpdate?: (projectId: number | null) => Promise<void>;
+    /**
+     * Callback invoked after the default agent is swapped on project switch.
+     * Allows index.ts to update defaultAgentRef for grantSession.
+     */
+    onDefaultAgentSwapped?: (newAgent: Agent) => void;
 }
 /**
  * Options for switchAgent().
@@ -220,6 +230,8 @@ export declare class ReplV2 {
     private readonly onBackgroundDelegationReady?;
     private readonly onSessionRegistered?;
     private readonly onTeamReplaced?;
+    private readonly onProjectStateUpdate?;
+    private readonly onDefaultAgentSwapped?;
     private readonly authOnly;
     private restoredSessionInfo;
     private currentExecutingBackgroundAgentId;

package/dist/repl-v2.js

@@ -197,6 +197,8 @@ export class ReplV2 {
     onBackgroundDelegationReady;
     onSessionRegistered;
     onTeamReplaced;
+    onProjectStateUpdate;
+    onDefaultAgentSwapped;
     authOnly;
     restoredSessionInfo = null;
     // Phase 3b: Track which background agent is currently executing (for permission routing)
@@ -242,6 +244,8 @@ export class ReplV2 {
         this.onBackgroundDelegationReady = options.onBackgroundDelegationReady;
         this.onSessionRegistered = options.onSessionRegistered;
         this.onTeamReplaced = options.onTeamReplaced;
+        this.onProjectStateUpdate = options.onProjectStateUpdate;
+        this.onDefaultAgentSwapped = options.onDefaultAgentSwapped;
         this.authOnly = options.authOnly ?? false;
     }
     /**
@@ -734,6 +738,7 @@ export class ReplV2 {
      */
     restoreAgent(newAgent) {
         this.agent = newAgent;
+        this.onDefaultAgentSwapped?.(newAgent);
     }
     /**
      * Get the current agent instance.
@@ -1667,6 +1672,7 @@ export class ReplV2 {
             agent: this.agent,
             team: this.team,
             agentFactory: this.agentFactory,
+            updateProjectState: this.onProjectStateUpdate,
             setTeam: (newTeam) => {
                 const oldTeam = this.team;
                 this.team = newTeam;
@@ -3245,13 +3251,12 @@ export class ReplV2 {
         if (metrics.toolCalls > 0) {
             parts.push(`${String(metrics.toolCalls)} tool${metrics.toolCalls > 1 ? 's' : ''}`);
         }
-        // DEBUG: Show payload debug info (chars sent to provider)
+        // DEBUG: Show payload debug info (token estimates sent to provider)
         if (metrics.debugPayload) {
-            const { systemChars, contentsChars, toolsChars } = metrics.debugPayload;
-            const totalChars = systemChars + contentsChars + toolsChars;
-            const estTokens = Math.ceil(totalChars / 4);
-            // Format: [dbg 2calls sent:123k (~31k est) sys:10k cont:100k tools:13k]
-            parts.push(`[dbg ${String(metrics.apiCalls)}calls sent:${formatTokens(totalChars)} (~${formatTokens(estTokens)} est) sys:${formatTokens(systemChars)} cont:${formatTokens(contentsChars)} tools:${formatTokens(toolsChars)}]`);
+            const { systemTokens, contentsTokens, toolsTokens } = metrics.debugPayload;
+            const totalTokens = systemTokens + contentsTokens + toolsTokens;
+            // Format: [dbg 2calls sent:31k sys:10k cont:8k tools:13k]
+            parts.push(`[dbg ${String(metrics.apiCalls)}calls sent:${formatTokens(totalTokens)} sys:${formatTokens(systemTokens)} cont:${formatTokens(contentsTokens)} tools:${formatTokens(toolsTokens)}]`);
         }
         // Print as muted info line
         this.ui.print({ type: 'turn-summary', parts });

package/dist/tool-names.d.ts

@@ -102,6 +102,10 @@ export declare const TOOL_NAMES: {
 export type ToolName = (typeof TOOL_NAMES)[keyof typeof TOOL_NAMES];
 /** Array of all direct tool names (always available) */
 export declare const DIRECT_TOOL_NAMES: readonly ToolName[];
+/** Hot tools — used in >50% of turns, always declared as direct schemas */
+export declare const HOT_TOOL_NAMES: readonly ToolName[];
+/** Warm tools — used occasionally, moved to meta-registry in hot-tools mode */
+export declare const WARM_TOOL_NAMES: readonly ToolName[];
 /** Array of all meta-tool names (tool discovery) */
 export declare const META_TOOL_NAMES: readonly ToolName[];
 /** Array of all meta-registry tool names (accessed via use_tool) */

package/dist/tool-names.js

@@ -142,6 +142,30 @@ export const DIRECT_TOOL_NAMES = [
     TOOL_NAMES.TASK,
     TOOL_NAMES.SUGGEST,
 ];
+/** Hot tools — used in >50% of turns, always declared as direct schemas */
+export const HOT_TOOL_NAMES = [
+    TOOL_NAMES.READ_FILE,
+    TOOL_NAMES.WRITE_FILE,
+    TOOL_NAMES.EDIT,
+    TOOL_NAMES.BASH,
+    TOOL_NAMES.GREP,
+    TOOL_NAMES.GLOB,
+    TOOL_NAMES.ASK_USER,
+];
+/** Warm tools — used occasionally, moved to meta-registry in hot-tools mode */
+export const WARM_TOOL_NAMES = [
+    TOOL_NAMES.BASH_OUTPUT,
+    TOOL_NAMES.KILL_SHELL,
+    TOOL_NAMES.TODO_WRITE,
+    TOOL_NAMES.TODO_READ,
+    TOOL_NAMES.TODO_CLAIM,
+    TOOL_NAMES.TODO_HANDOFF,
+    TOOL_NAMES.ASK_USER_SIMPLE,
+    TOOL_NAMES.DELEGATE,
+    TOOL_NAMES.DELEGATE_BACKGROUND,
+    TOOL_NAMES.HANDOFF,
+    TOOL_NAMES.COMPILR_GUIDE,
+];
 /** Array of all meta-tool names (tool discovery) */
 export const META_TOOL_NAMES = [
     TOOL_NAMES.LIST_TOOLS,

package/dist/tools.d.ts

@@ -14,7 +14,7 @@
  * Tool names are defined in tool-names.ts (a dependency-free module).
  * This file re-exports them for convenience. Import from here or tool-names.ts.
  */
-export { TOOL_NAMES, type ToolName, DIRECT_TOOL_NAMES, META_TOOL_NAMES, META_REGISTRY_TOOL_NAMES, getAllToolNames, } from './tool-names.js';
+export { TOOL_NAMES, type ToolName, DIRECT_TOOL_NAMES, HOT_TOOL_NAMES, WARM_TOOL_NAMES, META_TOOL_NAMES, META_REGISTRY_TOOL_NAMES, getAllToolNames, } from './tool-names.js';
 import { TodoStore, type Tool } from '@compilr-dev/sdk';
 export declare const todoStore: TodoStore;
 import { setMetaToolFilter, getRegisteredMetaTools } from './tools/meta-tools.js';
@@ -32,9 +32,10 @@ export declare function createToolRegistry(): unknown[];
 export declare function createMinimalToolRegistry(): unknown[];
 /**
  * Get direct tools that are always available.
- * These are declared normally and can be called by name.
+ * When hotOnly is true, returns only hot tools (7 tools, ~2.1K tokens).
+ * When false/undefined, returns all direct tools (18 tools, ~5.4K tokens).
  */
-export declare function getDirectTools(): Tool[];
+export declare function getDirectTools(hotOnly?: boolean): Tool[];
 /**
  * Get meta-tools for agent registration.
  * Only get_tool_info is kept as a direct tool — use_tool and list_tools
@@ -47,11 +48,18 @@ export declare function getMetaTools(): Tool[];
  * checks the meta-registry and executes it transparently.
  */
 export declare function createToolFallback(): (name: string, input: Record<string, unknown>) => Promise<import('@compilr-dev/sdk').ToolExecutionResult | null>;
+/**
+ * Check if hot-tools mode is active.
+ * When true, only hot tools are declared as direct schemas; warm tools are in meta-registry.
+ */
+export declare function isHotToolsMode(): boolean;
 /**
  * Initialize the meta-tool registry with specialized tools.
+ * When includeWarmTools is true, warm tools are also added to the meta-registry
+ * (enabling hot-tools mode where only 7 core tools are declared directly).
  * Call this once at startup.
  */
-export declare function initializeMetaTools(): void;
+export declare function initializeMetaTools(includeWarmTools?: boolean): void;
 /**
  * Get the tool index for the system prompt.
  * This lists all meta-registry tools with their signatures.
@@ -71,6 +79,8 @@ export declare function isMetaToolsEnabled(): boolean;
  */
 export declare function getToolStats(): {
     directTools: number;
+    hotTools: number;
+    warmTools: number;
     metaRegistryTools: number;
     totalTools: number;
     estimatedDirectTokens: number;