@withpica/mcp-server 2.5.2 → 2.5.4

package/dist/tools/index.js

@@ -5,14 +5,11 @@ import { RecordingsTools } from "./recordings.js";
 import { SearchTools } from "./search.js";
 import { LicensingTools } from "./licensing.js";
 import { CreditsTools } from "./credits.js";
-import { PicaScoreTools } from "./pica-score.js";
 import { AudioFilesTools } from "./audio-files.js";
 import { MultimediaTools } from "./multimedia.js";
 import { AgreementsTools } from "./agreements.js";
 import { MemoryTools } from "./memory.js";
 import { EnrichmentTools } from "./enrichment.js";
-import { RegistrationTools } from "./registration.js";
-import { HealthTools } from "./health.js";
 import { BulkTools } from "./bulk.js";
 import { ExportTools } from "./exports.js";
 import { DuplicatesTools } from "./duplicates.js";
@@ -43,239 +40,281 @@ import { ShareLinksTools } from "./share-links.js";
 import { DisputesTools } from "./disputes.js";
 import { PurchasesTools } from "./purchases.js";
 import { TelegramTools } from "./telegram.js";
+import { PublishersTools } from "./publishers.js";
+import { AuthTools } from "./auth.js";
+import { AppTools } from "./app-tools.js";
+import { readCredentials } from "../utils/credentials.js";
 import { formatError, ToolExecutionError } from "../utils/errors.js";
