@withpica/mcp-server 2.47.0 → 2.49.0

package/dist/tools/index.d.ts

@@ -40,8 +40,74 @@ export interface NextStepHint {
  * lands so every tool is forced to declare its workflow at compile time.
  */
 export type WorkflowTag = "work-required" | "recording-required" | "work-credits-required" | "recording-credits-required" | "person-required" | "audio-upload-required" | "enrichment-resolve-required" | "agreement-required" | "multimedia-required" | "export-required" | "claim-required" | "session-required" | "split-sheet-required" | "recording-splits-required" | "sync-placement-required" | "infrastructure";
+/**
+ * ADR-226 Decision 2 — vernacular intent posture for every tool.
+ *
+ *  - `creator-entry` — Atlas covers it; `Use when the user asks: '...'` block
+ *    in the description is required (Phase 7 lint enforces).
+ *  - `internal` — programmatic handoff between tools (e.g. presigned-PUT
+ *    finalize step). Requires a one-line `vernacular_reason`.
+ *  - `specialist` — mutating / destructive / not-yet-covered context;
+ *    invoked by exact name. Requires a one-line `vernacular_reason`.
+ *
+ * Universal coverage: every tool declares its kind. Phase 7 lint promotes
+ * the field to a required-with-blocking check; Phase 3 (this commit)
+ * leaves it optional during the bulk-classification ramp and flips it to
+ * required in the same commit once all 244 tools have been populated by
+ * `scripts/bulk-classify-vernacular-kind.ts`.
+ */
+export type VernacularKind = "creator-entry" | "internal" | "specialist";
+/**
+ * ADR-230 — authority tier declared on every tool definition.
+ *
+ *  - `read`        — pure query, no state mutation. Maps to readOnlyHint:true,
+ *                    risk_level:"safe", required scope `read:*` (or `write:*`
+ *                    via the read-implies-write rule in `hasScope`).
+ *  - `draft`       — produces a proposal/preview/hint without persisting
+ *                    state. Same hints as `write` (readOnlyHint:false,
+ *                    risk_level:"mutating"). No confirmation token.
+ *  - `write`       — persistent state change. May opt into per-tool
+ *                    confirmation via `previewMode: "two_step_token"`.
+ *  - `destructive` — irreversible state change (delete / merge / send
+ *                    broadcast / disconnect). destructiveHint:true,
+ *                    risk_level:"destructive", confirmation token required,
+ *                    requires elevated `destructive:*` scope (admin satisfies).
+ *
+ * The 4-value `tier` is PICA's authority surface. The 3-value `risk_level`
+ * on `mcp_audit_log` is derived from `tier` (read→safe, draft|write→mutating,
+ * destructive→destructive) — sister of the MCP-standard `readOnlyHint` /
+ * `destructiveHint` fields, kept for ADR-199 client compatibility.
+ */
+export type Tier = "read" | "draft" | "write" | "destructive";
+/**
+ * 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 declare function tierToRiskLevel(tier: Tier): "safe" | "mutating" | "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 declare function tierToScopeKind(tier: Tier): "read" | "write" | "destructive";
 export interface ToolDefinition {
     name: string;
+    /**
+     * ADR-230 — authority tier. Required for every customer-facing tool.
+     * Sourced from per-tool declaration; drives MCP hints, audit-log
+     * `risk_level`, confirmation-token requirement, and required scope.
+     * See {@link Tier} above for semantics.
+     */
+    tier: Tier;
     description: string;
     /**
      * ADR-214 — workflow(s) this tool belongs to. See `WorkflowTag` above.
@@ -50,6 +116,21 @@ export interface ToolDefinition {
      * part of any user-facing workflow.
      */
     workflows: WorkflowTag | WorkflowTag[];
+    /**
+     * ADR-226 Decision 2 — vernacular intent posture. See `VernacularKind`
+     * above. Optional during Phase 3 ramp; Phase 7 lint flips it to a
+     * required-with-blocking check once every tool is populated.
+     */
+    vernacular_kind?: VernacularKind;
+    /**
+     * ADR-226 Decision 2 — required when `vernacular_kind` is `'internal'`
+     * or `'specialist'`. One-line documentation of why the tool is not a
+     * creator-vernacular entry point (e.g. "Invoked after presigned PUT
+     * completes" or "Specialist context; not yet covered by the Creator
+     * Question Atlas"). Phase 7 lint enforces presence on non-`creator-entry`
+     * kinds.
+     */
+    vernacular_reason?: string;
     inputSchema: {
         type: string;
         properties: Record<string, any>;
@@ -118,6 +199,16 @@ export interface ToolDefinition {
 export type ToolCategory = "catalog" | "enrichment" | "business" | "discovery" | "media" | "comms" | "settings";
 export interface ToolMetadata {
     category: ToolCategory;
+    /**
+     * @deprecated ADR-230 — use the declared `tier` on the tool
+     * definition (`ToolDefinition.tier` — required by lint Rule 13) as
+     * the source of truth. `risk` is retained as a quiet fallback for
+     * the unlikely case of a tool that bypasses lint (legacy tolerance
+     * inside `ToolRegistry.listTools`) and to drive the
+     * `injectMetadataIntoDescription` annotations + `retry_safe` hints
+     * exposed via `getToolMetadata`. Do NOT add new consumers; route
+     * tier-aware logic through the tool definition's declared `tier`.
+     */
     risk: "safe" | "mutating" | "destructive";
     retry_safe: boolean;
     display_name: string;
@@ -196,10 +287,14 @@ export declare class ToolRegistry {
      * Register all available tools
      */
     private registerAllTools;
-    private static readonly DESTRUCTIVE_PATTERNS;
-    private static readonly MUTATING_PATTERNS;
-    private static readonly SAFE_OVERRIDES;
-    private classifyTool;
+    /**
+     * 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: string): Tier | undefined;
     /**
      * List all available tools with write-safety prefixes injected.
      * When discoveryMode is enabled, only the 5 handshake-visible tools are returned.

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AA4D/C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAU5C,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,oBAAoB,CAAC;CAC1D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,oBAAoB,GACpB,uBAAuB,GACvB,4BAA4B,GAC5B,iBAAiB,GACjB,uBAAuB,GACvB,6BAA6B,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,sBAAsB,GACtB,2BAA2B,GAC3B,yBAAyB,GACzB,gBAAgB,CAAC;AAErB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACvC,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChD;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACpD,WAAW,CAAC,EAAE;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC;QAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,0BAA0B,CAAC,EAAE,OAAO,CAAC;QACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,0BAA0B,CAAC,EAAE,OAAO,CAAC;KACtC,CAAC;IACF,KAAK,CAAC,EAAE;QACN,EAAE,CAAC,EAAE;YACH,WAAW,EAAE,MAAM,CAAC;SACrB,CAAC;QACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,YAAY,GACZ,UAAU,GACV,WAAW,GACX,OAAO,GACP,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,GACrB,MAAM,CAKR;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAQzD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CACV;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QACE,IAAI,EAAE,eAAe,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACD;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAC1D,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE;QACN,aAAa,CAAC,EAAE,YAAY,CAAC;QAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,GAAG,CAAC,EAAE,mBAAmB,KACtB,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAOX;IACF,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAe;IAC9B,OAAO,CAAC,oBAAoB,CAAC,CAA2B;IACxD,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,aAAa,CAAgB;gBAGnC,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,MAAM,CAAC,EAAE,YAAY,EACrB,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,EAC/C,aAAa,CAAC,EAAE,aAAa,EAC7B,eAAe,CAAC,EAAE,MAAM,IAAI;IAc9B,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI5C,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAI9C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyZxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAM1C;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CA4BvC;IAGF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAanC;IAEH,OAAO,CAAC,YAAY;IAapB;;;;OAIG;IACH,SAAS,IAAI,cAAc,EAAE;IAiG7B;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;IAkDjC;;OAEG;YACW,uBAAuB;IA8MrC;;;OAGG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kBAAkB,CAqDxB;IAEF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;;;OAMG;YACW,kBAAkB;IA6BhC;;;;;;OAMG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,GAAG,CAAC,EAAE,mBAAmB,GACxB,OAAO,CAAC,GAAG,CAAC;CA2MhB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.js

@@ -43,9 +43,12 @@ 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 { DisputesTools } from "./disputes.js";
 import { CustodyTools } from "./custody.js";
 import { PurchasesTools } from "./purchases.js";
@@ -65,6 +68,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"
@@ -370,6 +413,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
@@ -388,6 +446,16 @@ 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);
+        });
         // Disputes tools (ADR-139 Step 3)
         const disputesTools = new DisputesTools(pica);
         disputesTools.getTools().forEach((tool) => {
@@ -449,72 +517,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.
@@ -536,9 +547,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,
@@ -566,6 +582,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,
@@ -574,27 +610,27 @@ export class ToolRegistry {
                         title: metadata.display_name,
                         readOnlyHint: metadata.risk === "safe",
                         destructiveHint: metadata.risk === "destructive",
-                        idempotentHint: metadata.risk === "safe" && metadata.retry_safe,
+                        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 };
@@ -609,9 +645,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 = [
@@ -631,10 +674,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,
@@ -1011,10 +1060,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();
@@ -1032,12 +1093,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: [
@@ -1063,6 +1127,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",
@@ -1074,8 +1139,9 @@ export class ToolRegistry {
                     .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: [
@@ -1108,10 +1174,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);
             }
@@ -1137,7 +1203,8 @@ 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,
@@ -1163,10 +1230,15 @@ 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,