@polygraph/codex-plugin 0.4.51 → 0.4.53

package/.codex-plugin/plugin.json

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

package/hooks/agent-session-link.mjs

@@ -1,6 +1,6 @@
 import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
@@ -8,6 +8,13 @@ const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
 const AGENT_TYPES = new Set(['claude', 'codex', 'opencode', 'cursor']);
 const COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
 const OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
+// Cursor reports MCP tools as `MCP:<tool>` with no server namespace, so the
+// shim filters on the claim-worthy tool names to avoid spawning the CLI on
+// every unrelated MCP call. This list is an optimization mirror of
+// PARENT_CLAIM_POLICIES in the Polygraph CLI (parent-session-claim-evidence);
+// classification authority stays in the CLI.
+const CURSOR_MCP_CLAIM_TOOL =
+  /^MCP:(?:add_repo|allow_agent|archive_session|associate_pr|create_pr|deny_agent|git_fetch|link_reference|mark_pr_ready|pack_and_copy|push_branch|spawn_agent|start_session|stop_agent|update_session|upload_artifact)$/;
 
 function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value : undefined;
@@ -30,6 +37,7 @@ export function buildLinkAgentSessionArgs({
   transcriptPath,
   pid,
   source,
+  hookOperation,
 }) {
   const session = nonEmptyString(polygraphSessionId);
   const harnessSession = nonEmptyString(agentSessionId);
@@ -52,14 +60,38 @@ export function buildLinkAgentSessionArgs({
     args.push('--pid', String(pid));
   }
 
+  // Cursor post-tool evidence rides the hook payload (the transcript stores
+  // no tool results); forwarded verbatim, classified by the CLI. The
+  // operation travels on STDIN, never argv: toolInput can carry an entire
+  // upload_artifact document and Linux caps one argv string at 128KB, so an
+  // inline argument would kill the spawn with E2BIG and silently lose the
+  // evidence. The flag tells the CLI to read stdin; older strict CLIs
+  // reject it, which is why publication is gated on the Ocean deployment.
+  let input;
+  if (hookOperation && typeof hookOperation === 'object') {
+    args.push('--hook-operation-stdin');
+    input = JSON.stringify(hookOperation);
+  }
+
   args.push('--source', claimSource);
-  return args;
+  return { args, input };
+}
+
+/**
+ * Node runtime for the JS-entry fallback. This shim also runs inside
+ * non-Node hosts (the opencode plugin executes it in-process, and opencode
+ * is a compiled Bun binary), where process.execPath is not a Node
+ * executable — fall back to PATH resolution there.
+ */
+function nodeRuntime() {
+  const base = basename(process.execPath).toLowerCase();
+  return base === 'node' || base === 'node.exe' ? process.execPath : 'node';
 }
 
 export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
   if (isManagedChildEnvironment(env)) return false;
 
-  const args = buildLinkAgentSessionArgs(claim);
+  const { args, input } = buildLinkAgentSessionArgs(claim);
   const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? 'polygraph';
   const commandEnv = nonEmptyString(claim.polygraphSessionId) ? env : { ...env };
   if (commandEnv !== env) {
@@ -67,11 +99,23 @@ export function linkAgentSession(claim, spawn = spawnSync, env = process.env) {
     delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
   }
 
-  const result = spawn(command, args, {
+  const spawnOptions = {
     encoding: 'utf8',
     env: commandEnv,
-    stdio: ['ignore', 'ignore', 'pipe'],
-  });
+    stdio: [input === undefined ? 'ignore' : 'pipe', 'ignore', 'pipe'],
+    ...(input === undefined ? {} : { input }),
+  };
+
+  let result = spawn(command, args, spawnOptions);
+
+  // POLYGRAPH_CLI may point at a plain JS entry that cannot be spawned
+  // directly: a dev build without the executable bit, or a platform that
+  // cannot exec scripts. A spawn that failed to LAUNCH ran nothing, so the
+  // retry under a Node runtime is side-effect free — and anything that
+  // spawns directly today keeps its exact behavior.
+  if (result?.error && /\.[cm]?js$/i.test(command)) {
+    result = spawn(nodeRuntime(), [command, ...args], spawnOptions);
+  }
 
   if (result?.error) throw result.error;
   if (result?.status !== 0) {
@@ -126,6 +170,24 @@ export function buildCommandHookLink(payload, agentType, env = process.env) {
     return isPolygraphMcpToolName(payload.tool_name) ? common : undefined;
   }
 
+  // Cursor's camelCase postToolUse: the payload carries the whole operation
+  // (tool_name `MCP:<tool>`, tool_input, tool_output) and is forwarded as
+  // evidence because the cursor transcript stores no tool results and lags
+  // the hook. The CLI classifies the operation; this filter only avoids
+  // spawning the CLI for unrelated tools.
+  if (payload.hook_event_name === 'postToolUse') {
+    const toolName = nonEmptyString(payload.tool_name);
+    if (!toolName || !CURSOR_MCP_CLAIM_TOOL.test(toolName)) return undefined;
+    return {
+      ...common,
+      hookOperation: {
+        toolName,
+        toolInput: payload.tool_input,
+        toolOutput: payload.tool_output,
+      },
+    };
+  }
+
   return undefined;
 }
 

package/package.json

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

package/skills/polygraph/reference/delegation.md

@@ -40,7 +40,12 @@ For each id, launch one background poller subagent whose entire job is to block
 
 - **Claude Code** — a background `Task` with `subagent_type: "polygraph:polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Fall back to the bare agent name only if the namespaced form is not found.
 - **OpenCode** — invoke `@polygraph-delegate-subagent`.
-- **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`.
+- **Codex** — launch `agent_type: "polygraph-delegate-subagent"` via Codex's own `spawn_agent`, and collect it with `wait_agent`, passing a long `timeout_ms` (five minutes or more): `wait_agent` returns as soon as the poller stops, so a short timeout only adds wake-ups that burn tokens and fill the user-visible transcript with waiting noise.
+- **Cursor** — a background `Task` with `subagent_type: "polygraph-delegate-subagent"`, `run_in_background: true`, and description `Delegate to <repo>`. Collect it with `Await`.
+
+A collect step that returns while the poller subagent is still running has not failed. It has only reached the end of its collection window. Collect the same background-task id again, as many times as it takes for the poller subagent to stop. A poller that runs for several minutes is ordinary, and it is never a reason to take the wait back into the main conversation.
+
+The background-task id is the handle your own harness returned when you launched the poller. It is not the Polygraph delegation id (`frontend-1`), which addresses the child agent. Once the poller subagent has finished, do not collect it again: read the child instead, as described below. A child that stops for attention also ends the poller, so treat that as a finished poller and not as a collection window running out.
 
 The poller has exactly one tool and cannot read logs. It exits with a few lines naming the repo, the id, and the final status. That message is a doorbell, not a report — it tells you the child is worth reading, and nothing about what the child did.