ai-install-guard 0.2.0 → 0.3.1

package/hooks/gate/resolve.ts

@@ -0,0 +1,210 @@
+// Where an install would come from: the repository, folder and commit Claude
+// Code would install, read from its own plugin listing and marketplace
+// catalogs. Only the `claude` command and file reads are used; nothing from
+// the candidate runs.
+
+import type { Host } from '../scan/host'
+import { looksRemote, parseRemote, type RemoteSpec } from '../scan/remote'
+import { safeLine } from '../scan/safe-text'
+import type { InstallRequest } from './requests'
+
+export type Target =
+  /** One commit of a repository, and the folder in it. */
+  | { kind: 'remote'; spec: RemoteSpec }
+  /** A folder on this machine: a marketplace's own copy of a plugin, or a marketplace added from a folder. */
+  | { kind: 'local'; path: string }
+  /** A marketplace name: Claude Code shows its menu to pick a plugin from. */
+  | { kind: 'browse' }
+  | { kind: 'unverifiable'; reason: string }
+
+/** The most a marketplace catalog may weigh before the guard stops reading it. */
+const MAX_CATALOG_BYTES = 4 * 1024 * 1024
+
+type Listed = { pluginId?: unknown; name?: unknown; marketplaceName?: unknown; source?: unknown }
+type Marketplace = { name: string; installLocation?: string }
+
+/** The target an install request names. A lookup that fails says why, as an unverifiable target. */
+export async function targetOf(host: Host, request: InstallRequest): Promise<Target> {
+  try {
+    return request.kind === 'marketplace' ? await marketplaceTarget(host, request.source) : await pluginTarget(host, request)
+  } catch (error) {
+    return { kind: 'unverifiable', reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+async function pluginTarget(host: Host, request: Extract<InstallRequest, { kind: 'plugin' }>): Promise<Target> {
+  const listing = await claudeJson(host, ['plugin', 'list', '--available', '--json'], 'the plugin list')
+  const available: Listed[] = isRecord(listing) && Array.isArray(listing.available) ? (listing.available as Listed[]) : []
+  const installed = isRecord(listing) && Array.isArray(listing.installed) ? (listing.installed as { id?: unknown }[]) : []
+  const id = request.marketplace === undefined ? request.plugin : `${request.plugin}@${request.marketplace}`
+  const matches = available.filter(item => item.name === request.plugin && (request.marketplace === undefined || item.marketplaceName === request.marketplace))
+  // Where marketplaces live is read only when it is needed: for a relative source or a catalog file.
+  let listed: Promise<Marketplace[]> | undefined
+  const marketplaces = (): Promise<Marketplace[]> => (listed ??= marketplaceList(host))
+
+  if (matches.length === 0) {
+    // An installed plugin is not in the available list: its catalog says where an update comes from.
+    // A marketplace named is that marketplace's plugin and no other's.
+    const mine = installed.map(item => (typeof item.id === 'string' ? item.id : '')).filter(item => (request.marketplace === undefined ? item.startsWith(`${request.plugin}@`) : item === id))
+    if (mine.length > 1 && request.marketplace === undefined) return ambiguous(request.plugin, mine.map(item => item.split('@')[1] ?? ''))
+    const owner = mine[0]?.split('@')[1] ?? request.marketplace
+    const market = (await marketplaces()).find(item => item.name === owner)
+    if (market !== undefined) {
+      const entry = await catalogEntry(host, market, request.plugin)
+      if (entry !== undefined) return sourceTarget(host, entry, async () => market)
+    }
+    // `/plugin install <marketplace>` opens that marketplace's menu.
+    if (request.verb === 'install' && request.marketplace === undefined && (await marketplaces()).some(item => item.name === request.plugin)) return { kind: 'browse' }
+    return { kind: 'unverifiable', reason: `${safeLine(id)} is not in the marketplaces you added, so there was nothing to scan` }
+  }
+
+  // The same plugin can be listed by two marketplaces. One source between them is one target.
+  const distinct = new Map(matches.map(item => [sourceKey(item), item]))
+  if (distinct.size > 1) return ambiguous(request.plugin, matches.map(item => String(item.marketplaceName)))
+  const entry = [...distinct.values()][0] as Listed
+  return sourceTarget(host, entry, () => marketplaces().then(list => list.find(item => item.name === entry.marketplaceName)))
+}
+
+function ambiguous(plugin: string, marketplaces: readonly string[]): Target {
+  const names = [...new Set(marketplaces)].map(safeLine)
+  return {
+    kind: 'unverifiable',
+    reason: `${safeLine(plugin)} is in more than one marketplace (${names.join(', ')}); name one, as in ${safeLine(plugin)}@${names[0] ?? '<marketplace>'}`,
+  }
+}
+
+/**
+ * A source's identity: a relative source belongs to its marketplace, so two
+ * marketplaces' `./x` are never the same; an object source is its fields in
+ * name order, however a listing orders them.
+ */
+function sourceKey(item: Listed): string {
+  if (typeof item.source === 'string') return `${String(item.marketplaceName)}:${item.source}`
+  return JSON.stringify(canonical(item.source ?? null))
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (!isRecord(value)) return value
+  return Object.keys(value)
+    .sort()
+    .map(key => [key, canonical(value[key])])
+}
+
+/** Where a catalog entry's `source` says the plugin comes from; `marketOf` finds its marketplace when a relative source needs it. */
+async function sourceTarget(host: Host, entry: Listed, marketOf: () => Promise<Marketplace | undefined>): Promise<Target> {
+  const source = entry.source
+  if (typeof source === 'string') {
+    if (!source.startsWith('./')) return { kind: 'unverifiable', reason: `its source "${safeLine(source)}" is not a folder inside its marketplace` }
+    const market = await marketOf()
+    if (market?.installLocation === undefined) return { kind: 'unverifiable', reason: 'its marketplace has no copy on this machine to read it from' }
+    return { kind: 'local', path: await insideFolder(host, market.installLocation, source) }
+  }
+  if (!isRecord(source) || typeof source.source !== 'string') return { kind: 'unverifiable', reason: 'its catalog entry names no source' }
+  const ref = text(source.sha) ?? text(source.ref)
+  switch (source.source) {
+    case 'url':
+      return remote(text(source.url), ref)
+    case 'git-subdir':
+      // Without its folder the entry would name the whole repository, which is not what installs.
+      if (text(source.path) === undefined) return { kind: 'unverifiable', reason: 'its catalog entry names no folder inside its repository' }
+      return remote(text(source.url), ref, text(source.path))
+    case 'github':
+      return remote(text(source.repo) === undefined ? undefined : `https://github.com/${text(source.repo)}.git`, ref)
+    default:
+      return { kind: 'unverifiable', reason: `it installs from a ${safeLine(source.source)} source, which the guard cannot read yet` }
+  }
+}
+
+function remote(url: string | undefined, ref: string | undefined, subdir?: string): Target {
+  if (url === undefined) return { kind: 'unverifiable', reason: 'its catalog entry names no repository' }
+  return { kind: 'remote', spec: parseRemote(url, { ref, subdir }) }
+}
+
+/** What `marketplace add <source>` would add: a repository, or a folder. */
+async function marketplaceTarget(host: Host, source: string): Promise<Target> {
+  const shape = looksRemote(source)
+  if (shape === 'local' || (shape === 'maybe' && (await host.stat(source).catch(() => undefined)) !== undefined)) {
+    const path = await expandHome(host, source)
+    const stat = await host.stat(path).catch(() => undefined)
+    if (stat === undefined) return { kind: 'unverifiable', reason: `there is no folder at ${safeLine(source)}` }
+    if (stat.kind !== 'dir') return { kind: 'unverifiable', reason: `${safeLine(source)} is a file; the guard scans the folder or repository a marketplace lives in` }
+    return { kind: 'local', path }
+  }
+  const spec = parseRemote(source)
+  if (/\.json$/i.test(spec.url)) return { kind: 'unverifiable', reason: 'it adds a catalog file from a web address; the guard scans the repository a marketplace lives in' }
+  return { kind: 'remote', spec }
+}
+
+async function marketplaceList(host: Host): Promise<Marketplace[]> {
+  const listed = await claudeJson(host, ['plugin', 'marketplace', 'list', '--json'], 'the marketplace list')
+  if (!Array.isArray(listed)) return []
+  return listed.flatMap(item => (isRecord(item) && typeof item.name === 'string' ? [{ name: item.name, installLocation: text(item.installLocation) }] : []))
+}
+
+/** A plugin's entry in a marketplace's own catalog file. */
+async function catalogEntry(host: Host, market: Marketplace, plugin: string): Promise<Listed | undefined> {
+  if (market.installLocation === undefined) return undefined
+  const path = await insideFolder(host, market.installLocation, './.claude-plugin/marketplace.json')
+  const stat = await host.stat(path)
+  if (stat.kind !== 'file' || stat.size > MAX_CATALOG_BYTES) throw new Error(`the catalog of ${safeLine(market.name)} is not a file the guard can read`)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(await host.readBytes(path)))
+  } catch {
+    throw new Error(`the catalog of ${safeLine(market.name)} is not valid JSON`)
+  }
+  const plugins = isRecord(parsed) && Array.isArray(parsed.plugins) ? parsed.plugins : []
+  const found = plugins.find(item => isRecord(item) && item.name === plugin)
+  return isRecord(found) ? { name: plugin, marketplaceName: market.name, source: found.source } : undefined
+}
+
+/**
+ * `relative` inside `folder`: no `..` above it, and no symbolic link on the
+ * way, which could lead the scan (and the install) out to other files.
+ */
+async function insideFolder(host: Host, folder: string, relative: string): Promise<string> {
+  const parts = relative.split(/[\\/]+/).filter(part => part !== '' && part !== '.')
+  if (parts.includes('..')) throw new Error(`"${safeLine(relative)}" leads outside its marketplace`)
+  let path = folder.replace(/[\\/]+$/, '')
+  for (const part of parts) {
+    path = `${path}/${part}`
+    const stat = await host.stat(path, { resolve: false }).catch(() => undefined)
+    if (stat === undefined) throw new Error(`its marketplace has no ${safeLine(relative)}`)
+    if (stat.isLink) throw new Error(`"${safeLine(relative)}" passes through a symbolic link, which could lead outside its marketplace`)
+  }
+  return path
+}
+
+/** Runs `claude <args>` and reads its JSON answer. */
+async function claudeJson(host: Host, args: readonly string[], what: string): Promise<unknown> {
+  const result = await host.run(['claude', ...args], { timeoutMs: 60_000 }).catch((error: unknown) => {
+    throw new Error(`could not read ${what}: ${error instanceof Error ? safeLine(error.message) : 'the claude command did not run'}`)
+  })
+  if (result.exitCode !== 0) {
+    const line = result.stderr.split('\n').find(item => item.trim() !== '') ?? `claude exited with ${result.exitCode}`
+    throw new Error(`could not read ${what}: ${safeLine(line.trim().slice(0, 300))}`)
+  }
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    throw new Error(`could not read ${what}: its answer was not valid JSON`)
+  }
+}
+
+/** `~` and `~/…` as the full path of your home folder. */
+export async function expandHome(host: Host, path: string): Promise<string> {
+  if (path !== '~' && !path.startsWith('~/')) return path
+  const { exitCode, stdout } = await host.run(['printenv', 'HOME'])
+  const home = stdout.trim()
+  if (exitCode !== 0 || home === '') throw new Error('could not find the home folder')
+  return home + path.slice(1)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}

