agents-can-communicate 0.1.5 → 0.1.7

package/docs/CAPABILITIES.md

@@ -60,10 +60,17 @@ toolset contained no `apply_patch`.
 `plan` modes the client declares no write tool to the model at all. `write_file` and
 `replace` appear under `auto_edit`; `run_shell_command` under `yolo`.
 
-**`guards.beforeShell` is never resource-aware.** A shell command can write anywhere, and
-ACC does not parse commands. The guard fires and is allowed through, because guessing a
-path out of a command would block work at random and still miss real writes. Shell calls
-therefore declare no targets on every adapter.
+**`guards.beforeShell` is resource-aware where the write is unambiguous.** ACC reads the
+command for its write positions only - a redirection, an operand of a command whose whole
+job is to put bytes somewhere - and declares those paths as targets. Reading positions are
+left alone: `cat file` and `grep file` name a path and write nothing, and treating them as
+writes would have sessions blocking each other for looking.
+
+What it does not see is a language runtime opening the file itself (`python3 -c
+"open(...)"`), a command assembled at runtime, or an `eval`. A shell can still evade the
+guard. Until 0.1.7 every shell write did, which is why partial sight is the improvement it
+is: a session told to prefer the shell for file changes walked through every claim in the
+workspace.
 
 Where the guard cannot help, the turn context does: it names the claims other sessions
 hold and says which way this session stands with them. Two facts decide the wording -
@@ -71,7 +78,7 @@ what the claim's owner asked for, and whether ACC can stop this session at all:
 
 | Claim | This session | Note |
 |---|---|---|
-| guarded | can be guarded | `file edits are blocked; edits made through a shell are not` |
+| guarded | can be guarded | `file edits and recognised shell writes are blocked; a runtime can still get past` |
 | guarded | cannot be guarded | `not enforced for this session; do not edit it` |
 | advisory | either | `advisory; nothing will stop you, the owner is asking` |
 
@@ -154,5 +161,9 @@ harness name. Both default to the weaker reading, so a generic MCP client or a h
 the CLI reads as advisory and manual.
 
 A workspace reports `protection: guarded` only when every live session can be stopped. One
-MCP client, one Kimi session, or one Codex session on a shell-editing model, and a guarded
-claim is advice - so the workspace says `advisory`, whatever its claims were declared as.
+MCP client and a guarded claim is advice - so the workspace says `advisory`, whatever its
+claims were declared as.
+
+"Stoppable" is not "unevadable". Even in a guarded workspace, a session that writes through
+a language runtime rather than a recognised shell form gets past. The claim still says who
+is working where; enforcement is the floor, not the ceiling.

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-claude-code/plugin/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Coordinate this Claude Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs."
 }

package/node_modules/@agents-can-communicate/adapter-claude-code/src/hooks.mjs

