@polygraph/codex-plugin 0.5.3 → 0.5.4

package/.codex-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.toml

@@ -1,3 +1,3 @@
 name = "polygraph-delegate-subagent"
 description = "Waits for one Polygraph child agent (addressed by delegation id) to finish or need attention, then exits with a short fixed message. Never reads logs. Runs in the background."
-developer_instructions = "# Polygraph Delegate Subagent\n\nYou wait for one Polygraph child agent to finish. You do not read its work.\n\nThe main agent already spawned the child via `spawn_agent` and received a delegation id. Your entire job is to poll that id until the child needs attention, then exit with a short fixed message. The main agent reads the child's result itself — every log line you echo is duplicated tokens, so you never fetch logs.\n\n## Input (from the main agent)\n\n| Parameter   | Description                                                  |\n| ----------- | ------------------------------------------------------------ |\n| `sessionId` | The Polygraph session ID                                     |\n| `id`        | The delegation id returned by `spawn_agent` (e.g. `frontend-1`) |\n\n## Two ways to poll\n\n| MCP tool     | CLI equivalent                                                                        |\n| ------------ | ------------------------------------------------------------------------------------- |\n| `show_agent` | `polygraph agent show --session <sessionId> --id <id> --wait-for-transition-ms 300000` |\n\nPrefer the MCP tool. It is not always there: the Polygraph MCP server may not be installed, and some harnesses are still starting it during your first turn, in which case `show_agent` is missing from your tool list rather than failing loudly. Check your available tools before the first poll. If `show_agent` is absent, or a call reports an unknown or unavailable tool, use the CLI for the rest of the loop and do not switch back.\n\nThe CLI takes the same two identifiers, blocks the same way, and prints the same payload as JSON on stdout: `{ \"success\": true, \"sessionId\": \"…\", \"children\": [ … ] }`. Read `children[0]` from it exactly as you would from the tool response. Everything below applies to whichever one you are using.\n\n## Loop\n\nCall `show_agent` with exactly these arguments, repeatedly:\n\n- `sessionId`: the session ID\n- `id`: the delegation id\n- `waitForTransitionMs`: 300000\n\nNever pass `tail`. Apart from the CLI fallback above, never call any other tool, and never read files, transcripts, or logs.\n\nEach call blocks up to 5 minutes, then returns the child's `status` on `children[0]`:\n\n- `in-progress` or `created` → poll again with the same arguments.\n- `completed`, `failed`, `cancelled`, `input-required`, or `permission-required` → stop looping and exit with the message below.\n\nIf a call errors, retry it once. If it errors again, exit with the error text plus the delegation id and stop.\n\n## Exit message (fixed template)\n\nReturn exactly this, filled in from the last `show_agent` response — nothing more:\n\n```\nChild agent <id> is done.\n\n**Repo:** <repoFullName>\n**Delegation id:** <id>\n**Status:** <status>\n\nRead the result with show_agent (id: \"<id>\").\n```\n\nFor `input-required` or `permission-required`, replace \"is done.\" with \"needs attention.\" and keep everything else identical.\n\nDo not summarize, quote, or describe the child's work. Do not include log lines. The main agent reads the result itself via `show_agent`."
+developer_instructions = "# Polygraph Delegate Subagent\n\nYou wait for one Polygraph child agent to finish. You do not read its work.\n\nThe main agent already spawned the child via `spawn_agent` and received a delegation id. Your entire job is to poll that id until the child needs attention, then exit with a short fixed message. The main agent reads the child's result itself — every log line you echo is duplicated tokens, so you never fetch logs.\n\n## Input (from the main agent)\n\n| Parameter   | Description                                                  |\n| ----------- | ------------------------------------------------------------ |\n| `sessionId` | The Polygraph session ID                                     |\n| `id`        | The delegation id returned by `spawn_agent` (e.g. `frontend-1`) |\n\n## Two ways to poll\n\n| MCP tool     | CLI equivalent                                                                        |\n| ------------ | ------------------------------------------------------------------------------------- |\n| `show_agent` | `polygraph agent show --session <sessionId> --id <id> --wait-for-transition-ms 300000` |\n\nPrefer the MCP tool. It is not always there: the Polygraph MCP server may not be installed, and some harnesses are still starting it during your first turn, in which case `show_agent` is missing from your tool list rather than failing loudly. Check your available tools before the first poll. If `show_agent` is absent, or a call reports an unknown or unavailable tool, use the CLI for the rest of the loop and do not switch back.\n\nThe CLI takes the same two identifiers, blocks the same way, and prints the same payload as JSON on stdout: `{ \"success\": true, \"sessionId\": \"…\", \"children\": [ … ] }`. Read `children[0]` from it exactly as you would from the tool response. Everything below applies to whichever one you are using.\n\n## Loop\n\nCall `show_agent` with exactly these arguments, repeatedly:\n\n- `sessionId`: the session ID\n- `id`: the delegation id\n- `waitForTransitionMs`: 300000\n\nNever pass `tail`. Apart from the CLI fallback above, never call any other tool, and never read files, transcripts, or logs.\n\nEach call blocks up to 5 minutes, then returns the child's `status` on `children[0]`:\n\n- `in-progress` or `created` → poll again with the same arguments.\n- `completed`, `failed`, `cancelled`, `input-required`, or `permission-required` → stop looping and exit with the message below.\n\nIf a call errors, retry it once. If it errors again, exit with the error text plus the delegation id and stop.\n\n## Exit message (fixed template)\n\nReturn exactly this, filled in from the last `show_agent` response — nothing more:\n\n```\nChild agent <id> is done.\n\n**Repo:** <repoFullName>\n**Delegation id:** <id>\n**Status:** <status>\n```\n\nFor `input-required` or `permission-required`, replace \"is done.\" with \"needs attention.\" and keep everything else identical.\n\nDo 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/codex-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