package/hooks/guard/decisions.ts

@@ -22,6 +22,8 @@ export type Decision = {
 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
+/** The last report as text, under the name of the scan that wrote it. */
+const REPORT_TEXT = 'last-report-text'
 const LAST_VIEW = 'last-view'
 /** The store is capped at 4 MiB in all: keep the newest decisions only. */
 const MAX_DECISIONS = 500
@@ -81,6 +83,36 @@ export async function decisionFor($: EngineInterface, version: { treeHash: strin
   return approvedUpTo !== undefined && SEVERITY[kind] <= approvedUpTo ? found : undefined
 }
 
+/**
+ * The decision on one commit of one source, found before any scan: a commit
+ * names its files exactly, so the same commit of the same folder is the same
+ * version however it is asked for.
+ */
+export async function pinnedDecision($: EngineInterface, pin: { root: string; sha: string }): Promise<Decision | undefined> {
+  return (await loadDecisions($)).find(item => item.sha === pin.sha && item.root === pin.root)
+}
+
+/**
+ * Stores the text report of one scan, held well inside the store's limit. A
+ * failed write leaves no report, never another scan's.
+ */
+export async function saveReport($: EngineInterface, scanId: string, text: string): Promise<void> {
+  // A newer scan's report is never replaced by an older one's.
+  const stored = await $.store.get(REPORT_TEXT).catch(() => undefined)
+  const storedId = stored !== null && typeof stored === 'object' ? (stored as { scanId?: unknown }).scanId : undefined
+  if (typeof storedId === 'string' && storedId > scanId) return
+  const kept = 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, { scanId, text: kept }).catch(() => $.store.delete(REPORT_TEXT).catch(() => undefined))
+}
+
+/** The text report of the scan `scanId` names, if it is still the one stored. */
+export async function loadReport($: EngineInterface, scanId: string | undefined): Promise<string | undefined> {
+  const stored = await $.store.get(REPORT_TEXT)
+  if (stored === null || typeof stored !== 'object') return undefined
+  const { scanId: storedId, text } = stored as { scanId?: unknown; text?: unknown }
+  return storedId === scanId && typeof text === 'string' ? text : 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.

package/hooks/guard/pane.tsx

@@ -1,16 +1,19 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, RenderElement, RenderInput } from 'claude-code'
 
-import type { GuardRow, GuardStatus, GuardView } from '../../types'
+import type { GuardRequest, GuardRow, GuardStatus, GuardView } from '../../types'
 import { GROUPS } from '../scan/checks/types'
+import { safeLine } from '../scan/safe-text'
 import { locate } from '../scan/verdict'
 import { badgeFor } from './badge'
-import { recordDecision, saveLastView } from './decisions'
+import { changedSinceScan } from '../gate/recheck'
+import { modHost } from '../mod-host'
+import { loadReport, recordDecision, saveLastView } from './decisions'
+import { grantPass, takePass } from './passes'
 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' }
@@ -54,14 +57,63 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
       return { ...current, codeOpen: open.includes(id) ? open.filter(item => item !== id) : [...open, id] }
     })
 