@@ -1,4 +1,4 @@
-import { normalizedEvent } from "@agents-can-communicate/adapter-sdk";
+import { normalizedEvent, shellWriteTargets } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 // Confirmed by capture on 2.1.233, and matching the published documentation
@@ -66,10 +66,15 @@ export const CLAUDE_EDIT_TOOLS = Object.freeze(["Write", "Edit", "MultiEdit",
  * Only the path is taken. `content`, `old_string` and `new_string` are the
  * file's contents, which ACC has no use for and must not carry.
  *
- * `Bash` declares nothing: a command can write anywhere, and a path guessed out
- * of one gives a guard that is wrong in both directions.
+ * `Bash` declares no path, but its command names the ones it would write. Those
+ * are read out of the write positions only - a redirection, an operand of a
+ * command whose job is to put bytes somewhere - because a session told to prefer
+ * the shell would otherwise walk through every claim in the workspace. The
+ * command string itself is conversation content and stays out; only paths leave
+ * this function.
  */
 function writeTargets(tool, input) {
+  if (tool === "Bash") return shellWriteTargets(input?.command);
   if (!CLAUDE_EDIT_TOOLS.includes(tool)) return [];
   const target = input?.file_path ?? input?.notebook_path;
   return typeof target === "string" && target !== "" ? [target] : [];

package/node_modules/@agents-can-communicate/adapter-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Coordinate this Codex session with other AI agent sessions working in the same workspace.",
   "license": "UNLICENSED",
   "keywords": ["coordination", "multi-agent", "claims", "handoff"],

package/node_modules/@agents-can-communicate/adapter-codex/src/adapter.mjs

@@ -62,10 +62,12 @@ export function createCodexAdapter() {
           // property of the model's metadata (apply_patch_tool_type), not a user
           // setting. With a model that does not have it, edits go through
           // exec_command, which reaches hooks as tool_name \"Bash\" carrying a
-          // command string - and a command names no resource, so a write guard
-          // has nothing to match. Verified on 0.147.0.
-          "write guards apply only to models that offer apply_patch; with the rest, "
-            + "edits run through the shell and cannot be matched to a claim",
+          // command string. Since 0.1.7 that command is read for its write
+          // positions, so those edits are matched too - as far as the reading
+          // goes. Verified on 0.147.0.
+          "write guards cover apply_patch and the shell writes ACC can read; a model "
+            + "without apply_patch edits through the shell, where a redirection or an "
+            + "mv is matched and a runtime opening the file is not",
           "Codex requires hooks to be trusted before they run; an untrusted plugin is "
             + "installed but inert",
         ],

package/node_modules/@agents-can-communicate/adapter-codex/src/hooks.mjs

@@ -1,4 +1,4 @@
-import { normalizedEvent } from "@agents-can-communicate/adapter-sdk";
+import { normalizedEvent, shellWriteTargets } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 // The event names are settled: they are an enum in the installed 0.147.0 binary,
@@ -68,7 +68,7 @@ export function normalizeCodexHook(payload) {
     model: pick(payload, FIELD_CANDIDATES.model),
     parentSessionId: pick(payload, FIELD_CANDIDATES.parentSessionId),
     tool,
-    targets: patchTargets(tool, payload?.tool_input),
+    targets: writeTargets(tool, payload?.tool_input),
   });
 }
 
@@ -76,6 +76,7 @@ export function normalizeCodexHook(payload) {
 // patch body, one per operation, so a single call can touch several files.
 // Reading `tool_input.path` here - the shape every other harness uses - would
 // find nothing and leave every edit unguarded.
+const PATCH_ENVELOPE = "*** Begin Patch";
 const PATCH_OPERATION = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/;
 const PATCH_MOVE = /^\*\*\* Move to: (.+)$/;
 
@@ -86,9 +87,9 @@ const PATCH_MOVE = /^\*\*\* Move to: (.+)$/;
  * are never read: they are the file's contents, which ACC has no use for.
  */
 export function patchTargets(tool, input) {
-  if (tool !== "apply_patch") return [];
   const body = input?.command ?? input?.patch ?? input?.input;
   if (typeof body !== "string") return [];
+  if (tool !== "apply_patch" && !body.trimStart().startsWith(PATCH_ENVELOPE)) return [];
   const targets = [];
   for (const line of body.split("\n")) {
     const operation = PATCH_OPERATION.exec(line) ?? PATCH_MOVE.exec(line);
@@ -97,6 +98,24 @@ export function patchTargets(tool, input) {
   return targets;
 }
 
+/**
+ * The paths a tool call would write.
+ *
+ * The guard is wired to three tool names here, and which one a shell command
+ * arrives under is a property of the model's metadata rather than of this
+ * config. So the shape decides instead of the name: a patch envelope is read as
+ * a patch, and any other command string is read as a shell command. Reading
+ * positions in that command are left alone.
+ */
+export function writeTargets(tool, input) {
+  const patched = patchTargets(tool, input);
+  if (patched.length > 0) return patched;
+  const command = input?.command ?? input?.input;
+  if (typeof command !== "string") return [];
+  if (command.trimStart().startsWith(PATCH_ENVELOPE)) return [];
+  return shellWriteTargets(command);
+}
+
 /**
  * Deny a tool call the way this client understands it.
  *

package/node_modules/@agents-can-communicate/adapter-codex/src/install.mjs

@@ -118,8 +118,37 @@ const entryFor = () => ({
  * an install that writes files alone leaves a plugin the client never sees and
  * a hook that never runs - while reporting success.
  */
+/**
+ * The table that lets an agent here record anything at all.
+ *
+ * This client sandboxes the shell commands a model runs to the workspace, and
+ * ACC keeps its state outside every workspace on purpose - so an agent could
+ * read the roster and write nothing: `acc claim`, `acc work`, `acc message` all
+ * failed with `EPERM ... locks/writer.lock`. Measured with `codex exec`, which
+ * is how an agent actually runs, and confirmed by watching the same commands
+ * succeed once this root was declared.
+ *
+ * Left out when the user declares the table themselves. Declaring it twice is
+ * what makes this client refuse the whole config, and their setting is theirs -
+ * the diagnostic says what to add rather than adding it for them.
+ */
+const sandboxTable = (stateRoot, theirs) => {
+  if (typeof stateRoot !== "string" || stateRoot === "") return [];
+  if (theirs) return [];
+  return ["", "[sandbox_workspace_write]",
+    `writable_roots = [${tomlString(stateRoot)}]`];
+};
+
+// Every spelling TOML allows for the same table: the header, a sub-table
+// header, a dotted key, and an inline table on one line. Missing one means ACC
+// appends a second declaration - which is the duplicate this exists to avoid,
+// and the client refuses the whole config over it.
+const declaresSandbox = config =>
+  /^\s*\[sandbox_workspace_write[\].]/m.test(config)
+  || /^\s*sandbox_workspace_write\s*[.=]/m.test(config);
+
 export async function installCodexPlugin({ home, agentsHome = home,
-  codexHome = path.join(home, ".codex"), runner, node }) {
+  codexHome = path.join(home, ".codex"), stateRoot, runner, node }) {
   // Read before writing, so a manifest that will not parse is found before a
   // plugin tree is laid down that nothing will then be able to remove.
   const existing = await readJson(marketplacePath(agentsHome), { name: MARKETPLACE,
@@ -157,6 +186,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
       `marketplace ${MARKETPLACE} is already registered in this config; `
       + "remove it and install again", { config });
   }
+  const theirSandbox = declaresSandbox(stripBlock(before));
   await writeTomlBlock(config, [
     `[marketplaces.${MARKETPLACE}]`,
     `source_type = "local"`,
@@ -164,6 +194,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
     "",
     `[plugins.${tomlString(QUALIFIED)}]`,
     "enabled = true",
+    ...sandboxTable(stateRoot, theirSandbox),
   ]);
 
   // The client runs the cached copy, so this has to happen after the shim and
@@ -184,7 +215,11 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // while ACC invented its own marketplace name and so had a root to itself.
   // make the record stale the moment the plugin version changes.
   return { ok: true, changes: [target, file, config, cachePath(codexHome)],
-    diagnostics: ["hooks require explicit trust in Codex before they run"] };
+    diagnostics: ["hooks require explicit trust in Codex before they run",
+      ...(theirSandbox
+        ? [`this config sets its own sandbox_workspace_write; add ${stateRoot} to `
+          + "writable_roots, or an agent here can read the roster and record nothing"]
+        : [])] };
 }
 
 /** Remove each directory that is empty, in the order given. */
@@ -194,6 +229,34 @@ async function removeEmptyDirs(directories) {
   }
 }
 
+/**
+ * Drop the client's trust record for hooks that are about to stop existing.
+ *
+ * Scoped to tables whose key begins with ACC's own `plugin@marketplace:` - a
+ * table belonging to any other plugin is the client's business and stays. The
+ * file is rewritten only when something was found, so an install that never ran
+ * here leaves the config byte for byte as it was.
+ */
+export async function removeHookTrust(file, prefix) {
+  const before = await readFile(file, "utf8").catch(() => null);
+  if (before === null || !before.includes(`hooks.state."${prefix}`)) return false;
+
+  const lines = before.split("\n");
+  const kept = [];
+  let dropping = false;
+  for (const line of lines) {
+    const header = /^\s*\[([^\]]*)\]\s*$/.exec(line);
+    if (header !== null) dropping = header[1].startsWith(`hooks.state."${prefix}`);
+    if (dropping) continue;
+    kept.push(line);
+  }
+  // A table's trailing blank line goes with it rather than piling up.
+  const text = kept.join("\n").replace(/\n{3,}/g, "\n\n");
+  if (text === before) return false;
+  await writeFile(file, text, "utf8");
+  return true;
+}
+
 export async function uninstallCodexPlugin({ home, agentsHome = home,
   codexHome = path.join(home, ".codex"), keep = [] }) {
   const file = marketplacePath(agentsHome);
@@ -205,6 +268,15 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
     await writeMarketplace(file, { ...existing, plugins: kept });
   }
   if (await removeTomlBlock(configPath(codexHome))) changes.push(configPath(codexHome));
