praxis-agent 0.49.0 → 0.51.0

package/README.md

@@ -212,7 +212,13 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and append-only `praxis.transcript` JSONL sessions under `~/.praxis`,
   with bounded MCP connection, discovery, and tool operations plus safe
-  disconnect recovery that never replays an already-dispatched call.
+  disconnect recovery that never replays an already-dispatched call. Default
+  tool selection defers `mcp__*` schemas behind a turn-scoped `ToolSearch`;
+  each query activates at most eight deterministic matches for the next model
+  request, and published MCP tool descriptions are capped at 2,048 Unicode
+  code points. Explicit concrete `--tools` selections load selected tools
+  directly, while `--disallowedTools ToolSearch` restores the complete tool
+  list.
 - **Provider-neutral models** — native Provider Registry/Vault routing, API
   adapters, an experimental Codex OAuth adapter, explicit capability checks,
   separate per-attempt connect, byte-idle, and absolute-total timeouts, typed
@@ -304,7 +310,7 @@ normal/low-capability full-frame p95 budgets of `<16.7/<33 ms`.
 `npm run test:coverage` measures all production code under `src/**` with V8 and
 enforces global floors of 79% statements, 70% branches, 85% functions, and 81% lines,
 and rejects any production runtime module with zero covered statements (while allowing
-type-only modules). `npm run test:fixtures` executes the 69-behavior native contract; 61 behaviors
+type-only modules). `npm run test:fixtures` executes the 70-behavior native contract; 62 behaviors
 are qualified and 8 are explicitly excluded. `npm run verify:fixture-contracts`
 performs the structural check and is part of `npm run check`.
 `npm run test:core-completion` is retained as a compatibility alias for

package/dist/application/session-service.d.ts

