@polygraph/cursor-plugin 0.4.51 → 0.4.53

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/hooks/hooks.json

@@ -5,6 +5,11 @@
       {
         "command": "node hooks/record-session-mapping.mjs cursor"
       }
+    ],
+    "postToolUse": [
+      {
+        "command": "node hooks/record-session-mapping.mjs cursor"
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/cursor-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/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "polygraph",
-  "version": "0.4.51",
+  "version": "0.4.53",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination"
 }

package/skills/polygraph/SKILL.md

@@ -43,6 +43,8 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `select_account` | `polygraph account select` | Select the organization that future commands run against |
 | `whoami` | `polygraph whoami` | Show current auth status and org |
 
+**Delegation rules:** `list_repos` and `start_session` MUST be called via the `polygraph-init-subagent` as described in the "Initialize or Join Polygraph Session" section. Direct `add_repo` is allowed only when the user provides exact repo refs for an existing session. `spawn_agent` is a fast, non-blocking call and IS allowed directly in the main conversation — it returns a delegation id. Waited `show_agent` POLLING must run in a background `Task` (`subagent_type: "polygraph-delegate-subagent"`, `run_in_background: true`), collected with `Await`, never inline. One-off unwaited `show_agent` reads in the main conversation are fine and expected — that is how you read a child's result. See [`reference/delegation.md`](reference/delegation.md). The init subagent is launched the same way, by its bare name: a `Task` with `subagent_type: "polygraph-init-subagent"` — without `run_in_background`, since you need its summary before continuing.
+
 ## CLI Statefulness
 
 The Polygraph CLI (`polygraph`) is **stateful**. When you select an organization — via `polygraph account select` or the equivalent MCP tool — that selection is saved globally and all subsequent CLI commands and MCP tool calls operate against it. You do not need to pass the org on every command.
@@ -69,8 +71,8 @@ After logging in (or if logged in but no org is selected), use `polygraph accoun
 
 The delegate/monitor/stop steps apply only when working across repos. A single-repo session skips them and still benefits from shared progress, resume, and CI visibility.
 
-2. **Initialize or join Polygraph session** - If you already have a session ID, call `show_session` to fetch details. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. Otherwise, discover candidate repos, select relevant repositories, and create a new session via `list_repos` and `start_session`.
-3. **Delegate work to each repo** - Use `spawn_agent` to start child agents in other repositories (returns immediately with a delegation id). With the default role, delegate only to *other* repos — never to the repo you are in; work on it directly. Delegating into the repo you are in is allowed only with an explicit non-default `role`. Parallel delegation across repos is encouraged. Read [`reference/delegation.md`](reference/delegation.md) before delegating.
+0. **Initialize or join Polygraph session** - If you were spawned inside an existing session (the startup banner names a session ID), reuse it. Call `show_session` first; if it already has repos and the user did not ask to add more, you're done. If the user asks to add exact repo refs, call `add_repo` directly and skip candidate discovery. If the session has no repos and no exact refs were provided, launch the `polygraph-init-subagent` with that `sessionId` so it discovers candidates and uses `add_repo` (NOT `start_session`). Only when there is no session ID at all should the init subagent create a new session.
+1. **Delegate work to each repo** - Call `spawn_agent` for each repo to get a delegation id, then launch one background `polygraph-delegate-subagent` per id to wait on it. With the default role, delegate only to *other* repos — never to the repo you are in; work on it directly (your regular subagents are fine for local work — only Polygraph delegation is reserved for other repos). Delegating into the repo you are in is allowed only with an explicit non-default `role`. Parallel delegation across repos is encouraged. Read [`reference/delegation.md`](reference/delegation.md) before delegating.
    
 4. **Monitor child agents** - Let the background poller subagent do the waiting. When it exits, read that child's answer with a single unwaited `show_agent(sessionId, id)` — `result.text` is the child's final message.
 5. **Stop child agents** (if needed) - Use `stop_agent` with the delegation id to cancel an in-progress child agent. The agent's session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
@@ -97,7 +99,7 @@ There are three cases. Pick exactly one before calling any tool. The case labels
 
 **Case C — No session at all.** Launch the `polygraph-init-subagent` with only `userContext` (no `sessionId`). The subagent will discover candidates and call `start_session` to create a new session.
 
-In case B, direct exact repo refs go straight to `add_repo`; use `list_repos` only when discovery/filtering is needed. In case C, discover candidate repos using `list_repos`, select relevant repositories, and call `start_session`. In case A, just call `show_session`.
+In case B, call `add_repo` yourself when exact repo refs were provided; otherwise the subagent handles discovery and attachment. In case C the subagent handles session creation. In case A you call `show_session` yourself.
 
 **Session ID handling:**
 
@@ -281,7 +283,7 @@ If the session has a description timeline, also display:
 
 ## Best Practices
 
-1. **Delegate asynchronously** — Use `spawn_agent` which returns immediately with a delegation id, then poll with `show_agent`.
+1. **Wait in background subagents** — `spawn_agent` is fine to call directly and returns a delegation id, but every waited `show_agent` poll belongs in a background `Task` with `subagent_type: "polygraph-delegate-subagent"` and `run_in_background: true`. Collect that Task with `Await`, and if `Await` returns while the poller is still running, call `Await` again with the same background-task id. Inline polling floods the context with status noise.
    
 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. **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
@@ -291,4 +293,6 @@ If the session has a description timeline, also display:
 1. **Test integration** before marking PRs ready
 1. **Coordinate merge order** if there are deployment dependencies
    
+1. **NEVER run a waited `show_agent` loop in the main conversation**. Waiting MUST run inside `polygraph-delegate-subagent`, launched as a background `Task` and collected with `Await`.
+   
 1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed (pass the delegation id). The child's session is preserved (`sessionPreserved: true`) so the context can be restored later, but after resuming you must wait for explicit user instructions before making changes.

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.