+import { guardResponseSize } from "../utils/formatting.js";
+import { getToolMetadata } from "./metadata.js";
+import { getRecoveryHint } from "./recovery-hints.js";
+import { generateConfirmationToken, validateAndConsumeToken, } from "../utils/confirmation.js";
+/**
+ * Build a tool description with metadata injected.
+ * Format: "[category] original description"
+ */
+export function injectMetadataIntoDescription(description, metadata) {
+    // Category tag helps the agent understand tool grouping.
+    // Risk prefixes removed — annotations (readOnlyHint, destructiveHint) handle this structurally.
+    // Behavioral guidance (tell user what you're doing) is in server instructions (one copy).
+    return `[${metadata.category}] ${description}`;
+}
+export const CATEGORY_DISPLAY = {
+    catalog: "manage your catalog",
+    enrichment: "enrich your metadata",
+    business: "handle business and agreements",
+    discovery: "search and explore",
+    media: "manage photos, audio, and video",
+    comms: "send and share",
+    settings: "manage your account and team",
+};
 export class ToolRegistry {
     tools;
     pica;
-    constructor(pica) {
+    config;
+    reinitializeCallback;
+    auditLogger;
+    constructor(pica, config, reinitializeCallback) {
         this.pica = pica;
+        this.config = config;
+        this.reinitializeCallback = reinitializeCallback;
         this.tools = new Map();
         this.registerAllTools();
     }
+    setAuditLogger(logger) {
+        this.auditLogger = logger;
+    }
     /**
      * Register all available tools
      */
     registerAllTools() {
+        // Auth tools — always registered (lobby + authenticated mode)
+        if (this.config) {
+            const authTools = new AuthTools(this.config, this.reinitializeCallback || (() => { }));
+            authTools.getTools().forEach((tool) => {
+                this.tools.set(tool.definition.name, tool);
+            });
+        }
+        // In lobby mode, only auth tools are available
+        if (this.config?.lobbyMode || !this.pica) {
+            return;
+        }
+        const pica = this.pica;
         // Works tools
-        const worksTools = new WorksTools(this.pica);
+        const worksTools = new WorksTools(pica);
         worksTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // People tools
-        const peopleTools = new PeopleTools(this.pica);
+        const peopleTools = new PeopleTools(pica);
         peopleTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Recordings tools
-        const recordingsTools = new RecordingsTools(this.pica);
+        const recordingsTools = new RecordingsTools(pica);
         recordingsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Search tools
-        const searchTools = new SearchTools(this.pica);
+        const searchTools = new SearchTools(pica);
         searchTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Licensing tools
-        const licensingTools = new LicensingTools(this.pica);
+        const licensingTools = new LicensingTools(pica);
         licensingTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Credits tools
-        const creditsTools = new CreditsTools(this.pica);
+        const creditsTools = new CreditsTools(pica);
         creditsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
-        // PICA Score tools
-        const picaScoreTools = new PicaScoreTools(this.pica);
-        picaScoreTools.getTools().forEach((tool) => {
-            this.tools.set(tool.definition.name, tool);
-        });
         // Audio Files tools
-        const audioFilesTools = new AudioFilesTools(this.pica);
+        const audioFilesTools = new AudioFilesTools(pica);
         audioFilesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Multimedia tools
-        const multimediaTools = new MultimediaTools(this.pica);
+        const multimediaTools = new MultimediaTools(pica);
         multimediaTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Agreements tools
-        const agreementsTools = new AgreementsTools(this.pica);
+        const agreementsTools = new AgreementsTools(pica);
         agreementsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Memory tools
-        const memoryTools = new MemoryTools(this.pica);
+        const memoryTools = new MemoryTools(pica);
         memoryTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Enrichment tools
-        const enrichmentTools = new EnrichmentTools(this.pica);
+        const enrichmentTools = new EnrichmentTools(pica);
         enrichmentTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
-        // Registration tools
-        const registrationTools = new RegistrationTools(this.pica);
-        registrationTools.getTools().forEach((tool) => {
-            this.tools.set(tool.definition.name, tool);
-        });
-        // Health tools
-        const healthTools = new HealthTools(this.pica);
-        healthTools.getTools().forEach((tool) => {
-            this.tools.set(tool.definition.name, tool);
-        });
         // Bulk operations tools
-        const bulkTools = new BulkTools(this.pica);
+        const bulkTools = new BulkTools(pica);
         bulkTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Export tools
-        const exportTools = new ExportTools(this.pica);
+        const exportTools = new ExportTools(pica);
         exportTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Duplicates tools
-        const duplicatesTools = new DuplicatesTools(this.pica);
+        const duplicatesTools = new DuplicatesTools(pica);
         duplicatesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Directory tools
-        const directoryTools = new DirectoryTools(this.pica);
+        const directoryTools = new DirectoryTools(pica);
         directoryTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Collaborator tools
-        const collaboratorsTools = new CollaboratorsTools(this.pica);
+        const collaboratorsTools = new CollaboratorsTools(pica);
         collaboratorsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Upload tools (generic file upload — images, videos, documents)
-        const uploadTools = new UploadTools(this.pica);
+        const uploadTools = new UploadTools(pica);
         uploadTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Document tools (AI analysis)
-        const documentTools = new DocumentTools(this.pica);
+        const documentTools = new DocumentTools(pica);
         documentTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Bulk import tools (CSV import pipeline)
-        const importTools = new ImportTools(this.pica);
+        const importTools = new ImportTools(pica);
         importTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Comparison tools (ADR-116 Phase 2: enrichment + registration comparison)
-        const comparisonTools = new ComparisonTools(this.pica);
+        const comparisonTools = new ComparisonTools(pica);
         comparisonTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Send Hub tools (messages, invites, file requests, audio shares)
-        const sendTools = new SendTools(this.pica);
+        const sendTools = new SendTools(pica);
         sendTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Import document tools
-        const importDocumentTools = new ImportDocumentTools(this.pica);
+        const importDocumentTools = new ImportDocumentTools(pica);
         importDocumentTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Physical assets tools (equipment, instruments, studio gear)
-        const assetsTools = new AssetsTools(this.pica);
+        const assetsTools = new AssetsTools(pica);
         assetsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Work sessions tools (studio session tracking)
-        const sessionsTools = new SessionsTools(this.pica);
+        const sessionsTools = new SessionsTools(pica);
         sessionsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Analytics tools (carbon, provenance, diligence)
-        const analyticsTools = new AnalyticsTools(this.pica);
+        const analyticsTools = new AnalyticsTools(pica);
         analyticsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Notifications tools
-        const notificationsTools = new NotificationsTools(this.pica);
+        const notificationsTools = new NotificationsTools(pica);
         notificationsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Notes tools (catalog notes on works, people, general observations)
-        const notesTools = new NotesTools(this.pica);
+        const notesTools = new NotesTools(pica);
         notesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Team management tools (invite, list, update, remove members)
-        const teamTools = new TeamTools(this.pica);
+        const teamTools = new TeamTools(pica);
         teamTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Projects tools (albums, EPs, compilations — grouping works)
-        const projectsTools = new ProjectsTools(this.pica);
+        const projectsTools = new ProjectsTools(pica);
         projectsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Releases tools (albums, EPs, singles with dates, labels, UPCs)
-        const releasesTools = new ReleasesTools(this.pica);
+        const releasesTools = new ReleasesTools(pica);
         releasesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Calendar tools
-        const calendarTools = new CalendarTools(this.pica);
+        const calendarTools = new CalendarTools(pica);
         calendarTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Split sheets & recording splits tools
-        const splitSheetsTools = new SplitSheetsTools(this.pica);
+        const splitSheetsTools = new SplitSheetsTools(pica);
         splitSheetsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Agreement types tools (templates, producer agreements, work-for-hire)
-        const agreementTypesTools = new AgreementTypesTools(this.pica);
+        const agreementTypesTools = new AgreementTypesTools(pica);
         agreementTypesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Dashboard & discovery tools
-        const dashboardTools = new DashboardTools(this.pica);
+        const dashboardTools = new DashboardTools(pica);
         dashboardTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Integrations tools (connection status)
-        const integrationsTools = new IntegrationsTools(this.pica);
+        const integrationsTools = new IntegrationsTools(pica);
         integrationsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Settings tools (credits history, storage, org profile)
-        const settingsTools = new SettingsTools(this.pica);
+        const settingsTools = new SettingsTools(pica);
         settingsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Royalties & statements tools (ADR-139 Step 2)
-        const royaltiesTools = new RoyaltiesTools(this.pica);
+        const royaltiesTools = new RoyaltiesTools(pica);
         royaltiesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Share links tools (ADR-139 Step 3)
-        const shareLinksTools = new ShareLinksTools(this.pica);
+        const shareLinksTools = new ShareLinksTools(pica);
         shareLinksTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Disputes tools (ADR-139 Step 3)
-        const disputesTools = new DisputesTools(this.pica);
+        const disputesTools = new DisputesTools(pica);
         disputesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Purchases tools (credit checkout)
-        const purchasesTools = new PurchasesTools(this.pica);
+        const purchasesTools = new PurchasesTools(pica);
         purchasesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
         // Telegram tools (user notification channel)
-        const telegramTools = new TelegramTools(this.pica);
+        const telegramTools = new TelegramTools(pica);
         telegramTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // Publishers tools (lookup + create)
+        const publishersTools = new PublishersTools(pica);
+        publishersTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // App tools (MCP Apps — interactive UI cards)
+        const appTools = new AppTools(pica);
+        appTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
     }
     // ── Write-safety classification ──
     // Destructive tools require confirmation before AND summary after.
@@ -320,25 +359,18 @@ export class ToolRegistry {
     // Read-only tools that match mutating patterns by name but are actually safe
     static SAFE_OVERRIDES = new Set([
         "pica_collaborators_invites_list",
-        "pica_completeness_low",
         "pica_enrichment_candidates",
         "pica_enrichment_compare",
-        "pica_enrichment_status",
         "pica_find_duplicates",
         "pica_import_analyze",
         "pica_import_validate",
         "pica_import_fields",
         "pica_import_template",
-        "pica_import_documents_list",
-        "pica_import_documents_get",
-        "pica_import_documents_diff",
-        "pica_send_list",
-        "pica_send_pending",
+        "pica_import_documents_query",
+        "pica_import_documents_inspect",
+        "pica_send_query",
         "pica_share_links_list",
-        "pica_work_completeness",
     ]);
-    static DESTRUCTIVE_PREFIX = "⚠️ DESTRUCTIVE: Before calling this tool, you MUST describe exactly what will be deleted/merged to the user and get explicit confirmation. After execution, confirm what was done and what was affected. ";
-    static MUTATING_PREFIX = "✏️ WRITE OPERATION: Before calling this tool, briefly tell the user what you're about to do. After execution, confirm what was created/changed. ";
     classifyTool(name) {
         if (ToolRegistry.SAFE_OVERRIDES.has(name)) {
             return "safe";
@@ -356,33 +388,330 @@ export class ToolRegistry {
      */
     listTools() {
         return Array.from(this.tools.values()).map((tool) => {
-            const classification = this.classifyTool(tool.definition.name);
-            if (classification === "safe") {
-                return tool.definition;
+            let definition = tool.definition;
+            const metadata = getToolMetadata(definition.name);
+            // Inject confirmation_token into destructive tool schemas
+            const isDestructive = metadata?.risk === "destructive" ||
+                (!metadata && this.classifyTool(definition.name) === "destructive");
+            if (isDestructive) {
+                definition = {
+                    ...definition,
+                    inputSchema: {
+                        ...definition.inputSchema,
+                        properties: {
+                            ...definition.inputSchema.properties,
+                            confirmation_token: {
+                                type: "string",
+                                description: "Confirmation token from a previous call. Required to execute destructive operations. " +
+                                    "Call this tool once without a token to get a preview and token, then call again with the token to confirm.",
+                            },
+                        },
+                    },
+                };
             }
-            const prefix = classification === "destructive"
-                ? ToolRegistry.DESTRUCTIVE_PREFIX
-                : ToolRegistry.MUTATING_PREFIX;
-            return {
-                ...tool.definition,
-                description: prefix + tool.definition.description,
+            // Normalize _meta.ui.resourceUri → legacy "ui/resourceUri" key for older MCP Apps clients
+            if (definition._meta?.ui?.resourceUri &&
+                !definition._meta["ui/resourceUri"]) {
+                definition = {
+                    ...definition,
+                    _meta: {
+                        ...definition._meta,
+                        "ui/resourceUri": definition._meta.ui.resourceUri,
+                    },
+                };
+            }
+            if (metadata) {
+                return {
+                    ...definition,
+                    description: injectMetadataIntoDescription(tool.definition.description, metadata),
+                    annotations: {
+                        title: metadata.display_name,
+                        readOnlyHint: metadata.risk === "safe",
+                        destructiveHint: metadata.risk === "destructive",
+                        idempotentHint: metadata.risk === "safe" && metadata.retry_safe,
+                        openWorldHint: false,
+                    },
+                };
+            }
+            // Fallback to old pattern-matching for any tool without explicit metadata
+            const classification = this.classifyTool(definition.name);
+            const annotations = {
+                title: definition.name,
+                readOnlyHint: classification === "safe",
+                destructiveHint: classification === "destructive",
+                idempotentHint: false,
+                openWorldHint: false,
             };
+            // No risk prefix needed — annotations handle this structurally
+            return { ...definition, annotations };
         });
     }
+    /**
+     * Build a human-readable preview of what a destructive operation will affect.
+     */
+    async buildDestructivePreview(name, args) {
+        const metadata = getToolMetadata(name);
+        const displayName = metadata?.display_name || name;
+        // buildDestructivePreview is only called during tool execution,
+        // which is gated behind lobby mode check — pica is always available here.
+        const pica = this.pica;
+        try {
+            switch (name) {
+                case "pica_works_delete": {
+                    const work = await pica.works.get(args.id).catch(() => null);
+                    const title = work?.title || args.id;
+                    return {
+                        action: "delete work",
+                        target: title,
+                        warning: "this will remove linked credits, agreement links, and audio files. recordings will be unlinked. this cannot be undone for works without verified identifiers.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_works_bulk_delete": {
+                    const count = args.ids?.length || 0;
+                    return {
+                        action: "bulk delete works",
+                        target: `${count} works`,
+                        warning: `this will delete ${count} work(s) and cascade to their credits and agreement links. this cannot be undone for works without verified identifiers.`,
+                        display_name: displayName,
+                    };
+                }
+                case "pica_people_delete": {
+                    const person = await pica.people.get(args.id).catch(() => null);
+                    const personName = person?.first_name
+                        ? `${person.first_name} ${person.last_name || ""}`.trim()
+                        : args.id;
+                    return {
+                        action: "remove person",
+                        target: personName,
+                        warning: "the person record will be soft-deleted. credits and agreements will remain linked.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_agreements_delete": {
+                    const agreementResult = await pica.agreements
+                        .get(args.id)
+                        .catch(() => null);
+                    const title = agreementResult?.agreement?.title || args.id;
+                    return {
+                        action: "delete agreement",
+                        target: title,
+                        warning: "this will remove all linked work and party records. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_merge_duplicates": {
+                    const loserCount = args.loser_ids?.length || 0;
+                    const entityType = args.entity_type || "entities";
+                    return {
+                        action: `merge ${entityType}`,
+                        target: `${loserCount} ${entityType} into winner`,
+                        warning: `all credits, recordings, and agreements from ${loserCount} loser(s) will be moved to the winner. loser records will be permanently deleted. this cannot be undone.`,
+                        display_name: displayName,
+                    };
+                }
+                case "pica_projects_delete": {
+                    const project = await pica.projects?.get(args.id).catch(() => null);
+                    const projectName = project?.name || args.id;
+                    return {
+                        action: "delete project",
+                        target: projectName,
+                        warning: "linked works will be unlinked but not deleted. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                case "pica_team_remove": {
+                    return {
+                        action: "remove team member",
+                        target: args.id,
+                        warning: "their user account will be permanently deleted. works and agreements they contributed will remain. this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+                default: {
+                    return {
+                        action: displayName,
+                        target: args.id || "unknown",
+                        warning: "this cannot be undone.",
+                        display_name: displayName,
+                    };
+                }
+            }
+        }
+        catch {
+            return {
+                action: displayName,
+                target: args.id || "unknown",
+                warning: "this cannot be undone.",
+                display_name: displayName,
+            };
+        }
+    }
+    /**
+     * Sanitize tool parameters for audit logging.
+     * Strips confirmation tokens and truncates large string values.
+     */
+    sanitizeParams(args) {
+        const sanitized = { ...args };
+        delete sanitized.confirmation_token;
+        for (const [key, value] of Object.entries(sanitized)) {
+            if (typeof value === "string" && value.length > 500) {
+                sanitized[key] = value.substring(0, 500) + "...[truncated]";
+            }
+        }
+        return sanitized;
+    }
     /**
      * Execute a tool by name
      */
     async executeTool(name, args) {
+        const startTime = Date.now();
         const tool = this.tools.get(name);
         if (!tool) {
             throw new ToolExecutionError(`Tool not found: ${name}`);
         }
+        const metadata = getToolMetadata(name);
+        // ── Session freshness gate (ADR-151) ──
+        if (metadata?.risk === "destructive" &&
+            this.config &&
+            !this.config.lobbyMode) {
+            const creds = readCredentials(this.config.credentialsPath);
+            if (creds?.authenticated_at) {
+                const authAge = Date.now() - new Date(creds.authenticated_at).getTime();
+                const sevenDays = 7 * 24 * 60 * 60 * 1000;
+                if (authAge > sevenDays) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: 'this action requires re-verification — say "sign me in" to confirm your identity',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+        }
+        // ── Destructive confirmation gate ──
+        if (metadata?.risk === "destructive") {
+            const confirmationToken = args.confirmation_token;
+            if (!confirmationToken) {
+                // First call — generate preview and return confirmation challenge
+                const token = generateConfirmationToken(name, args);
+                const preview = await this.buildDestructivePreview(name, args);
+                const response = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "confirmation_required",
+                                confirmation_token: token,
+                                expires_in: 120,
+                                preview,
+                            }, null, 2),
+                        },
+                    ],
+                    structuredContent: {
+                        status: "confirmation_required",
+                        confirmation_token: token,
+                        expires_in: 120,
+                        preview,
+                    },
+                };
+                // Fire-and-forget audit for confirmation challenge
+                this.auditLogger
+                    ?.logToolExecution({
+                    tool_name: name,
+                    tool_category: metadata?.category || "unknown",
+                    risk_level: "destructive",
+                    parameters: this.sanitizeParams(args),
+                    result_status: "confirmation_required",
+                    confirmation_token: token,
+                    execution_time_ms: Date.now() - startTime,
+                    // TODO(ADR-149): Wire caller_identity from API key hash and transport from server context
+                    caller_identity: "unknown",
+                    transport: "stdio",
+                })
+                    .catch(() => { }); // Never block on audit
+                return response;
+            }
+            // Second call — validate token
+            const validation = validateAndConsumeToken(confirmationToken, name, args);
+            if (!validation.valid) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: validation.reason?.includes("expired")
+                                    ? "CONFIRMATION_EXPIRED"
+                                    : "CONFIRMATION_INVALID",
+                                message: validation.reason,
+                                retry_safe: false,
+                                suggestion: "start the operation again without the confirmation token",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Token valid — fall through to execute
+        }
+        // ── Normal execution ──
         try {
-            return await tool.executor(args);
+            const result = await tool.executor(args);
+            // Guard response size — truncate oversized payloads with recovery hint
+            if (result?.content) {
+                for (const block of result.content) {
+                    if (block.type === "text" && typeof block.text === "string") {
+                        block.text = guardResponseSize(block.text, name);
+                    }
+                }
+            }
+            // Fire-and-forget audit
+            this.auditLogger
+                ?.logToolExecution({
+                tool_name: name,
+                tool_category: metadata?.category || "unknown",
+                risk_level: metadata?.risk || this.classifyTool(name),
+                parameters: this.sanitizeParams(args),
+                result_status: "success",
+                execution_time_ms: Date.now() - startTime,
+                // TODO(ADR-149): Wire caller_identity from API key hash and transport from server context
+                caller_identity: "unknown",
+                transport: "stdio",
+            })
+                .catch(() => { }); // Never block on audit
+            return result;
         }
         catch (error) {
+            const formatted = formatError(error);
+            const parsed = JSON.parse(formatted.text);
+            // Attach recovery hint if available for this tool + error code
+            const hint = getRecoveryHint(name, parsed.error);
+            if (hint) {
+                parsed.suggestion = hint.suggestion;
+                if (hint.next_tool) {
+                    parsed.next_tool = hint.next_tool;
+                }
+            }
+            // Fire-and-forget audit for errors
+            this.auditLogger
+                ?.logToolExecution({
+                tool_name: name,
+                tool_category: metadata?.category || "unknown",
+                risk_level: metadata?.risk || this.classifyTool(name),
+                parameters: this.sanitizeParams(args),
+                result_status: "error",
+                error_code: parsed.error,
+                execution_time_ms: Date.now() - startTime,
+                // TODO(ADR-149): Wire caller_identity from API key hash and transport from server context
+                caller_identity: "unknown",
+                transport: "stdio",
+            })
+                .catch(() => { }); // Never block on audit
             return {
-                content: [formatError(error)],
+                content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
                 isError: true,
             };
         }