feat(quarantine): render input + output schema diff in tool approval UI (#639)

The tool-quarantine approval UI flagged a tool as "changed" whenever its
description, input schema, OR output schema hash differed from the approved
version, but rendered only the description diff. A schema-only change was
therefore an invisible phantom diff — the operator saw a "changed" badge with
no visible reason.

Render up to three labeled before/after sections (Description, Input Schema,
Output Schema), each shown only when that field actually changed, consuming
the previous_output_schema / current_output_schema fields the diff endpoint
now exposes (PR #638). Schema bodies are pretty-printed before the word-diff
so additive changes (e.g. a new enum value) read clearly. Backend keeps
rug-pull detection strict; this change is transparency only.

Diff-section selection is extracted into computeToolDiffSections (utils/toolDiff)
with a vitest covering the output-schema-only case.

Related MCP-2096, MCP-2085

Author: Dumbris

frontend/src/types/api.ts

@@ -302,6 +302,11 @@ export interface ToolApproval {
   current_description?: string
   previous_schema?: string
   current_schema?: string
+  // Output schema diff fields (MCP-2096 / PR #638): exposed by
+  // GET /api/v1/servers/{id}/tools/{tool}/diff so the approval UI can render
+  // an Output-Schema diff section, not just description/input-schema.
+  previous_output_schema?: string
+  current_output_schema?: string
   enabled?: boolean
   disabled?: boolean
 }

frontend/src/utils/toolDiff.ts

@@ -0,0 +1,79 @@
+// MCP-2096 (MCP-2085): build the list of diff sections shown in the
+// tool-quarantine approval UI. A tool is flagged `changed` whenever its
+// description OR input schema OR output schema hash differs from the approved
+// version, but the UI historically rendered only the description diff — so a
+// schema-only change read as a phantom false positive. This helper selects the
+// fields that actually changed and produces readable before/after bodies (JSON
+// schemas are pretty-printed) so the operator can see WHAT changed before
+// approving.
+
+import type { ToolApproval } from '@/types'
+
+export interface ToolDiffSection {
+  /** Stable key for v-for + tests. */
+  key: 'description' | 'input_schema' | 'output_schema'
+  /** Human label for the section header. */
+  label: string
+  /** Short explanation of why this section matters (e.g. additive schema). */
+  hint?: string
+  /** Approved (previous) body, normalized for display. */
+  before: string
+  /** Current body, normalized for display. */
+  after: string
+}
+
+// Pretty-print a JSON schema string with 2-space indent so the word-diff is
+// line-oriented and readable. Falls back to the raw string when the body isn't
+// valid JSON (defensive — the backend stores schemas as JSON strings).
+function formatSchema(raw: string | undefined): string {
+  if (!raw) return ''
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2)
+  } catch {
+    return raw
+  }
+}
+
+export function computeToolDiffSections(tool: ToolApproval): ToolDiffSection[] {
+  const sections: ToolDiffSection[] = []
+
+  // 1. Description — plain text, no formatting.
+  const prevDesc = tool.previous_description ?? ''
+  const curDesc = tool.current_description ?? tool.description ?? ''
+  if (prevDesc !== curDesc) {
+    sections.push({
+      key: 'description',
+      label: 'Description changed',
+      before: prevDesc,
+      after: curDesc,
+    })
+  }
+
+  // 2. Input schema — the tool's argument contract.
+  const prevSchema = formatSchema(tool.previous_schema)
+  const curSchema = formatSchema(tool.current_schema)
+  if (prevSchema !== curSchema) {
+    sections.push({
+      key: 'input_schema',
+      label: 'Input schema changed',
+      hint: 'The arguments this tool accepts changed.',
+      before: prevSchema,
+      after: curSchema,
+    })
+  }
+
+  // 3. Output schema — the shape of what the tool returns.
+  const prevOut = formatSchema(tool.previous_output_schema)
+  const curOut = formatSchema(tool.current_output_schema)
+  if (prevOut !== curOut) {
+    sections.push({
+      key: 'output_schema',
+      label: 'Output schema changed',
+      hint: 'The shape of this tool’s results changed (e.g. a new enum value or field).',
+      before: prevOut,
+      after: curOut,
+    })
+  }
+
+  return sections
+}

frontend/src/views/ServerDetail.vue

@@ -372,27 +372,45 @@
                         </span>
                       </div>
                       <p
-                        v-if="tool.status !== 'changed' || !tool.previous_description"
+                        v-if="tool.status !== 'changed' || computeToolDiffSections(tool).length === 0"
                         class="text-sm text-base-content/70 mt-1"
                       >{{ tool.description }}</p>
