ai-install-guard 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ai-install-guard",
       "source": "./",
-      "version": "0.1.0",
+      "version": "0.2.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.1.0",
+  "version": "0.2.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",
@@ -19,5 +19,13 @@
     "skills",
     "mcp",
     "mods"
-  ]
+  ],
+  "userConfig": {
+    "outsideLookups": {
+      "type": "boolean",
+      "title": "Outside lookups",
+      "description": "Check the packages a plugin uses against OSV, and its name against Anthropic's official plugins. Sends package and plugin names to those services. Off by default.",
+      "default": false
+    }
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to ai-install-guard. Ordered newest to oldest.
 
 ---
 
+## v0.2.0  ·  2026-10-22
+
+**`outsideLookups`** - Harder to fool: each package runner's own options are read (`-p` is a package to npx but a Python version to uvx), so `--with`, `--with-requirements` and file arguments no longer hide the main package; Python extras such as `httpx[cli]` are looked up; an advisory OSV answers with an empty or malformed record stays unresolved and a package with no usable answer is reported as not looked up; up to 300 advisories are read for malware instead of 30; every marketplace name is compared; and one scan asks for the official list and each advisory once, however many plugins it lists
+
+**`provenance`** - A GitHub request that fails late is noted where it belongs and no longer hides the warnings earlier requests found; a listed plugin's worse finding now brings its own reason to the marketplace's row
+
+**`skill`** - AI Install Guard for Claude chat: `npm run build:skill` bundles the scanner into an Agent Skill, `dist/ai-install-guard-skill.zip`, to upload to Claude. Attach a zip of a plugin, skill or MCP server, or paste a repository link, and Claude runs the same deterministic checks and presents the verdict, the plain-language summary and the evidence, treating the scanned files as untrusted data and never softening a failure. Where a chat's network settings block GitHub, it says so and asks for a zip
+
+**`cli`** - `node scan.js <folder | zip | repository>` runs the scan outside Claude Code, with `--ref`, `--path`, `--details`, `--json` and `--lookups`, and exits with the verdict (0 to 3). A zip is unpacked by the scanner itself into its own temporary folder, which is removed afterwards. When it holds one folder, or one plugin or skill beside other files, that is what is scanned; several side by side need `--path`. Paths that would land outside the folder, special files, encrypted entries, names listed twice and anything over the size limits stop the scan as Could not verify, and links are recreated as links and judged, never followed. It starts only `git`, `sh`, `mktemp` and `rm` (PowerShell on Windows), without any `GIT_` variable from its own environment, and a command that prints more than 4 MiB fails the scan rather than being read in part
+
+**`checks`** - A right-to-left plugin is no longer told Do not install just for defining a direction mark as a constant: a bidirectional control that is the whole of a one-line string, with nothing after it on its line but `;`, `,` or a comment, is a warning that names the escape to write instead, since it cannot reorder any code. Anywhere else, in a language the tokenizer does not know, and for tag characters, it still fails, and a file full of such constants cannot crowd out a real one
+
+**`verdict`** - The middle verdict is now **Review what it can do**, formerly Install with caution. It means the candidate has powerful access worth knowing about, which a trustworthy tool may need too, not that it is a lesser kind of safe. The badge uses the new words, and a badge with the old words still counts as that verdict
+
+**`pane`** - The mod capability rows now say in plain words what a mod can do and whether its README says why, which programs it starts (read from its code, with shells and other risky ones called out), and the README's own explanation, quoted and marked as the plugin's words
+
+**`provenance`** - For a repository on GitHub, the report now says how old it and its owner's account are, its stars, forks and contributors, whether it is archived or a fork, and whether the scanned commit is signed and on the default branch. A brand-new account, a new repository with one author and few stars, and a commit named by id that is not on the default branch (it may come from a fork) are warnings; a lookup that fails is only noted
+
+**`outsideLookups`** - A new setting, off by default. Turned on, the packages a plugin's MCP servers start or its manifests pin are checked against OSV, where malware (MAL ids, or advisories marked CWE-506) fails and a pinned version's known vulnerabilities warn, and its name is compared with Anthropic's official plugins, where a near miss warns
+
+**`/guard badge`** - A README badge for plugin authors: after a scan that was Safe to install or Install with caution, `/guard badge` or Copy badge in the pane gives a shields.io badge naming the verdict and the exact commit or tree hash scanned, linked to how to check it. The guard never trusts a badge it meets: one that claims more than its own scan finds is a warning, and one that matches is only noted
+
+**`README`** - The Reviewed by AI Install Guard mark heads the README
+
+**`/guard scan <repository>`** - Scans one commit of a remote repository (`https://`, `github:owner/repo` or `owner/repo`, with `@ref`, `--ref` and `--path`). The ref is resolved with `git ls-remote`, only that commit is fetched into the guard's own temporary folder with no hooks, submodules, LFS downloads or filters, and the checkout must land on the pinned commit before anything is read; the folder is removed afterwards. Short commit ids, refs that name both a branch and a tag, and non-https sources are refused
+
+**`provenance`** - New rows for a remote scan: the source and its pinned commit, branches or tags named like a commit id or `FETCH_HEAD` (the Plugin4Shell trick, a failure), and submodules whose code was not scanned. For a marketplace, each plugin it lists from elsewhere is checked for a full commit pin or an exact package version
+
+**`mcp`** - MCP server checks: every server and what it runs or talks to, servers that download code or start unpinned packages or container images, inline shell scripts, remote and unencrypted servers, and API keys sent to a host that is not their own service
+
+**`structure`** - Flags Git LFS pointers and git filters, whose real content is filled in at install and could not be scanned
+
+**`pane`** - A row now says what it found in plain words before any code: which programs a candidate starts and what each is for, with shells, compilers and programs chosen at run time called out as worth a look, and which secrets or credential files its code reads. The code lines sit behind their own Show the code toggle, and the verdict's reasons use the same plain headline
+
+**`checks`** - Fewer false alarms, found by scanning a real skill: a standalone skill is no longer failed for having no plugin manifest, a local preview address is not a remote instruction, a person called a reviewer is not a security scanner, a browser's program path is not its profile data, and one-word placeholder hosts are not listed
+
+---
+
 ## v0.1.0 &nbsp;·&nbsp; 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

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="assets/reviewed-by-ai-install-guard-light@1x.png" alt="Reviewed by AI Install Guard" width="406" height="104">
+
 # AI Install Guard
 
 **A security gate for Claude Code. Nothing new gets installed until you have seen what it can do.**
@@ -16,7 +18,7 @@
 
 </div>
 
-> **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).
+> **Status: early development.** Today `/guard scan` runs the deterministic checks on a local folder, or on one commit of a repository it fetches without running anything, and shows the verdict in a pane, where you approve or reject that exact version. 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.
 