+  // A press counts only on the scan it was drawn from, and only once: the
+  // first press claims the decision, and a scan that took the pane since, or
+  // a second press, changes nothing.
+  const claim = async (): Promise<GuardView | undefined> => {
+    let claimed: GuardView | undefined
+    await update($, viewAtom, latest => {
+      claimed = undefined
+      if (latest === null || latest.scanId !== view.scanId || latest.verdict === undefined || latest.decision !== undefined || latest.deciding === true) return latest
+      claimed = { ...latest, deciding: true }
+      return claimed
+    })
+    return claimed
+  }
+  /** Puts `next` in the pane while it still shows this scan; false once another scan has taken it. */
+  const replaceOwn = async (next: GuardView): Promise<boolean> => {
+    let ours = false
+    await update($, viewAtom, latest => {
+      ours = latest !== null && latest.scanId === view.scanId
+      return ours ? next : latest
+    })
+    return ours
+  }
+  const release = (current: GuardView) => replaceOwn({ ...current, deciding: false })
+  /**
+   * Saves this scan's outcome for /guard report; should a newer scan take
+   * the pane meanwhile, its view is saved instead, so the reopened report is
+   * always the pane's.
+   */
+  const saveOwn = async (outcome: GuardView): Promise<void> => {
+    await saveLastView($, outcome).catch(() => undefined)
+    const now = await read($, viewAtom).catch(() => null)
+    if (now !== null && now.scanId !== outcome.scanId) await saveLastView($, now).catch(() => undefined)
+  }
+  const movedOn = 'the pane has moved on to another scan'
+
   const decide = (decision: 'approved' | 'rejected', overridden: boolean) => async () => {
-    const current = await read($, viewAtom)
-    if (current === null || current.verdict === undefined) return
+    const current = await claim()
+    if (current === undefined || current.verdict === undefined) return
+    const held = current.action === 'install' ? current.request : undefined
     // 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.
+    // nothing is remembered, and nothing claims otherwise. A held install the
+    // person allows anyway goes through once, as that exact command.
     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 })