-                      <!-- Show before/after diff for changed tools -->
-                      <div v-if="tool.status === 'changed' && tool.previous_description" class="mt-2 space-y-2 text-xs">
-                        <div>
-                          <div class="text-[10px] font-semibold uppercase tracking-wide text-base-content/60 mb-1">Before (approved)</div>
-                          <div class="bg-error/5 border border-error/20 px-2 py-1.5 rounded font-mono leading-relaxed">
-                            <template v-for="(part, i) in computeWordDiff(tool.previous_description, tool.current_description || tool.description)" :key="'b'+i">
-                              <span v-if="part.type === 'removed'" class="bg-error/20 text-error font-semibold px-0.5 rounded">{{ part.text }}</span>
-                              <span v-else-if="part.type === 'same'">{{ part.text }}</span>
-                            </template>
-                          </div>
-                        </div>
-                        <div>
-                          <div class="text-[10px] font-semibold uppercase tracking-wide text-base-content/60 mb-1">After (current)</div>
-                          <div class="bg-success/5 border border-success/20 px-2 py-1.5 rounded font-mono leading-relaxed">
-                            <template v-for="(part, i) in computeWordDiff(tool.previous_description, tool.current_description || tool.description)" :key="'a'+i">
-                              <span v-if="part.type === 'added'" class="bg-success/20 text-success font-semibold px-0.5 rounded">{{ part.text }}</span>
-                              <span v-else-if="part.type === 'same'">{{ part.text }}</span>
-                            </template>
+                      <!-- Per-field before/after diff for changed tools: a tool is
+                           flagged "changed" when its description, input schema, OR
+                           output schema differs from the approved version (MCP-2096).
+                           Render one section per field that actually changed so a
+                           schema-only change isn't an invisible phantom diff. -->
+                      <div
+                        v-if="tool.status === 'changed' && computeToolDiffSections(tool).length > 0"
+                        class="mt-2 space-y-3 text-xs"
+                        data-test="tool-diff"
+                      >
+                        <div
+                          v-for="section in computeToolDiffSections(tool)"
+                          :key="section.key"
+                          :data-test="'tool-diff-' + section.key"
+                        >
+                          <div class="text-[11px] font-semibold text-base-content/80 mb-0.5">{{ section.label }}</div>
+                          <div v-if="section.hint" class="text-[10px] text-base-content/50 mb-1">{{ section.hint }}</div>
+                          <div class="space-y-2">
+                            <div>
+                              <div class="text-[10px] font-semibold uppercase tracking-wide text-base-content/60 mb-1">Before (approved)</div>
+                              <div class="bg-error/5 border border-error/20 px-2 py-1.5 rounded font-mono leading-relaxed whitespace-pre-wrap">
+                                <template v-for="(part, i) in computeWordDiff(section.before, section.after)" :key="'b'+i">
+                                  <span v-if="part.type === 'removed'" class="bg-error/20 text-error font-semibold px-0.5 rounded">{{ part.text }}</span>
+                                  <span v-else-if="part.type === 'same'">{{ part.text }}</span>
+                                </template>
+                              </div>
+                            </div>
+                            <div>
+                              <div class="text-[10px] font-semibold uppercase tracking-wide text-base-content/60 mb-1">After (current)</div>
+                              <div class="bg-success/5 border border-success/20 px-2 py-1.5 rounded font-mono leading-relaxed whitespace-pre-wrap">
+                                <template v-for="(part, i) in computeWordDiff(section.before, section.after)" :key="'a'+i">
+                                  <span v-if="part.type === 'added'" class="bg-success/20 text-success font-semibold px-0.5 rounded">{{ part.text }}</span>
+                                  <span v-else-if="part.type === 'same'">{{ part.text }}</span>
+                                </template>
+                              </div>
+                            </div>
                           </div>
                         </div>
                       </div>
@@ -1207,6 +1225,7 @@ import api from '@/services/api'
 import { useSecurityScannerStatus } from '@/composables/useSecurityScannerStatus'
 import { serverDisplayName } from '@/utils/serverRoute'
 import { oauthSignInState } from '@/utils/health'
+import { computeToolDiffSections } from '@/utils/toolDiff'
 
 interface Props {
   // MCP-1112: vue-router decodes the percent-encoded ':serverName' param, so
@@ -1747,7 +1766,10 @@ async function _loadToolApprovalsWithGen(gen: number) {
         }
       })
 