@@ -32,7 +34,7 @@ Company security platforms such as AIR, Pluto and Neo watch a whole fleet of age
 
 1. **Fetch without running.** The candidate is fetched at an exact commit into a folder the guard owns. Nothing is installed, built or run.
 2. **Check every file.** Deterministic checks read the hooks, MCP servers, mod code, skills, scripts, images and manifest.
-3. **Show a verdict.** A pane shows **Safe to install**, **Install with caution**, **Do not install** or **Could not verify**, a PASS / WARN / FAIL list with file and line evidence, and two buttons: **Install** and **Reject**.
+3. **Show a verdict.** A pane shows **Safe to install**, **Review what it can do**, **Do not install** or **Could not verify**, a PASS / WARN / FAIL list with file and line evidence, and two buttons: **Install** and **Reject**.
 4. **Install only what was scanned.** Install is pinned to the scanned commit and content hash. If the source changed since the scan, it is scanned again first.
 
 Approvals are remembered by commit and content hash, so the same version is never scanned twice, and an update is reviewed as a diff: anything new since the version you approved is listed and flagged. An optional model review can add warnings but can never clear a failure, so a README that says "this plugin is safe" changes nothing.
@@ -51,12 +53,12 @@ Approvals are remembered by commit and content hash, so the same version is neve
 
 | Threat | What gets flagged |
 |--------|-------------------|
