@withpica/mcp-server 2.52.0 → 2.52.2

package/dist/tools/index.js

@@ -2,6 +2,7 @@
 import { WorksTools } from "./works.js";
 import { PeopleTools } from "./people.js";
 import { GroupsTools } from "./groups.js";
+import { ShareSendTools } from "./share-send.js";
 import { RecordingsTools } from "./recordings.js";
 import { SearchTools } from "./search.js";
 import { LicensingTools } from "./licensing.js";
@@ -10,6 +11,7 @@ import { AudioFilesTools } from "./audio-files.js";
 import { MultimediaTools } from "./multimedia.js";
 import { AgreementsTools } from "./agreements.js";
 import { MemoryTools } from "./memory.js";
+import { SkillsTools } from "./skills.js";
 import { EnrichmentTools } from "./enrichment.js";
 import { BulkTools } from "./bulk.js";
 import { ExportTools } from "./exports.js";
@@ -36,7 +38,6 @@ import { CalendarTools } from "./calendar.js";
 import { SplitSheetsTools } from "./split-sheets.js";
 import { AgreementTypesTools } from "./agreement-types.js";
 import { DashboardTools } from "./dashboard.js";
-import { IntegrationsTools } from "./integrations.js";
 import { SettingsTools } from "./settings.js";
 import { FeedbackTools } from "./feedback.js";
 import { StorageConfigTools } from "./storage-config.js";
@@ -44,9 +45,13 @@ import { SubscriptionTools } from "./subscription.js";
 import { OnboardingTools } from "./onboarding.js";
 import { ReportIssueTools } from "./report-issue.js";
 import { MyReportedIssuesTools } from "./my-reported-issues.js";
+import { MyRecentQuestionsTools } from "./my-recent-questions.js";
 import { AgentIdentityTools } from "./agent-identity.js";
 import { RoyaltiesTools } from "./royalties.js";
 import { ShareLinksTools } from "./share-links.js";
+import { SharingTools } from "./sharing.js";
+import { ExplainabilityTools } from "./explainability.js";
+import { AccessSimulateTools } from "./access-simulate.js";
 import { DisputesTools } from "./disputes.js";
 import { CustodyTools } from "./custody.js";
 import { PurchasesTools } from "./purchases.js";
@@ -66,6 +71,46 @@ import { getToolMetadata } from "./metadata.js";
 import { getRecoveryHint } from "./recovery-hints.js";
 import { generateConfirmationToken, validateAndConsumeToken, } from "@withpica/mcp-utils";
 import { buildSessionState, incrementSessionMutations, resetSinceLastBriefing, } from "@withpica/mcp-utils";
