ai-install-guard 0.2.0 → 0.3.1

package/hooks/guard/run.ts

@@ -0,0 +1,158 @@
+// A scan shown in the pane: progress while it runs, then the verdict, the
+// stored report Copy report copies and the view /guard report reopens.
+
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface } from 'claude-code'
+
+import type { GuardAction, GuardRequest, GuardView } from '../../types'
+import { modHost } from '../mod-host'
+import type { RemoteSpec } from '../scan/remote'
+import { formatReport } from '../scan/report'
+import { safeLine } from '../scan/safe-text'
+import { scanFolder, scanRemote, type ScanReport } from '../scan/scan'
+import { decisionFor, saveLastView, saveReport } from './decisions'
+import { PANE_ID, scanningView, viewOf } from './view'
+
+const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null)
+
+export type ScanHow = { remote: RemoteSpec } | { folder: string }
+
+export type ShowOptions = {
+  action: GuardAction
+  /** The install the pane's Install button carries out, for a held install. */
+  request?: GuardRequest
+  lookups: boolean
+}
+
+export type Shown =
+  | { kind: 'done'; report: ScanReport; view: GuardView; text: string; placed: boolean; superseded: boolean }
+  | { kind: 'failed'; reason: string; view: GuardView; placed: boolean; superseded: boolean }
+
+let scans = 0
+
+/**
+ * A name for one scan, unique in this session, that sorts after every scan
+ * started before it: the time, then a count for scans in the same moment.
+ */
+function newScanId(): string {
+  scans += 1
+  return `${Date.now().toString(36).padStart(10, '0')}-${scans.toString(36).padStart(6, '0')}`
+}
+
+/** Opens the pane on a scan of `how`, and leaves the verdict in it. */
+export async function showScan($: EngineInterface, target: string, how: ScanHow | (() => Promise<ScanHow>), options: ShowOptions): Promise<Shown> {
+  // Named before anything waits, so a scan asked for later is always the newer one.
+  const scanId = newScanId()
+  const host = modHost($)
+  const opened = await openPane($)
+  const scanning = { ...withRequest(scanningView(target, options.action), options.request), scanId }
+  if (!(await takePane($, scanning))) {
+    return { kind: 'failed', reason: `Could not verify ${safeLine(target)}: a newer scan has the pane`, view: scanning, placed: opened, superseded: true }
+  }
+  $.ui.status(`AI Install Guard: scanning ${safeLine(target)}`)
+  try {
+    const scanOptions = {
+      lookups: options.lookups,
+      // Stage names can carry a candidate's own words (a plugin's name).
+      onStage: (stage: string) => update($, viewAtom, current => (current === null || current.scanId !== scanId ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
+    }
+    const resolved = typeof how === 'function' ? await how() : how
+    const report = 'remote' in resolved ? await scanRemote(host, target, resolved.remote, scanOptions) : await scanFolder(host, target, resolved.folder, scanOptions)
+    // 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($, { treeHash: report.inventory.treeHash, sha: report.source?.sha }, report.verdict.kind).catch(() => undefined)
+    const base = { ...withRequest(viewOf(report, options.action), options.request), scanId }
+    const view = earlier === undefined ? base : { ...base, decision: earlier.decision, decidedAt: earlier.decidedAt }
+    const text = formatReport(report, { details: true })
+    // A scan started since owns the pane now: this one leaves it, its report
+    // and the reopened report alone, so no press lands on the wrong scan.
+    if (!(await owns($, scanId))) return { kind: 'done', report, view, text, placed: opened, superseded: true }
+    // The report is stored under this scan's name before the pane shows the
+    // verdict, so Copy report copies it, and never another scan's.
+    await saveReport($, scanId, text)
+    if (!(await showOwn($, view))) return { kind: 'done', report, view, text, placed: opened, superseded: true }
+    $.ui.toast(`AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}`)
+    return { kind: 'done', report, view, text, placed: opened, superseded: false }
+  } catch (error) {
+    const reason = `Could not verify ${safeLine(target)}: ${safeLine(error instanceof Error ? error.message : String(error))}`
+    const failed = await showFailure($, target, reason, options, scanId)
+    return { kind: 'failed', reason, view: failed.view, placed: opened, superseded: !failed.shown }
+  } finally {
+    $.ui.status(undefined)
+  }
+}
+
+/**
+ * Opens the pane on an install the guard could not scan: Could not verify,
+ * with the reason, and Install anyway behind a second confirmation.
+ * `superseded` says a newer scan has the pane instead.
+ */
+export async function showUnverified($: EngineInterface, target: string, reason: string, options: ShowOptions): Promise<{ view: GuardView; placed: boolean; superseded: boolean }> {
+  const scanId = newScanId()
+  const placed = await openPane($)
+  const scanning = { ...withRequest(scanningView(target, options.action), options.request), scanId }
+  if (!(await takePane($, scanning))) return { view: scanning, placed, superseded: true }
+  const failed = await showFailure($, target, `Could not verify ${safeLine(target)}: ${safeLine(reason)}`, options, scanId)
+  return { view: failed.view, placed, superseded: !failed.shown }
+}
+
+/**
+ * The pane, and the report /guard report reopens, show a failure: never a
+ * scanning pane, and never an older verdict in its place. Only while this
+ * scan still owns the pane; `shown` says whether it did.
+ */
+async function showFailure($: EngineInterface, target: string, reason: string, options: ShowOptions, scanId: string): Promise<{ view: GuardView; shown: boolean }> {
+  const failed: GuardView = {
+    ...withRequest(scanningView(target, options.action), options.request),
+    scanId,
+    stage: '',
+    verdict: { kind: 'unverified', recommendation: 'Could not verify', reasons: [reason], counts: { pass: 0, warn: 0, fail: 0, info: 0 } },
+  }
+  if (!(await owns($, scanId).catch(() => false))) return { view: failed, shown: false }
+  await saveReport($, scanId, reason)
+  return { view: failed, shown: await showOwn($, failed).catch(() => false) }
+}
+
+/** Whether the pane still shows this scan. */
+async function owns($: EngineInterface, scanId: string): Promise<boolean> {
+  return (await read($, viewAtom))?.scanId === scanId
+}
+
+/** Takes the pane for a scan just started, unless a newer scan already has it. */
+async function takePane($: EngineInterface, view: GuardView): Promise<boolean> {
+  let taken = false
+  await update($, viewAtom, current => {
+    taken = current === null || current.scanId === undefined || view.scanId === undefined || current.scanId <= view.scanId
+    return taken ? view : current
+  })
+  return taken
+}
+
+/**
+ * Shows a scan's finished view while the pane still shows that scan, and
+ * saves it for /guard report. Should a newer scan take the pane while it is
+ * saved, the newer view is saved instead, so the reopened report is always
+ * the pane's.
+ */
+async function showOwn($: EngineInterface, view: GuardView): Promise<boolean> {
+  let shown = false
+  await update($, viewAtom, current => {
+    shown = current?.scanId === view.scanId
+    return shown ? view : current
+  })
+  if (!shown) return false
+  await saveLastView($, view).catch(() => undefined)
+  const now = await read($, viewAtom).catch(() => null)
+  if (now !== null && now.scanId !== view.scanId) await saveLastView($, now).catch(() => undefined)
+  return true
+}
+
+/** Opens the pane; false where no surface can show it (a headless run). */
+async function openPane($: EngineInterface): Promise<boolean> {
+  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
+  return opened.isPlaced
+}
+
+function withRequest(view: GuardView, request: GuardRequest | undefined): GuardView {
+  return request === undefined ? view : { ...view, request }
+}

package/hooks/guard/view.ts

@@ -35,7 +35,7 @@ export function viewOf(report: ScanReport, action: GuardAction): GuardView {
     // A remote scan's folder is a temporary one: its source names it instead.
     root:
       report.source !== undefined
-        ? safeLine(`${report.source.url}${report.source.subdir === undefined ? '' : `#${report.source.subdir}`}`)
+        ? sourceRoot(report.source.url, report.source.subdir)
         : report.inventory === undefined
           ? undefined
           : safeLine(report.inventory.root),
@@ -48,6 +48,11 @@ export function viewOf(report: ScanReport, action: GuardAction): GuardView {
   }
 }
 
+/** How a decision names a remote source: its address, and the folder in it after `#`. */
+export function sourceRoot(url: string, subdir: string | undefined): string {
+  return safeLine(`${url}${subdir === undefined ? '' : `#${subdir}`}`)
+}
+
 function rowOf(result: CheckResult): GuardRow {
   return {
     id: result.id,

package/hooks/register.tsx

@@ -1,16 +1,18 @@
 import type { EngineInterface, Register } from 'claude-code'
 import { atom, update } from 'claude-code'
 
+import { BROWSE_NOTE, judge } from './gate/gate'
+import { readPluginArgs, readShellCommand } from './gate/requests'
+import { expandHome } from './gate/resolve'
 import { badgeFor } from './guard/badge'
-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 { forgetDecisions, loadDecisions, loadLastView, loadReport } from './guard/decisions'
+import { drawPane } from './guard/pane'
+import { showScan } from './guard/run'
+import { PANE_ID } from './guard/view'
 import { modHost } from './mod-host'
 import type { Host } from './scan/host'
 import { looksRemote, parseRemote, type RemoteSpec } from './scan/remote'
-import { formatReport } from './scan/report'
 import { safeLine } from './scan/safe-text'
-import { scanFolder, scanRemote } 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.
@@ -57,6 +59,33 @@ export const register: Register = (on, options) => {
     return { text: USAGE }
   }).catch(() => ({ text: 'AI Install Guard: the command failed before it could answer.' }))
 
+  // Gate A: the person's own /plugin install and /plugin marketplace add. An
+  // install is answered in the command's place, so nothing installs, until
+  // the person approves that exact version.
+  on('command.run', { command: 'plugin' }, async ($, e, next) => {
+    const reading = readPluginArgs(e.args)
+    if (reading.kind === 'pass') {
+      if (reading.browse) $.ui.toast(BROWSE_NOTE)
+      return next(e)
+    }
+    const judged = await judge($, reading, { origin: 'command', args: e.args, label: reading.label }, lookups)
+    if (judged.kind === 'hold') return { text: judged.text }
+    if (judged.note !== undefined) $.ui.toast(judged.note)
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e) : { text: 'AI Install Guard stopped this install: it failed before it could check it, so nothing was installed.' }))
+
+  // Gate B: Claude installing a plugin or adding a marketplace with the claude
+  // command. The command is refused, with a reason Claude reads, until the
+  // person approves that exact version in the pane.
+  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
+    const reading = readShellCommand(e.command)
+    if (reading.kind === 'pass') return next(e)
+    const judged = await judge($, reading, { origin: 'tool', args: e.command, label: reading.label }, lookups)
+    if (judged.kind === 'hold') return { deny: judged.text }
+    if (judged.note !== undefined) $.ui.toast(judged.note)
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'AI Install Guard stopped this command: it may install a plugin or add a marketplace, and the guard failed before it could check it. Nothing was installed.' }))
+
   on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e) => drawPane($, e))
 }
 
