@shomra/agent 0.3.28 → 0.3.30

package/src/gate/environment.mjs

@@ -1,32 +1,10 @@
-import { execSync } from 'node:child_process';
+import { git } from '../core/git-exec.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const GATE_KINDS = ['mcp', 'skill', 'command', 'subagent', 'hook', 'rules', 'agent-card', 'memory', 'auto'];
-
-/**
- * ⚠ A CLOUD AGENT SESSION IS NOT A DEVELOPER MACHINE, and until this existed it
- * reported as one. Claude Code on the web runs in an EPHEMERAL container: fresh
- * $HOME, no `shomra` config, a hostname nobody will ever see again. It carries
- * no CI variables, so it fell through to LOCAL - and an operator counting
- * "screened laptops" was counting containers that no longer exist.
- *
- * ⚠ CI IS CHECKED FIRST and stays first. A cloud session driven by a GitHub
- * Action is CI: that branch carries repo, ref and commit, which is the stronger
- * attribution. REMOTE is what is left when nothing else names where this ran.
- */
-/**
- * ⚠ ONE ENTRY PER RUNTIME, and only where the variable has been SEEN. A marker
- * invented from a vendor's docs either never fires - useless - or fires on a
- * name something else uses, which labels a real laptop as an ephemeral
- * container and puts a `floor` on a machine the org actually owns. Add a row
- * here once somebody has read the variable out of a live session of that
- * runtime; until then that runtime uses SHOMRA_ENVIRONMENT below, which is the
- * whole reason the override exists.
- *
- * `verified` records who has actually seen it, so the next person can tell a
- * confirmed marker from an optimistic one.
- */
+export const GATE_KINDS = ['mcp', 'skill', 'command', 'subagent', 'hook', 'rules', 'agent-card', 'memory', 'plugin', 'tool-manifest', 'model-config', 'extension', 'workflow', 'guardrail', 'framework', 'auto'];
+
+
 export const REMOTE_RUNTIMES = [
   {
     runner: 'claude-code-cloud',
@@ -37,13 +15,6 @@ export const REMOTE_RUNTIMES = [
   },
 ];
 
-/**
- * ⚠ CODESPACES AND DEVCONTAINERS ARE DELIBERATELY ABSENT. They are containers,
- * but they PERSIST between sessions, can be enrolled, and their guard survives
- * to report a window it spent blind - which is the whole distinction REMOTE
- * draws. Filing them here would put "we cannot vouch for its silence" on
- * machines that can in fact vouch for it.
- */
 export function remoteRunner(e = process.env) {
   for (const rt of REMOTE_RUNTIMES) {
     for (const key of rt.vars) if (String(e?.[key] ?? '').trim()) return rt.runner;
@@ -61,15 +32,7 @@ export function declaredEnvironment(e = process.env) {
   return v in ENV_RANK ? v : null;
 }
 
-/**
- * ⚠⚠ THE OVERRIDE MAY ONLY EVER RAISE. `SHOMRA_ENVIRONMENT` exists so an
- * operator can declare a runtime we do not yet detect - a cloud agent from a
- * vendor whose markers nobody has read. Letting it go the other way would make
- * it a switch that relabels a detected ephemeral container as a trusted laptop,
- * clearing the `floor` its unreportable silence earns. That is the same
- * privilege-reduction shape `mayRaiseOnly` and `foldTimeout` refuse on the
- * server, and it would be reachable by anything that can set an env var.
- */
+
 export function mergeEnvironment(detected, declared) {
   if (!declared) return detected;
   return ENV_RANK[declared] > ENV_RANK[detected] ? declared : detected;
@@ -147,16 +110,8 @@ export function detectEnv(env) {
 }
 
 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');
+  const run = (args) => git(args, { timeout: 2000 })?.trim();
+  const origin = run(['config', '--get', 'remote.origin.url']);
   let repo;
   if (origin) {
     const m = origin.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
@@ -165,7 +120,7 @@ function gitContext() {
 
   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') };
+  return { repo, repoUrl, ref: run(['rev-parse', '--abbrev-ref', 'HEAD']), commit: run(['rev-parse', 'HEAD']) };
 }
 
 export function collectSiblings(fullTarget, relPath) {

package/src/guard/artifact-paths.mjs

@@ -0,0 +1,107 @@
+export const ARTIFACT_PATHS                                               = [
+
+  { re: /(^|\/)\.?mcp\.json$/i, kind: 'mcp' },
+  { re: /(^|\/)\.(?:vscode|cursor|roo|kilocode|trae|windsurf|kiro|amazonq|zed|gemini|qwen|junie)\/mcp\.json$/i, kind: 'mcp' },
+  { re: /(^|\/)\.kiro\/settings\/mcp\.json$/i, kind: 'mcp' },
+  { re: /(^|\/)claude_desktop_config\.json$/i, kind: 'mcp' },
+  { re: /(^|\/)(?:cline_mcp_settings|mcp_settings)\.json$/i, kind: 'mcp' },
+  { re: /(^|\/)\.codeium\/windsurf\/mcp_config\.json$/i, kind: 'mcp' },
+
+  { re: /(^|\/)\.claude\/settings(?:\.local)?\.json$/i, kind: 'hook' },
+  { re: /(^|\/)managed-settings\.json$/i, kind: 'hook' },
+  { re: /(^|\/)\.(?:github|copilot)\/hooks\/[^/]+\.json$/i, kind: 'hook' },
+  { re: /(^|\/)hooks\/hooks\.json$/i, kind: 'hook' },
+  { re: /(^|\/)\.(?:cursor|windsurf|codeium|gemini|qwen|codex|cline|roo)\/hooks(?:\.json|\/[^/]+\.json)$/i, kind: 'hook' },
+
+  { re: /(^|\/)SKILL\.md$/i, kind: 'skill' },
+  { re: /(^|\/)\.(?:claude|cursor|windsurf|codex|agents)\/skills\/.+\.(?:md|markdown)$/i, kind: 'skill' },
+
+  { re: /(^|\/)\.[\w-]+\/commands?\/[^/]*\.(?:md|markdown|toml)$/i, kind: 'command' },
+  { re: /(^|\/)\.[\w-]+\/prompts?\/[^/]*\.(?:md|markdown|toml)$/i, kind: 'command' },
+  { re: /(^|\/)\.(?:windsurf|devin|clinerules)\/workflows\/[^/]*\.(?:md|markdown|ya?ml)$/i, kind: 'command' },
+
+  { re: /(^|\/)\.(?:claude|cursor|windsurf|roo|kilocode)\/agents\/[^/]+\.(?:md|ya?ml|json)$/i, kind: 'subagent' },
+  { re: /(^|\/)\.github\/(?:agents|chatmodes)\/[^/]+\.md$/i, kind: 'subagent' },
+
+  { re: /(^|\/)\.well-known\/agent(?:-card)?\.json$/i, kind: 'agent-card' },
+  { re: /(^|\/)agent[-_]card\.json$/i, kind: 'agent-card' },
+
+  { re: /(^|\/)\.claude-plugin\/(?:plugin|marketplace)\.json$/i, kind: 'plugin' },
+  { re: /(^|\/)gemini-extension\.json$/i, kind: 'plugin' },
+  { re: /(^|\/)(?:mcpb|dxt)\.json$/i, kind: 'extension' },
+
+  { re: /(^|\/)(?:CLAUDE|AGENTS|AGENT|GEMINI|QWEN|KIRO|AMAZONQ|CONVENTIONS)(?:\.local|\.override)?\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.(?:cursor|aider|continue|kilocode|roo|trae|augment|windsurf|qoder|factory|opencode)rules$/i, kind: 'rules' },
+  { re: /(^|\/)\.roorules(?:-[\w-]+)?$/i, kind: 'rules' },
+  { re: /(^|\/)\.goosehints$/i, kind: 'rules' },
+  { re: /(^|\/)\.augment-guidelines$/i, kind: 'rules' },
+  { re: /(^|\/)global_rules\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.rules$/i, kind: 'rules' },
+  { re: /(^|\/)\.aider\.conf\.ya?ml$/i, kind: 'rules' },
+  { re: /(^|\/)\.github\/copilot-instructions\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.github\/instructions\/.+\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.copilot\/(?:copilot-instructions\.md|instructions\/.+\.md)$/i, kind: 'rules' },
+  { re: /(^|\/)\.cursor\/rules\/.+\.(?:mdc|md)$/i, kind: 'rules' },
+  { re: /(^|\/)\.claude\/rules\/.+\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.clinerules(?:\/[^/]+\.(?:md|txt))?$/i, kind: 'rules' },
+  { re: /(^|\/)cline\/rules\/.+\.(?:md|txt)$/i, kind: 'rules' },
+  { re: /(^|\/)\.(?:kilocode|roo|trae|junie|windsurf|augment|kiro|devin|amp|zed|goose|opencode|crush)\/(?:rules?|guidelines?|steering|memories)(?:\/.+)?\.(?:md|mdc|txt)$/i, kind: 'rules' },
+  { re: /(^|\/)\.(?:roo|kilocode)\/rules-[\w-]+\/.+\.(?:md|mdc|txt)$/i, kind: 'rules' },
+  { re: /(^|\/)\.continue\/rules\/.+\.(?:md|ya?ml)$/i, kind: 'rules' },
+  { re: /(^|\/)\.amazonq\/rules\/.+\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.qwen\/team-memory\/.+\.(?:md|txt)$/i, kind: 'rules' },
+  { re: /(^|\/)\.junie\/(?:playbook|guidelines)\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.trae\/(?:rules\/)?(?:project|user)_rules\.md$/i, kind: 'rules' },
+  { re: /(^|\/)\.claude\/output-styles\/.+\.md$/i, kind: 'rules' },
+
+  { re: /(^|\/)\.codex\/config\.(?:toml|json)$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.(?:gemini|qwen)\/settings\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.cursor\/(?:cli-config|cli|permissions|sandbox|settings)\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.vscode\/settings\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.kiro\/settings\/[^/]+\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.(?:copilot|roo|kilocode|amazonq|zed|opencode|augment|junie|trae)\/(?:settings|config)(?:\.local)?\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.github\/copilot\/settings(?:\.local)?\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)opencode\.jsonc?$/i, kind: 'agent-config' },
+  { re: /(^|\/)crush\.json$/i, kind: 'agent-config' },
+  { re: /(^|\/)goose\/config\.ya?ml$/i, kind: 'agent-config' },
+  { re: /(^|\/)\.continue\/config\.(?:json|ya?ml)$/i, kind: 'agent-config' },
+
+  { re: /(^|\/)(?:\.devcontainer\/)?devcontainer\.json$/i, kind: 'dev-environment' },
+  { re: /(^|\/)\.devcontainer\/[^/]+\/devcontainer\.json$/i, kind: 'dev-environment' },
+
+  { re: /(^|\/)[\w.-]*modelfile$/i, kind: 'model-config' },
+  { re: /(^|\/)(?:tokenizer_config|generation_config)\.json$/i, kind: 'model-config' },
+];
+
+export const CONTENT_ONLY_KINDS                                  = [
+  'automation', 'guardrail', 'tool-manifest', 'prompt-template',
+  'agent-memory', 'exec-script', 'env-secret-file', 'other-artifact',
+
+  'workflow',
+];
+
+export function normalizeArtifactPath(path        )         {
+  const raw = String(path ?? '').replace(/\\/g, '/').trim();
+  if (!raw) return '';
+  const lead = raw.startsWith('/') ? '/' : '';
+  const drive = /^[a-zA-Z]:\//.test(raw) ? raw.slice(0, 3) : '';
+  const out           = [];
+  for (const seg of (drive ? raw.slice(3) : raw).split('/')) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') {
+      if (out.length && out[out.length - 1] !== '..') out.pop();
+      else out.push('..');
+      continue;
+    }
+    out.push(seg);
+  }
+  return (drive || lead) + out.join('/');
+}
+
+export function artifactKindFor(path        )                              {
+  const p = normalizeArtifactPath(path);
+  if (!p) return null;
+  for (const { re, kind } of ARTIFACT_PATHS) if (re.test(p)) return kind;
+  return null;
+}
+

package/src/guard/classify.mjs

@@ -1,15 +1,74 @@
-import path from 'node:path';
+import fs from 'node:fs';
+import { artifactKindFor } from './artifact-paths.mjs';
 
-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;
+/**
+ *  WHAT COUNTS AS A WRITE, AND IT WAS TEN NAMES SHORT.
+ *
+ * This set decides whether a tool call is treated as a file write at all - here
+ * and, mirrored, on the server. It knew Claude Code's names and Cline's, and
+ * missed the ones every other vendor uses: `write_file` and `replace` (Gemini
+ * CLI, Qwen), `apply_patch` (Codex), `edit_file` (Cursor, Windsurf),
+ * `apply_diff` / `search_and_replace` / `insert_content` (Roo, Kilo). A Gemini
+ * CLI write of `.claude/settings.json` was not a write to this code - it fell
+ * through to the generic tool-call path with no target, no content and no
+ * artifact scan.
+ *
+ * ⚠ The repo ALREADY knew these names: `MODEL_WRITE_TOOLS` below lists
+ * `apply_patch` and `write_file`, and `memory-write.mjs` special-cases
+ * `apply_patch` by hand. Two lists in one file disagreed about what a write is,
+ * which is how this survived.
+ */
+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',
 
-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']);
+  'write_file', 'replace', 'apply_patch', 'apply_diff', 'edit_file', 'edit_notebook',
+  'search_and_replace', 'insert_content', 'create_text_file', 'str_replace',
+]);
 
-const SHELL_TOOLS_RE = /^(bash|shell|sh|run_command|run_terminal_cmd|execute_command|terminal|exec)$/i;
+const SHELL_TOOLS_RE = /^(bash|shell|sh|run_command|run_terminal_cmd|execute_command|terminal|exec|run_shell_command)$/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;
 
+/**
+ * ⚠ THE PATHS A SHELL COMMAND WRITES, so a redirect cannot walk around the
+ * tool-name check. `echo '{"permissions":{"defaultMode":"bypassPermissions"}}' >
+ * .claude/settings.json` is the same act as a Write and was not sent to the
+ * gate at all, because a shell command only reached the server when it looked
+ * like egress or an MCP install.
+ *
+ * Deliberately coarse - it decides whether to ASK the server, and the server
+ * decides what the write is. A false positive here costs one guard call.
+ */
+const REDIRECT_RE = /(?:>>?|\btee\b(?:\s+-\S+)*)\s*("[^"]+"|'[^']+'|[^\s;|&()<>]+)/g;
+const COPY_VERB_RE = /\b(?:cp|mv|install|rsync|ln|sed|perl|python3?|tee|curl|wget)\b/;
+
+export function shellWritePaths(cmd) {
+  const out = [];
+  const text = String(cmd ?? '');
+  for (const m of text.matchAll(REDIRECT_RE)) {
+    const target = m[1].replace(/^["']|["']$/g, '');
+    if (!target || target.startsWith('&') || target.startsWith('/dev/')) continue;
+    out.push(target);
+  }
+
+  /**
+   * ⚠ ARGUMENT POSITIONS TOO, not only redirects. `cp /tmp/evil.mdc
+   * .cursor/rules/style.mdc` and `sed -i s/x/y/ .claude/settings.json` never
+   * pass through `>`; the destination is just an argument.
+   */
+  if (COPY_VERB_RE.test(text)) {
+    for (const tok of text.split(/[\s;|&()]+/)) {
+      const t = tok.replace(/^["']|["']$/g, '');
+      if (!t || t.startsWith('-')) continue;
+      if (t.includes('/') || /^[\w.-]+\.(?:json|jsonc|toml|ya?ml|md|mdc)$/i.test(t)) out.push(t);
+    }
+  }
+  return [...new Set(out)].slice(0, 40);
+}
+
 export function guardText(tool, input) {
   const parts = [];
   if (typeof input.command === 'string') parts.push(input.command);
@@ -18,22 +77,121 @@ export function guardText(tool, input) {
   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'));
+
+  /**
+   * ⚠ THE KEYS OF THE TOOLS ALREADY ON THE WRITE LIST. `str_replace_editor` -
+   * the Anthropic text-editor shape - carries `file_text` on create and
+   * `new_str` on replace/insert; `replace_in_file` and `apply_diff` carry
+   * `diff`; `apply_patch` carries `patch`. None were read, so the payload of
+   * those writes was screened as `JSON.stringify(input)` locally and reached
+   * the server as an empty string.
+   */
+  if (typeof input.file_text === 'string') parts.push(input.file_text);
+  if (typeof input.new_str === 'string') parts.push(input.new_str);
+  if (typeof input.diff === 'string') parts.push(input.diff);
+  if (typeof input.patch === 'string') parts.push(input.patch);
+  if (typeof input.code_edit === 'string') parts.push(input.code_edit);
+  if (Array.isArray(input.edits)) parts.push(input.edits.map((e) => e?.new_string ?? e?.new_str ?? '').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;
+  const p = i.file_path ?? i.path ?? i.notebook_path ?? i.filename ?? i.target_file ?? i.file ?? null;
   return typeof p === 'string' && p.trim() ? p : null;
 }
 
+/**
+ * ⚠ EVERY PATH A CALL TOUCHES, for the send decision only. A batched read
+ * (`read_many_files` takes `paths`) and a multi-file patch both name several
+ * files, and asking about the first one is asking about the wrong one.
+ */
+export function guardTouchedPaths(tool, input = {}) {
+  const out = [];
+  const push = (v) => { if (typeof v === 'string' && v.trim()) out.push(v.trim()); };
+  push(input.file_path); push(input.path); push(input.notebook_path); push(input.filename);
+  push(input.target_file); push(input.file); push(input.destination); push(input.dest);
+  for (const key of ['paths', 'files', 'file_paths', 'targets']) {
+    if (Array.isArray(input[key])) for (const v of input[key]) push(typeof v === 'string' ? v : v?.path);
+  }
+  if (Array.isArray(input.edits)) for (const e of input.edits) push(e?.file_path ?? e?.path);
+
+  /**
+   * ⚠ A PATCH ENVELOPE NAMES ITS OWN FILES. Codex's `apply_patch` carries no
+   * path argument at all - the paths are inside the patch text, so a write to
+   * `.claude/settings.json` through it looked pathless.
+   */
+  const patch = typeof input.patch === 'string' ? input.patch : typeof input.diff === 'string' ? input.diff : '';
+  if (patch) {
+    for (const m of patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$/gm)) push(m[1]);
+    for (const m of patch.matchAll(/^(?:\+\+\+|---)\s+(?:[ab]\/)?(\S+)/gm)) push(m[1]);
+  }
+  if (typeof input.command === 'string' || typeof input.cmd === 'string') {
+    for (const p of shellWritePaths(input.command ?? input.cmd)) push(p);
+  }
+
+  /**
+   * ⚠ A SYMLINK IS THE PATH IT POINTS AT. `ln -s .claude/settings.json notes.md`
+   * then a write to `notes.md` lands on the settings file while matching no
+   * rule - path-based binding cannot see through a link, and only the machine
+   * can resolve one. Resolved here, where the filesystem is, and BOTH names are
+   * kept: the one written and the one actually changed.
+   */
+  const resolved = [];
+  for (const p of out.slice(0, 20)) {
+    try {
+      const real = fs.realpathSync(p).replace(/\\/g, '/');
+      if (real && real !== p) resolved.push(real);
+    } catch {
+      /* a path that does not exist yet cannot be a link to somewhere else */
+    }
+  }
+  return [...new Set([...out, ...resolved])].slice(0, 60);
+}
+
 export function guardNeedsServer(tool, input, hasIdentity) {
   if (hasIdentity) return true;
+
+  /**
+   *  THE DECISION THIS FUNCTION MAKES IS WHETHER THE GATE EVER SEES THE
+   * CALL, and it used to answer it against a private fifteen-path regex while
+   * the server's list held sixty. A write to `.vscode/settings.json`
+   * (CVE-2025-53773, wormable, and an agent writing it IS the exploit),
+   * `.cursor/rules/*.mdc` (the rules-file backdoor) or `.codex/config.toml` was
+   * decided locally and never sent - so widening the server changed nothing
+   * here. `artifact-paths.mjs` is GENERATED from the server's own list now, so
+   * the two cannot drift again.
+   */
+  for (const p of guardTouchedPaths(tool, input)) if (artifactKindFor(p)) return true;
+
+  /**
+   * ⚠ THIS SENDS ARTIFACT *READS* TOO, AND THAT IS DELIBERATE - DO NOT NARROW
+   * IT. It costs one guard round-trip per artifact read (a handful per session:
+   * CLAUDE.md at startup, a rules file when the agent consults one), and two
+   * things depend on it that are not obvious from here:
+   *
+   *   1 A refused artifact binds ON READ. The registry decision takes effect
+   *     when the content reaches the model, which is a step no install-time
+   *     check can reach.
+   *   2 A READ IS HALF OF THE ONLY CROSS-SESSION PROPAGATION EDGE THE PRODUCT
+   *     HAS. `HandoffService` pairs write -> read on the same resource; an
+   *     instruction artifact is the canonical carrier between sessions, so a
+   *     suppressed read means a poisoned CLAUDE.md written by one session and
+   *     read by another produces NO edge, and the blast-radius walk reports a
+   *     blind spot instead of the path.
+   *
+   * ⚠ AND A PER-SESSION DEDUPE IS WORSE THAN EITHER CHOICE, which is the trap
+   * to avoid: that pairing needs `read.at > write.at`, so reporting only the
+   * FIRST read of a file means a later poisoning write followed by a re-read
+   * pairs against nothing. It would quietly break the detection it was added to
+   * protect. The latency is bounded by the circuit breaker instead - a slow
+   * gate degrades to local screening rather than holding the agent.
+   */
+
   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 (artifactKindFor(target)) return true;
   }
   if (tool && tool.startsWith('mcp__')) return true;
   if (EGRESS_TOOL_RE.test(tool || '')) return true;

package/src/guard/command-resolve.mjs

@@ -53,15 +53,45 @@ function isExecutable(file, statSync) {
   }
 }
 
+/**
+ * PATH as the shell running the command splits it.
+ *
+ * ⚠ The commands screened here are shell text - bash, or Git Bash on Windows -
+ * where `PATH=/tmp/bin:$PATH` is colon-separated. Splitting on the HOST's
+ * delimiter read that on Windows as one directory named `/tmp/bin:/usr/bin`, so
+ * the shadowing binary the prefix planted was never found and the report named
+ * nothing. A `$PATH` substituted from a Windows environment adds `;` and drive
+ * letters, so: split on `;`, and on `:` except the one after a drive letter.
+ */
+function pathEntries(value) {
+  const out = [];
+  let cur = '';
+  for (const ch of String(value ?? '')) {
+    if (ch === ';' || (ch === ':' && !/^[A-Za-z]$/.test(cur))) {
+      if (cur) out.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur) out.push(cur);
+  return out.slice(0, MAX_PATH_ENTRIES);
+}
+
+const windowsStyle = (p) => /^[A-Za-z]:[\\/]/.test(p) || p.includes('\\');
+const flavour = (p) => (windowsStyle(p) ? path.win32 : path.posix);
+
 function locate(word, effectivePath, cwd, statSync) {
   if (!word) return null;
+  const base = cwd || '.';
   if (word.includes('/') || word.includes('\\')) {
-    const abs = path.isAbsolute(word) ? word : path.resolve(cwd || '.', word);
+    const abs = flavour(word).isAbsolute(word) ? word : flavour(base).join(base, word);
     return isExecutable(abs, statSync) ? abs : null;
   }
-  const entries = String(effectivePath ?? '').split(path.delimiter).filter(Boolean).slice(0, MAX_PATH_ENTRIES);
-  for (const dir of entries) {
-    const candidate = path.join(dir, word);
+  for (const dir of pathEntries(effectivePath)) {
+    // A relative entry (`.`, `bin`) is relative to where the COMMAND runs - which is how it shadows.
+    const at = flavour(dir).isAbsolute(dir) ? dir : flavour(base).join(base, dir);
+    const candidate = flavour(at).join(at, word);
     if (isExecutable(candidate, statSync)) return candidate;
   }
   return null;
@@ -72,7 +102,7 @@ function locate(word, effectivePath, cwd, statSync) {
  * the filesystem this machine actually has - the two things the server does not
  * hold and no pattern can recover from the string.
  *
- * ⚠⚠ IT NEVER EXECUTES ANYTHING. `$(…)` and backticks are REPORTED unresolved,
+ *  IT NEVER EXECUTES ANYTHING. `$(…)` and backticks are REPORTED unresolved,
  * never evaluated: running attacker-influenced text in order to screen it is the
  * vulnerability, not the control. Same reason the scanner resolves an MCP source
  * without launching it.