-      // Fetch diffs for changed tools to populate previous_description
+      // Fetch diffs for changed tools to populate the before/after fields used
+      // by computeToolDiffSections: description, input schema, AND output schema
+      // (MCP-2096 — output schema added in PR #638). Rendering only one field
+      // made schema-only changes look like phantom "changed" false positives.
       const changedTools = approvals.filter(t => t.status === 'changed')
       if (changedTools.length > 0) {
         const diffPromises = changedTools.map(async (tool) => {
@@ -1756,6 +1778,10 @@ async function _loadToolApprovalsWithGen(gen: number) {
             if (diffResp.success && diffResp.data) {
               tool.previous_description = diffResp.data.previous_description
               tool.current_description = diffResp.data.current_description
+              tool.previous_schema = diffResp.data.previous_schema
+              tool.current_schema = diffResp.data.current_schema
+              tool.previous_output_schema = diffResp.data.previous_output_schema
+              tool.current_output_schema = diffResp.data.current_output_schema
             }
           } catch {
             // Diff fetch failed, continue without it

frontend/tests/unit/tool-diff-sections.spec.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest'
+import { computeToolDiffSections } from '@/utils/toolDiff'
+import type { ToolApproval } from '@/types'
+
+// MCP-2096 (MCP-2085): the tool-quarantine diff UI previously rendered ONLY
+// the description diff. The backend now exposes input + output schema fields
+// (previous_schema/current_schema, previous_output_schema/current_output_schema
+// — PR #638), so a `changed` tool whose only change is a schema must surface a
+// labeled diff section instead of reading as a phantom false positive.
+
+function makeTool(overrides: Partial<ToolApproval>): ToolApproval {
+  return {
+    server_name: 'srv',
+    tool_name: 'do_thing',
+    status: 'changed',
+    hash: 'h',
+    description: '',
+    ...overrides,
+  }
+}
+
+describe('computeToolDiffSections (MCP-2096)', () => {
+  it('produces a non-empty, labeled Output-Schema section when ONLY the output schema changed', () => {
+    const tool = makeTool({
+      description: 'List files',
+      previous_description: 'List files',
+      current_description: 'List files',
+      previous_schema: '{"type":"object"}',
+      current_schema: '{"type":"object"}',
+      previous_output_schema: '{"type":"object","properties":{"files":{"type":"array"}}}',
+      current_output_schema:
+        '{"type":"object","properties":{"files":{"type":"array"},"mode":{"enum":["r","w"]}}}',
+    })
+
+    const sections = computeToolDiffSections(tool)
+
+    // Description + input schema are identical → skipped; only output schema.
+    expect(sections).toHaveLength(1)
+    const out = sections[0]
+    expect(out.key).toBe('output_schema')
+    expect(out.label.toLowerCase()).toContain('output schema')
+    expect(out.before).not.toBe(out.after)
+    expect(out.before.length).toBeGreaterThan(0)
+    expect(out.after).toContain('mode')
+  })
+
+  it('renders all three sections in order when description + both schemas changed', () => {
+    const tool = makeTool({
+      previous_description: 'old desc',
+      current_description: 'new desc',
+      previous_schema: '{"a":1}',
+      current_schema: '{"a":2}',
+      previous_output_schema: '{"b":1}',
+      current_output_schema: '{"b":2}',
+    })
+
+    const keys = computeToolDiffSections(tool).map(s => s.key)
+    expect(keys).toEqual(['description', 'input_schema', 'output_schema'])
+  })
+
+  it('skips sections whose fields are identical (no phantom diffs)', () => {
+    const tool = makeTool({
+      previous_description: 'same',
+      current_description: 'same',
+      previous_schema: '{"x":1}',
+      current_schema: '{"x":1}',
+    })
+    expect(computeToolDiffSections(tool)).toHaveLength(0)
+  })
+
+  it('pretty-prints JSON schema bodies so the word-diff is readable', () => {
+    const tool = makeTool({
+      previous_schema: '{"type":"object","properties":{"id":{"type":"string"}}}',
+      current_schema: '{"type":"object","properties":{"id":{"type":"number"}}}',
+    })
+    const sections = computeToolDiffSections(tool)
+    expect(sections).toHaveLength(1)
+    expect(sections[0].key).toBe('input_schema')
+    // Pretty-printed multi-line output (indented) rather than the raw one-liner.
+    expect(sections[0].after).toContain('\n')
+  })
+
+  it('falls back to the raw string when a schema body is not valid JSON', () => {
+    const tool = makeTool({
+      previous_output_schema: 'not-json-old',
+      current_output_schema: 'not-json-new',
+    })
+    const sections = computeToolDiffSections(tool)
+    expect(sections).toHaveLength(1)
+    expect(sections[0].before).toBe('not-json-old')
+    expect(sections[0].after).toBe('not-json-new')
+  })
+})