sf-docs-agent 0.1.3 → 0.1.4

package/README.md

@@ -28,7 +28,7 @@ Needs Node 22+ and Claude Code.
 npx sf-docs-agent
 ```
 
-Then start a new Claude Code session. The agent is listed as `sf-docs`. Add `--project` to install it for the current project only.
+Then start a new Claude Code session. The agent is listed as `sf-docs`. Add `--project` to install it for the current project only. Claude Code then runs the agent's hook only in a folder you trust: in one you have not trusted, for example under `claude -p`, the agent runs without it.
 
 <details>
 <summary>Headless browser, Linux, update, remove, cache</summary>
@@ -102,9 +102,9 @@ Every number, per question, with the method: [docs/benchmarks.md](https://github
 - Help, admin and some older developer guides have no `.md` copy, so those pages are slower. If Salesforce changes their layout, the agent may read only part of an article. A daily check in this repo flags it.
 - No Help search, because Help's `robots.txt` disallows it.
 - From a page it found, it follows at most two more links in a row, and only toward a missing part of the answer. Anything further comes back as a gap.
-- On a long list it sometimes stops a row early. The quotes it gives are still right.
+- When a search term lands in a list or table, the script prints the whole list, one a page, up to 60 lines; a longer one it names by its line range. It cannot see a list on a rendered page, which has no list markers, and there the agent can still stop a row early. The quotes it gives are still right.
 - If a site blocks headless browsers, it stops and tells you. It does not try to get around the block.
-- The agent has Bash. Its instructions limit it to its script and cache, but that is an instruction to the model, not a sandbox.
+- The agent has Bash and Read. A hook limits Bash to the agent's script and to `grep` on files in its install folder. It limits Read to that folder. The hook stops all other commands. It checks the text of each command before the command runs, so it is not an operating system sandbox.
 - No telemetry. Only the docs pages it fetches leave your machine.
 
 How it reads each site, and the full list: [docs/how-it-works.md](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/how-it-works.md)

package/agents/sf-docs.md

@@ -3,6 +3,12 @@ name: sf-docs
 description: Answers a question from official Salesforce docs (developer, architect, help, admin and lightningdesignsystem.com) with verbatim quotes the script copies from the cached page, each tied to its official URL and line. Use it proactively whenever the user wants something read, scanned, checked or looked up in Salesforce documentation, even without naming this agent ("what does Help say about X", "check the Apex guide for Y", "scan the docs on Z"), and when you do not know which page holds the answer. Brief it with the question, the site or product if known, and the width ("the one concept page" or "the whole doc set"). Delegate even for one page you already know, with its URL in the brief: a page is thousands of tokens in your context and the agent's report is about 400. A URL on one of those sites in the question is for this agent too; do not WebFetch or curl it, those get a 403, an empty JavaScript shell or a raw HTML page. Show the user its Answer and Sources. To check a quote, run `grep -c -F -f - <cache path>` with the quote on stdin through a quoted heredoc (`<<'EOF'`), so an apostrophe in it cannot break the shell: one quote on one line, no blank line, since grep counts a blank line as matching every line. Reads docs only. Not for org state.
 model: claude-sonnet-5-5
 tools: Bash, Read
+hooks:
+  PreToolUse:
+    - matcher: "Bash|Read"
+      hooks:
+        - type: command
+          command: 'node "/path/to/sf-docs-agent/guard.mjs" || exit 2'
 ---
 
 ## Role
@@ -30,7 +36,7 @@ node "/path/to/sf-docs-agent/fetch-docs.mjs" <url> [<url> ...]
 
 Each argument is a URL on one of the sites above (`https://` may be left off). Always write the host: a bare
 `/docs/...` path means developer.salesforce.com, but Git Bash on Windows rewrites a leading `/` into a Windows path.
-Quote any URL that holds `?` or `&`. Pass many URLs in one call: it opens one browser.
+Quote any URL that holds `?`, `&` or `#`. Pass many URLs in one call: it opens one browser.
 Pass `--budget 480` on every fetch and `timeout: 600000` on its Bash call. The script starts no page after 480 s and
 prints `not fetched (time limit) <url>` for each one left: rerun only those URLs. A call that passes the Bash limit is
 moved to the background and you lose its output, though every page it printed is cached. Up to 20 URLs a call; past
