@polygraph/claude-plugin 0.4.50 → 0.4.52

package/.claude-plugin/plugin.json

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

package/README.md

@@ -61,7 +61,7 @@ Neither is required — they are a throughput optimization, not a correctness fi
 ## Skills
 
 - **polygraph** — Comprehensive guidance for Polygraph sessions: shared context, repository graph visibility, PR/CI state, delegation, and session management.
-- **adversarial-review** — Second-opinion review of a session's work by independent reviewer agents, one per repo, running under a read-only `reviewer` role.
+- **adversarial-review** — Second-opinion review by independent per-repo agents that presents and attaches one consolidated review artifact.
 - **await-polygraph-ci** — Wait for CI pipelines to settle across all repos in a session, investigate failures, and present fix options.
 - **get-latest-ci** — One-shot fetch of the latest CI pipeline execution for the current branch.
 - **session-debrief** — Analyze the raw logs of past Polygraph sessions and produce structured, rank-ordered debriefs for use in a different session.
@@ -82,6 +82,18 @@ npm install
 npm run sync-artifacts
 ```
 
+Estimate the compiled prompt cost of every skill and subagent for Claude Code,
+Codex, and OpenCode:
+
+```sh
+npm run report:token-costs
+```
+
+The report uses four characters per estimated token by default. Override the
+ratio when needed with `npm run report:token-costs -- --characters-per-token 3.5`.
+Pull requests run the same report when opened or updated and keep the latest
+results in a single collapsible comment.
+
 ## Releasing
 
 Run the `Release PR` GitHub Actions workflow with a version bump (`patch`, `minor`, or `major`).

package/agents/session-debrief.md

@@ -2,6 +2,7 @@
 
 name: session-debrief
 description: Analyze the raw logs of one or more past Polygraph sessions and return a structured, rank-ordered debrief for the current task. Launch as a background agent with a ranked list of relevant Polygraph session IDs/lines and a one-paragraph statement of the current task; it invokes the session-debrief skill, pulls parent and child transcripts via the polygraph CLI, and returns one consolidated debrief. Read-only with respect to the inspected sessions.
+model: haiku
 
 ---
 

package/hooks/agent-session-link.mjs

@@ -1,11 +1,11 @@
 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;
 
-const AGENT_TYPES = new Set(['claude', 'codex', 'opencode']);
+const AGENT_TYPES = new Set(['claude', 'codex', 'opencode', 'cursor']);
 const COMMAND_HOOK_TOOL = /^mcp__(?:plugin_polygraph_)?polygraph[-_]mcp__/;
 const OPENCODE_TOOL = /^polygraph(?:(?:-|_)mcp)?_/;
 
@@ -56,6 +56,17 @@ export function buildLinkAgentSessionArgs({
   return args;
 }
 
+/**
+ * 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;
 
@@ -67,11 +78,22 @@ 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'],
-  });
+  };
+
+  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) {
@@ -89,18 +111,30 @@ export function buildCommandHookLink(payload, agentType, env = process.env) {
   if (!payload || typeof payload !== 'object') return undefined;
   if (isManagedChildEnvironment(env)) return undefined;
 
-  const agentSessionId = nonEmptyString(payload.session_id);
+  // Cursor payloads carry the id in both session_id and conversation_id;
+  // the fallback keeps the link working if one of them disappears.
+  const agentSessionId =
+    nonEmptyString(payload.session_id) ?? nonEmptyString(payload.conversation_id);
   if (!agentSessionId) return undefined;
 
+  // Cursor has no top-level cwd; workspace_roots[0] is the launch directory.
+  const workspaceRoot = Array.isArray(payload.workspace_roots)
+    ? nonEmptyString(payload.workspace_roots[0])
+    : undefined;
+
   const common = {
     agentType,
     agentSessionId,
-    cwd: nonEmptyString(payload.cwd),
+    cwd: nonEmptyString(payload.cwd) ?? workspaceRoot,
     transcriptPath: nonEmptyString(payload.transcript_path),
     source: 'hook',
   };
 
-  if (payload.hook_event_name === 'SessionStart') {
+  // Claude and Codex send PascalCase event names; cursor sends camelCase.
+  if (
+    payload.hook_event_name === 'SessionStart' ||
+    payload.hook_event_name === 'sessionStart'
+  ) {
     const polygraphSessionId = nonEmptyString(env.POLYGRAPH_SESSION_ID);
     if (polygraphSessionId) return { ...common, polygraphSessionId };
 

package/package.json

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

package/skills/adversarial-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adversarial-review
-description: Independent second-opinion review of a Polygraph session's work. USE WHEN user says "adversarial review", "review this session", or when the Polygraph CLI launches an agent with an instruction to load this skill.
+description: Review a Polygraph session with independent per-repo reviewers and attach one consolidated review artifact.
 
 user-invocable: true
 allowed-tools:
@@ -14,10 +14,10 @@ allowed-tools:
 
 # Adversarial Review
 
-1. **Pick the agent.** Ask whether Claude, Codex, or OpenCode should review — `claude`, `codex`, or `opencode` for `spawn_agent`'s `agent` parameter. Skip if the user already named one.
+1. Skip this step entirely if a reviewer agent was already named — by the user, or in the instruction that launched you (e.g. from `polygraph session review --adversarial`); in that case use that agent and do not ask. Otherwise, **pick the agent**: Ask which should review—`claude`, `codex`, or `opencode` for `spawn_agent`'s `agent` parameter. If the user names a model, pass it via `spawn_agent`'s optional `model` parameter; don't ask about models.
 2. **Get the session description.**
-3. **Get each repo's plan.** Ask each repo's agent to provide the plan.
-4. **Delegate one reviewer per repo** in parallel, with `role: "reviewer"`. Pass the overall plan and that repo's plan, and ask it to review the code, identify issues, and return a summary. Do the delegation even for the "initiator" repo.
-5. **Summarize.** Once every review is back, analyze them and present one summary to the user.
-6. **Ask what next.** Address the feedback, upload the summary via `upload_artifact`, or continue with the session. Skip if the user already said.
+3. **Get each repo's plan.**
+4. **Delegate one reviewer per repo** in parallel, `role: "reviewer"`. Ask to review, identify issues. Do the delegation even for the "initiator" repo.
+5. **Summarize and attach.** Consolidate reviews into one consolidated Markdown review with per-repo sections and present it to the user. Then call `upload_artifact` once with `sessionId`, that review as `content`, `kind: "review"`, `format: "markdown"`, name `adversarial-review-YYYY-MM-DDTHH-mm-ssZ.md`. If the upload fails, report that separately without suppressing the review.
+6. **Ask what next.** Address feedback or continue. Skip if the user already said.
 7. If the user selects "address the feedback", pass each repo's feedback to the repo default agent (not the reviewer). The initiator should fix things itself without delegating.

package/skills/polygraph/reference/delegation.md

@@ -20,10 +20,14 @@ spawn_agent(
   repo: "<org/repo-name>",
   instruction: "<the task instruction>",
   role: "<optional role>",
-  context: "<optional context>"
+  context: "<optional context>",
+  agent: "<optional: claude | codex | opencode>",
+  model: "<optional model override>"
 )
 ```
 
+`agent` picks the child's harness and `model` overrides its default model; include either only when the user named one.
+
 Write the instruction as if to a competent engineer who cannot see your conversation: state the goal, the constraints, and what "done" looks like. 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.
@@ -37,6 +41,11 @@ 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`.
+- **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.