+      if (held !== undefined && decision === 'approved') {
+        // The pass is spent on this request: the reopened report shows it allowed, not the buttons again.
+        const allowed = { ...current, decision, decidedAt: Date.now(), confirming: false, deciding: false }
+        if (!(await replaceOwn(allowed))) {
+          $.ui.toast(`AI Install Guard: nothing was allowed: ${movedOn}`)
+          return
+        }
+        await grantPass($, { origin: held.origin, args: held.args })
+        await saveOwn(allowed)
+        await carryOut($, held, allowed)
+        return
+      }
+      $.ui.toast(held !== undefined ? 'AI Install Guard: rejected; nothing was installed' : 'AI Install Guard: closed; the scan read nothing, so there is no decision to remember')
+      if (await release(current)) await closeOwn($, current)
       return
     }
     const decidedAt = Date.now()
@@ -80,21 +132,33 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     } 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')
+      await release(current)
+      return
+    }
+    const decided = { ...current, decision, decidedAt, confirming: false, deciding: false }
+    // The decision is saved for its version either way; the pane, the
+    // reopened report and the install are this scan's only while it has the pane.
+    if (!(await replaceOwn(decided))) {
+      $.ui.toast(`AI Install Guard: ${decision} ${current.target}, but ${movedOn}${held !== undefined && decision === 'approved' ? '; run the install again and it goes through' : ''}`)
       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 })