-| Code execution | Shell hooks, MCP servers that launch binaries or unpinned `npx` / `uvx` packages, mods that run processes |
-| Data theft | Reads of `~/.ssh`, `~/.aws`, `.env`, keychains or secret env vars, combined with network calls |
+| Code execution | Shell hooks, MCP servers that download code or launch unpinned `npx` / `uvx` packages or container images, mods that run processes |
+| Data theft | Reads of `~/.ssh`, `~/.aws`, `.env`, keychains or secret env vars, combined with network calls; API keys an MCP server sends to a host that is not their own service |
 | Prompt injection | Hidden instructions in skills, commands, agents and tool descriptions, including invisible Unicode |
 | Permission escalation | Mods that auto-approve tools, writes to Claude settings or permissions, skills granting broad `Bash` |
 | Persistence | Writes to shell rc files, crontab, launchd, systemd, git hooks |
-| Supply chain | Marketplaces on a moving branch, brand-new repos, look-alike names, committed secrets, binaries, data hidden after the end of images |
+| Supply chain | Brand-new repositories and accounts, commits that are not on the default branch (they may come from a fork), packages known to be malware or vulnerable (an optional lookup), names one letter away from an official plugin's (an optional lookup), marketplace plugins not pinned to a commit, branches named like a commit id or `FETCH_HEAD` (the Plugin4Shell trick), submodules and Git LFS files whose code is fetched at install, remote MCP servers, committed secrets, binaries, data hidden after the end of images |
 | Sneaky updates | An update that adds capabilities, hooks, domains or servers without saying so |
 
 ## Commands
@@ -64,26 +66,85 @@ 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 and open the verdict pane |
-| `/guard scan --details <path>` | The same, and print the full report with every finding and its advice |
+| `/guard scan <repository>` | Fetch one commit of a repository into the guard's own temporary folder, scan it and remove it. Takes `https://host/owner/repo`, a GitHub `…/tree/<ref>/<folder>` link, `github:owner/repo` or `owner/repo`, with an optional `@ref` |
+| `/guard scan --ref <ref> --path <folder> <repository>` | Scan a branch, tag or full commit id (the default branch otherwise), and a folder inside the repository |
+| `/guard scan --details …` | Any of the above, and print the full report with every finding and its advice |
 | `/guard report` | Reopen the last report |