+  // This client keeps its own record of which hook files it has trusted, one
+  // table per hook, keyed by the plugin that declared them. ACC never writes
+  // those - they are the client's bookkeeping about ACC - but once the plugin is
+  // gone they name a thing that does not exist, five of them per install, and
+  // nothing else will ever clear them. Verified inert first: a hook whose hash
+  // no longer matches still runs, so this is tidiness rather than repair.
+  if (await removeHookTrust(configPath(codexHome), `${PLUGIN_NAME}@${MARKETPLACE}:`)) {
+    if (!changes.includes(configPath(codexHome))) changes.push(configPath(codexHome));
+  }
   // The marketplace directory is ACC's too, so it goes rather than being left
   // behind empty.
   // A blank TOML config and an absent one are the same to this client, and a

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

package/node_modules/@agents-can-communicate/adapter-gemini-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-gemini-cli/src/hooks.mjs

@@ -1,4 +1,4 @@
-import { normalizedEvent } from "@agents-can-communicate/adapter-sdk";
+import { normalizedEvent, shellWriteTargets } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 // All eight observed in a live 0.37.0 configuration; the six that ACC uses were
@@ -59,10 +59,11 @@ export function normalizeGeminiHook(payload) {
  * Both editing tools take `file_path`, confirmed from a capture. The file's
  * contents are not read: they are conversation content.
  *
- * `run_shell_command` declares nothing. A command can write anywhere, and a path
- * guessed out of one gives a guard that is wrong in both directions.
+ * `run_shell_command` declares no path, so its command is read for the positions
+ * where a write is unambiguous, and for nothing else.
  */
 function writeTargets(tool, input) {
+  if (tool === "run_shell_command") return shellWriteTargets(input?.command);
   if (!GEMINI_EDIT_TOOLS.includes(tool)) return [];
   const target = input?.file_path;
   return typeof target === "string" && target !== "" ? [target] : [];

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/plugin/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Coordinate this Kimi Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs.",
   "skills": "./skills/",
   "sessionStart": {

package/node_modules/@agents-can-communicate/adapter-kimi/src/hooks.mjs

@@ -1,4 +1,4 @@
-import { normalizedEvent } from "@agents-can-communicate/adapter-sdk";
+import { normalizedEvent, shellWriteTargets } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 // Not read from documentation and not guessed: this client validates its config
@@ -73,11 +73,12 @@ export function normalizeKimiHook(payload) {
  * `old_string` and `new_string`. Nothing else is read: the contents and the
  * replacement strings are conversation content and stay out.
  *
- * `Bash` declares nothing. A command can write anywhere, and a path guessed out
- * of one would give a guard that blocks work it holds no claim over while
- * missing writes it does.
+ * `Bash` declares no path of its own, so the command is read for the positions
+ * where a write is unambiguous. Reading positions are left alone: naming a file
+ * is not touching it.
  */
 function writeTargets(tool, input) {
+  if (tool === "Bash") return shellWriteTargets(input?.command);
   if (!KIMI_EDIT_TOOLS.includes(tool)) return [];
   const path = input?.path;
   return typeof path === "string" && path !== "" ? [path] : [];

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/src/context-projector.mjs

@@ -85,11 +85,12 @@ function claimNote(claim) {
   if (claim.enforceable === false) {
     return " - not enforced for this session; do not edit it";
   }
-  // Guarded, and this session can be stopped - but only on a file edit. No
-  // harness intercepts a shell command, so an edit made through one goes
-  // through whatever the claim says, and a session told merely "this is
-  // claimed" would reasonably assume otherwise.
-  return " - file edits are blocked; edits made through a shell are not";
+  // Guarded, and this session can be stopped - on a file edit, and on the shell
+  // writes the guard can read: a redirection, an operand of a command whose job
+  // is to put bytes somewhere. A language runtime opening the file itself still
+  // gets past, and a session told merely "this is claimed" would reasonably
+  // assume either more or less than is true.
+  return " - file edits and recognised shell writes are blocked; a runtime can still get past";
 }
 
 function claimLines(claims) {

package/node_modules/@agents-can-communicate/adapter-sdk/src/index.mjs

@@ -8,6 +8,7 @@ export { assertRunner, bakeSkillCommand, defaultCli, defaultRunner, removeInstal
 export { BEGIN, END, removeTomlBlock, renderBlock, stripBlock, tomlString, writeTomlBlock }
   from "./toml-block.mjs";
 export { projectContext } from "./context-projector.mjs";
+export { shellWriteTargets } from "./shell-writes.mjs";
 export { editJson, readJson } from "./json-text.mjs";
 export { formatJsonAs, jsonStyleOf, mergeOwnedConfig, mergeOwnedEntries, ownedEntries, ownedKeys,
   acccreatedFile, removeIfEmpty, removeOwnedConfig, removeOwnedEntries, writeForeignJson,

package/node_modules/@agents-can-communicate/adapter-sdk/src/shell-writes.mjs

@@ -0,0 +1,319 @@
+/**
+ * What a shell command would write.
+ *
+ * The guard used to declare no targets for a shell call at all, on the reasoning
+ * that a command can write anywhere and a guessed path is wrong in both
+ * directions. That reasoning held until agents started being told to prefer the
+ * shell for file edits: a claim that any `printf >> file` walks through is not a
+ * claim. The answer is not to guess. It is to read the positions where a write
+ * is unambiguous - a redirection, the operand of a command whose whole job is to
+ * put bytes somewhere - and to stay silent everywhere else.
+ *
+ * Two properties matter more than coverage:
+ *
+ *   - A read is never reported. `cat file` and `grep file` name a path in an
+ *     argument position that writes nothing; treating those as writes would have
+ *     sessions blocking each other for looking.
+ *   - It never throws. This runs on the hook path inside a budget that fails
+ *     open, so an unparseable command yields no targets rather than an error.
+ *
+ * What it does not see is stated where a person reads it (`context-projector`):
+ * a language runtime opening a file, an `eval`, a command built at runtime. A
+ * shell can still evade this. Partial sight is not the same as none - today
+ * every one of these walks through - and an agent told where the guard ends
+ * behaves better than one who believes it absolute.
+ */
+
+const SEPARATORS = new Set([";", "&&", "||", "|", "|&", "&", "\n"]);
+
+// Redirections that write. `<` and `<<` read; `>&`/`<&` duplicate a descriptor
+// and name no file.
+const WRITE_REDIRECTION = /^(?:[0-9]*|&)(?:>>|>\|?)$/;
+
+// Sinks that discard. Naming one is not touching a file anybody claims.
+const NOT_A_FILE = new Set(["/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty"]);
+
+/**
+ * How each command spends its operands.
+ *
+ * `pick` decides which operands are written: every one, only the last (a
+ * destination), or every one but the first (a script that is not a file).
+ * `valueFlags` are the flags whose following token is a value rather than a
+ * path - without them, `truncate -s 0 file` would report a file named `0`.
+ */
+const WRITERS = new Map(Object.entries({
+  tee: { pick: "all" },
+  touch: { pick: "all", valueFlags: new Set(["-d", "-r", "-t", "--date", "--reference"]) },
+  truncate: { pick: "all", valueFlags: new Set(["-s", "--size", "-r", "--reference"]) },
+  rm: { pick: "all" },
+  unlink: { pick: "all" },
+  shred: { pick: "all", valueFlags: new Set(["-n", "--iterations", "-s", "--size"]) },
+  mkdir: { pick: "all", valueFlags: new Set(["-m", "--mode"]) },
+  rmdir: { pick: "all" },
+  cp: { pick: "last", valueFlags: new Set(["-t", "--target-directory", "-S", "--suffix"]) },
+  install: { pick: "last", valueFlags: new Set(["-t", "--target-directory", "-m", "-o", "-g"]) },
+  rsync: { pick: "last", valueFlags: new Set(["-e", "--rsh", "--exclude"]) },
+  ln: { pick: "last", valueFlags: new Set(["-t", "--target-directory", "-S", "--suffix"]) },
+  // A move writes the destination and empties the source. Both are the peer's
+  // business, so both are reported.
+  mv: { pick: "all", valueFlags: new Set(["-t", "--target-directory", "-S", "--suffix"]) },
+}));
+
+// In-place editors: a write only when the in-place flag is present, and their
+// script operand is never a file.
+const IN_PLACE = new Map(Object.entries({
+  sed: { valueFlags: new Set(["-e", "--expression", "-f", "--file", "-l", "-E"]) },
+  perl: { valueFlags: new Set(["-e", "-E", "-M", "-m"]) },
+  ruby: { valueFlags: new Set(["-e", "-r"]) },
+}));
+
+/**
+ * Split a command line into tokens, keeping quoted text out of the grammar.
+ *
+ * Returns null on anything it cannot read - an unterminated quote, most often -
+ * which the caller turns into "no targets" rather than a guess.
+ */
+function tokenize(command) {
+  const tokens = [];
+  let text = "";
+  let started = false;
+  let quoted = false;
+
+  const flush = () => {
+    if (started) tokens.push({ text, quoted });
+    text = "";
+    started = false;
+    quoted = false;
+  };
+
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index];
+
+    if (character === "\\") {
+      const next = command[index + 1];
+      if (next === undefined) return null;
+      text += next;
+      started = true;
+      quoted = true;
+      index += 1;
+      continue;
+    }
+
+    if (character === "'" || character === '"') {
+      const close = command.indexOf(character, index + 1);
+      if (close === -1) return null;
+      text += command.slice(index + 1, close);
+      started = true;
+      quoted = true;
+      index = close;
+      continue;
+    }
+
+    if (character === " " || character === "\t") {
+      flush();
+      continue;
+    }
+
+    if (character === "\n") {
+      flush();
+      tokens.push({ operator: "\n" });
+      continue;
+    }
+
+    if (character === ";" || character === "&" || character === "|" || character === ">"
+      || character === "<") {
+      // A redirection may carry its descriptor on the front (`2>`), which is
+      // already sitting in `text` unquoted.
+      const prefix = !quoted && /^[0-9]+$/.test(text) ? text : null;
+      if (prefix === null) flush();
+      else { text = ""; started = false; }
+
+      let operator = character;
+      while (index + 1 < command.length && "&|<>".includes(command[index + 1])) {
+        operator += command[index + 1];
+        index += 1;
+      }
+      tokens.push({ operator: prefix === null ? operator : prefix + operator });
+      continue;
+    }
+
+    text += character;
+    started = true;
+  }
+  flush();
+  return tokens;
+}
+
+/** Break a token list at the separators, so every simple command is read. */
+function simpleCommands(tokens) {
+  const commands = [[]];
+  for (const token of tokens) {
+    if (token.operator !== undefined && SEPARATORS.has(token.operator)) commands.push([]);
+    else commands.at(-1).push(token);
+  }
+  return commands.filter(command => command.length > 0);
+}
+
+/**
+ * Drop heredoc bodies.
+ *
+ * The body is content the shell never parses, and it is exactly where a `>` or
+ * an `rm` is most likely to appear innocently. Reading it would invent targets
+ * out of a file's own text.
+ */
+function stripHeredocs(command) {
+  const pattern = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+  let result = command;
+  for (;;) {
+    pattern.lastIndex = 0;
+    const opener = pattern.exec(result);
+    if (opener === null) return result;
+    const lineEnd = result.indexOf("\n", opener.index);
+    if (lineEnd === -1) return result.slice(0, opener.index) + result.slice(opener.index).replace(pattern, "");
+    const terminator = new RegExp(`^\\s*${opener[2]}\\s*$`, "m");
+    const rest = result.slice(lineEnd + 1);
+    const end = terminator.exec(rest);
+    const body = end === null ? rest.length : end.index + end[0].length;
+    result = result.slice(0, opener.index) + result.slice(opener.index, lineEnd).replace(pattern, "")
+      + "\n" + rest.slice(body);
+  }
+}
+
+/** The word a redirection writes to, or null when it names no file. */
+function redirectionTarget(tokens, index) {
+  const next = tokens[index + 1];
+  if (next === undefined || next.operator !== undefined) return null;
+  if (next.text.startsWith("&")) return null;
+  return NOT_A_FILE.has(next.text) ? null : next.text;
+}
+
+/** Operands of a simple command, with flags and their values removed. */
+function operandsOf(words, valueFlags = new Set()) {
+  const operands = [];
+  for (let index = 1; index < words.length; index += 1) {
+    const word = words[index];
+    if (!word.quoted && word.text.startsWith("-") && word.text !== "-") {
+      if (valueFlags.has(word.text)) index += 1;
+      continue;
+    }
+    operands.push(word.text);
+  }
+  return operands;
+}
+
+/** Strip the leading environment assignments and wrappers off a command. */
+function commandWords(words) {
+  let start = 0;
+  while (start < words.length) {
+    const word = words[start];
+    if (word.operator !== undefined) return null;
+    if (!word.quoted && /^[A-Za-z_][A-Za-z0-9_]*=/.test(word.text)) { start += 1; continue; }
+    if (["sudo", "command", "nohup", "time", "nice"].includes(word.text)) { start += 1; continue; }
+    if (word.text === "env") { start += 1; continue; }
+    break;
+  }
+  return start >= words.length ? null : words.slice(start);
+}
+
+/** Targets a `dd` call writes, which it names as `of=`. */
+function ddTargets(words) {
+  return words.slice(1)
+    .filter(word => word.text.startsWith("of="))
+    .map(word => word.text.slice(3))
+    .filter(target => target !== "" && !NOT_A_FILE.has(target));
+}
+
+/**
+ * Targets a `git` call writes into the working tree.
+ *
+ * Only the two that overwrite a file a peer may be holding. `git log -- path`
+ * and `git diff path` name the same path and touch nothing, which is why the
+ * subcommand is read before the operands.
+ */
+function gitTargets(words) {
+  const subcommand = words[1]?.text;
+  if (subcommand === "restore") {
+    return operandsOf(words.slice(1), new Set(["--source", "-s"]));
+  }
+  if (subcommand === "checkout") {
+    const separator = words.findIndex(word => word.text === "--" && !word.quoted);
+    if (separator === -1) return [];
+    return words.slice(separator + 1).map(word => word.text);
+  }
+  return [];
+}
+
+/** Targets of an in-place editor, whose script operand is not a file. */
+function inPlaceTargets(words, spec) {
+  const flags = words.slice(1).filter(word => !word.quoted && word.text.startsWith("-"));
+  const inPlace = flags.some(word => word.text === "-i" || word.text.startsWith("-i")
+    || word.text === "--in-place" || word.text.startsWith("--in-place="));
+  if (!inPlace) return [];
+
+  const valueFlags = new Set(spec.valueFlags);
+  const operands = [];
+  for (let index = 1; index < words.length; index += 1) {
+    const word = words[index];
+    if (!word.quoted && word.text.startsWith("-") && word.text !== "-") {
+      // `-i ''` on BSD takes its suffix as a separate word; a cluster carrying
+      // `e` takes the script that follows it.
+      if (valueFlags.has(word.text)) index += 1;
+      else if (/^-[A-Za-z]*[eEf]$/.test(word.text)) index += 1;
+      else if (word.text === "-i" && words[index + 1]?.quoted
+        && (words[index + 1].text === "" || words[index + 1].text.startsWith("."))) index += 1;
+      continue;
+    }
+    operands.push(word.text);
+  }
+
+  const scriptGiven = flags.some(word => /^-[A-Za-z]*[eEf]$/.test(word.text)
+    || word.text.startsWith("--expression") || word.text.startsWith("--file"));
+  return scriptGiven ? operands : operands.slice(1);
+}
+
+/**
+ * Paths a shell command would write.
+ *
+ * Order is the order they appear; a path named twice is reported once. Anything
+ * unreadable yields an empty list.
+ */
+export function shellWriteTargets(command) {
+  if (typeof command !== "string" || command.trim() === "") return [];
+
+  let targets = [];
+  try {
+    const tokens = tokenize(stripHeredocs(command));
+    if (tokens === null) return [];
+
+    for (const simple of simpleCommands(tokens)) {
+      for (let index = 0; index < simple.length; index += 1) {
+        const token = simple[index];
+        if (token.operator === undefined || !WRITE_REDIRECTION.test(token.operator)) continue;
+        const target = redirectionTarget(simple, index);
+        if (target !== null) targets.push(target);
+      }
+
+      const words = commandWords(simple.filter(token => token.operator === undefined));
+      if (words === null || words.length === 0) continue;
+      const name = words[0].text.split("/").at(-1);
+
+      if (name === "dd") { targets.push(...ddTargets(words)); continue; }
+      if (name === "git") { targets.push(...gitTargets(words)); continue; }
+
+      const inPlace = IN_PLACE.get(name);
+      if (inPlace !== undefined) { targets.push(...inPlaceTargets(words, inPlace)); continue; }
+
+      const writer = WRITERS.get(name);
+      if (writer === undefined) continue;
+      const operands = operandsOf(words, writer.valueFlags);
+      if (operands.length === 0) continue;
+      targets.push(...(writer.pick === "last" ? operands.slice(-1) : operands));
+    }
+  } catch {
+    // The hook path fails open. A command this cannot read is a command it
+    // reports nothing about.
+    return [];
+  }
+
+  return [...new Set(targets.filter(target => target !== "" && !NOT_A_FILE.has(target)))];
+}

package/node_modules/@agents-can-communicate/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/cli/src/args.mjs

@@ -17,8 +17,12 @@ export const COMMANDS = Object.freeze({
     "state", "workstream"], repeated: ["hint"], flags: ["clear"] },
   claim: { required: ["resource"],
     optional: ["session", "generation", "mode", "enforcement", "reason", "lease"] },
-  release: { required: ["claim"],
-    optional: ["session", "generation", "authority", "reason"] },
+  // Neither is required on its own, because either one names the claim: an id
+  // is precise, and a resource is what the caller typed to take it in the first
+  // place. Requiring the id meant a round trip through `acc status --json` to
+  // look up something the caller never chose.
+  release: { required: [],
+    optional: ["claim", "resource", "session", "generation", "authority", "reason"] },
   message: { required: ["subject", "body"],
     optional: ["session", "generation", "type", "priority", "workstream"],
     repeated: ["to"], flags: ["requires-ack"] },

package/node_modules/@agents-can-communicate/cli/src/doctor-command.mjs

@@ -1,11 +1,13 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
+import path from "node:path";
 
 import { detectInstallation, loadOwnership, verifyOwned }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs";
+import { describePresence } from "./main.mjs";
 import { platformPaths } from "./platform-paths.mjs";
 import { noticeUpdate } from "./update-check.mjs";
 import { diagnoseFilesystemStore, repairFilesystemStore }
@@ -37,9 +39,9 @@ async function diagnoseAdapters({ options, runtime }) {
   // The same home `acc install --home` writes to, or the real one. Reading a
   // different home than install wrote to reports every adapter as missing.
   const home = options?.home ?? runtime?.env?.HOME ?? homedir();
-  const clients = clientContext(home);
   const { data: dataHome } = platformPaths({ platform: runtime?.platform,
     env: runtime?.env ?? {} });
+  const clients = clientContext(home, path.join(dataHome, "acc"));
   const adapters = ALL_ADAPTERS();
   const detected = await detectInstallation({ adapters, context: clients,
     probeTimeoutMs: probeTimeout(runtime?.env) });
@@ -129,7 +131,7 @@ export async function runDoctor({ options, context, runtime }) {
   // command documented as saying "what to run next" said it only to `--json`.
   // A person running `acc doctor` on a client wired to an older plugin was told
   // the store was healthy and nothing else.
-  const text = [`store healthy; ${status.counts.live} live session(s); `
+  const text = [`store healthy; ${describePresence(status.counts)}; `
     + `protection ${status.protection}; ${installed} of ${adapters.length} adapter(s) installed`,
   ...data.remediation.map(line => `  ${line}`)].join("\n");
   return { data, text };

package/node_modules/@agents-can-communicate/cli/src/install-command.mjs

@@ -17,12 +17,18 @@ import { platformPaths } from "./platform-paths.mjs";
 // Each client keeps its own directory under the user's home, and an adapter
 // pointed at the home itself writes beside them rather than inside them. That
 // install reports success and the client never reads a byte of it.
-export const clientContext = home => ({
+export const clientContext = (home, stateRoot) => ({
   home,
   configDir: path.join(home, ".claude"),
   agentsHome: home,
   codexHome: path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
+  // Where ACC keeps its own state, for the client that has to be told. Codex
+  // sandboxes the commands a model runs to the workspace, and ACC's state is
+  // outside every workspace on purpose - so an agent there could read the
+  // roster and record nothing, every write failing with EPERM on the writer
+  // lock. Measured with `codex exec`, which is how an agent actually runs.
+  stateRoot,
 });
 
 export const ALL_ADAPTERS = () => [createClaudeCodeAdapter(), createCodexAdapter(),
@@ -153,9 +159,9 @@ export function actedOn(result) {
 export async function runInstallCommand({ options, runtime, action = "install" }) {
   const adapters = selectAdapters(options.adapter);
   const home = options.home ?? runtime.env?.HOME ?? homedir();
-  const context = clientContext(home);
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
     env: runtime.env ?? {} });
+  const context = clientContext(home, path.join(dataHome, "acc"));
 
   const detected = await detectInstallation({ adapters, context,
     probeTimeoutMs: probeTimeout(runtime.env) });

package/node_modules/@agents-can-communicate/cli/src/main.mjs

@@ -21,6 +21,39 @@ import { discoverWorkspace } from "./workspace-discovery.mjs";
 
 const DEFAULT_CADENCE_MS = 30_000;
 
+/**
+ * The claim a caller means when they name a resource instead of an id.
+ *
+ * `acc claim` takes `--resource`; `acc release` took `--claim`. The asymmetry
+ * cost every caller - a person and an agent alike - a round trip through
+ * `acc status --json` to find an id they never chose. The id is still accepted,
+ * and is still the precise answer when two sessions hold the same resource and
+ * an authority is releasing someone else's.
+ */
+async function claimOn(options, context) {
+  if (options.resource === undefined) {
+    throw new AccError(EXIT.USAGE,
+      "release needs the claim to give back: --resource is what you claimed, "
+      + "--claim is its id");
+  }
+  const resource = await canonicalClaim(options.resource, context.descriptor);
+  const { claims } = await context.service.collectStatus({});
+  // An authority releasing another session's claim is not looking for its own.
+  const mine = claims.filter(claim => claim.resource === resource
+    && (options.authority !== undefined || claim.ownerSessionId === options.session));
+
+  if (mine.length === 0) {
+    throw new AccError(EXIT.DATA, `no claim on ${resource} to release`,
+      { resource, held: claims.map(claim => claim.resource) });
+  }
+  if (mine.length > 1) {
+    throw new AccError(EXIT.DATA,
+      `${mine.length} claims on ${resource}; name the one you mean with --claim`,
+      { resource, claims: mine.map(claim => claim.claimId) });
+  }
+  return mine[0].claimId;
+}
+
 async function openContext(options, runtime) {
   const descriptor = await discoverWorkspace({
     cwd: options.cwd ?? runtime.cwd,
@@ -42,6 +75,14 @@ async function openContext(options, runtime) {
 
 const human = value => (typeof value === "string" ? value : JSON.stringify(value, null, 2));
 
+/** How many are here, and how many only look it. */
+export function describePresence({ live = 0, stale = 0 } = {}) {
+  if (live === 0) return "0 live";
+  if (stale === 0) return `${live} live`;
+  if (stale === live) return `${live} present, none answering`;
+  return `${live} live (${stale} not answering)`;
+}
+
 const HANDLERS = Object.freeze({
   attach: async ({ options, context }) => {
     const session = await context.service.openSession({
@@ -112,11 +153,12 @@ const HANDLERS = Object.freeze({
   },
 
   release: async ({ options, context }) => {
-    const request = { claimId: options.claim, sessionId: options.session,
+    const claimId = options.claim ?? await claimOn(options, context);
+    const request = { claimId, sessionId: options.session,
       generation: options.generation, authority: options.authority, reason: options.reason };
     if (options.authority === undefined) await context.service.releaseClaim(request);
     else await context.service.forceReleaseClaim(request);
-    return { data: { claimId: options.claim }, text: `released ${options.claim}` };
+    return { data: { claimId }, text: `released ${claimId}` };
   },
 
   message: async ({ options, context }) => {
@@ -241,7 +283,12 @@ const HANDLERS = Object.freeze({
   status: async ({ options, context }) => {
     const status = await context.service.collectStatus({
       participantId: options.participant, all: options.all === true });
-    const text = `${status.counts.live} live; ${status.counts.claims} claim(s); `
+    // `live` counts everyone present, which includes sessions gone stale - a
+    // client that exited without its session being closed keeps a record that
+    // stops being answered but does not disappear. Printing the number alone
+    // said "1 live" about a workspace where the last agent had left minutes
+    // before, which is the one thing a person reads this line to find out.
+    const text = `${describePresence(status.counts)}; ${status.counts.claims} claim(s); `
       + `protection ${status.protection}`;
     return { data: status, text };
   },

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [