ai-install-guard 0.0.0 → 0.1.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ai-install-guard",
       "source": "./",
-      "version": "0.0.0",
+      "version": "0.1.0",
       "description": "Scans plugins, mods, skills and MCP servers without running them, shows a PASS / WARN / FAIL verdict, and installs nothing until you approve.",
       "category": "security",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-install-guard",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "A pre-install security gate for Claude Code: scans plugins, mods, skills and MCP servers without running them, and installs nothing until you approve.",
   "author": {
     "name": "Boaz Ziniman",
@@ -10,6 +10,7 @@
   "homepage": "https://github.com/ziniman/ai-install-guard",
   "repository": "https://github.com/ziniman/ai-install-guard",
   "license": "Apache-2.0",
+  "types": "./types/index.d.ts",
   "keywords": [
     "security",
     "supply-chain",

package/CHANGELOG.md

@@ -4,7 +4,15 @@ All notable changes to ai-install-guard. Ordered newest to oldest.
 
 ---
 
-## Unreleased
+## v0.1.0  ·  2026-10-22
+
+**`pane`** - `/guard scan` opens a verdict pane: the recommendation and its reasons in a coloured banner, the counts, and every check grouped with failures first, each row opening to its evidence and advice. Approve and Reject record the decision against the exact tree hash; on Do not install or Could not verify the button reads Approve anyway and asks a second time. Details opens every row and Copy report copies the full text. Progress shows in the pane and the status line, and a toast says when the verdict is ready
+
+**`/guard report`, `/guard list`, `/guard forget`** - Reopen the last report, list your decisions, and forget the ones about a name
+
+**`checks`** - Deterministic checks for structure and manifest (Claude Code's own validator, binaries and disguised files, symbolic links that leave the folder, data after an image's end, bundled permission settings), mod capabilities (every hooked event and `$` call in plain language, high-risk calls, capability mismatch), classic shell hooks and their scripts, skills, commands and agents (prompt injection, credential instructions, broad `allowed-tools`, remote instructions, look-alike names, text aimed at the scanner), code patterns (hidden Unicode with tag characters decoded, execution, obfuscation, credentials with network code, persistence, install scripts, registry redirects, network addresses) and committed secrets, each with a fixture and a test
+
+**`/guard scan`** - Prints a verdict (Safe to install, Install with caution, Do not install, Could not verify), its top reasons and one line per check; `--details` adds every finding and its advice. Quoted text is escaped and marked as untrusted
 
 **`/guard scan`** - Lists every file of a local folder, reads and hashes each one, records symbolic links with where they land without following them, and prints a SHA-256 tree hash that pins the exact content
 

package/README.md

@@ -16,12 +16,18 @@
 
 </div>
 
-> **Status: early development.** Today the guard can list and hash a local folder with `/guard scan <path>`. The checks, the verdict pane and the install gates below are being built in stages; see [Roadmap](#roadmap).
+> **Status: early development.** Today `/guard scan <path>` runs the deterministic checks on a local folder and shows the verdict in a pane, where you approve or reject that exact version. Remote fetching and the install gates below are being built in stages; see [Roadmap](#roadmap).
 
 Everything you add to Claude Code runs with your permissions. A plugin can ship shell hooks that run every session, an MCP server can download and launch a package, a mod can read files or auto-approve tools, and a skill can carry hidden instructions the model will follow. The install prompt asks you to trust the author, and an update can change the files after you looked.
 
 AI Install Guard is a Claude Code mod that stops every new plugin, mod, skill, MCP server or marketplace, and every update to one, scans it without running any of its code, and installs nothing until you approve it.
 
+## Who it is for
+
+You, before you add something to Claude Code. It runs inside your own session, needs no account, server or agent, and is open source, so you can read every check it makes. This release makes no network calls; later stages fetch the candidate itself, and any outside lookup stays optional and off by default. Today you run `/guard scan` on a folder yourself before installing it; the gates that hold an install automatically come in later stages (see [Roadmap](#roadmap)).
+
+Company security platforms such as AIR, Pluto and Neo watch a whole fleet of agents and enforce policy across it. The guard does not replace them: it is an open, local check for one developer's installs, and it works the same whether or not your company runs one.
+
 ## How it works
 
 1. **Fetch without running.** The candidate is fetched at an exact commit into a folder the guard owns. Nothing is installed, built or run.
@@ -57,7 +63,27 @@ Approvals are remembered by commit and content hash, so the same version is neve
 
 | Command | What it does |
 |---------|--------------|
-| `/guard scan <path>` | Scan a local folder without installing it |
+| `/guard scan <path>` | Scan a local folder without installing it and open the verdict pane |
+| `/guard scan --details <path>` | The same, and print the full report with every finding and its advice |
+| `/guard report` | Reopen the last report |
+| `/guard list` | Your approved and rejected versions, newest first |
+| `/guard forget <name>` | Forget decisions about a name, so it is judged again |
+
+In the pane, **Approve** (`i`) and **Reject** (`r`) record your decision for that exact content (its tree hash). When the verdict is Do not install or Could not verify, the button reads **Approve anyway** and asks a second time. **Details** (`d`) opens every row, and **Copy report** (`c`) copies the full report as text. Where no pane can show (a headless `claude -p` run), `/guard scan` prints the report instead.
+
+## What the guard itself can do
+
+A security tool should be held to its own rules, so here is everything this mod uses, as `claude plugin validate .` lists it:
+
+| Capability | Why |
+|------------|-----|
+| `process.run` | Runs `claude plugin validate` on a candidate (it reads source and runs none of it), `readlink` to see where a symbolic link points without following it, and `printenv HOME` to expand `~`. Later stages add `git` to fetch candidates into the guard's own temporary folder. It never runs anything from a candidate. |
+| `fs.read`, `fs.list`, `fs.stat` | Reads the candidate's files to scan them. It never writes files. |
+| `command.register` | Adds the `/guard` command. |
+| `store`, `state` | Remembers your decisions and the last report, and holds what the pane shows. |
+| `ui` | The verdict pane, its status line and toasts, and copying the report. |
+
+Later stages add `http.fetch` (public repository metadata) and, optionally, `model.complete` (a review that can only add warnings).
 
 ## What it is not
 
@@ -68,9 +94,9 @@ Approvals are remembered by commit and content hash, so the same version is neve
 ## Roadmap
 
 1. [x] Skeleton mod: `/guard scan <path>` lists and hashes a local folder
-2. [ ] Checks for structure, mod capabilities, classic hooks, skills, code patterns and committed secrets
-3. [ ] The verdict pane with Install and Reject
-4. [ ] Remote fetch pinned to a commit, provenance checks, MCP server checks
+2. [x] Checks for structure, mod capabilities, classic hooks, skills, code patterns and committed secrets
+3. [x] The verdict pane with Install and Reject
+4. [ ] Remote fetch pinned to a commit, provenance checks (with an optional reputation lookup against outside catalogs and vulnerability databases), MCP server checks
 5. [ ] Gates on `/plugin` and on Claude's own install commands, with approvals
 6. [ ] Module load gate with hash match, skill gate, session-start reconciliation
 7. [ ] Update diffs and the optional model review

package/hooks/guard/decisions.ts

@@ -0,0 +1,91 @@
+import type { EngineInterface } from 'claude-code'
+
+import type { GuardVerdict, GuardView } from '../../types'
+import { safeLine } from '../scan/safe-text'
+
+/** One decision, remembered across sessions so the same tree is never judged twice. */
+export type Decision = {
+  target: string
+  root?: string
+  treeHash: string
+  verdict: string
+  /** The verdict the decision was made on; an approval holds up to this one. */
+  verdictKind: GuardVerdict['kind']
+  decision: 'approved' | 'rejected'
+  /** Approved although the verdict was Do not install or Could not verify. */
+  overridden: boolean
+  decidedAt: number
+}
+
+const DECISIONS = 'decisions'
+/** Room for the report text, well inside the store's 4 MiB in all. */
+export const MAX_REPORT_CHARS = 1_000_000
+const LAST_VIEW = 'last-view'
+/** The store is capped at 4 MiB in all: keep the newest decisions only. */
+const MAX_DECISIONS = 500
+/** How serious each verdict is, to tell whether an approval still covers it. */
+const SEVERITY: Record<GuardVerdict['kind'], number> = { safe: 0, caution: 1, unverified: 2, reject: 3 }
+
+export async function loadDecisions($: EngineInterface): Promise<Decision[]> {
+  const stored = await $.store.get(DECISIONS)
+  return Array.isArray(stored) ? (stored as Decision[]) : []
+}
+
+export async function recordDecision($: EngineInterface, decision: Decision): Promise<void> {
+  const others = (await loadDecisions($)).filter(item => item.treeHash !== decision.treeHash)
+  await $.store.set(DECISIONS, [decision, ...others].slice(0, MAX_DECISIONS))
+}
+
+/**
+ * Removes the decisions about `name`: its target as typed, its folder, or the
+ * last part of either. A name inside another (tool in my-tool-2) does not count.
+ */
+export async function forgetDecisions($: EngineInterface, name: string): Promise<Decision[]> {
+  const all = await loadDecisions($)
+  const last = (path: string): string => path.replace(/\/+$/, '').split('/').pop() ?? path
+  // Stored paths are display-safe; compare the name both as typed and made
+  // safe, without trailing slashes.
+  const wanted = new Set([name, safeLine(name)].map(value => value.replace(/\/+$/, '')))
+  const matches = (item: Decision): boolean =>
+    [item.target, item.root ?? '', last(item.target), last(item.root ?? '')].some(candidate => candidate !== '' && wanted.has(candidate.replace(/\/+$/, '')))
+  const kept = all.filter(item => !matches(item))
+  await $.store.set(DECISIONS, kept)
+  // The last report must not keep claiming a decision that is gone.
+  const forgotten = all.filter(matches)
+  const view = await loadLastView($)
+  if (view?.decision !== undefined && forgotten.some(item => item.treeHash === view.treeHash)) {
+    await saveLastView($, { ...view, decision: undefined, confirming: false })
+  }
+  return forgotten
+}
+
+/**
+ * The decision that still holds for this tree at this verdict. A rejection
+ * always holds. An approval holds only while the verdict is no worse than the
+ * one it was given on: the same files can judge worse in another place (a
+ * copy whose absolute link now leaves the folder), and that needs a new look.
+ */
+export async function decisionFor($: EngineInterface, treeHash: string, kind: GuardVerdict['kind']): Promise<Decision | undefined> {
+  const found = (await loadDecisions($)).find(item => item.treeHash === treeHash)
+  if (found === undefined || found.decision === 'rejected') return found
+  const approvedUpTo = SEVERITY[found.verdictKind] as number | undefined
+  return approvedUpTo !== undefined && SEVERITY[kind] <= approvedUpTo ? found : undefined
+}
+
+/**
+ * Saves the view /guard report reopens. When it cannot be saved, the old one
+ * is removed, so a reopened report never shows an older verdict as current.
+ */
+export async function saveLastView($: EngineInterface, view: GuardView): Promise<void> {
+  try {
+    await $.store.set(LAST_VIEW, view)
+  } catch (error) {
+    await $.store.delete(LAST_VIEW).catch(() => undefined)
+    throw error
+  }
+}
+
+export async function loadLastView($: EngineInterface): Promise<GuardView | undefined> {
+  const stored = await $.store.get(LAST_VIEW)
+  return stored !== null && typeof stored === 'object' ? (stored as GuardView) : undefined
+}

package/hooks/guard/pane.tsx

@@ -0,0 +1,206 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, RenderElement, RenderInput } from 'claude-code'
+
+import type { GuardRow, GuardStatus, GuardView } from '../../types'
+import { GROUPS } from '../scan/checks/types'
+import { locate } from '../scan/verdict'
+import { recordDecision, saveLastView } from './decisions'
+import { needsConfirmation, PANE_ID, primaryLabel } from './view'
+
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
+
+export const REPORT_TEXT = 'last-report-text'
+
+const ICON: Record<GuardStatus, string> = { fail: '✖', warn: '⚠', pass: '✔', info: '·' }
+const COLOR: Record<GuardStatus, string> = { fail: 'error', warn: 'warning', pass: 'success', info: 'subtle' }
+const VERDICT_COLOR = { safe: 'success', caution: 'warning', reject: 'error', unverified: 'warning' } as const
+
+type PaneInput = RenderInput<'Pane'>
+
+/** The pane's tree for the scan in state, or a note when there is none. */
+export async function drawPane($: EngineInterface, e: PaneInput): Promise<RenderElement> {
+  const { Box, Text, Button } = $.ui.resolve(e)
+  const view = await read($, viewAtom)
+  const width = Math.max(20, e.props.bodyColumns)
+
+  if (view === null) {
+    return (
+      <Box flexDirection="column" width={width}>
+        <Text dimColor>No scan yet. Run /guard scan &lt;path&gt;.</Text>
+      </Box>
+    )
+  }
+
+  const header = [view.kind === undefined ? undefined : `A ${view.kind}`, view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`]
+    .filter(part => part !== undefined)
+    .join(' · ')
+
+  const rowsOf = (group: string): GuardRow[] => view.rows.filter(row => row.group === group)
+  const isOpen = (row: GuardRow): boolean => view.details || view.expanded.includes(row.id)
+  const toggle = (id: string) => () =>
+    update($, viewAtom, current =>
+      current === null ? current : { ...current, expanded: current.expanded.includes(id) ? current.expanded.filter(item => item !== id) : [...current.expanded, id] },
+    )
+
+  const decide = (decision: 'approved' | 'rejected', overridden: boolean) => async () => {
+    const current = await read($, viewAtom)
+    if (current === null || current.verdict === undefined) return
+    // A scan that never read the files has no tree hash to pin a decision to:
+    // the pane closes, nothing is remembered, and nothing claims otherwise.
+    if (current.treeHash === undefined) {
+      $.ui.toast('AI Install Guard: closed; the scan read nothing, so there is no decision to remember')
+      await $.ui.close({ id: PANE_ID })
+      return
+    }
+    const decidedAt = Date.now()
+    try {
+      await recordDecision($, {
+        target: current.target,
+        root: current.root,
+        treeHash: current.treeHash,
+        verdict: current.verdict.recommendation,
+        verdictKind: current.verdict.kind,
+        decision,
+        overridden,
+        decidedAt,
+      })
+    } catch {
+      // Nothing was saved: say so, and leave the pane open to try again.
+      $.ui.toast('AI Install Guard: could not save the decision; nothing was recorded')
+      return
+    }
+    const decided = { ...current, decision, decidedAt, confirming: false }
+    await update($, viewAtom, () => decided)
+    // The reopened report shows the outcome, not the buttons again.
+    await saveLastView($, decided).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: ${decision === 'approved' ? 'approved' : 'rejected'} ${current.target}`)
+    await $.ui.close({ id: PANE_ID })
+  }
+
+  const primary = async () => {
+    const current = await read($, viewAtom)
+    if (current === null) return
+    if (needsConfirmation(current)) {
+      await update($, viewAtom, latest => (latest === null ? latest : { ...latest, confirming: true }))
+      return
+    }
+    await decide('approved', false)()
+  }
+
+  const copy = async () => {
+    const text = await $.store.get(REPORT_TEXT)
+    const result = await $.ui.copy({ text: typeof text === 'string' ? text : 'No report yet.', surface: e.surface })
+    $.ui.toast(result.isCopied ? 'AI Install Guard: report copied' : 'AI Install Guard: could not copy the report here')
+  }
+
+  const verdict = view.verdict
+  return (
+    <Box flexDirection="column" width={width}>
+      <Text bold wrap="truncate-end">
+        AI Install Guard · {view.target}
+      </Text>
+      {header !== '' && (
+        <Text dimColor wrap="truncate-end">
+          {header}
+        </Text>
+      )}
+
+      {verdict === undefined ? (
+        <Text color="suggestion" wrap="truncate-end">
+          Scanning: {view.stage}…
+        </Text>
+      ) : (
+        <Box key="verdict" flexDirection="column" borderStyle="round" borderColor={VERDICT_COLOR[verdict.kind]} paddingX={1} marginTop={1}>
+          <Text bold color={VERDICT_COLOR[verdict.kind]}>
+            {verdict.recommendation}
+          </Text>
+          {verdict.reasons.map(reason => (
+            <Text wrap="truncate-end">
+              {reason}
+            </Text>
+          ))}
+        </Box>
+      )}
+
+      {verdict !== undefined && (
+        <Text>
+          {verdict.counts.pass} passed · {verdict.counts.warn} warning{verdict.counts.warn === 1 ? '' : 's'} · {verdict.counts.fail} failed
+        </Text>
+      )}
+      {verdict !== undefined && view.rows.length > 0 && (
+        <Text dimColor wrap="truncate-end">
+          Quoted text comes from the scanned files and is untrusted.
+        </Text>
+      )}
+
+      {GROUPS.filter(group => rowsOf(group.id).length > 0).map(group => (
+        <Box key={`group-${group.id}`} flexDirection="column" marginTop={1}>
+          <Text bold>{group.title}</Text>
+          {rowsOf(group.id).map(row => {
+            const first = row.evidence[0]
+            const summary = first === undefined ? '' : `: ${locate(first.file, first.line)}${first.excerpt}`
+            return (
+              <Box key={`row-${row.id}`} flexDirection="column">
+                <Button key={`toggle-${row.id}`} plain onPress={toggle(row.id)}>
+                  <Text color={COLOR[row.status]}>{ICON[row.status]}</Text> {row.title}
+                  <Text dimColor>{truncate(summary, width - row.title.length - 4)}</Text>
+                </Button>
+                {isOpen(row) && (
+                  <Box key={`detail-${row.id}`} flexDirection="column" paddingLeft={2}>
+                    {row.evidence.map(item => (
+                      <Text wrap="wrap" color={item.status === undefined ? undefined : COLOR[item.status]}>
+                        {locate(item.file, item.line)}
+                        {item.excerpt}
+                      </Text>
+                    ))}
+                    {row.more > 0 && <Text dimColor>… and {row.more} more in the copied report</Text>}
+                    {(row.status === 'fail' || row.status === 'warn') && (
+                      <Text dimColor wrap="wrap">
+                        {row.advice}
+                      </Text>
+                    )}
+                  </Box>
+                )}
+              </Box>
+            )
+          })}
+        </Box>
+      ))}
+
+      {verdict !== undefined && view.decision === undefined && !view.confirming && (
+        <Box key="actions" flexDirection="row" gap={1} marginTop={1}>
+          {view.treeHash !== undefined && (
+            <Button key="install" label={primaryLabel(view)} hotkey="i" variant={needsConfirmation(view) ? 'secondary' : 'primary'} onPress={primary} />
+          )}
+          <Button key="reject" label="Reject" hotkey="r" variant={needsConfirmation(view) ? 'primary' : 'secondary'} onPress={decide('rejected', false)} />
+          <Button key="details" label={view.details ? 'Fewer details' : 'Details'} hotkey="d" onPress={() => update($, viewAtom, current => (current === null ? current : { ...current, details: !current.details }))} />
+          <Button key="copy" label="Copy report" hotkey="c" onPress={copy} />
+        </Box>
+      )}
+
+      {verdict !== undefined && view.confirming && (
+        <Box key="confirm-row" flexDirection="column" marginTop={1}>
+          <Text color="warning" wrap="wrap">
+            The verdict is {verdict.recommendation}. {primaryLabel(view)}?
+          </Text>
+          <Box flexDirection="row" gap={1}>
+            <Button key="confirm" label={`Yes, ${primaryLabel(view).toLowerCase()}`} hotkey="y" onPress={decide('approved', true)} />
+            <Button key="cancel" label="Cancel" hotkey="n" variant="primary" onPress={() => update($, viewAtom, current => (current === null ? current : { ...current, confirming: false }))} />
+          </Box>
+        </Box>
+      )}
+
+      {view.decision !== undefined && (
+        <Text color={view.decision === 'approved' ? 'success' : 'error'}>
+          {view.decision === 'approved' ? 'Approved' : 'Rejected'}
+          {view.decidedAt === undefined ? '' : ` on ${new Date(view.decidedAt).toISOString().slice(0, 10)}`}. The decision is saved for this exact version; /guard forget clears it.
+        </Text>
+      )}
+    </Box>
+  )
+}
+
+function truncate(text: string, room: number): string {
+  if (room <= 1) return ''
+  return text.length <= room ? text : `${text.slice(0, Math.max(0, room - 1))}…`
+}

package/hooks/guard/view.ts

@@ -0,0 +1,69 @@
+import type { GuardAction, GuardRow, GuardView } from '../../types'
+import { redactSecrets } from '../scan/checks/patterns'
+import type { CheckResult } from '../scan/checks/types'
+import { safeLine } from '../scan/safe-text'
+import type { ScanReport } from '../scan/scan'
+
+/** Evidence the pane keeps per row; the full list stays in the stored report. */
+const EVIDENCE_PER_ROW = 20
+/** Characters the pane keeps per excerpt or reason: one huge hook command cannot fill the store. */
+const MAX_TEXT = 500
+
+function clip(text: string): string {
+  return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}…` : text
+}
+
+export const PANE_ID = 'ai-install-guard'
+
+export function scanningView(target: string, action: GuardAction): GuardView {
+  return { target: safeLine(target), action, stage: 'Starting', rows: [], expanded: [], details: false, confirming: false }
+}
+
+/** The pane's view of a finished scan: compact, every quoted text made safe. */
+export function viewOf(report: ScanReport, action: GuardAction): GuardView {
+  return {
+    // The person's own words, but drawn beside an Approve button: made safe too.
+    target: safeLine(report.target),
+    action,
+    stage: '',
+    verdict: {
+      ...report.verdict,
+      reasons: report.verdict.reasons.map(reason => clip(safeLine(redactSecrets(reason)))),
+    },
+    rows: report.results.map(rowOf),
+    kind: report.kind,
+    root: report.inventory === undefined ? undefined : safeLine(report.inventory.root),
+    treeHash: report.inventory?.treeHash,
+    expanded: [],
+    details: false,
+    confirming: false,
+  }
+}
+
+function rowOf(result: CheckResult): GuardRow {
+  return {
+    id: result.id,
+    group: result.group,
+    title: result.title,
+    status: result.status,
+    evidence: result.evidence.slice(0, EVIDENCE_PER_ROW).map(item => ({
+      file: clip(safeLine(redactSecrets(item.file))),
+      line: item.line,
+      excerpt: clip(safeLine(redactSecrets(item.excerpt))),
+      status: item.status,
+    })),
+    more: Math.max(0, result.evidence.length - EVIDENCE_PER_ROW),
+    advice: result.advice,
+  }
+}
+
+/** Whether the primary button needs a second, explicit confirmation: the verdict is Do not install or Could not verify. */
+export function needsConfirmation(view: GuardView): boolean {
+  return view.verdict === undefined || view.verdict.kind === 'reject' || view.verdict.kind === 'unverified'
+}
+
+/** The primary button's label for this verdict. */
+export function primaryLabel(view: GuardView): string {
+  const verb = view.action === 'install' ? 'Install' : 'Approve'
+  return needsConfirmation(view) ? `${verb} anyway` : verb
+}

package/hooks/register.tsx

@@ -1,14 +1,26 @@
-import type { Register } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+import { atom, update } from 'claude-code'
 
+import { decisionFor, forgetDecisions, loadDecisions, loadLastView, MAX_REPORT_CHARS, saveLastView } from './guard/decisions'
+import { drawPane, REPORT_TEXT } from './guard/pane'
+import { PANE_ID, scanningView, viewOf } from './guard/view'
 import { modHost } from './mod-host'
 import type { Host } from './scan/host'
-import { takeInventory } from './scan/inventory'
-import { formatInventory } from './scan/report'
+import { formatReport } from './scan/report'
 import { safeLine } from './scan/safe-text'
+import { scanFolder } from './scan/scan'
+
+// Claude Code reads every state reference from the file that uses it, so each
+// module declares its own atom for the pane's view.
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
 
 const USAGE = [
   'Usage:',
-  '  /guard scan <path>   Scan a local plugin, mod or skill folder without installing it',
+  '  /guard scan <path>            Scan a local plugin, mod or skill folder without installing it',
+  '  /guard scan --details <path>  The same, with the full report as text',
+  '  /guard report                 Reopen the last report',
+  '  /guard list                   Your approved and rejected versions',
+  '  /guard forget <name>          Forget decisions about a name, so it is judged again',
 ].join('\n')
 
 export const register: Register = on => {
@@ -16,34 +28,113 @@ export const register: Register = on => {
     await $.command.register({
       name: 'guard',
       description: 'Scan a plugin, mod, skill or MCP server without installing it',
-      argumentHint: 'scan <path>',
+      argumentHint: 'scan <path> | report | list | forget <name>',
     })
     return next(e)
   })
 
   on('command.run', { command: 'guard' }, async ($, e) => {
-    const { sub, rest } = splitArgs(e.args)
-    if (sub !== 'scan' || rest === '') {
-      return { text: USAGE }
-    }
-    const host = modHost($)
-    try {
-      const tree = await takeInventory(host, await expandHome(host, rest))
-      return { text: formatInventory(rest, tree.inventory) }
-    } catch (error) {
-      return { text: `Could not verify ${safeLine(rest)}: ${safeLine(reasonOf(error))}` }
+    const { sub, rest, details } = splitArgs(e.args)
+    if (sub === 'scan' && rest !== '') return { text: await scan($, rest, details) }
+    if (sub === 'report') return { text: await reopen($) }
+    if (sub === 'list') return { text: await list($) }
+    if (sub === 'forget' && rest !== '') {
+      const count = (await forgetDecisions($, rest)).length
+      return { text: `AI Install Guard: forgot ${count} decision${count === 1 ? '' : 's'} about ${safeLine(rest)}.` }
     }
+    return { text: USAGE }
   }).catch(() => ({ text: 'AI Install Guard: the command failed before it could answer.' }))
+
+  on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e) => drawPane($, e))
+}
+
+/**
+ * Scans a folder with the pane showing progress and then the verdict. The
+ * command's own answer, which the model also reads, is one line: the quoted
+ * findings stay in the pane. Where no pane can show (a headless run), or with
+ * --details, the answer is the full text report.
+ */
+async function scan($: EngineInterface, target: string, details: boolean): Promise<string> {
+  const host = modHost($)
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  // Until this scan's report is stored, Copy report has nothing to copy, never
+  // the previous scan's report.
+  await $.store.delete(REPORT_TEXT).catch(() => undefined)
+  await update($, viewAtom, () => scanningView(target, 'approve'))
+  $.ui.status(`AI Install Guard: scanning ${safeLine(target)}`)
+  try {
+    const report = await scanFolder(host, target, await expandHome(host, target), {
+      // Stage names can carry a candidate's own words (a plugin's name).
+      onStage: stage => update($, viewAtom, current => (current === null ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
+    })
+    // A tree you already decided on shows that decision, not the buttons
+    // again, unless it now judges worse than when you approved it.
+    const earlier = report.inventory === undefined ? undefined : await decisionFor($, report.inventory.treeHash, report.verdict.kind).catch(() => undefined)
+    const view = earlier === undefined ? viewOf(report, 'approve') : { ...viewOf(report, 'approve'), decision: earlier.decision, decidedAt: earlier.decidedAt }
+    const text = formatReport(report, { details: true })
+    // The report text is stored before the pane shows the verdict, so Copy
+    // report always copies this scan's report. It is held well inside the
+    // store's limit; a failed write leaves Copy with nothing, not old text.
+    const stored = text.length > MAX_REPORT_CHARS ? `${text.slice(0, MAX_REPORT_CHARS)}\n… the report was cut here to fit the store` : text
+    await $.store.set(REPORT_TEXT, stored).catch(() => undefined)
+    await update($, viewAtom, () => view)
+    await saveLastView($, view).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}`)
+    // Where no pane shows, the answer is the whole report: findings and advice.
+    if (!opened.isPlaced || details) return text
+    return `AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}. The report is in the pane; /guard report reopens it.`
+  } catch (error) {
+    const reason = `Could not verify ${safeLine(target)}: ${safeLine(reasonOf(error))}`
+    await $.store.set(REPORT_TEXT, reason).catch(() => undefined)
+    // The pane, and the report /guard report reopens, show this failure: never
+    // a scanning pane, and never an older verdict in its place.
+    const failed = { ...scanningView(target, 'approve'), stage: '', verdict: { kind: 'unverified' as const, recommendation: 'Could not verify', reasons: [reason], counts: { pass: 0, warn: 0, fail: 0, info: 0 } } }
+    await update($, viewAtom, () => failed).catch(() => undefined)
+    await saveLastView($, failed).catch(() => undefined)
+    return reason
+  } finally {
+    $.ui.status(undefined)
+  }
 }
 
-/** `scan "my folder"` → `{ sub: 'scan', rest: 'my folder' }`. */
-export function splitArgs(args: string): { sub: string; rest: string } {
+async function reopen($: EngineInterface): Promise<string> {
+  const view = await loadLastView($)
+  if (view === undefined) return 'AI Install Guard: no report yet. Run /guard scan <path>.'
+  await update($, viewAtom, () => ({ ...view, confirming: false }))
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  if (opened.isPlaced) return `AI Install Guard: reopened the report for ${safeLine(view.target)}.`
+  const text = await $.store.get(REPORT_TEXT)
+  return typeof text === 'string' ? text : 'AI Install Guard: the last report is no longer stored.'
+}
+
+async function list($: EngineInterface): Promise<string> {
+  const decisions = await loadDecisions($)
+  if (decisions.length === 0) return 'AI Install Guard: no decisions yet.'
+  const lines = decisions.map(item => {
+    const when = new Date(item.decidedAt).toISOString().slice(0, 10)
+    const how = item.decision === 'approved' ? (item.overridden ? 'approved against the verdict' : 'approved') : 'rejected'
+    return `  ${when}  ${how.padEnd(28)} ${safeLine(item.target)}  (${item.verdict}, tree ${item.treeHash.slice(7, 19)})`
+  })
+  return ['AI Install Guard: your decisions, newest first', ...lines].join('\n')
+}
+
+/**
+ * `scan --details "my folder"` → `{ sub: 'scan', details: true, rest: 'my folder' }`.
+ * `--details` counts only as its own token right after the subcommand, so a
+ * quoted path that contains it is left whole.
+ */
+export function splitArgs(args: string): { sub: string; rest: string; details: boolean } {
   const trimmed = args.trim()
   const space = trimmed.search(/\s/)
   const sub = space === -1 ? trimmed : trimmed.slice(0, space)
-  const rest = space === -1 ? '' : trimmed.slice(space).trim()
-  const unquoted = /^(["']).*\1$/.test(rest) ? rest.slice(1, -1) : rest
-  return { sub: sub.toLowerCase(), rest: unquoted }
+  let rest = space === -1 ? '' : trimmed.slice(space).trim()
+  const details = /^--details(?:\s|$)/.test(rest)
+  if (details) rest = rest.slice('--details'.length).trim()
+  return { sub: sub.toLowerCase(), rest: unquote(rest), details }
+}
+
+function unquote(text: string): string {
+  return /^(["']).*\1$/.test(text) ? text.slice(1, -1) : text
 }
 
 async function expandHome(host: Host, path: string): Promise<string> {