@@ -68,58 +97,28 @@ export const register: Register = (on, options) => {
  */
 async function scan($: EngineInterface, target: string, details: boolean, flags: { ref?: string; path?: string }, lookups: 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 options = {
-      lookups,
-      // Stage names can carry a candidate's own words (a plugin's name).
-      onStage: (stage: string) => update($, viewAtom, current => (current === null ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
-    }
-    const spec = await remoteSpecFor(host, target, flags)
-    const report = spec === undefined ? await scanFolder(host, target, await expandHome(host, target), options) : await scanRemote(host, target, spec, options)
-    // 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($, { treeHash: report.inventory.treeHash, sha: report.source?.sha }, 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)
-  }
+  const shown = await showScan(
+    $,
+    target,
+    async () => {
+      const spec = await remoteSpecFor(host, target, flags)
+      return spec === undefined ? { folder: await expandHome(host, target) } : { remote: spec }
+    },
+    { action: 'approve', lookups },
+  )
+  if (shown.kind === 'failed') return shown.reason
+  // Where no pane shows, the answer is the whole report: findings and advice.
+  if (!shown.placed || details) return shown.text
+  return `AI Install Guard: ${shown.report.verdict.recommendation} for ${safeLine(target)}. The report is in the pane; /guard report reopens it.`
 }
 
 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 }))