+/**
+ * ADR-230 — derive the MCP-standard 3-value risk classification from the
+ * declared tier. Sourced once at registration and at audit-write time so
+ * the contract that hints, audit row, and confirmation requirement all
+ * agree is mechanical.
+ */
+export function tierToRiskLevel(tier) {
+    switch (tier) {
+        case "read":
+            return "safe";
+        case "draft":
+        case "write":
+            return "mutating";
+        case "destructive":
+            return "destructive";
+    }
+}
+/**
+ * ADR-230 — derive the required API-key scope from the declared tier.
+ *
+ *  - `read`        → `read:<resource>` (write:* satisfies via `hasScope`).
+ *  - `draft|write` → `write:<resource>`.
+ *  - `destructive` → `destructive:*` (admin satisfies via `hasScope`); the
+ *                    write:<resource> scope is also required for the
+ *                    underlying write surface.
+ *
+ * Returns the *additional* scope tier beyond per-resource. Resource scope
+ * is composed at call-site by `lib/services/mcp-scopes.ts`.
+ */
+export function tierToScopeKind(tier) {
+    switch (tier) {
+        case "read":
+            return "read";
+        case "draft":
+        case "write":
+            return "write";
+        case "destructive":
+            return "destructive";
+    }
+}
 /**
  * Build a tool description with metadata injected.
  * Format: "[category] original description"
@@ -85,6 +130,64 @@ export const CATEGORY_DISPLAY = {
     comms: "send and share",
     settings: "manage your account and team",
 };
+/**
+ * Sanitize tool parameters for `mcp_audit_log.parameters`. Pure function
+ * so it's directly testable; the registry's private method delegates here.
+ *
+ * Security audit 2026-05-11 P2. The audit log is queryable by anyone with
+ * team-portal access. Tools like `pica_sign_in`, `pica_share_links_*`,
+ * and `team_comms_send` previously landed bare emails / share tokens /
+ * OAuth refresh tokens in the log because the only redaction was a
+ * `delete sanitized.confirmation_token` + length truncation.
+ *
+ * Deny-list is keyed off the param name (case-insensitive substring
+ * match) — covers `password`, `api_key`, `token`, `secret`,
+ * `authorization`, plus `confirmation_token` via the `token` substring.
+ * Sister keys like `refresh_token` / `id_token` / `access_token` /
+ * `share_token` / `client_secret` also match.
+ *
+ * Email values (regardless of param key) get the local-part masked to
+ * the first two characters: `jane@example.com` → `ja***@example.com`.
+ * Locals ≤ 2 chars become all-asterisk.
+ *
+ * Strings > 500 chars are truncated to 500 + `...[truncated]`.
+ *
+ * Exported under `_internal` so test files can exercise the function
+ * without instantiating a `ToolRegistry`.
+ */
+function sanitizeAuditParams(args) {
+    const sanitized = { ...args };
+    const denyKeySubstrings = [
+        "password",
+        "api_key",
+        "token",
+        "secret",
+        "authorization",
+    ];
+    for (const [key, value] of Object.entries(sanitized)) {
+        const lowerKey = key.toLowerCase();
+        if (denyKeySubstrings.some((needle) => lowerKey.includes(needle))) {
+            sanitized[key] = "[redacted]";
+            continue;
+        }
+        if (typeof value === "string" &&
+            /^[^\s@]{1,64}@[^\s@]{1,255}\.[^\s@]+$/.test(value)) {
+            const atIdx = value.indexOf("@");
+            const local = value.slice(0, atIdx);
+            const domain = value.slice(atIdx);
+            const maskedLocal = local.length <= 2
+                ? "*".repeat(local.length)
+                : `${local.slice(0, 2)}***`;
+            sanitized[key] = `${maskedLocal}${domain}`;
+            continue;
+        }
+        if (typeof value === "string" && value.length > 500) {
+            sanitized[key] = value.substring(0, 500) + "...[truncated]";
+        }
+    }
+    return sanitized;
+}
+export const _internal = { sanitizeAuditParams };
 export class ToolRegistry {
     tools;
     pica;
@@ -111,6 +214,25 @@ export class ToolRegistry {
     setCallerContext(context) {
         this.callerContext = context;
     }
+    /**
+     * Read clientInfo from the MCP `initialize` handshake. SDK populates this
+     * on the per-request `Server` for HTTP and on the long-lived `Server` for
+     * stdio; either way getClientVersion() returns the same shape after the
+     * handshake completes. Returns empty when ctx is absent or the handshake
+     * hasn't run (lobby-mode dispatches that bypass the per-request transport).
+     *
+     * Stamped onto audit rows as provenance only — never used as a permission
+     * boundary, since clientInfo is self-declared by the client.
+     */
+    extractClientInfo(ctx) {
+        const info = ctx?.server?.getClientVersion?.();
+        if (!info)
+            return {};
+        return {
+            client_name: typeof info.name === "string" ? info.name : undefined,
+            client_version: typeof info.version === "string" ? info.version : undefined,
+        };
+    }
     /**
      * Register all available tools
      */
@@ -159,6 +281,11 @@ export class ToolRegistry {
         groupsTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // Share-send tool (ADR-231)
+        const shareSendTools = new ShareSendTools(pica);
+        shareSendTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
         // Recordings tools
         const recordingsTools = new RecordingsTools(pica);
         recordingsTools.getTools().forEach((tool) => {
@@ -199,6 +326,11 @@ export class ToolRegistry {
         memoryTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // Skills tools (ADR-140 Phase 2b — SEP-2640 bridge tool lane)
+        const skillsTools = new SkillsTools();
+        skillsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
         // Enrichment tools
         const enrichmentTools = new EnrichmentTools(pica);
         enrichmentTools.getTools().forEach((tool) => {
@@ -330,11 +462,6 @@ export class ToolRegistry {
         dashboardTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
-        // Integrations tools (connection status)
-        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(pica);
         settingsTools.getTools().forEach((tool) => {
@@ -377,6 +504,21 @@ export class ToolRegistry {
         myReportedIssuesTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // My-recent-questions tool (ADR-226 Phase 5 — pica_my_recent_questions)
+        // — user-scoped read of the Phase 4 substrate (assistant_interactions
+        // joined with mcp_sessions for client identity). Atlas-resolved entry
+        // for "what did I ask the AI?".
+        //
+        // ADR-230 post-ship cleanup — the tier resolver is the registry's
+        // own `getToolTier` shape (declared `tier` on each tool definition).
+        // Lint Rule 13 makes tier required for every customer MCP tool, so
+        // this resolver returns a populated value for all known tools and
+        // `undefined` only for unknown / meta tools — `dominantTier` falls
+        // back to "read" in that case.
+        const myRecentQuestionsTools = new MyRecentQuestionsTools(pica, (name) => this.tools.get(name)?.definition.tier);
+        myRecentQuestionsTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
         // Agent identity tools (ADR-185 Part 1 — session-auth-only MCP surface).
         // The three tools refuse grant-auth callers at the HTTP API layer;
         // the stdio path carries an API key so behaviour is identical either
@@ -395,6 +537,21 @@ export class ToolRegistry {
         shareLinksTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // Sharing trace tool (ADR-232 § Decision 2)
+        const sharingTools = new SharingTools(pica);
+        sharingTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Explainability tools (ADR-232 § Decision 3)
+        const explainabilityTools = new ExplainabilityTools(pica);
+        explainabilityTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // Access simulator — read-only "who would see what?" preview.
+        const accessSimulateTools = new AccessSimulateTools(pica);
+        accessSimulateTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
         // Disputes tools (ADR-139 Step 3)
         const disputesTools = new DisputesTools(pica);
         disputesTools.getTools().forEach((tool) => {
@@ -456,72 +613,15 @@ export class ToolRegistry {
             });
         }
     }
-    // ── Write-safety classification ──
-    // Destructive tools require confirmation before AND summary after.
-    // Mutating tools should present what they'll do and confirm after.
-    // Safe (read-only) tools need no confirmation.
-    static DESTRUCTIVE_PATTERNS = [
-        "_delete",
-        "_bulk_delete",
-        "_merge",
-        "_remove",
-        "_disconnect",
-    ];
-    static MUTATING_PATTERNS = [
-        "_create",
-        "_update",
-        "_bulk_update",
-        "_invite",
-        "_link",
-        "_send_",
-        "_import_",
-        "_execute",
-        "_ingest",
-        "_enrich",
-        "_verify",
-        "_mark_",
-        "_review",
-        "_purchase",
-        "_submit",
-        "_generate",
-        "_set_default",
-        "_duplicate",
-        "_toggle",
-        "_save",
-        "_upload",
-        "_complete",
-        "_analyze",
-        "_analyse",
-        "_identify",
-        "_resend",
-        "_notify",
-    ];
-    // Read-only tools that match mutating patterns by name but are actually safe
-    static SAFE_OVERRIDES = new Set([
-        "pica_collaborators_invites_list",
-        "pica_enrichment_candidates",
-        "pica_enrichment_compare",
-        "pica_find_duplicates",
-        "pica_import_analyze",
-        "pica_import_validate",
-        "pica_import_fields",
-        "pica_import_template",
-        "pica_import_documents_query",
-        "pica_import_documents_inspect",
-        "pica_send_query",
-        "pica_share_links_list",
-    ]);
-    classifyTool(name) {
-        if (ToolRegistry.SAFE_OVERRIDES.has(name)) {
-            return "safe";
-        }
-        if (ToolRegistry.DESTRUCTIVE_PATTERNS.some((p) => name.includes(p))) {
-            return "destructive";
-        }
-        if (ToolRegistry.MUTATING_PATTERNS.some((p) => name.includes(p))) {
-            return "mutating";
-        }
-        return "safe";
+    /**
+     * ADR-230 — declared tier lookup by tool name. Used by the HTTP MCP
+     * dispatcher (`app/api/mcp/route.ts`) to enforce the elevated
+     * `destructive:*` scope on top of the resource-level scope from
+     * `lib/services/mcp-scopes`. Returns undefined for unknown tools or
+     * tools that haven't declared tier yet (legacy tolerance).
+     */
+    getToolTier(name) {
+        return this.tools.get(name)?.definition.tier;
     }
     /**
      * List all available tools with write-safety prefixes injected.
@@ -543,9 +643,14 @@ export class ToolRegistry {
         return toolsToList.map((tool) => {
             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");
+            // ADR-230 — declared tier is the source of truth for hints + risk.
+            // Lint Rule 13 enforces tier presence on every customer MCP tool;
+            // metadata.risk is a quiet fallback for the unlikely case of a tool
+            // that bypasses lint.
+            const declaredTier = definition.tier;
+            const isDestructive = declaredTier
+                ? declaredTier === "destructive"
+                : metadata?.risk === "destructive";
             if (isDestructive) {
                 definition = {
                     ...definition,
@@ -573,6 +678,26 @@ export class ToolRegistry {
                     },
                 };
             }
+            // ADR-230 — derive hints from declared tier when present (every
+            // tool registered in mcp-server/src/tools/*.ts has tier as of
+            // PR-1; the metadata branch stays as a defensive code path).
+            if (declaredTier && metadata) {
+                return {
+                    ...definition,
+                    description: injectMetadataIntoDescription(tool.definition.description, metadata),
+                    annotations: {
+                        title: metadata.display_name,
+                        readOnlyHint: declaredTier === "read",
+                        destructiveHint: declaredTier === "destructive",
+                        idempotentHint: declaredTier !== "destructive" && metadata.retry_safe,
+                        openWorldHint: false,
+                        // ADR-199 extended annotation classes — read by ChatGPT/Claude.ai
+                        // connectors directly. Derived from declared tier so the four
+                        // surfaces (hint, riskLevel, audit row, scope) all agree.
+                        ...this.deriveExtendedAnnotations(definition, metadata, undefined, declaredTier),
+                    },
+                };
+            }
             if (metadata) {
                 return {
                     ...definition,
@@ -583,25 +708,25 @@ export class ToolRegistry {
                         destructiveHint: metadata.risk === "destructive",
                         idempotentHint: metadata.risk !== "destructive" && metadata.retry_safe,
                         openWorldHint: false,
-                        // ADR-199 extended annotation classes — read by ChatGPT/Claude.ai
-                        // connectors directly. Derived from existing metadata so existing
-                        // tools get this for free without per-tool edits.
                         ...this.deriveExtendedAnnotations(definition, metadata),
                     },
                 };
             }
-            // Fallback to old pattern-matching for any tool without explicit metadata
-            const classification = this.classifyTool(definition.name);
+            // ADR-230 — tools without a TOOL_METADATA entry (the 5 lobby
+            // meta-tools — sign_in/out/discover/tool_details/execute) still
+            // declare tier. Source hints from declared tier; default to read
+            // when tier is somehow missing (lint blocks; defensive only).
+            const tierForHints = declaredTier ?? "read";
             const annotations = {
                 title: definition.name,
-                readOnlyHint: classification === "safe",
-                destructiveHint: classification === "destructive",
+                readOnlyHint: tierForHints === "read",
+                destructiveHint: tierForHints === "destructive",
                 idempotentHint: false,
                 openWorldHint: false,
-                // ADR-199: derive the extended classes even without explicit
-                // metadata so the fallback tools also surface category/risk to
-                // ChatGPT/Claude.ai connectors.
-                ...this.deriveExtendedAnnotations(definition, null, classification),
+                // ADR-199: derive the extended classes from declared tier so the
+                // category/risk surface stays aligned with the rest of the
+                // hint/audit/scope chain.
+                ...this.deriveExtendedAnnotations(definition, null, undefined, tierForHints),
             };
             // No risk prefix needed — annotations handle this structurally
             return { ...definition, annotations };
@@ -616,9 +741,16 @@ export class ToolRegistry {
      * edits required for the retrofit. Future tool authors can override by
      * setting fields directly on definition.annotations.
      */
-    deriveExtendedAnnotations(definition, metadata, classification) {
+    deriveExtendedAnnotations(definition, metadata, _classification, declaredTier) {
         const name = definition.name;
-        const risk = metadata?.risk ?? classification ?? "safe";
+        // ADR-230 — declared tier is the source of truth. metadata.risk
+        // remains a quiet fallback for any tool that bypasses lint Rule 13.
+        // (The `_classification` parameter is retained as an unused
+        // positional slot so legacy call signatures continue to compile;
+        // its value is now ignored — classifyTool was removed in PR-3.)
+        const risk = declaredTier
+            ? tierToRiskLevel(declaredTier)
+            : (metadata?.risk ?? "safe");
         // Side-effecting external systems: telegram, send-hub, comms, broadcasts.
         // Pattern-derived so new tools inherit without edits.
         const externalSideEffectPatterns = [
@@ -638,10 +770,16 @@ export class ToolRegistry {
         // the agent wants to confirm — the gap report flagged this as a useful
         // class for ChatGPT to surface in the UI.
         const requiresFollowUpInspection = risk === "mutating" || risk === "destructive";
+        // ADR-230 — destructive tier always requires confirmation. Other tiers
+        // never do via this annotation (per-tool opt-in for `write` tier is
+        // expressed through `previewMode: "two_step_token"`, not here).
+        const requiresConfirmation = declaredTier
+            ? declaredTier === "destructive"
+            : risk === "destructive";
         return {
             riskLevel: risk,
             category: metadata?.category,
-            requiresConfirmation: risk === "destructive",
+            requiresConfirmation,
             createsExternalSideEffects,
             returnsPaginated,
             requiresFollowUpInspection,
@@ -677,6 +815,15 @@ export class ToolRegistry {
                         display_name: displayName,
                     };
                 }
+                case "pica_works_bulk_move_to_performances": {
+                    const count = args.ids?.length || 0;
+                    return {
+                        action: "bulk reclassify works → performances",
+                        target: `${count} ${count === 1 ? "work" : "works"}`,
+                        warning: `this creates ${count} new live_performance row(s) and removes the source work(s) from the catalog. for works with verified identifiers (ISRC/ISWC/MLC) the source is soft-deleted — credits and agreement links survive but are orphaned to the removed work; for unverified works the deletion is permanent. performance metadata is sparse by default and will need filling in.`,
+                        display_name: displayName,
+                    };
+                }
                 case "pica_people_delete": {
                     const person = await pica.people.get(args.id).catch(() => null);
                     const personName = person?.first_name
@@ -689,6 +836,15 @@ export class ToolRegistry {
                         display_name: displayName,
                     };
                 }
+                case "pica_people_bulk_delete": {
+                    const count = args.ids?.length || 0;
+                    return {
+                        action: "bulk delete people",
+                        target: `${count} ${count === 1 ? "person" : "people"}`,
+                        warning: `this will soft-delete ${count} person record(s). credits and agreements remain linked to the removed records.`,
+                        display_name: displayName,
+                    };
+                }
                 case "pica_agreements_delete": {
                     const agreementResult = await pica.agreements
                         .get(args.id)
@@ -834,18 +990,11 @@ export class ToolRegistry {
         }
     }
     /**
-     * Sanitize tool parameters for audit logging.
-     * Strips confirmation tokens and truncates large string values.
+     * Sanitize tool parameters for audit logging — delegates to the
+     * pure-function impl below so it can be exercised directly in tests.
      */
     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;
+        return sanitizeAuditParams(args);
     }
     /**
      * ADR-208 Primitive B — opaque per-org cache key.
@@ -1018,10 +1167,22 @@ export class ToolRegistry {
             throw new ToolExecutionError(`Tool not found: ${name}`);
         }
         const metadata = getToolMetadata(name);
+        // ADR-230 — declared tier is the source of truth for the freshness +
+        // confirmation gates and the audit-log surfaces. Fall back to
+        // metadata.risk only if the tool somehow lacks tier (lint blocks
+        // missing tier on creator + team + directory MCPs as of PR-2).
+        const declaredTier = tool.definition.tier;
+        const fallbackRisk = metadata?.risk ?? "safe";
+        const auditTier = declaredTier ??
+            (fallbackRisk === "safe"
+                ? "read"
+                : fallbackRisk === "destructive"
+                    ? "destructive"
+                    : "write");
+        const auditRiskLevel = tierToRiskLevel(auditTier);
+        const isDestructive = auditTier === "destructive";
         // ── Session freshness gate (ADR-151) ──
-        if (metadata?.risk === "destructive" &&
-            this.config &&
-            !this.config.lobbyMode) {
+        if (isDestructive && 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();
@@ -1039,12 +1200,15 @@ export class ToolRegistry {
                 }
             }
         }
-        // ── Destructive confirmation gate ──
-        if (metadata?.risk === "destructive") {
+        // ── Destructive confirmation gate (ADR-230 — keyed on declared tier) ──
+        if (isDestructive) {
             const confirmationToken = args.confirmation_token;
             if (!confirmationToken) {
-                // First call — generate preview and return confirmation challenge
-                const token = generateConfirmationToken(name, args);
+                // First call — generate preview and return confirmation challenge.
+                // ADR-230 PR-4 — token state lives in Postgres for HTTP MCP under
+                // Fluid Compute (or in-memory for stdio); both paths via the
+                // active ConfirmationStore singleton, so callers stay unchanged.
+                const token = await generateConfirmationToken(name, args);
                 const preview = await this.buildDestructivePreview(name, args);
                 const response = {
                     content: [
@@ -1070,6 +1234,7 @@ export class ToolRegistry {
                     ?.logToolExecution({
                     tool_name: name,
                     tool_category: metadata?.category || "unknown",
+                    tier: "destructive",
                     risk_level: "destructive",
                     parameters: this.sanitizeParams(args),
                     result_status: "confirmation_required",
@@ -1077,12 +1242,14 @@ export class ToolRegistry {
                     execution_time_ms: Date.now() - startTime,
                     caller_identity: this.callerContext.callerIdentity,
                     transport: this.callerContext.transport,
+                    ...this.extractClientInfo(ctx),
                 })
                     .catch(() => { }); // Never block on audit
                 return response;
             }
-            // Second call — validate token
-            const validation = validateAndConsumeToken(confirmationToken, name, args);
+            // Second call — validate token (Postgres-backed under Fluid Compute
+            // since ADR-230 PR-4; the active store handles cross-instance state).
+            const validation = await validateAndConsumeToken(confirmationToken, name, args);
             if (!validation.valid) {
                 return {
                     content: [
@@ -1115,10 +1282,10 @@ export class ToolRegistry {
                 }
             }
             // ADR-208 Primitive B — ambient session-state on write-tool results.
-            // Read tools (`risk: safe` ⇒ `readOnlyHint: true`) skip this entirely so
-            // the high-volume read path stays cheap. `result.isError === true` also
-            // skips because a failed mutation didn't change catalog state.
-            const isWriteTool = (metadata?.risk ?? this.classifyTool(name)) !== "safe";
+            // Read tools (`tier: "read"`) skip this entirely so the high-volume
+            // read path stays cheap. `result.isError === true` also skips because
+            // a failed mutation didn't change catalog state.
+            const isWriteTool = auditRiskLevel !== "safe";
             if (isWriteTool && result && !result.isError) {
                 await this.attachSessionState(result, name);
             }
@@ -1144,12 +1311,14 @@ export class ToolRegistry {
                 ?.logToolExecution({
                 tool_name: name,
                 tool_category: metadata?.category || "unknown",
-                risk_level: metadata?.risk || this.classifyTool(name),
+                tier: auditTier,
+                risk_level: auditRiskLevel,
                 parameters: this.sanitizeParams(args),
                 result_status: "success",
                 execution_time_ms: Date.now() - startTime,
                 caller_identity: this.callerContext.callerIdentity,
                 transport: this.callerContext.transport,
+                ...this.extractClientInfo(ctx),
             })
                 .catch(() => { }); // Never block on audit
             return result;
@@ -1170,13 +1339,19 @@ export class ToolRegistry {
                 ?.logToolExecution({
                 tool_name: name,
                 tool_category: metadata?.category || "unknown",
-                risk_level: metadata?.risk || this.classifyTool(name),
+                tier: auditTier,
+                risk_level: auditRiskLevel,
                 parameters: this.sanitizeParams(args),
                 result_status: "error",
                 error_code: parsed.error,
+                // Stage A — forward the parsed body's message so mcp_audit_log
+                // captures the underlying cause. Without this every error row had
+                // error_message=null, leaving UNKNOWN_ERROR rows opaque.
+                error_message: typeof parsed.message === "string" ? parsed.message : undefined,
                 execution_time_ms: Date.now() - startTime,
                 caller_identity: this.callerContext.callerIdentity,
                 transport: this.callerContext.transport,
+                ...this.extractClientInfo(ctx),
             })
                 .catch(() => { }); // Never block on audit
             return {