+    await saveOwn(decided)
+    // The approval is saved for this exact version, so the install, asked for
+    // again, now goes through: the gate looks the version up again first.
+    if (held !== undefined && decision === 'approved') {
+      await carryOut($, held, decided)
+      return
+    }
+    $.ui.toast(`AI Install Guard: ${decision === 'approved' ? 'approved' : 'rejected'} ${current.target}${held === undefined ? '' : '; nothing was installed'}`)
+    await closeOwn($, decided)
   }
 
   const primary = async () => {
     const current = await read($, viewAtom)
-    if (current === null) return
+    if (current === null || current.scanId !== view.scanId) return
     if (needsConfirmation(current)) {
-      await update($, viewAtom, latest => (latest === null ? latest : { ...latest, confirming: true }))
+      await update($, viewAtom, latest => (latest === null || latest.scanId !== view.scanId ? latest : { ...latest, confirming: true }))
       return
     }
     await decide('approved', false)()
@@ -112,8 +176,9 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
   const offersBadge = view.treeHash !== undefined && (view.verdict?.kind === 'safe' || view.verdict?.kind === 'caution')
 
   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 })
+    // Only this scan's own report: never another scan's in its place.
+    const text = await loadReport($, view.scanId)
+    const result = await $.ui.copy({ text: 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')
   }
 
@@ -129,6 +194,12 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
         </Text>
       )}
 
+      {view.request !== undefined && (
+        <Text dimColor wrap="truncate-end">
+          {requestLine(view.request)}
+        </Text>
+      )}
+
       {verdict === undefined ? (
         <Text color="suggestion" wrap="truncate-end">
           Scanning: {view.stage}…
@@ -208,9 +279,9 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
         </Box>
       ))}
 