+  await update($, viewAtom, () => ({ ...view, confirming: false, deciding: 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.'
+  return (await loadReport($, view.scanId)) ?? 'AI Install Guard: the last report is no longer stored.'
 }
 
 async function badge($: EngineInterface): Promise<string> {
@@ -195,19 +194,3 @@ async function remoteSpecFor(host: Host, target: string, flags: { ref?: string;
 function unquote(text: string): string {
   return /^(["']).*\1$/.test(text) ? text.slice(1, -1) : text
 }
-
-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 reasonOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}

package/hooks/scan/checks/mod.ts

@@ -250,6 +250,15 @@ function eventCapability(use: ModuleUse): Capability {
     if (SENSITIVE_COMMANDS.has(command)) return { risk: 'high', plain: `intercepts /${command}` }
     return { risk: 'low', plain: `answers /${command}` }
   }
+  // A tool hook narrowed to one tool is described as that tool's, still high risk.
+  if (use.name === 'tool.call' || use.name === 'tool.check') {
+    const tool = /\btool\s*:\s*['"`]([\w.-]{1,64})['"`]/.exec(use.detail ?? '')?.[1]
+    if (tool !== undefined) {
+      return use.name === 'tool.call'
+        ? { risk: 'high', plain: `sees every ${tool} call and can deny, rewrite or answer it` }
+        : { risk: 'high', plain: `decides whether ${tool} calls are allowed, so it can auto-approve them` }
+    }
+  }
   if (Object.hasOwn(EVENTS, use.name)) return EVENTS[use.name] as Capability
   const namespace = use.name.split('.')[0] ?? ''
   return Object.hasOwn(NAMESPACES, namespace) ? (NAMESPACES[namespace] as Capability) : { risk: 'low', plain: 'an event this scanner does not know' }

package/hooks/scan/remote.ts

@@ -216,9 +216,7 @@ export function resolveRef(listed: RemoteRefs, ref: string | undefined): Pick<Pi
  */
 export async function fetchPinned(host: Host, spec: RemoteSpec, onStage?: (stage: string) => Promise<void> | void): Promise<FetchedSource> {
   await onStage?.(`resolving ${safeLine(spec.url)}`)
-  const listing = await git(host, ['ls-remote', '--symref', spec.url, 'HEAD', 'refs/heads/*', 'refs/tags/*'], 60_000)
-  if (listing.exitCode !== 0) throw failure(listing, `could not reach ${spec.url}`)
-  const listed = parseLsRemote(listing.stdout)
+  const listed = await listRefs(host, spec.url)
   const fromLink = spec.treePath !== undefined && spec.ref === undefined ? splitTreePath(listed, spec.treePath) : undefined
   const subdir = spec.subdir ?? fromLink?.subdir
   const pinned = resolveRef(listed, spec.ref ?? fromLink?.ref)
@@ -280,6 +278,29 @@ export async function fetchPinned(host: Host, spec: RemoteSpec, onStage?: (stage
   }
 }
 
+/**
+ * The commit `spec` names now, and the folder in it, without fetching
+ * anything: what a later fetch of the same spec would pin, so a decision made
+ * on that commit can be found before a scan.
+ */
+export async function resolvePin(host: Host, spec: RemoteSpec): Promise<{ sha: string; subdir?: string }> {
+  // A full commit id needs no listing: it already is the pin.
+  if (spec.ref !== undefined && spec.treePath === undefined && FULL_SHA.test(spec.ref.toLowerCase())) {
+    return { sha: spec.ref.toLowerCase(), ...(spec.subdir === undefined ? {} : { subdir: spec.subdir }) }
+  }
+  const listed = await listRefs(host, spec.url)
+  const fromLink = spec.treePath !== undefined && spec.ref === undefined ? splitTreePath(listed, spec.treePath) : undefined
+  const subdir = spec.subdir ?? fromLink?.subdir
+  return { sha: resolveRef(listed, spec.ref ?? fromLink?.ref).sha, ...(subdir === undefined ? {} : { subdir }) }
+}
+
+/** The repository's branches and tags, as `git ls-remote` lists them. */
+async function listRefs(host: Host, url: string): Promise<RemoteRefs> {
+  const listing = await git(host, ['ls-remote', '--symref', url, 'HEAD', 'refs/heads/*', 'refs/tags/*'], 60_000)
+  if (listing.exitCode !== 0) throw failure(listing, `could not reach ${url}`)
+  return parseLsRemote(listing.stdout)
+}
+
 function git(host: Host, args: readonly string[], timeoutMs = 60_000, env: Record<string, string> = GIT_ENV): Promise<RunResult> {
   return host.run(['git', ...args], { timeoutMs, env })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-install-guard",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.",
   "scripts": {
     "build:fixtures": "node scripts/build-fixtures.js",