+| `/guard badge` | A README badge for the last scan, when it was Safe to install or Review what it can do (see [Review badge](#review-badge)) |
 | `/guard list` | Your approved and rejected versions, newest first |
 | `/guard forget <name>` | Forget decisions about a name, so it is judged again |
 
+A remote scan resolves the ref to one commit, fetches only that commit (no hooks, submodules, Git LFS downloads or filters), checks it out by its id and confirms that `HEAD` is that commit before reading a file. The report and the pane name the commit, and your decision is recorded against it and the tree hash.
+
+Each row opens to say what it found in plain words first: which programs the candidate starts and what each is for, which secrets its code reads, and what is worth a closer look. The code lines that back it up sit behind **Show the code**.
+
 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.
 
+## Use it in Claude chat
+
+A chat cannot hold an install, but it can run the same scan before you install something elsewhere. The scanner also builds into an Agent Skill for Claude:
+
+```bash
+npm ci --ignore-scripts
+npm run build:skill
+```
+
+This writes `dist/ai-install-guard-skill.zip`. Upload it in Claude under **Settings > Capabilities > Skills** (code execution must be on). Then, in any chat, attach a zip of a plugin, skill or MCP server, or paste a repository link, and ask:
+
+> Is this plugin safe to install?
+
+Claude runs the skill's `scripts/scan.js`: the same deterministic checks as `/guard scan`, without `claude plugin validate`, which a chat does not have. A zip is unpacked by the script itself into a temporary folder of its own, refusing any path that would land outside it, and a repository is fetched at one commit exactly as `/guard scan` fetches it. Claude answers with the verdict, each finding in plain words and the evidence behind it. The skill tells Claude that the scanned files are untrusted data, never instructions, and that a failure is never softened.
+
+To fetch a repository, the chat's code execution must be allowed to reach `github.com` (and `api.github.com` for the repository's details) in its network settings. Where it is not, Claude says so and asks for a zip instead (on GitHub: **Code > Download ZIP**).
+
+The same script runs anywhere with Node.js 18 or later: `node skill/ai-install-guard/scripts/scan.js --details <folder | zip | repository>`, with `--ref`, `--path`, `--json` and `--lookups`. Its exit status is the verdict: 0 Safe to install, 1 warnings to review, 2 Do not install, 3 Could not verify.
+
+## Review badge
+
+If you publish a plugin, mod, skill or MCP server, you can show that it was scanned. Scan your own repository, then run `/guard badge` or press **Copy badge** (`b`) in the pane, and paste the result near the top of your README:
+
+```markdown
+[![AI Install Guard: Safe to install at 4ac6edc](https://img.shields.io/badge/AI_Install_Guard-safe_to_install_%C2%B7_4ac6edc-2ea44f)](https://github.com/ziniman/ai-install-guard#review-badge "Scanned at commit 4ac6edc…, sha256:…")
+```
+
+The badge says two things: the verdict (green for **Safe to install**, yellow for **Review what it can do**) and the exact version that was scanned, the commit or, for a local folder, the tree hash. Hovering over it shows the full commit and tree hash. There is no badge for **Do not install** or **Could not verify**.
+
+A badge is a picture anyone can paste, so the guard never trusts one:
+
+- **When you see one:** scan that version yourself with `/guard scan owner/repo --ref <commit>`, adding `--path <folder>` when the badge names a folder. Your own scan is what counts.
+- **When the guard meets one:** a README badge that claims a better verdict than the guard's own scan is a warning, saying the badge is outdated or was never earned. A badge that matches is only noted. It never lifts a verdict.
+- **When the code changes:** the badge still names the old commit. A new version needs a new scan and a new badge.
+
 ## 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. |
+| `process.run` | Runs `git` to resolve a ref and fetch one commit into the guard's own temporary folder (made with `mktemp` and removed with `rm` afterwards), `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 `~`. It never runs anything from a candidate. |
+| `fs.read`, `fs.list`, `fs.stat` | Reads the candidate's files to scan them. It writes no files itself; only `git` writes, into the guard's temporary folder. |
 | `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).
+| `http.fetch` | For a repository on GitHub, reads its public metadata from GitHub's API: age, owner, stars, contributors, and whether the scanned commit is signed and on the default branch. GitHub is where the code came from, so this tells it nothing new. With **outside lookups** on, also sends package names to [OSV](https://osv.dev) and reads Anthropic's [official plugin list](https://github.com/anthropics/claude-plugins-official). |
+
+A later stage adds, optionally, `model.complete` (a review that can only add warnings).
+
+### Outside lookups
+
+Off by default, because they send names to other services. Turned on, the guard checks:
+
+- **Packages:** every package an MCP server starts or the candidate's `package.json` or `requirements.txt` pins, against OSV. A package OSV lists as malware is a failure; a pinned version with known vulnerabilities is a warning.
+- **Names:** its name against Anthropic's official plugins. A name one letter away from an official one is a warning; the same name is noted, so you can check it is that plugin.
+
+Turn them on in `/config` (the AI Install Guard row), or with:
+
+```bash
+claude plugin configure ai-install-guard
+```
+
+A lookup that fails or hits a rate limit is noted in the report and never fails the scan.
 
 ## What it is not
 
@@ -96,7 +157,7 @@ Later stages add `http.fetch` (public repository metadata) and, optionally, `mod
 1. [x] Skeleton mod: `/guard scan <path>` lists and hashes a local folder
 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
+4. [x] Remote fetch pinned to a commit, repository provenance, MCP server checks, and optional lookups against OSV and the official plugin list
 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/badge.ts

@@ -0,0 +1,35 @@
+import type { GuardView } from '../../types'
+
+/** Where the badge links: what it means and how to check it. */
+export const BADGE_PAGE = 'https://github.com/ziniman/ai-install-guard#review-badge'
+
+const COLOR = { safe: '2ea44f', caution: 'dbab09' } as const
+const MESSAGE = { safe: 'safe to install', caution: 'review what it can do' } as const
+
+/** A shields.io static badge part: dashes and underscores doubled, spaces as underscores. */
+function shieldPart(text: string): string {
+  return encodeURIComponent(text.replace(/-/g, '--').replace(/_/g, '__').replace(/ /g, '_'))
+}
+
+/**
+ * The README badge for the last scan: its verdict and the exact version it
+ * covers. Offered for Safe to install and Review what it can do only, and
+ * only for a scan that read the files, so it always names what was scanned.
+ */
+export function badgeFor(view: GuardView | undefined): { markdown: string; pin: string } | { refusal: string } {
+  if (view?.verdict === undefined || view.treeHash === undefined) return { refusal: 'Scan something first: /guard scan <path | repository>.' }
+  const kind = view.verdict.kind
+  if (kind !== 'safe' && kind !== 'caution') return { refusal: `There is no badge for ${view.verdict.recommendation}.` }
+  // Only hex from the scan goes into the badge, never text from the candidate.
+  const sha = view.sha !== undefined && /^[0-9a-f]{40,64}$/.test(view.sha) ? view.sha : undefined
+  const tree = /^sha256:[0-9a-f]{64}$/.test(view.treeHash) ? view.treeHash : undefined
+  if (tree === undefined) return { refusal: 'The last scan has no tree hash to pin a badge to.' }
+  const pin = sha !== undefined ? sha.slice(0, 7) : `tree ${tree.slice(7, 15)}`
+  // A scan of one folder always says so: the rest of the commit was not
+  // judged. The view holds the folder percent-encoded, whole, never cut.
+  const folder = sha !== undefined ? view.subdir : undefined
+  if (folder !== undefined && !/^[\w./%-]{1,400}$/.test(folder)) return { refusal: 'The folder name is too long to show in a badge.' }
+  const image = `https://img.shields.io/badge/${shieldPart('AI Install Guard')}-${shieldPart(`${MESSAGE[kind]} · ${pin}`)}-${COLOR[kind]}`
+  const scanned = sha !== undefined ? `commit ${sha}${folder === undefined ? '' : `, folder ${folder}`}, ${tree}` : tree
+  return { markdown: `[![AI Install Guard: ${view.verdict.recommendation} at ${pin}${folder === undefined ? '' : ` in ${folder}`}](${image})](${BADGE_PAGE} "Scanned at ${scanned}")`, pin }
+}

package/hooks/guard/decisions.ts

@@ -7,6 +7,8 @@ import { safeLine } from '../scan/safe-text'
 export type Decision = {
   target: string
   root?: string
+  /** The commit, for a remote source. */
+  sha?: string
   treeHash: string
   verdict: string
   /** The verdict the decision was made on; an approval holds up to this one. */
@@ -31,8 +33,13 @@ export async function loadDecisions($: EngineInterface): Promise<Decision[]> {
   return Array.isArray(stored) ? (stored as Decision[]) : []
 }
 
+/** One decision per version: the same files at the same commit (or as a folder). */
+function sameVersion(a: { treeHash: string; sha?: string }, b: { treeHash: string; sha?: string }): boolean {
+  return a.treeHash === b.treeHash && (a.sha ?? '') === (b.sha ?? '')
+}
+
 export async function recordDecision($: EngineInterface, decision: Decision): Promise<void> {
-  const others = (await loadDecisions($)).filter(item => item.treeHash !== decision.treeHash)
+  const others = (await loadDecisions($)).filter(item => !sameVersion(item, decision))
   await $.store.set(DECISIONS, [decision, ...others].slice(0, MAX_DECISIONS))
 }
 
@@ -65,8 +72,10 @@ export async function forgetDecisions($: EngineInterface, name: string): Promise
  * 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)
+export async function decisionFor($: EngineInterface, version: { treeHash: string; sha?: string }, kind: GuardVerdict['kind']): Promise<Decision | undefined> {
+  // A decision is about one version: another commit with the same files, or
+  // the same files as a local folder, is judged on its own.
+  const found = (await loadDecisions($)).find(item => sameVersion(item, version))
   if (found === undefined || found.decision === 'rejected') return found
   const approvedUpTo = SEVERITY[found.verdictKind] as number | undefined
   return approvedUpTo !== undefined && SEVERITY[kind] <= approvedUpTo ? found : undefined

package/hooks/guard/pane.tsx

@@ -4,6 +4,7 @@ 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 { badgeFor } from './badge'
 import { recordDecision, saveLastView } from './decisions'
 import { needsConfirmation, PANE_ID, primaryLabel } from './view'
 
@@ -31,7 +32,11 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     )
   }
 
