@polygraph/claude-plugin 0.5.3 → 0.5.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.5.3",
+  "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.3",
+  "version": "0.5.4",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/reference/delegation.md

@@ -97,7 +97,7 @@ 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.
+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