-      {verdict !== undefined && view.decision === undefined && !view.confirming && (
+      {verdict !== undefined && view.decision === undefined && !view.confirming && view.deciding !== true && (
         <Box key="actions" flexDirection="row" gap={1} marginTop={1}>
-          {view.treeHash !== undefined && (
+          {(view.treeHash !== undefined || (view.action === 'install' && view.request !== 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)} />
@@ -220,7 +291,7 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
         </Box>
       )}
 
-      {verdict !== undefined && view.confirming && (
+      {verdict !== undefined && view.confirming && view.deciding !== true && (
         <Box key="confirm-row" flexDirection="column" marginTop={1}>
           <Text color="warning" wrap="wrap">
             The verdict is {verdict.recommendation}. {primaryLabel(view)}?
@@ -234,8 +305,9 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
 
       {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.
+          {view.treeHash === undefined ? 'Allowed once' : view.decision === 'approved' ? 'Approved' : 'Rejected'}
+          {view.decidedAt === undefined ? '' : ` on ${new Date(view.decidedAt).toISOString().slice(0, 10)}`}
+          {view.treeHash === undefined ? '. Nothing could be pinned, so nothing is remembered; the same install is held again next time.' : '. The decision is saved for this exact version; /guard forget clears it.'}
         </Text>
       )}
       {view.decision !== undefined && offersBadge && (
@@ -247,6 +319,58 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
   )
 }
 
+/**
+ * Closes the pane while it shows this scan. Closing is a step of its own, so
+ * a newer scan may take the pane in that moment: while that scan still runs
+ * or waits for a decision it gets the pane back at once, so its verdict is
+ * never left hidden; one already decided closed the pane itself.
+ */
+async function closeOwn($: EngineInterface, view: GuardView): Promise<void> {
+  const before = await read($, viewAtom).catch(() => null)
+  if (before !== null && before.scanId !== view.scanId) return
+  await $.ui.close({ id: PANE_ID })
+  const after = await read($, viewAtom).catch(() => null)
+  const waiting = after !== null && after.scanId !== view.scanId && after.decision === undefined && after.deciding !== true
+  if (waiting) await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => undefined)
+}
+
+/** What the held install is, in the person's or Claude's own words. */
+function requestLine(request: GuardRequest): string {
+  return request.origin === 'tool' ? `Claude asked to run: ${safeLine(request.args)}` : `Held until you decide: /plugin ${safeLine(request.args)}`
+}
+
+/**
+ * Carries out a held install the person approved. Their own /plugin command
+ * runs again once the version it would install is checked to be the one
+ * scanned; a command Claude ran is Claude's to run again, once the person
+ * tells it to, and its gate checks the version then.
+ */
+async function carryOut($: EngineInterface, held: GuardRequest, view: GuardView): Promise<void> {
+  await closeOwn($, view)
+  if (held.origin === 'tool') {
+    $.ui.toast(`AI Install Guard: approved ${held.label}. Tell Claude to run the install again; it goes through now`)
+    return
+  }
+  // The plugin's own command does not pass through its own gate, so the
+  // version is looked up again here: a commit that moved since the scan is
+  // not installed on the strength of the old one's verdict.
+  const changed = await changedSinceScan(modHost($), view).catch((error: unknown) => `the guard could not look it up again (${error instanceof Error ? error.message : String(error)})`)
+  if (changed !== undefined) {
+    await takePass($, { origin: 'command', args: held.args }).catch(() => undefined)
+    $.ui.toast(`AI Install Guard: nothing was installed: ${safeLine(changed)}. Run /plugin ${safeLine(held.args)} again to scan it`)
+    return
+  }
+  $.ui.toast(`AI Install Guard: approved; installing ${held.label}`)
+  try {
+    await $.command.run({ command: 'plugin', args: held.args })
+  } catch {
+    $.ui.toast(`AI Install Guard: approved, but the install did not start. Run /plugin ${safeLine(held.args)} again; it goes through now`)
+  } finally {
+    // A pass the gate did not use up is not left for a later command.
+    await takePass($, { origin: 'command', args: held.args }).catch(() => undefined)
+  }
+}
+
 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/passes.ts

@@ -0,0 +1,34 @@
+// Installs the person allowed once although nothing could be pinned: Could
+// not verify, then Install anyway, confirmed. Each pass lets that exact
+// command through one time in this session and is then used up.
+
+import { atom, update } from 'claude-code'
+import type { EngineInterface } from 'claude-code'
+
+import type { GuardPass } from '../../types'
+
+const passesAtom = atom({ plugin: 'ai-install-guard', key: 'passes' } as const, [] as GuardPass[])
+
+/** Passes kept at once; an old one unused falls off. */
+const MAX_PASSES = 20
+
+function samePass(a: GuardPass, b: GuardPass): boolean {
+  return a.origin === b.origin && a.args === b.args
+}
+
+export async function grantPass($: EngineInterface, pass: GuardPass): Promise<void> {
+  await update($, passesAtom, current => [...current.filter(item => !samePass(item, pass)), pass].slice(-MAX_PASSES))
+}
+
+/**
+ * Uses up the pass for this command, if there is one. Finding and removing it
+ * is one write, so two commands at once cannot both use the same pass.
+ */
+export async function takePass($: EngineInterface, pass: GuardPass): Promise<boolean> {
+  let taken = false
+  await update($, passesAtom, latest => {
+    taken = latest.some(item => samePass(item, pass))
+    return taken ? latest.filter(item => !samePass(item, pass)) : latest
+  })
+  return taken
+}