-  const header = [view.kind === undefined ? undefined : `A ${view.kind}`, view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`]
+  const header = [
+    view.kind === undefined ? undefined : `A ${view.kind}`,
+    view.sha === undefined ? undefined : `commit ${view.sha.slice(0, 12)}`,
+    view.treeHash === undefined ? undefined : `tree ${view.treeHash.slice(7, 19)}`,
+  ]
     .filter(part => part !== undefined)
     .join(' · ')
 
@@ -41,6 +46,13 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     update($, viewAtom, current =>
       current === null ? current : { ...current, expanded: current.expanded.includes(id) ? current.expanded.filter(item => item !== id) : [...current.expanded, id] },
     )
+  const codeOpen = (row: GuardRow): boolean => (view.codeOpen ?? []).includes(row.id)
+  const toggleCode = (id: string) => () =>
+    update($, viewAtom, current => {
+      if (current === null) return current
+      const open = current.codeOpen ?? []
+      return { ...current, codeOpen: open.includes(id) ? open.filter(item => item !== id) : [...open, id] }
+    })
 
   const decide = (decision: 'approved' | 'rejected', overridden: boolean) => async () => {
     const current = await read($, viewAtom)
@@ -57,6 +69,7 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
       await recordDecision($, {
         target: current.target,
         root: current.root,
+        sha: current.sha,
         treeHash: current.treeHash,
         verdict: current.verdict.recommendation,
         verdictKind: current.verdict.kind,
@@ -87,6 +100,17 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
     await decide('approved', false)()
   }
 
+  const copyBadge = async () => {
+    const made = badgeFor(view)
+    if ('refusal' in made) {
+      $.ui.toast(`AI Install Guard: ${made.refusal}`)
+      return
+    }
+    const result = await $.ui.copy({ text: made.markdown, surface: e.surface })
+    $.ui.toast(result.isCopied ? 'AI Install Guard: badge copied; paste it near the top of your README' : 'AI Install Guard: could not copy the badge here')
+  }
+  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 })
@@ -138,7 +162,11 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
           <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}`
+            const headline = row.summary?.[0]
+            const summary = headline !== undefined ? `: ${headline}` : first === undefined ? '' : `: ${locate(first.file, first.line)}${first.excerpt}`
+            const places = row.evidence.length + row.more
+            // With a summary, the code lines are one step further in.
+            const showCode = row.summary === undefined || codeOpen(row)
             return (
               <Box key={`row-${row.id}`} flexDirection="column">
                 <Button key={`toggle-${row.id}`} plain onPress={toggle(row.id)}>
@@ -147,18 +175,31 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
                 </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}
+                    {row.summary?.map((line, index) => (
+                      <Text wrap="wrap" bold={index === 0}>
+                        {line}
                       </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>
                     )}
+                    {row.summary !== undefined && places > 0 && (
+                      <Button key={`code-${row.id}`} plain onPress={toggleCode(row.id)}>
+                        <Text color="suggestion">
+                          {codeOpen(row) ? 'Hide the code' : `Show the code (${places} place${places === 1 ? '' : 's'})`}
+                        </Text>
+                      </Button>
+                    )}
+                    {showCode &&
+                      row.evidence.map(item => (
+                        <Text wrap="wrap" color={item.status === undefined ? undefined : COLOR[item.status]}>
+                          {locate(item.file, item.line)}
+                          {item.excerpt}
+                        </Text>
+                      ))}
+                    {showCode && row.more > 0 && <Text dimColor>… and {row.more} more in the copied report</Text>}
                   </Box>
                 )}
               </Box>
