@polygraph/claude-plugin 0.5.2 → 0.5.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/agents/polygraph-delegate-subagent.md

@@ -59,10 +59,8 @@ Child agent <id> is done.
 **Repo:** <repoFullName>
 **Delegation id:** <id>
 **Status:** <status>
-
-Read the result with show_agent (id: "<id>").
 ```
 
 For `input-required` or `permission-required`, replace "is done." with "needs attention." and keep everything else identical.
 
-Do not summarize, quote, or describe the child's work. Do not include log lines. The main agent reads the result itself via `show_agent`.
+Do not summarize, quote, or describe the child's work. Do not include log lines. The main agent reads the result itself via `show_agent`, and chooses how to read it. Never tell it which call to make.

package/hooks/reinject-polygraph-context.mjs

@@ -20,6 +20,8 @@
 //       holds selectedUrl, used to build the session URL.
 //
 // Outside a Polygraph session (no matching sidecar) the hook is a silent no-op.
+// Speculative captures (implicit session context, not explicit Polygraph sessions)
+// are also treated as no-op and not injected as context.
 
 import {
   appendFileSync,
@@ -94,7 +96,9 @@ function sessionsRoot(root) {
 
 // Scan the immediate subdirectories of `baseDir`; for each, `candidatePath`
 // maps the subdirectory name to a candidate sidecar file. Returns the first
-// parsed match, or null.
+// parsed match that is not a speculative sidecar, or null.
+// Speculative sidecars (target === 'speculative') are skipped; only regular
+// sidecars (target === 'regular' or missing target) are returned.
 function scanForSidecar(baseDir, candidatePath) {
   if (!existsSync(baseDir)) return null;
 
@@ -109,7 +113,13 @@ function scanForSidecar(baseDir, candidatePath) {
     if (!entry.isDirectory()) continue;
     const candidate = candidatePath(entry.name);
     if (existsSync(candidate)) {
-      return readJson(candidate);
+      const sidecar = readJson(candidate);
+      if (sidecar) {
+        // Skip speculative sidecars; only return regular ones (missing or 'regular' target).
+        if (sidecar.target !== 'speculative') {
+          return sidecar;
+        }
+      }
     }
   }
   return null;
@@ -118,7 +128,7 @@ function scanForSidecar(baseDir, candidatePath) {
 // Find the sidecar that maps an agent session id to a Polygraph session.
 // Checks the new per-session layout first, then falls back to the legacy
 // shared sidecars directory. Returns the parsed sidecar object, or null when
-// none matches.
+// none matches or only speculative sidecars are found.
 export function findSidecar(agentSessionId, root = polygraphRoot()) {
   if (!agentSessionId) return null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/SKILL.md

@@ -297,6 +297,7 @@ If the session has a description timeline, also display:
    
 1. **Read each result once** — when a poller exits, read that child with a single unwaited `show_agent(sessionId, id)`; `result.text` is the child's final message. Only reach for an explicit `tail` if that is not enough.
 1. **State the output in every brief** — children are told to be concise, so the instruction must say what to return: the shape, a cap where one makes sense, and the exact token for "nothing to report". See [`reference/delegation.md`](reference/delegation.md).
+1. **Batch the spawn and the read** — send several repos in one spawn call and collect their results in one read. Identical work rides a single instruction; differing work goes in a spec file with an entry per repo, sharing only what is genuinely shared. See [`reference/delegation.md`](reference/delegation.md).
 1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) before pushing branches or creating PRs
 1. **Link PRs in descriptions** - Reference related PRs in each PR body
 1. **Keep PRs as drafts** until all repos are ready

package/skills/polygraph/reference/delegation.md

@@ -30,7 +30,29 @@ spawn_agent(
 
 Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, what "done" looks like, and what to report back. The child has its own repo and its own context; it inherits nothing from yours.
 
-Delegate to several repos in parallel by calling `spawn_agent` once per repo before waiting on any of them.
+Delegate to several repos in parallel before waiting on any of them, and prefer one call over N. There are three shapes, the same three `polygraph agent spawn` takes:
+
+- **One repo** — `repo` with an `instruction`.
+- **Several repos, one task** — `repos` with one `instruction`, run verbatim in each.
+- **Several repos, different tasks** — `specFile`, a JSON file you write, whose path you pass.
+
+Batching pays because the shared text is transmitted once rather than once per repo, and every sibling starts from a byte-identical prompt prefix that can be served from cache. Each id still gets its own poller.
+
+The spec file is the many-to-many form. Each entry names a repo and carries its own `instruction`, and optionally its own `context`, `role`, `agent`, and `model`. Whatever the entries share goes in `sharedInstruction` / `sharedContext`, which are prepended to each entry's own text with a blank line between — so the common brief stays one identical prefix and only the per-repo part varies. An entry may carry no `instruction` of its own and rely entirely on the shared one. Being a file, it also carries a brief too large to pass as an argument, and it is straightforward to generate programmatically.
+
+```jsonc
+{
+  "sharedInstruction": "Brief every child gets, verbatim.",
+  "sharedContext": "Optional background every child gets.",
+  "agents": [
+    { "repo": "api", "instruction": "Add the expand parameter to the endpoint." },
+    { "repo": "people", "instruction": "Consume it in the client.", "context": "This repo still pins the old SDK." },
+    { "repo": "planets", "role": "reviewer", "agent": "codex", "instruction": "Review the change against the shared brief." }
+  ]
+}
+```
+
+One qualifier is load-bearing: share only what is genuinely shared. Flattening several different tasks into one `sharedInstruction` to look efficient produces worse work, and the round trips to repair it cost more than the batch saved. Work that differs belongs in each entry's own `instruction`, which is what the file is for.
 
 **Own-repo rule.** With the default role, `repo` must be a repository other than the one you are working in — never delegate into your own repo with the default role; work on it directly (ordinary local subagents are fine for that). Delegating into your own repo IS allowed with an explicit non-default `role`, because each (repo, role) pair is a separate agent slot and the child then runs alongside your own default-role work without colliding with it.
 
@@ -75,6 +97,8 @@ show_agent(sessionId: "<sessionId>", id: "<id>")
 
 One-off unwaited reads like this are cheap and expected inline. It is the *waiting* that belongs in a subagent, not the reading.
 
+When several pollers have exited, a **batch read** collects their results in one unwaited call: pass the list of ids and correlate each result by its delegation id. Batch when you spawned children together and have nothing to do until they all finish. Read one at a time when you act on each result as it lands, or only one child is in flight.
+
 ## When the result is not enough
 
 Only if `result.text` is missing, truncated, or the child failed in a way you cannot explain from it: