@shomra/agent 0.3.17 → 0.3.19

package/src/gate/batch.mjs

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import { MAX_ARTIFACT_BYTES } from '../artifacts/matchers.mjs';
+import { api, gateMachine } from '../core/api-client.mjs';
+import { clampInt } from '../core/numbers.mjs';
+import { SEV_COLOR, bold, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { localGate } from '../detect/guard-signals.mjs';
+import { applyRepoPolicy, loadRepoPolicy } from './repo-policy.mjs';
+import { localAsGateResult } from './result.mjs';
+import { collectLocalSast, mergeSastIntoResult } from './sast.mjs';
+import { loadBaseline, loadIgnoreRules, suppressResult } from './suppressions.mjs';
+
+const DEFAULT_CONCURRENCY = 8;
+const MIN_CONCURRENCY = 1;
+const MAX_CONCURRENCY = 32;
+const MAX_FINDINGS_SHOWN = 3;
+const FAIL_ON_RANK = { critical: 3, high: 2, medium: 1 };
+
+function readArtifact(artifact, quiet) {
+  try {
+    if (fs.statSync(artifact.full).size > MAX_ARTIFACT_BYTES) {
+      if (!quiet) console.log(`  ${gray('•')} ${dim(artifact.rel)} ${yellow('skipped (too large)')}`);
+      return null;
+    }
+    return fs.readFileSync(artifact.full, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function analyseLocally(artifacts, quiet) {
+  const prepared = [];
+  for (const artifact of artifacts) {
+    const content = readArtifact(artifact, quiet);
+    if (content == null) continue;
+    prepared.push({
+      artifact,
+      content,
+      local: localGate(content, { kind: artifact.kind, path: artifact.rel }),
+      sast: collectLocalSast({ fullPath: artifact.full, relPath: artifact.rel, kind: artifact.kind, content }),
+    });
+  }
+  return prepared;
+}
+
+async function requestServerVerdicts(prepared, { apiKey, url, env, flags, quiet }) {
+  const verdicts = new Array(prepared.length).fill(null);
+  const rejected = [];
+  let backendDown = false;
+  if (!apiKey) return { verdicts, rejected, backendDown };
+
+  const concurrency = clampInt(process.env.SHOMRA_GATE_CONCURRENCY, DEFAULT_CONCURRENCY, MIN_CONCURRENCY, MAX_CONCURRENCY);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    for (;;) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= prepared.length || backendDown) return;
+
+      const { artifact, content } = prepared[index];
+      try {
+        verdicts[index] = await api(url, apiKey, '/gate/check', {
+          kind: artifact.kind,
+          path: artifact.rel,
+          content,
+          machine: gateMachine(),
+          env,
+          ...(flags.project ? { projectId: String(flags.project) } : {}),
+        });
+      } catch (error) {
+        if (error?.rejected) {
+          rejected.push({ path: artifact.rel, kind: artifact.kind, reason: error.message });
+          continue;
+        }
+        if (!backendDown && !quiet) {
+          console.log(`  ${yellow('⚠')} ${dim(`backend unavailable (${error.message}) - on-machine analysis for the rest`)}`);
+        }
+        backendDown = true;
+        return;
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, prepared.length) }, worker));
+  return { verdicts, rejected, backendDown };
+}
+
+function printResult(result, artifact, source) {
+  const colour = result.decision === 'BLOCK' ? red : result.decision === 'FLAG' ? yellow : green;
+  const suppressedNote = result.suppressedCount ? dim(` · ${result.suppressedCount} suppressed`) : '';
+  const pathNote = artifact.rel !== result.name ? ` ${dim(artifact.rel)}` : '';
+  const localNote = source === 'local' ? dim(' ·local') : '';
+  const findingCount = result.findingCount ?? (result.findings || []).length;
+
+  console.log(`  ${colour('●')} ${bold(result.name)}${pathNote}${localNote} ${colour(result.decision)} ${dim(`risk ${result.riskScore} · ${findingCount} finding(s)`)}${suppressedNote}`);
+
+  const findings = result.findings || [];
+  for (const finding of findings.slice(0, MAX_FINDINGS_SHOWN)) {
+    const location = finding.line ? dim(` (${finding.file || artifact.rel}:${finding.line})`) : '';
+    console.log(`      ${SEV_COLOR[finding.severity](String(finding.severity).padEnd(8))} ${finding.title}${location}`);
+  }
+  const remaining = findings.length - Math.min(findings.length, MAX_FINDINGS_SHOWN);
+  if (remaining > 0) console.log(`      ${dim(`… and ${remaining} more (run with --json for all)`)}`);
+}
+
+function resolveSuppression(flags, root) {
+  const enabled = !flags['no-suppress'];
+  return {
+    enabled,
+    rules: enabled ? loadIgnoreRules(root) : { fileGlobs: [], findingRules: [] },
+    baseline: enabled && !flags['no-baseline'] ? loadBaseline(root) : null,
+    lineCache: new Map(),
+  };
+}
+
+export async function gateArtifactList(artifacts, { apiKey, url, env, flags, root }) {
+  const quiet = flags.json || flags.sarif;
+  const workingRoot = root || process.cwd();
+  const suppression = resolveSuppression(flags, workingRoot);
+  const policy = flags['no-policy'] ? null : loadRepoPolicy(workingRoot);
+
+  const prepared = analyseLocally(artifacts, quiet);
+  const { verdicts, rejected, backendDown } = await requestServerVerdicts(prepared, { apiKey, url, env, flags, quiet });
+
+  const results = [];
+  let blocked = 0;
+  let flagged = 0;
+  let suppressed = 0;
+
+  prepared.forEach(({ artifact, local, sast }, index) => {
+    const serverVerdict = verdicts[index];
+    const source = serverVerdict ? 'server' : 'local';
+    const base = serverVerdict || localAsGateResult(local, artifact.rel.split('/').pop(), artifact.kind);
+    const merged = mergeSastIntoResult(base, sast);
+
+    const raw = { path: artifact.rel, full: artifact.full, kind: artifact.kind, source, ...merged };
+    const withSuppressions = suppression.enabled
+      ? suppressResult(raw, suppression.rules, suppression.baseline, suppression.lineCache)
+      : raw;
+    const result = applyRepoPolicy(withSuppressions, policy);
+
+    suppressed += result.suppressedCount || 0;
+    results.push(result);
+    if (result.decision === 'BLOCK') blocked += 1;
+    else if (result.decision === 'FLAG') flagged += 1;
+
+    if (!quiet) printResult(result, artifact, source);
+  });
+
+  return { results, blocked, flagged, suppressed, backendDown, rejected };
+}
+
+export function failOnHit(flags, blocked, flagged) {
+  const threshold = FAIL_ON_RANK[String(flags['fail-on'] || 'critical').toLowerCase()] ?? 3;
+  const worst = blocked > 0 ? 3 : flagged > 0 ? 2 : 0;
+  return worst > 0 && worst >= threshold;
+}

package/src/gate/environment.mjs

@@ -0,0 +1,122 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const GATE_KINDS = ['mcp', 'skill', 'command', 'subagent', 'hook', 'rules', 'agent-card', 'memory', 'auto'];
+
+export function detectEnv() {
+  const e = process.env;
+  const pick = (...keys) => {
+    for (const k of keys) if (e[k]?.trim()) return e[k].trim();
+    return undefined;
+  };
+  let ci = null;
+
+  if (e.GITHUB_ACTIONS)
+    ci = {
+      ciProvider: 'github-actions',
+      repo: e.GITHUB_REPOSITORY,
+
+      repoUrl: e.GITHUB_SERVER_URL && e.GITHUB_REPOSITORY ? `${e.GITHUB_SERVER_URL.replace(/\/+$/, '')}/${e.GITHUB_REPOSITORY}` : undefined,
+      ref: e.GITHUB_REF_NAME,
+      commit: e.GITHUB_SHA,
+    };
+  else if (e.GITLAB_CI)
+    ci = { ciProvider: 'gitlab-ci', repo: e.CI_PROJECT_PATH, repoUrl: e.CI_PROJECT_URL, ref: e.CI_COMMIT_REF_NAME, commit: e.CI_COMMIT_SHA };
+  else if (e.CIRCLECI)
+    ci = {
+      ciProvider: 'circleci',
+      repo: e.CIRCLE_PROJECT_REPONAME,
+      repoUrl: e.CIRCLE_REPOSITORY_URL,
+      ref: e.CIRCLE_BRANCH,
+      commit: e.CIRCLE_SHA1,
+    };
+  else if (e.TF_BUILD)
+    ci = {
+      ciProvider: 'azure-pipelines',
+      repo: e.BUILD_REPOSITORY_NAME,
+      repoUrl: e.BUILD_REPOSITORY_URI,
+      ref: e.BUILD_SOURCEBRANCHNAME,
+      commit: e.BUILD_SOURCEVERSION,
+    };
+  else if (e.BITBUCKET_BUILD_NUMBER)
+    ci = {
+      ciProvider: 'bitbucket-pipelines',
+      repo: e.BITBUCKET_REPO_FULL_NAME,
+      repoUrl: e.BITBUCKET_GIT_HTTP_ORIGIN,
+      ref: e.BITBUCKET_BRANCH,
+      commit: e.BITBUCKET_COMMIT,
+    };
+
+  else if (e.JENKINS_URL) ci = { ciProvider: 'jenkins', repo: pick('JOB_NAME'), repoUrl: pick('GIT_URL'), ref: e.GIT_BRANCH, commit: e.GIT_COMMIT };
+  else if (e.CI) ci = { ciProvider: 'ci', repo: undefined, repoUrl: undefined, ref: undefined, commit: undefined };
+
+  if (ci) {
+
+    const git = gitContext();
+    return {
+      environment: 'CI',
+      ciProvider: ci.ciProvider,
+      repo: ci.repo ?? git.repo,
+      repoUrl: ci.repoUrl ?? git.repoUrl,
+      ref: ci.ref ?? git.ref,
+      commit: ci.commit ?? git.commit,
+    };
+  }
+
+  return { environment: 'LOCAL', ...gitContext() };
+}
+
+function gitContext() {
+  const run = (args) => {
+    try {
+      return execSync(`git ${args}`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 })
+        .toString()
+        .trim();
+    } catch {
+      return undefined;
+    }
+  };
+  const origin = run('config --get remote.origin.url');
+  let repo;
+  if (origin) {
+    const m = origin.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+    repo = m ? m[1] : undefined;
+  }
+
+  let repoUrl = origin || undefined;
+  if (repoUrl) repoUrl = repoUrl.replace(/^([a-z][\w+.-]*:\/\/)[^/@]*@/i, '$1');
+  return { repo, repoUrl, ref: run('rev-parse --abbrev-ref HEAD'), commit: run('rev-parse HEAD') };
+}
+
+export function collectSiblings(fullTarget, relPath) {
+  const MAX = 400;
+  const MAX_DEPTH = 3;
+  const SKIP = new Set(['.git', 'node_modules', '.venv', 'venv', '__pycache__', 'dist', 'build']);
+  if (!fullTarget || !relPath) return [];
+  try {
+    const root = path.dirname(fullTarget);
+    const rootRel = path.dirname(relPath);
+    const out = [];
+    const walk = (dir, depth) => {
+      if (out.length >= MAX || depth > MAX_DEPTH) return;
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        if (out.length >= MAX) return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+          if (!SKIP.has(e.name)) walk(full, depth + 1);
+          continue;
+        }
+        if (!e.isFile() || full === fullTarget) continue;
+        const rel = path.relative(root, full).split(path.sep).join('/');
+        out.push(rootRel && rootRel !== '.' ? `${rootRel}/${rel}` : rel);
+      }
+    };
+    walk(root, 0);
+    return out;
+  } catch {
+    return [];
+  }
+}