@@ -39,6 +39,7 @@ export interface ClaudeSessionServiceOptions {
     claudeVersion: string;
     provider?: ModelProvider;
     tools?: ToolRegistry;
+    deferMcpTools?: boolean;
     permissions?: PermissionResolver;
     permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
     permissionMode?: ClaudePermissionMode;

package/dist/application/session-service.js

@@ -49,6 +49,7 @@ import { ClaudeWorktreeToolRegistry } from '../tools/claude-worktree-tools.js';
 import { completeMeteredModelRequest } from './metered-model-completion.js';
 import { SessionMemoryController, SessionMemoryStateError, SessionMemoryStore, } from './session-memory.js';
 import { FilteredToolRegistry } from '../tools/filtered-tool-registry.js';
+import { DeferredToolCatalog } from '../tools/deferred-tool-catalog.js';
 import { ClaudeCapabilityToolRegistry, resolveClaudeToolCapabilities, } from '../tools/claude-capabilities.js';
 import { generateToolUseSummary } from './tool-use-summary.js';
 import { ClaudeUserMessageToolRegistry, } from '../tools/claude-user-message.js';
@@ -1108,6 +1109,9 @@ export class ClaudeSessionService {
                     ? { providerForModel: this.options.providerForModel }
                     : {}),
                 baseTools: wrappedBase,
+                ...(this.options.deferMcpTools === undefined
+                    ? {}
+                    : { deferMcpTools: this.options.deferMcpTools }),
                 permissions: this.options.permissions,
                 ...(this.options.permissionResolverForMode
                     ? {
@@ -2846,6 +2850,9 @@ export class ClaudeSessionService {
                             ? { providerForModel: this.options.providerForModel }
                             : {}),
                         baseTools,
+                        ...(this.options.deferMcpTools === undefined
+                            ? {}
+                            : { deferMcpTools: this.options.deferMcpTools }),
                         permissions: turnPermissions,
                         ...(this.options.permissionResolverForMode
                             ? {
@@ -3024,9 +3031,16 @@ export class ClaudeSessionService {
                 const structuredTools = this.options.structuredOutputSchema && structuredCapture
                     ? new StructuredOutputRegistry(agentScopedTools ?? this.options.tools ?? emptyToolRegistry, this.options.structuredOutputSchema, structuredCapture)
                     : agentScopedTools;
-                const hookTools = this.options.hooks && structuredTools && turnPermissions
+                const activeTurnTools = structuredTools
+                    ? new DeferredToolCatalog(structuredTools).startTurn({
+                        enabled: this.options.deferMcpTools !== false &&
+                            !(agent && agent.tools !== undefined),
+                        restoredToolNames: unresolvedToolCalls.map((call) => call.name),
+                    })
+                    : undefined;
+                const hookTools = this.options.hooks && activeTurnTools && turnPermissions
                     ? new ClaudeHookToolCoordinator({
-                        tools: structuredTools,
+                        tools: activeTurnTools,
                         permissions: turnPermissions,
                         hooks: this.options.hooks,
                         session: hookSession,
@@ -3063,7 +3077,7 @@ export class ClaudeSessionService {
                     ...(hookTools
                         ? { tools: hookTools, permissions: hookTools }
                         : {
-                            ...(structuredTools ? { tools: structuredTools } : {}),
+                            ...(activeTurnTools ? { tools: activeTurnTools } : {}),
                             ...(turnPermissions ? { permissions: turnPermissions } : {}),
                         }),
                 });
@@ -3446,8 +3460,8 @@ export class ClaudeSessionService {
                     let compactionDurationMs;
                     let compactionDurationWithoutRetriesMs;
                     let compactionModelUsage;
-                    const definitions = provider.capabilities.tools
-                        ? (structuredTools?.definitions() ?? [])
+                    const currentDefinitions = () => provider.capabilities.tools
+                        ? (activeTurnTools?.definitions() ?? [])
                         : [];
                     const budget = this.contextBudget(provider);
                     const contextEngine = new ContextEngine({
@@ -3526,7 +3540,7 @@ export class ClaudeSessionService {
                                         ...pendingMessages,
                                     ]),
                                 ],
-                                tools: definitions,
+                                tools: currentDefinitions(),
                             };
                         },
                         irreducible: () => ({
@@ -3540,12 +3554,13 @@ export class ClaudeSessionService {
                                     })),
                                 ]),
                             ],
-                            tools: definitions,
+                            tools: currentDefinitions(),
                         }),
                         propose: async () => {
                             const activeNativeLease = nativeLease;
                             if (!budget)
                                 throw new Error('Context budget is unavailable');
+                            const definitions = currentDefinitions();
                             const historyMessages = activeTurnMessages();
                             if (historyMessages.length === 0)
                                 throw new Error('Cannot compact an empty native transcript');
@@ -3754,7 +3769,10 @@ export class ClaudeSessionService {
                                 ]),
                             ];
                             return {
-                                envelope: { messages: proposedMessages, tools: definitions },
+                                envelope: {
+                                    messages: proposedMessages,
+                                    tools: definitions,
+                                },
                                 commit: async () => {
                                     if (signal?.aborted)
                                         throw new AgentRunCancelledError();
@@ -4062,6 +4080,7 @@ export class ClaudeSessionService {
                         };
                     }
                     if (shellCommand === undefined && budget) {
+                        const definitions = currentDefinitions();
                         await contextEngine.prepare(contextTransitionPort([], currentTurnUserMessages ?? []), signal);
                         budget.assertFits(budget.evaluate([
                             ...contextMessages,
@@ -4387,6 +4406,7 @@ export class ClaudeSessionService {
                         ...contextMessages,
                         ...injectTurnContext(memorySnapshot),
                     ];
+                    const definitions = currentDefinitions();
                     const currentContextTokens = contextEngine.report({
                         messages: providerVisibleMessages,
                         tools: definitions,

package/dist/application/subagent-service.d.ts

@@ -59,6 +59,7 @@ export interface ClaudeSubagentExecutorOptions {
     claudeVersion: string;
     provider: ModelProvider;
     baseTools: ToolRegistry;
+    deferMcpTools?: boolean;
     permissions: PermissionResolver;
     permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
     parentPermissionMode?: () => AgentPermissionMode;

package/dist/application/subagent-service.js

@@ -10,6 +10,7 @@ import { ContextBudget } from '../core/context-budget.js';
 import { AgentRuntime, } from '../core/runtime.js';
 import { composePermissionResolvers } from '../core/permission-policy.js';
 import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
+import { DeferredToolCatalog } from '../tools/deferred-tool-catalog.js';
 import { BUILTIN_STATUSLINE_AGENT_PATH, } from '../extensions/claude-extensions.js';
 import { ClaudeHookToolCoordinator } from '../hooks/claude-hook-tools.js';
 import { InMemorySidechainStore } from '../persistence/in-memory-sidechain-store.js';
@@ -2059,9 +2060,14 @@ export class ClaudeSubagentExecutor {
                 ? new RestrictedToolRegistry(structuredOnlyTools, ['Read', 'Edit'])
                 : structuredOnlyTools, options.outputSchema, options.structuredOutput)
             : scopedTools;
+        const activeAgentTools = new DeferredToolCatalog(agentTools).startTurn({
+            enabled: this.options.deferMcpTools !== false &&
+                customAgent?.tools === undefined,
+            restoredToolNames: nativeRecoveryCalls.map((call) => call.name),
+        });
         const runtimeTools = scopedHooks
             ? new ClaudeHookToolCoordinator({
-                tools: agentTools,
+                tools: activeAgentTools,
                 permissions,
                 hooks: scopedHooks,
                 session: hookSession,
@@ -2072,7 +2078,7 @@ export class ClaudeSubagentExecutor {
                     }
                     : {}),
             })
-            : agentTools;
+            : activeAgentTools;
         const runtimePermissions = scopedHooks
             ? runtimeTools
             : permissions;
@@ -2241,9 +2247,7 @@ export class ClaudeSubagentExecutor {
                         : { reserveTokens: this.options.contextReserveTokens }),
                 })
                 : null;
-            const definitions = options.provider.capabilities.tools
-                ? runtimeTools.definitions()
-                : [];
+            const currentDefinitions = () => options.provider.capabilities.tools ? runtimeTools.definitions() : [];
             let observedMessages;
             let stableSystemMessageCount = 0;
             const assembleMessages = async () => {
@@ -2272,6 +2276,7 @@ export class ClaudeSubagentExecutor {
                 ];
                 observedMessages = messages;
                 if (contextBudget) {
+                    const definitions = currentDefinitions();
                     contextBudget.assertFits(contextBudget.evaluate(messages, definitions));
                 }
                 return messages;
@@ -2393,7 +2398,7 @@ export class ClaudeSubagentExecutor {
                 ...(options.signal ? { signal: options.signal } : {}),
             };
             const result = await runtime.run(runtimeRequest);
-            contextBudget?.observeUsage(result.usage, observedMessages ?? [], definitions);
+            contextBudget?.observeUsage(result.usage, observedMessages ?? [], currentDefinitions());
             this.options.eventSink?.({
                 type: 'task-progress',
                 taskId: options.agentId,

package/dist/cli-runtime.d.ts

@@ -24,6 +24,11 @@ import { executeProviderAuthCommand } from './cli/provider-auth-command.js';
 import { type PluginEvalDependencies } from './plugins/claude-plugin-eval.js';
 import { type ProjectEvalDependencies } from './evals/project-eval.js';
 import { type SelfUpdateResult } from './maintenance/self-update.js';
+export declare function shouldDeferMcpTools(input: {
+    simpleMode: boolean;
+    tools?: readonly string[] | undefined;
+    disallowedTools: readonly string[];
+}): boolean;
 export { parseContextEnvironment, parseProviderEnvironment };
 export interface CliIO {
     stdout(message: string | Uint8Array): void;

package/dist/cli-runtime.js

@@ -77,6 +77,16 @@ import { formatDoctorReport, runDoctor } from './maintenance/doctor.js';
 import { runSelfUpdate, } from './maintenance/self-update.js';
 import { executeClaudeProjectPurge, planClaudeProjectPurge, } from './application/claude-project-purge.js';
 const VERSION = createRequire(import.meta.url)('../package.json').version;
+export function shouldDeferMcpTools(input) {
+    if (input.tools?.includes('ToolSearch')) {
+        throw new Error('Unknown tool in --tools: ToolSearch');
+    }
+    return (!input.simpleMode &&
+        !input.disallowedTools.includes('ToolSearch') &&
+        (input.tools === undefined ||
+            (input.tools.length > 0 &&
+                input.tools.every((tool) => tool === 'default'))));
+}
 function fileResourceBaseUrl(environment, providerEnvironment) {
     return (environment.PRAXIS_FILES_BASE_URL ??
         providerEnvironment?.baseUrl ??
@@ -981,6 +991,11 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             ? {}
             : { permissionMode: interactivePermissionMode }),
     }, cwd);
+    const deferMcpTools = shouldDeferMcpTools({
+        simpleMode,
+        tools: cli.tools,
+        disallowedTools: cli.disallowedTools,
+    });
     if (experimentalNativeTranscriptWrites) {
         const incompatible = [
             ['sessionPersistence', cli.sessionPersistence === false],
@@ -1208,6 +1223,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                 pricing: ModelPricingRegistry.fromEnvironment(runtimeEnvironment.PRAXIS_PRICING_JSON),
             }),
         collectMetrics: true,
+        deferMcpTools,
         ...(!experimentalNativeTranscriptWrites && sessionMemoryProviderFactory
             ? { sessionMemoryProviderFactory }
             : {}),

package/dist/core/runtime.js

@@ -337,9 +337,6 @@ export class AgentRuntime {
         let linesRemoved = 0;
         let activeAttemptHasPresentation = false;
         let activeAttemptDiscarded = false;
-        const definitions = this.provider.capabilities.tools
-            ? (this.options.tools?.definitions() ?? [])
-            : [];
         const maxModelTurns = request.maxModelTurns ?? this.options.maxModelTurns;
         if (maxModelTurns !== undefined &&
             (!Number.isSafeInteger(maxModelTurns) || maxModelTurns <= 0)) {
@@ -414,6 +411,9 @@ export class AgentRuntime {
                             stableSystemMessageCount: request.stableSystemMessageCount,
                         }),
                 };
+                const definitions = this.provider.capabilities.tools
+                    ? (this.options.tools?.definitions() ?? [])
+                    : [];
                 if (definitions.length > 0)
                     providerRequest.tools = definitions;
                 if (request.signal)

package/dist/hooks/claude-hook-tools.d.ts

@@ -20,9 +20,11 @@ export declare class ClaudeHookToolCoordinator implements ToolRegistry, Permissi
     private readonly prepared;
     constructor(options: ClaudeHookToolCoordinatorOptions);
     definitions(): readonly import("../core/runtime.js").ModelToolDefinition[];
-    schedulingPolicy(): {
+    schedulingPolicy(call: ModelToolCall): {
         concurrency: "exclusive";
         startAfterAssistant: boolean;
+        abortGroupOnError?: boolean;
+        cancelOnInterrupt?: boolean;
     };
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     resolve(call: ModelToolCall, context?: PermissionResolutionContext): Promise<PermissionDecision>;

package/dist/hooks/claude-hook-tools.js

@@ -8,8 +8,15 @@ export class ClaudeHookToolCoordinator {
     definitions() {
         return this.options.tools.definitions();
     }
-    schedulingPolicy() {
+    schedulingPolicy(call) {
+        const wrapped = this.options.tools.schedulingPolicy?.(call);
         return {
+            ...(wrapped?.cancelOnInterrupt === undefined
+                ? {}
+                : { cancelOnInterrupt: wrapped.cancelOnInterrupt }),
+            ...(wrapped?.abortGroupOnError === undefined
+                ? {}
+                : { abortGroupOnError: wrapped.abortGroupOnError }),
             concurrency: 'exclusive',
             startAfterAssistant: true,
         };

package/dist/mcp/claude-mcp-tools.js

@@ -21,6 +21,10 @@ function sanitizeMcpUnicode(value) {
         .replace(/[\p{Cf}\p{Co}\p{Cn}]/gu, '')
         .replace(/[\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF\uE000-\uF8FF]/gu, '');
 }
+const MAX_MCP_TOOL_DESCRIPTION_CODE_POINTS = 2_048;
+function capMcpToolDescription(value) {
+    return [...value].slice(0, MAX_MCP_TOOL_DESCRIPTION_CODE_POINTS).join('');
+}
 const MAX_RESOURCE_BYTES = 25 * 1024 * 1024;
 const NO_MCP_RESOURCES = 'No resources found. MCP servers may still provide tools even if they have no resources.';
 const MCP_RESOURCE_TOOL_DEFINITIONS = [
@@ -1250,7 +1254,7 @@ export class ClaudeMcpToolRegistry {
                 sensitiveValues,
                 definition: {
                     name,
-                    description: redactSensitiveText(tool.description ?? `MCP tool ${tool.name} from ${serverName}`, sensitiveValues),
+                    description: capMcpToolDescription(redactSensitiveText(tool.description ?? `MCP tool ${tool.name} from ${serverName}`, sensitiveValues)),
                     inputSchema: redactSensitiveValue(tool.inputSchema, sensitiveValues),
                 },
             };

package/dist/permissions/claude-permission-resolver.js

@@ -12,6 +12,7 @@ import { validateSedSafety } from './sed-safety.js';
 import { parseShellRule, shellRuleMatches } from './shell-rule-matching.js';
 import { effectiveAdditionalDirectories, effectivePermissionMode, filePermissionSuggestions, permissionRuleValueFromString, permissionRuleStringIsValid, permissionRuleValueToString, shellInputIsReadOnly, shellPermissionSuggestions, shellSubcommands, skillPermissionSuggestions, } from './permission-updates.js';
 const DEFAULT_BEHAVIOR = {
+    ToolSearch: 'allow',
     Agent: 'allow',
     SendMessage: 'allow',
     SendUserMessage: 'allow',

package/dist/tools/deferred-tool-catalog.d.ts

@@ -0,0 +1,11 @@
+import type { ToolRegistry } from '../core/runtime.js';
+export declare class DeferredToolCatalog {
+    private readonly base;
+    private readonly definitions;
+    constructor(base: ToolRegistry);
+    startTurn(options?: {
+        enabled?: boolean;
+        restoredToolNames?: readonly string[];
+    }): ToolRegistry;
+}
+//# sourceMappingURL=deferred-tool-catalog.d.ts.map

package/dist/tools/deferred-tool-catalog.js

@@ -0,0 +1,145 @@
+import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
+const TOOL_SEARCH = 'ToolSearch';
+const MAX_MATCHES = 8;
+const isDeferred = (definition) => definition.name.startsWith('mcp__');
+const truncateCodePoints = (value, max) => Array.from(value).slice(0, max).join('');
+const toolSearchDefinition = {
+    name: TOOL_SEARCH,
+    description: 'Search available MCP tools. A successful search activates matching tools, whose schemas appear on the next model request.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', minLength: 1, maxLength: 256 },
+        },
+        required: ['query'],
+        additionalProperties: false,
+    },
+};
+function invalidSearch() {
+    return { content: 'Invalid ToolSearch input', isError: true };
+}
+function summary(definition) {
+    const text = definition.description || '(no description)';
+    return Array.from(text).length > 240
+        ? `${truncateCodePoints(text, 237)}...`
+        : text;
+}
+class ActiveDeferredToolRegistry {
+    base;
+    definitionsByOrder;
+    active = new Set();
+    deferred;
+    constructor(base, definitionsByOrder, restoredToolNames) {
+        this.base = base;
+        this.definitionsByOrder = definitionsByOrder;
+        this.deferred = definitionsByOrder.filter(isDeferred);
+        for (const name of restoredToolNames) {
+            if (this.deferred.some((definition) => definition.name === name))
+                this.active.add(name);
+        }
+    }
+    definitions() {
+        const visible = this.definitionsByOrder.filter((definition) => !isDeferred(definition) || this.active.has(definition.name));
+        return [...visible, toolSearchDefinition];
+    }
+    schedulingPolicy(call) {
+        if (call.name === TOOL_SEARCH)
+            return { concurrency: 'exclusive', cancelOnInterrupt: true };
+        this.assertAvailable(call.name);
+        return resolveToolSchedulingPolicy(this.base, call);
+    }
+    async prepare(call, context) {
+        if (call.name === TOOL_SEARCH)
+            return call;
+        this.assertAvailable(call.name);
+        return this.base.prepare(call, context);
+    }
+    async execute(call, context) {
+        if (call.name === TOOL_SEARCH)
+            return this.search(call);
+        this.assertAvailable(call.name);
+        return this.base.execute(call, context);
+    }
+    assertAvailable(name) {
+        if (this.deferred.some((definition) => definition.name === name) &&
+            !this.active.has(name)) {
+            throw new Error(`Tool ${name} is inactive; call ToolSearch first`);
+        }
+    }
+    search(call) {
+        const input = call.input;
+        if (!input ||
+            typeof input !== 'object' ||
+            Array.isArray(input) ||
+            Object.keys(input).length !== 1 ||
+            typeof input.query !== 'string' ||
+            input.query.trim().length < 1 ||
+            Array.from(input.query).length > 256)
+            return invalidSearch();
+        const query = input.query.trim().toLowerCase();
+        const tokens = query.split(/\s+/);
+        const candidates = this.deferred
+            .map((definition, index) => ({ definition, index }))
+            .filter(({ definition }) => {
+            const haystack = `${definition.name} ${definition.description}`.toLowerCase();
+            return tokens.every((token) => haystack.includes(token));
+        })
+            .sort((left, right) => {
+            const score = (item) => {
+                const name = item.definition.name.toLowerCase();
+                if (name === query)
+                    return 0;
+                if (name.startsWith(query))
+                    return 1;
+                if (name.includes(query))
+                    return 2;
+                if (item.definition.description.toLowerCase().includes(query))
+                    return 3;
+                return 4;
+            };
+            return score(left) - score(right) || left.index - right.index;
+        })
+            .slice(0, MAX_MATCHES);
+        const newlyActivated = candidates.filter(({ definition }) => !this.active.has(definition.name));
+        const alreadyActive = candidates.filter(({ definition }) => this.active.has(definition.name));
+        for (const { definition } of candidates)
+            this.active.add(definition.name);
+        const names = candidates.map(({ definition }) => definition.name);
+        let content = names.length
+            ? 'Matching MCP tools were found; their schemas will appear on the next model request.'
+            : 'No matching MCP tools found; no schemas were activated.';
+        if (names.length) {
+            if (newlyActivated.length) {
+                content += `\nActivated: ${newlyActivated.map(({ definition }) => definition.name).join(', ')}`;
+            }
+            if (alreadyActive.length) {
+                content += `\nAlready active: ${alreadyActive.map(({ definition }) => definition.name).join(', ')}`;
+            }
+            content += `\n${candidates.map(({ definition }) => `${definition.name}: ${summary(definition)}`).join('\n')}`;
+        }
+        return { content: truncateCodePoints(content, 4096), isError: false };
+    }
+}
+export class DeferredToolCatalog {
+    base;
+    definitions;
+    constructor(base) {
+        this.base = base;
+        this.definitions = [...base.definitions()];
+    }
+    startTurn(options = {}) {
+        const deferred = this.definitions.some(isDeferred);
+        if (options.enabled === false || !deferred)
+            return this.base;
+        const seen = new Set();
+        for (const definition of this.definitions) {
+            if (seen.has(definition.name))
+                throw new Error(`Duplicate tool definition: ${definition.name}`);
+            seen.add(definition.name);
+        }
+        if (seen.has(TOOL_SEARCH))
+            throw new Error(`Tool definition collision: ${TOOL_SEARCH}`);
+        return new ActiveDeferredToolRegistry(this.base, this.definitions, options.restoredToolNames ?? []);
+    }
+}
+//# sourceMappingURL=deferred-tool-catalog.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",