@@ -55,6 +61,8 @@ that, the printed output is the limit, not time.
   term, numbered, under `== <file>`, then the matching lines of its `.links.txt`. Past 20 lines (10 for links), those with
   the rarest terms win: add a term to narrow. A page of up to 40 lines and 4,000 chars prints whole,
   marked `(short page, shown whole)`: read it all before saying it lacks something. To search a page you already have for other terms, fetch it again with them; it comes from the cache.
+  When matches land in a list or table, one a page prints whole, marked `(list or table, lines a-b, shown whole)`;
+  a longer one prints `(list or table, lines a-b, ...: too long to show; Read a-b)`.
   `--search 'a,b'` [`--site <host>`] prints the same ranked lines across every cached page except indexes and
   sitemaps, at most 3 a file, with the file.
 - Never pass `--out`. The cache dir every run shares is
@@ -84,11 +92,12 @@ Every tool call costs you the whole conversation again, so use as few Bash calls
 2. **Fetch and locate.** Fetch the pages you picked with `--terms`. On Help or LDS, the `.links.txt` matches name the
    next page.
 3. **Look.** To see the lines around a match, use Read with `offset` and `limit`, or `grep -n -C3 -e '<term>' <file>`:
-   both number lines as `--quote` counts them. `sed -n` and `head` do not, so never take a line number from them.
+   both number lines as `--quote` counts them.
    Leave quote marks out of a grep term and search the words on either side: a `'` ends the shell quote, and a
    curly one from the question misses a page saved with straight ones.