package/src/gate/repo-policy.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEC_RANK } from './sast.mjs';
+
+const SEV_THRESH = { none: 99, critical: 5, high: 4, medium: 3, low: 2, info: 1 };
+
+const SEV_RANK_LOCAL = { INFO: 1, LOW: 2, MEDIUM: 3, HIGH: 4, CRITICAL: 5 };
+
+const WEIGHT_LOCAL = { INFO: 2, LOW: 8, MEDIUM: 20, HIGH: 40, CRITICAL: 70 };
+
+function parseSimpleYaml(text) {
+  const data = {}; let key = null;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const li = /^\s*-\s+(.*)$/.exec(line);
+    if (li && key) { (Array.isArray(data[key]) ? data[key] : (data[key] = [])).push(unquote(li[1].trim())); continue; }
+    const kv = /^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    key = kv[1];
+    const v = kv[2].trim();
+    data[key] = v === '' ? (data[key] ?? null) : v.startsWith('[') ? v.replace(/^\[|\]$/g, '').split(',').map((s) => unquote(s.trim())).filter(Boolean) : unquote(v);
+  }
+  return data;
+}
+
+function unquote(s) { return String(s).replace(/^["']|["']$/g, ''); }
+
+export function loadRepoPolicy(root) {
+  let text, file;
+  for (const f of ['policy.yml', 'policy.yaml', 'policy.json']) {
+    try { text = fs.readFileSync(path.join(root, '.shomra', f), 'utf8'); file = f; break; } catch {  }
+  }
+  if (text === undefined) return null;
+  let raw;
+  if (file.endsWith('.json')) { try { raw = JSON.parse(text); } catch { return null; } }
+  else raw = parseSimpleYaml(text);
+  return {
+    block: SEV_THRESH[String(raw.block || '').toLowerCase()] ?? SEV_RANK_LOCAL.CRITICAL,
+    flag: SEV_THRESH[String(raw.flag || '').toLowerCase()] ?? SEV_RANK_LOCAL.HIGH,
+    allow: [].concat(raw.allow || []).map((s) => String(s).toLowerCase()),
+  };
+}
+
+export function applyRepoPolicy(r, policy) {
+  if (!policy) return r;
+  let findings = r.findings || [];
+  let dropped = 0;
+  if (policy.allow.length) {
+    const keep = [];
+    for (const f of findings) {
+      if (policy.allow.some((sub) => sub && String(f.title || '').toLowerCase().includes(sub))) dropped++;
+      else keep.push(f);
+    }
+    findings = keep;
+  }
+  let worst = 0;
+  for (const f of findings) worst = Math.max(worst, SEV_RANK_LOCAL[f.severity] || 0);
+  const pv = worst >= policy.block ? 'BLOCK' : worst >= policy.flag ? 'FLAG' : 'ALLOW';
+  const riskScore = Math.min(100, findings.reduce((s, f) => s + (WEIGHT_LOCAL[f.severity] || 0), 0));
+
+  const decision = r.source === 'server' ? (DEC_RANK[pv] > DEC_RANK[r.decision] ? pv : r.decision) : pv;
+  const extra = dropped ? { suppressedCount: (r.suppressedCount || 0) + dropped, suppressedFindings: [...(r.suppressedFindings || []), ...(r.findings || []).filter((f) => !findings.includes(f)).map((f) => ({ ...f, suppressedBy: 'policy allow' }))] } : {};
+  return { ...r, findings, findingCount: findings.length, decision, riskScore: r.source === 'server' ? Math.max(r.riskScore || 0, riskScore) : riskScore, ...extra };
+}

package/src/gate/result.mjs

@@ -0,0 +1,53 @@
+import { SEV_COLOR, VERDICT_COLOR, bold, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+
+export function localAsGateResult(local, name, kind) {
+  return {
+    decision: local.verdict,
+    name: name || 'artifact',
+    kind: kind || 'auto',
+    riskScore: local.riskScore,
+    findingCount: local.findings.length,
+    findings: local.findings.map((f) => ({ severity: f.severity, title: f.title, remediationText: f.remediationText, ...(f.line ? { line: f.line } : {}) })),
+  };
+}
+
+export function printGateResult(res, source, flags) {
+  if (flags.json) {
+    console.log(JSON.stringify({ source, ...res }, null, 2));
+    return;
+  }
+  const dc = res.decision === 'BLOCK' ? red : res.decision === 'FLAG' ? yellow : green;
+  console.log(dc(res.decision) + (source === 'local' ? dim('  (on-machine)') : ''));
+  console.log(`\n  ${dc('●')} ${bold(res.name)} ${dim(`${res.kind} · risk ${res.riskScore}/100 · ${res.findingCount ?? (res.findings || []).length} finding(s)`)}`);
+  for (const f of res.findings || []) {
+    console.log(`     ${SEV_COLOR[f.severity](String(f.severity).padEnd(8))} ${f.title}`);
+    if (f.remediationText) console.log(`     ${dim('fix: ' + f.remediationText)}`);
+  }
+  for (const c of res.catalog || []) {
+    const vc = VERDICT_COLOR[c.verdict] || gray;
+    console.log(`     ${dim('catalog:')} ${c.name} ${vc(c.verdict ?? 'UNSCANNED')} ${dim('risk ' + c.riskScore)}`);
+  }
+  for (const p of res.policyHits || []) {
+
+    const note = p.suppressed ? dim('  (not enforced - accepted risk / ignored in your org)') : '';
+    console.log(`     ${dim('policy:')} ${p.policy} ${dim('→')} ${p.action}${note}`);
+  }
+  const triaged = (res.policyHits || []).filter((p) => p.suppressed).length;
+  if (triaged) console.log(`     ${dim(`${triaged} policy hit(s) suppressed by triage - reopen or let the acceptance expire to re-enforce.`)}`);
+  const orgNote = source === 'local' ? dim(' (on-machine analysis; org policy not applied)') : '';
+
+  const sev = (res.findings || []).reduce((a, f) => { a[f.severity] = (a[f.severity] || 0) + 1; return a; }, {});
+  const highish = (sev.CRITICAL || 0) + (sev.HIGH || 0);
+  const highNote = highish
+    ? `${sev.CRITICAL || 0} critical · ${sev.HIGH || 0} high still present - allowed by your org policy, not by the analysis.`
+    : 'No high-risk findings.';
+  if (res.decision === 'BLOCK') console.log(`\n  ${red('✗ Blocked.')}${orgNote} ${dim('Review the findings above.')}\n`);
+  else if (res.decision === 'FLAG') console.log(`\n  ${yellow('⚠ Flagged.')}${orgNote} ${dim('Proceed with caution.')}\n`);
+  else if (highish) console.log(`\n  ${green('✓ Allowed')} ${yellow('by policy.')}${orgNote} ${dim(highNote)}\n`);
+  else console.log(`\n  ${green('✓ Allowed.')}${orgNote} ${dim(highNote)}\n`);
+
+  for (const n of res.notAttempted || []) {
+    console.log(`  ${yellow('!')} ${bold('Not checked:')} ${n.why}`);
+    console.log(`     ${dim(n.enabledBy)}\n`);
+  }
+}

package/src/gate/sarif.mjs

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { VERSION } from '../core/version.mjs';
+
+const SARIF_LEVEL = { CRITICAL: 'error', HIGH: 'error', MEDIUM: 'warning', LOW: 'note', INFO: 'note' };
+
+const SARIF_SEC = { CRITICAL: '9.0', HIGH: '7.5', MEDIUM: '5.0', LOW: '3.0', INFO: '1.0' };
+
+function sarifRuleId(f) {
+  return f.ruleId || 'shomra.' + String(f.title || 'finding').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
+}
+
+export function toSarif(results) {
+  const rules = new Map();
+  const sarifResults = [];
+  for (const r of results) {
+    for (const f of r.findings || []) {
+      const id = sarifRuleId(f);
+      if (!rules.has(id)) rules.set(id, { id, name: id, shortDescription: { text: String(f.title || id).slice(0, 200) }, ...(f.cwe ? { properties: { cwe: f.cwe, tags: ['security', f.cwe] } } : { properties: { tags: ['security'] } }) });
+      sarifResults.push({
+        ruleId: id,
+        level: SARIF_LEVEL[f.severity] || 'warning',
+        message: { text: f.remediationText ? `${f.title} - ${f.remediationText}` : String(f.title || id) },
+        locations: [{ physicalLocation: { artifactLocation: { uri: f.file || r.path }, ...(f.line ? { region: { startLine: f.line } } : {}) } }],
+        properties: { severity: f.severity, 'security-severity': SARIF_SEC[f.severity] || '5.0', ...(f.cwe ? { cwe: f.cwe } : {}) },
+      });
+    }
+  }
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{ tool: { driver: { name: 'Shomra', informationUri: 'https://shomra.dev', version: VERSION, rules: [...rules.values()] } }, results: sarifResults }],
+  };
+}

package/src/gate/sast.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MAX_ARTIFACT_BYTES, SKIP_DIRS } from '../artifacts/matchers.mjs';
+import { isModelConfig, isScannableSource, scanSourceFile } from '../detect/code-sast.mjs';
+import { grade } from '../detect/guard-signals.mjs';
+
+const MAX_SAST_FILES = 60;
+
+function walkScripts(root) {
+  const found = [];
+  const stack = [root];
+  while (stack.length && found.length < MAX_SAST_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) { if (!SKIP_DIRS.has(ent.name)) stack.push(full); continue; }
+      if (isScannableSource(ent.name) || isModelConfig(ent.name)) {
+        found.push({ full, rel: path.relative(process.cwd(), full).split(path.sep).join('/') });
+        if (found.length >= MAX_SAST_FILES) break;
+      }
+    }
+  }
+  return found;
+}
+
+function sastToFinding(h) {
+  const base = h.file ? h.file.split('/').pop() : '';
+  return {
+    severity: h.severity,
+    title: `Risky code - ${h.title}${base ? ` in ${base}` : ''} (${h.sink})`,
+    remediationText: h.remediation,
+    ...(h.line ? { line: h.line } : {}),
+    analysis: 'sast', ruleId: h.ruleId, cwe: h.cwe, sink: h.sink, source: h.source,
+    file: h.file, snippet: h.snippet, snippetStartLine: h.snippetStartLine,
+  };
+}
+
+export function collectLocalSast({ fullPath, relPath, kind, content }) {
+  const out = [];
+  if (relPath && (isScannableSource(relPath) || isModelConfig(relPath))) {
+    for (const h of scanSourceFile(content || '', relPath)) out.push(sastToFinding(h));
+  }
+  const isSkill = kind === 'skill' || /(^|\/)SKILL\.md$/i.test(relPath || '');
+  if (isSkill && fullPath) {
+    for (const s of walkScripts(path.dirname(fullPath))) {
+      let text;
+      try { if (fs.statSync(s.full).size > MAX_ARTIFACT_BYTES) continue; text = fs.readFileSync(s.full, 'utf8'); } catch { continue; }
+      for (const h of scanSourceFile(text, s.rel)) out.push(sastToFinding(h));
+    }
+  }
+  return out;
+}
+
+export const DEC_RANK = { ALLOW: 0, FLAG: 1, BLOCK: 2 };
+
+export function mergeSastIntoResult(result, sastFindings) {
+  if (!sastFindings || !sastFindings.length) return result;
+  const findings = [...(result.findings || []), ...sastFindings];
+  const g = grade(findings);
+  const decision = DEC_RANK[g.verdict] > DEC_RANK[result.decision] ? g.verdict : result.decision;
+  return { ...result, decision, riskScore: Math.max(result.riskScore || 0, g.riskScore), findingCount: findings.length, findings };
+}