@@ -175,6 +216,7 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
           <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} />
+          {offersBadge && <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />}
         </Box>
       )}
 
@@ -196,6 +238,11 @@ export async function drawPane($: EngineInterface, e: PaneInput): Promise<Render
           {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>
       )}
+      {view.decision !== undefined && offersBadge && (
+        <Box key="after-decision" flexDirection="row" gap={1} marginTop={1}>
+          <Button key="badge" label="Copy badge" hotkey="b" onPress={copyBadge} />
+        </Box>
+      )}
     </Box>
   )
 }

package/hooks/guard/view.ts

@@ -32,7 +32,15 @@ export function viewOf(report: ScanReport, action: GuardAction): GuardView {
     },
     rows: report.results.map(rowOf),
     kind: report.kind,
-    root: report.inventory === undefined ? undefined : safeLine(report.inventory.root),
+    // 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}`}`)
+        : report.inventory === undefined
+          ? undefined
+          : safeLine(report.inventory.root),
+    sha: report.source?.sha,
+    ...(report.source?.subdir === undefined ? {} : { subdir: encodeFolder(report.source.subdir) }),
     treeHash: report.inventory?.treeHash,
     expanded: [],
     details: false,
@@ -54,6 +62,7 @@ function rowOf(result: CheckResult): GuardRow {
     })),
     more: Math.max(0, result.evidence.length - EVIDENCE_PER_ROW),
     advice: result.advice,
+    ...(result.summary === undefined || result.summary.length === 0 ? {} : { summary: result.summary.slice(0, 8).map(line => clip(safeLine(redactSecrets(line)))) }),
   }
 }
 
@@ -67,3 +76,12 @@ export function primaryLabel(view: GuardView): string {
   const verb = view.action === 'install' ? 'Install' : 'Approve'
   return needsConfirmation(view) ? `${verb} anyway` : verb
 }
+
+/**
+ * A folder name as the pane and a badge show it: whole characters other than
+ * letters, digits and `_ . / -` percent-encoded, so the exact folder stays
+ * named and nothing in it can be read as markup or hide itself.
+ */
+export function encodeFolder(folder: string): string {
+  return folder.replace(/[^\w./-]/gu, char => [...new TextEncoder().encode(char)].map(byte => `%${byte.toString(16).toUpperCase().padStart(2, '0')}`).join(''))
+}

package/hooks/mod-host.ts

@@ -27,5 +27,6 @@ export function modHost($: EngineInterface): Host {
       throw new Error(`could not read the link ${path}`)
     },
     run: (argv, options) => $.process.run(argv, options),
+    fetch: (url, init) => $.http.fetch(url, init),
   }
 }