-   Never read a page whole. When the answer is a list or a table (patterns, editions, values), Read from its first
-   item to the next heading before you quote: a `--terms` match list stops at its cap, and the last rows may not
+   Never read a page whole. When the answer is a list or a table (patterns, editions, values), quote it from the
+   `(list or table ...)` block `--terms` printed. Read only a range it names as too long to show, or, when no block
+   printed, from the list's first item to the next heading: a match list stops at its cap, and the last rows may not
    hold your term.
 4. **Two hops at most.** If a matched line, a `.links.txt` match or a sentence you will quote names another page that
    holds part of the answer (a child article, a "Limitations for ..." heading with no text under it, an index entry
@@ -110,7 +119,10 @@ Every tool call costs you the whole conversation again, so use as few Bash calls
   JavaScript shell on Help, or raw HTML with no Source line for `--quote`.
 - If the script prints a `BLOCKED:` line, or Node cannot find `playwright-core`, stop and report the error lines as
   printed (after `BLOCKED:` they include the install command). Do not install anything yourself.
-- Bash is for running the script and reading the cache dir. Write nothing anywhere else.
+- A hook limits Bash to the script and to `grep` on files in the script's dir, and Read to files in that dir. Join
+  commands only with `&&`. Use absolute paths and name each file: no unquoted wildcards or `#`. grep takes short
+  options only (no `--`), `-r` but not `-R`. No pipes, `cd`, `;`, shell variables, loops, `eval` or redirects other
+  than `2>&1`: write each URL out in full, up to 20 a call. A denied call says why; change the call.
 - Run every command in the foreground and wait for it. Never run one in the background or wait on a monitor: your
   last message is the report, so a run that ends while a fetch is still going returns no answer.
 - Only the sites above: the script refuses any other host. A third-party blog or forum is never evidence, even when a

package/bin/install.mjs

@@ -16,6 +16,7 @@ const agents = project ? resolve('.claude', 'agents') : join(config, 'agents');
 
 mkdirSync(runtime, { recursive: true });
 cpSync(join(pkg, 'fetch-docs.mjs'), join(runtime, 'fetch-docs.mjs'));
+cpSync(join(pkg, 'guard.mjs'), join(runtime, 'guard.mjs')); // the agent's PreToolUse hook, named in its frontmatter
 // A devDependency: npx would otherwise download playwright-core once for the installer and again for the runtime.
 const version = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).devDependencies['playwright-core'];
 writeFileSync(join(runtime, 'package.json'),

package/fetch-docs.mjs

@@ -89,31 +89,126 @@ const matches = (name, text, t) => text.split('\n').flatMap((line, i, ls) => {
   const low = i || !ls[0].startsWith('Source: ') ? plain(line).toLowerCase() : '', hit = t.filter(s => low.includes(s)); // a page's line 1 is its Source line; a sidecar has none
   return hit.length ? [{ name, n: i + 1, line, hit, at: Math.min(...hit.map(s => low.indexOf(s))) }] : [];
 });
-const rank = (ms, max = MAX_HITS) => {
-  if (ms.length <= max) return ms;
+const scorer = ms => {
   const df = Object.create(null); // a term like 'constructor' must not read Object.prototype
   for (const m of ms) for (const s of m.hit) df[s] = (df[s] || 0) + 1;
-  const score = m => m.hit.reduce((a, s) => a + 1 / df[s], 0);
+  return m => m.hit.reduce((a, s) => a + 1 / df[s], 0);
+};
+const rank = (ms, max = MAX_HITS, score = scorer(ms)) => {
+  if (ms.length <= max) return ms;
   return ms.map((m, k) => [score(m), k, m]).sort((a, b) => b[0] - a[0] || a[1] - b[1]).slice(0, max)
     .sort((a, b) => a[1] - b[1]).map(x => x[2]);
 };
 const show = m => `${m.n}: ${m.line.length > 300 ? `...${m.line.slice(Math.max(0, m.at - 100), m.at + 200)}...` : m.line}`;
 const more = (all, top) => all.length > top.length ? [`(${all.length - top.length} more lower-ranked lines: add a term to narrow)`] : [];
+
+// A list or table a match lands in prints whole, so no reading window ends a row short. One block a page: three
+// doubled the benchmark's output with short lists nobody asked about.
+const BLOCKS = 1, BLOCK_LINES = 60, BLOCK_LINE = 1000, BLOCK_CHARS = 6000, BLOCK_MAX = 200;
+const BOLD = /^\*\*[^*]+\*\*:?\s*$/, HEAD = new RegExp(`^#{1,6}\\s|${BOLD.source}`);
+// Code fences, CommonMark: opened by ``` (no backtick after it) or ~~~, closed by a bare line of the same character, at
+// least as long; [open, close] line pairs. An opener that never closes fences the rest of the page, or with skipStray
+// is taken as stray text (rendered Help has them) and the scan goes on after it.
+const fences = (ls, skipStray) => {
+  const out = [];
+  for (let i = 0; i < ls.length; i++) {
+    const f = /^\s*(`{3,}(?=[^`]*$)|~{3,})/.exec(ls[i])?.[1];
+    if (!f) continue;
+    let j = i + 1;
+    for (let c; j < ls.length; j++) if ((c = /^\s*(`{3,}|~{3,})\s*$/.exec(ls[j])?.[1]) && c[0] === f[0] && c.length >= f.length) break;
+    if (j < ls.length) { out.push([i, j]); i = j; } else if (!skipStray) { out.push([i, ls.length - 1]); break; }
+  }
+  return out;
+};
+// Rows: markdown table and list lines, rendered table lines (tabs), and paragraphs that open with a link or are only
+// bold or italic text (a table or term list flattened, as on the architect pages).
+const rowKind = l => {
+  if (/^\s*\|/.test(l)) return '|';
+  if (l.includes('\t')) return '\t'; // before list markers: a rendered cell can start with '-' or '1.'
+  const li = /^(\s*)(?:[-*+]|\d+[.)])\s/.exec(l);
+  if (li) return `-${li[1].length}`; // a deeper item continues the one above it
+  return /^\[[^\]]+\]\(/.test(l) ? '[' : BOLD.test(l) ? '**' : /^_[^_]+_\s*$/.test(l) ? '_' : '';
+};
+// Paragraph rows may have a description of up to two lines between them; other rows none.
+const PARAS = new Set(['[', '**', '_']);
+// A rendered cell spills over lines up to the next tab row when that row opens with a tab.
+const spills = (ls, j) => { for (let n = j; n < Math.min(ls.length, j + 30); n++) if (ls[n].includes('\t')) return ls[n].startsWith('\t'); return false; };
+// Blocks of 3 or more rows of one kind, as 1-based [first, last] lines; a rendered row ending in a tab has an open
+// cell, which spills over up to 30 lines.
+const blocksOf = ls => {
+  // A fence is one unit, never rows (a doc comment's ' * ' lines read as a list). A stray opener is skipped here;
+  // lean keeps it as code to the end, which leaves the text untouched.
+  const fenced = ls.map(() => false), close = [];
+  for (const [o, c] of fences(ls, true)) { fenced.fill(true, o, c + 1); close[o] = c; }
+  const out = [];
+  for (let i = 1; i < ls.length; i++) {
+    const k = rowKind(ls[i]), indent = k[0] === '-' ? Number(k.slice(1)) : -1;
+    if (!k) continue;
+    let end = i, rows = 1, gap = 0, described = false, open = k === '\t' && ls[i].endsWith('\t') ? i : 0, j = i + 1;
+    for (; j < ls.length; j++) {
+      const l = ls[j];
+      if (!l.trim()) continue;
+      const deeper = indent >= 0 && /^\s*/.exec(l)[0].length > indent;
+      if (close[j] !== undefined && deeper) { end = j = close[j]; continue; } // code under the item: skip it whole
+      if (fenced[j]) break;
+      const rk = rowKind(l);
+      if (rk === k) { rows++; end = j; described ||= gap > 0; gap = 0; open = k === '\t' && l.endsWith('\t') ? j : 0; continue; }
+      if ((open && j - open <= 30) || deeper || (k === '\t' && spills(ls, j))) { end = j; continue; }
+      if (HEAD.test(l) || rk || ++gap > (PARAS.has(k) ? 2 : 0)) break; // a row of another kind starts its own run
+    }
+    if (described) for (let t = end + 1; t < j; t++) if (ls[t].trim()) end = t; // the last row's description
+    if (rows >= 3) {
+      // Lead-in: up to 2 caption lines, then a heading right above them (Q50 has both).
+      let a = i;
+      for (let t = i - 1, n = 0; t >= 1 && t > (out.at(-1)?.[1] ?? 0) - 1; t--) { // not into the block above
+        if (fenced[t]) break;
+        if (!ls[t].trim()) continue;
+        if (HEAD.test(ls[t])) { a = t; break; } // before rowKind: a bold caption also reads as a bold-term row
+        if (rowKind(ls[t]) || ls[t].length > 200 || n === 2) break;
+        a = t; n++;
+      }
+      out.push([a + 1, end + 1]);
+      i = end; // past a block only, to its last line: the line that broke the run may open the next one
+    }
+  }
+  return out;
+};
+// The block whose matches score highest (rarer terms count more), then the densest, prints whole or as its range;
+// one past BLOCK_MAX lines is left to its matching lines ("Read 1,300 lines" is no help).
+const blockLines = (ls, all, score) => blocksOf(ls).filter(([a, b]) => b - a < BLOCK_MAX)
+  .map(([a, b]) => ({ a, b, s: all.filter(m => m.n >= a && m.n <= b).reduce((t, m) => t + score(m), 0) }))
+  .filter(x => x.s).sort((x, y) => y.s - x.s || y.s / (y.b - y.a) - x.s / (x.b - x.a) || x.a - y.a)
+  .slice(0, BLOCKS).map(({ a, b }) => {
+    // Never cut: a block that prints is whole, so a line past BLOCK_LINE makes it too long instead.
+    const body = ls.slice(a - 1, b).map((l, i) => [a + i, l]).filter(([, l]) => l.trim());
+    const fits = body.length <= BLOCK_LINES && body.every(([, l]) => l.length <= BLOCK_LINE)
+      && body.reduce((s, [, l]) => s + l.length, 0) <= BLOCK_CHARS;
+    return { a, b, out: fits ? [`(list or table, lines ${a}-${b}, shown whole)`, ...body.map(([n, l]) => `${n}: ${l}`)]
+      : [`(list or table, lines ${a}-${b}, ${b - a + 1} lines: too long to show; Read ${a}-${b})`], fits };
+  });
 // A page this short is printed whole: its answer can sit on a line no term matches (a Help page's "95%" line).
 // Index files by shape (Help's /apex/Help_*SiteMap* pages, *sitemap*.xml), on the path under the cache dir: a doc
 // page about sitemaps, or an --out dir named for them, is neither.
 const indexKind = rel => /(^|\/)apex\/Help_\w*SiteMapIndex|sitemap_index[^/]*\.xml$/i.test(rel) ? 'index'
   : /(^|\/)apex\/Help_\w*SiteMap|[^/]*sitemap[^/]*\.xml$/i.test(rel) ? 'map' : '';
+// llms.txt and llms-<product>.txt, not a page whose cached name starts with llms (llms-overview.html.txt).
+const isLlms = rel => /(^|\/)llms(-[\w-]+)?\.txt$/i.test(rel);
 const grep = (file, t) => {
-  const text = readFileSync(file, 'utf8'), lines = text.split('\n'), kind = indexKind(slash(relative(out, file)));
-  if (!file.endsWith('.links.txt') && lines.length <= SHORT_LINES && text.length <= SHORT_CHARS)
+  const text = readFileSync(file, 'utf8'), lines = text.split('\n'), rel = slash(relative(out, file)), kind = indexKind(rel);
+  const links = file.endsWith('.links.txt');
+  if (!links && lines.length <= SHORT_LINES && text.length <= SHORT_CHARS)
     return ['(short page, shown whole)', ...lines.slice(1, text.endsWith('\n') ? -1 : undefined).map((l, i) => `${i + 2}: ${l}`)]; // line 1 is the Source line
   // A sitemap index names page sitemaps, not topics, so no term can pick among them: print every <loc> line.
   if (kind === 'index') return matches(null, text, ['<loc>']).map(show);
   // A sitemap lists each article twice (<loc> and its alternates): keep the <loc> line and show 40 articles.
   const map = kind === 'map', all = matches(null, text, t).filter(m => !map || m.line.includes('<loc>'));
-  const top = rank(all, map ? 40 : file.endsWith('.links.txt') ? MAX_LINKS : MAX_HITS);
-  return [...top.map(show), ...more(all, top)];
+  // An llms.txt index is one long list of pages: its matching lines are the answer, not the list.
+  if (map || links || isLlms(rel)) { const top = rank(all, map ? 40 : links ? MAX_LINKS : MAX_HITS); return [...top.map(show), ...more(all, top)]; }
+  // Lines a printed block shows are not repeated; the rest are ranked as before, and both print in page order.
+  const score = scorer(all), blocks = all.length ? blockLines(lines, all, score) : [], rest = all.filter(m => !blocks.some(x => x.fits && m.n >= x.a && m.n <= x.b));
+  const top = rank(rest, MAX_HITS, score); // rarity over the whole page, not only the lines left
+  return [...top.map(m => [m.n, [show(m)]]), ...blocks.map(x => [x.a, x.out])].sort((x, y) => x[0] - y[0])
+    .flatMap(x => x[1]).concat(more(rest, top));
 };
 
 // --quote: the agent picks line numbers, the script copies the lines, so quotes are verbatim by construction.
@@ -165,7 +260,7 @@ if (args[0] === '--search') {
     const rel = slash(relative(out, f));
     // Sidecars and markers are not pages; a file another run pruned mid-walk is skipped.
     if (/\.(links\.txt|missing|tmp|fallback)$/.test(rel) || !statSync(f, { throwIfNoEntry: false })?.isFile()) continue;
-    if (/(^|\/)llms[^/]*\.txt$/i.test(rel) || indexKind(rel)) continue; // indexes: --terms on the index already shows them
+    if (isLlms(rel) || indexKind(rel)) continue; // indexes: --terms on the index already shows them
     // At most PER_FILE lines a file, so ties across files cannot all come from the one that sorts first.
     try { const ms = matches(rel, readFileSync(f, 'utf8'), t); total += ms.length; all.push(...rank(ms, PER_FILE)); }
     catch (e) { if (e.code !== 'ENOENT') throw e; }
@@ -312,12 +407,10 @@ let ok = 0;
 // A saved page drops what is not doc text: image URLs (LDS signs S3 URLs of about 450 chars; the alt text stays) and
 // the padding in markdown table rows. Code blocks and wording are untouched.
 const lean = text => {
-  let code = ''; // the open fence: closed only by the same character, at least as long (CommonMark)
-  return text.split('\n').map(l => {
-    const f = /^\s*(`{3,}|~{3,})/.exec(l)?.[1];
-    if (f && !code) { code = f; return l; }
-    if (f && f[0] === code[0] && f.length >= code.length) { code = ''; return l; }
-    if (code) return l;
+  const ls = text.split('\n'), code = ls.map(() => false);
+  for (const [o, c] of fences(ls)) code.fill(true, o, c + 1);
+  return ls.map((l, i) => {
+    if (code[i]) return l;
     l = l.replace(/!\[([^\]]*)\]\(https?:\/\/[^)\s]+\)/g, '![$1]');
     return /^\s*\|/.test(l) ? l.replace(/ {2,}/g, ' ') : l;
   }).join('\n');

package/guard.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// PreToolUse hook for the sf-docs agent: Bash may run fetch-docs.mjs and grep on files in this dir; Read may open them.
+// It only denies (exit 2, reason on stderr), and denies anything its parser does not recognise; the rest falls through.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = realpathSync(dirname(fileURLToPath(import.meta.url)));
+const SCRIPT = join(ROOT, 'fetch-docs.mjs');
+const deny = why => {
+  console.error(`sf-docs guard: ${why}. Allowed: node "${SCRIPT.replaceAll('\\', '/')}" <args>, and grep on files under`
+    + ` "${ROOT.replaceAll('\\', '/')}" by absolute path, commands joined only by &&, grep with short options only (no -R).`
+    + ' No unquoted wildcards or #, pipes, cd, ;, variables, loops, redirects other than 2>&1, or other commands.');
+  process.exit(2);
+};
+// A crash exits 1, which Claude Code treats as a non-blocking error and runs the call: make it a deny.
+process.on('uncaughtException', e => deny(`guard error: ${e.message}`));
+// Judged by real path (of its nearest existing parent, for a file not there yet), so no symlink leads in or out.
+const real = p => {
+  let head = p, tail = '';
+  while (!existsSync(head)) { if (dirname(head) === head) return p; tail = join(basename(head), tail); head = dirname(head); }
+  return join(realpathSync(head), tail);
+};
+const inside = p => { const r = relative(ROOT, real(p)); return !r.startsWith('..') && !isAbsolute(r); };
+
+let input;
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { deny('hook input is not JSON'); }
+const { tool_name: tool, tool_input: args = {} } = input;
+if (tool === 'Read') {
+  if (typeof args.file_path !== 'string' || !isAbsolute(args.file_path) || !inside(resolve(args.file_path)))
+    deny(`Read is limited to files under the install dir, not ${args.file_path}`);
+  process.exit(0);
+}
+if (tool !== 'Bash') process.exit(0);
+if (typeof args.command !== 'string') deny('no command');
+
+// Split into commands of words on &&. Single quotes are literal; a $, backtick or any other shell syntax outside
+// them is refused, so every word the shell will see is the word checked here.
+const commands = [];
+{
+  // Trim space, tab and newline only: JS trim() also strips \v, \r and NBSP, which the shell keeps as word text.
+  const src = args.command.replace(/^[ \t\n]+|[ \t\n]+$/g, '');
+  // No control character but tab, quoted or not: a NUL cuts a word, and a backslash-newline is dropped even in "...".
+  if (/[\0-\x08\x0a-\x1f\x7f-\x9f]/.test(src)) deny('a newline or control character');
+  let cmd = [], word = null;
+  const end = () => { if (word) cmd.push(word); word = null; };
+  const add = c => { word ??= { text: '' }; word.text += c; };
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (c === "'") {
+      const j = src.indexOf("'", i + 1);
+      if (j < 0) deny('unclosed quote');
+      add(src.slice(i + 1, j)); i = j;
+    } else if (c === '"') {
+      add('');
+      for (i++; src[i] !== '"'; i++) {
+        if (i >= src.length) deny('unclosed quote');
+        if (src[i] === '$' || src[i] === '`') deny('variables and command substitution');
+        if (src[i] === '\\' && '"\\'.includes(src[i + 1])) i++;
+        word.text += src[i];
+      }
+    } else if (c === '\\') {
+      if (i + 1 >= src.length) deny('trailing backslash');
+      add(src[++i]);
+    } else if (c === ' ' || c === '\t') end();
+    else if (c === '&' && src[i + 1] === '&') { end(); commands.push(cmd); cmd = []; i++; }
+    else if (c === '2' && !word && src.startsWith('2>&1', i)
+      && ([' ', '\t', undefined].includes(src[i + 4]) || src.startsWith('&&', i + 4))) i += 3;
+    // A wildcard is checked as text but run as the files it matches (a symlink, or .. on bash before 5.2).
+    else if ('*?['.includes(c)) deny(`wildcard ${c}: name each file, or quote the pattern`);
+    else if ('$`'.includes(c)) deny('variables and command substitution');
+    else if (c === '|' || c === ';') deny(`${c}: join commands only with &&`);
+    // # anywhere: zsh's extendedglob makes x# a wildcard. = only starts a word in zsh's =cmd expansion.
+    else if ('&<>(){}!#~=^'.includes(c) && (!word || c !== '=')) deny(`shell syntax ${c}`);
+    else add(c);
+  }
+  end();
+  commands.push(cmd);
+}
+
+// grep short options only; VALUES take a value. -C only attached (-C3): BSD's -C value is optional. No -R: GNU -R
+// follows every symlink it meets, GNU -r only those named on the line (checked here), BSD -r none by default.
+const FLAGS = 'cEFhHiIlLnoqrsvwx0123456789', VALUES = 'eABmC';
+for (const words of commands) {
+  const [cmd, ...rest] = words.map(w => w.text);
+  const path = w => {
+    if (!isAbsolute(w.text) || !inside(w.text)) deny(`${cmd} ${w.text}: not an absolute path under the install dir`);
+  };
+  if (cmd === 'node') {
+    if (!isAbsolute(rest[0]) || real(rest[0]) !== SCRIPT) deny(`node runs only fetch-docs.mjs, not ${rest[0]}`);
+    if (rest.some(a => a === '--out' || a.startsWith('--out='))) deny('--out moves the cache');
+    continue;
+  }
+  if (cmd !== 'grep') deny(`${cmd} is not allowed`);
+  // GNU grep reorders options, so an -e anywhere makes every positional a file: then none is taken as the pattern.
+  let pattern = !words.some(w => /^-[^-]*e/.test(w.text)), paths = 0;
+  for (let k = 1; k < words.length; k++) {
+    const t = words[k].text;
+    if (t === '--') deny('grep --: drop it, and give the pattern with -e');
+    if (t.startsWith('--')) deny(`grep ${t.split('=')[0]}: use the short option`); // the allowlist below denies it anyway
+    if (t.startsWith('-') && t.length > 1) {
+      for (let p = 1; p < t.length; p++) {
+        const c = t[p];
+        if (VALUES.includes(c)) {
+          if (p === t.length - 1) { if (c === 'C') deny('grep -C takes its number attached, like -C3'); if (++k >= words.length) deny(`-${c} needs a value`); }
+          break; // the rest of the word, or the next word, is the value
+        }
+        if (!FLAGS.includes(c)) deny(`grep -${c} is not allowed`);
+      }
+      continue;
+    }
+    if (pattern) { pattern = false; continue; }
+    path(words[k]);
+    paths++;
+  }
+  // grep with no file reads stdin, which nothing feeds here; -r with no file reads the shell's unknown cwd.
+  if (!paths) deny('grep needs a file under the install dir');
+}
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sf-docs-agent",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Claude Code subagent that answers from official Salesforce docs (developer, architect, help, admin, lightningdesignsystem.com) with grep-checked quotes",
   "devDependencies": {
@@ -12,7 +12,8 @@
   "files": [
     "bin",
     "agents",
-    "fetch-docs.mjs"
+    "fetch-docs.mjs",
+    "guard.mjs"
   ],
   "repository": {
     "type": "git",