package/src/guard/classify.mjs

@@ -0,0 +1,50 @@
+import path from 'node:path';
+
+const ARTIFACT_PATH_RE = /(^|\/)(\.?mcp\.json|SKILL\.md|CLAUDE\.md|AGENTS\.md|GEMINI\.md|\.cursorrules|\.windsurfrules|\.aider\.conf\.yml|agent[-_]card\.json)$|(^|\/)\.claude\/(commands|agents)\/[^/]+\.md$|(^|\/)\.claude\/settings(\.local)?\.json$|(^|\/)\.well-known\/agent(-card)?\.json$|(^|\/)\.clinerules|(^|\/)\.github\/copilot-instructions\.md$/i;
+
+export const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'create_file', 'str_replace_editor', 'str_replace_based_edit_tool', 'write_to_file', 'replace_in_file', 'new_rule']);
+
+const SHELL_TOOLS_RE = /^(bash|shell|sh|run_command|run_terminal_cmd|execute_command|terminal|exec)$/i;
+
+const EGRESS_TOOL_RE = /fetch|web|http|browser|request|download|curl|url|open/i;
+
+const EGRESS_CMD_RE = /\b(curl|wget|nc|ncat|http|https|invoke-restmethod|invoke-webrequest|irm|iwr|scp|rsync|ftp|telnet)\b/i;
+
+export function guardText(tool, input) {
+  const parts = [];
+  if (typeof input.command === 'string') parts.push(input.command);
+  if (typeof input.cmd === 'string') parts.push(input.cmd);
+  if (typeof input.script === 'string') parts.push(input.script);
+  if (typeof input.content === 'string') parts.push(input.content);
+  if (typeof input.new_string === 'string') parts.push(input.new_string);
+  if (typeof input.new_source === 'string') parts.push(input.new_source);
+  if (Array.isArray(input.edits)) parts.push(input.edits.map((e) => e?.new_string ?? '').join('\n'));
+  if (!parts.length) { try { parts.push(JSON.stringify(input)); } catch { parts.push(String(input)); } }
+  return parts.join('\n');
+}
+
+export function guardTargetPath(norm) {
+  const i = norm.tool_input || {};
+  const p = i.file_path ?? i.path ?? i.notebook_path ?? i.filename ?? null;
+  return typeof p === 'string' && p.trim() ? p : null;
+}
+
+export function guardNeedsServer(tool, input, hasIdentity) {
+  if (hasIdentity) return true;
+  if (WRITE_TOOLS.has(tool)) {
+    const target = String(input.file_path ?? input.path ?? input.notebook_path ?? '').replace(/\\/g, '/');
+    return ARTIFACT_PATH_RE.test(target);
+  }
+  if (tool && tool.startsWith('mcp__')) return true;
+  if (EGRESS_TOOL_RE.test(tool || '')) return true;
+  if (SHELL_TOOLS_RE.test(tool || '')) {
+    const cmd = String(input.command ?? input.cmd ?? input.script ?? '');
+    if (EGRESS_CMD_RE.test(cmd)) return true;
+    if (/\bmcp\s+add\b|claude\s+mcp\b|@modelcontextprotocol\b|\bmcp[-_]server\b/i.test(cmd)) return true;
+  }
+  const url = input?.url ?? input?.uri ?? input?.href ?? input?.endpoint;
+  if (typeof url === 'string' && url) return true;
+  return false;
+}
+
+export const MODEL_WRITE_TOOLS = ['write', 'edit', 'multiedit', 'notebookedit', 'create_file', 'str_replace_editor', 'apply_patch', 'write_file'];

package/src/guard/emit.mjs

@@ -0,0 +1,51 @@
+import { dim } from '../core/terminal.mjs';
+
+export function emitGuardDeny(agent, reason) {
+  if (agent === 'windsurf') {
+    process.stderr.write(reason);
+    process.exit(2);
+  }
+  const bodies = {
+    cursor: () => ({ permission: 'deny', user_message: reason, agent_message: reason }),
+    copilot: () => ({ permissionDecision: 'deny', permissionDecisionReason: reason }),
+    gemini: () => ({ decision: 'deny', reason }),
+    codex: () => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }),
+    cline: () => ({ decision: 'deny', reason, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }),
+    claude: () => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }),
+  };
+  process.stdout.write(JSON.stringify((bodies[agent] || bodies.claude)()));
+  process.exit(0);
+}
+
+export function emitResultBlock(agent, reason) {
+
+  if (agent === 'windsurf') {
+    console.error(dim(reason));
+    process.exit(0);
+  }
+  const bodies = {
+    cursor: () => ({ permission: 'deny', user_message: reason, agent_message: reason }),
+    copilot: () => ({ permissionDecision: 'deny', permissionDecisionReason: reason }),
+    gemini: () => ({ decision: 'deny', reason }),
+    codex: () => ({ decision: 'block', reason, hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reason } }),
+    cline: () => ({ decision: 'block', reason, hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reason } }),
+    claude: () => ({ decision: 'block', reason, hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: reason } }),
+  };
+  process.stdout.write(JSON.stringify((bodies[agent] || bodies.claude)()));
+  process.exit(0);
+}
+
+export function emitGuardAsk(agent, reason) {
+  const bodies = {
+    cursor: () => ({ permission: 'ask', user_message: reason, agent_message: reason }),
+    copilot: () => ({ permissionDecision: 'ask', permissionDecisionReason: reason }),
+    gemini: () => ({ decision: 'ask', reason }),
+    codex: () => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: reason } }),
+    cline: () => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: reason } }),
+    claude: () => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: reason } }),
+  };
+
+  if (agent === 'windsurf' || !bodies[agent]) { process.stderr.write(reason + '\n'); process.exit(0); }
+  process.stdout.write(JSON.stringify(bodies[agent]()));
+  process.exit(0);
+}

package/src/guard/ignore.mjs

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { globToRe, loadIgnoreRules } from '../gate/suppressions.mjs';
+
+const _guardIgnoreCache = new Map();
+
+function guardIgnoreGlobs(root) {
+  if (_guardIgnoreCache.has(root)) return _guardIgnoreCache.get(root);
+  const globs = [];
+  try { for (const re of loadIgnoreRules(root).fileGlobs) globs.push(re); } catch {  }
+  const env = process.env.SHOMRA_GUARD_IGNORE;
+  if (env) for (const g of String(env).split(/[,\n]+/).map((s) => s.trim()).filter(Boolean)) { try { globs.push(globToRe(g)); } catch {  } }
+  _guardIgnoreCache.set(root, globs);
+  return globs;
+}
+
+export function guardPathAllowlisted(cwd, filePath) {
+  if (!filePath) return false;
+  const root = cwd || process.cwd();
+  let rel;
+  try { rel = path.relative(root, path.resolve(root, filePath)); } catch { rel = filePath; }
+  rel = String(rel).split(path.sep).join('/');
+  const base = rel.split('/').pop();
+  return guardIgnoreGlobs(root).some((re) => re.test(rel) || re.test(base));
+}