@polygraph/claude-plugin 0.4.49 → 0.4.51

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.49",
+  "version": "0.4.51",
   "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/polygraph-delegate-subagent.md

@@ -5,6 +5,7 @@ description: Waits for one Polygraph child agent (addressed by delegation id) to
 model: haiku
 tools:
   - mcp__plugin_polygraph_polygraph-mcp__show_agent
+  - Bash
 
 ---
 
@@ -21,19 +22,29 @@ The main agent already spawned the child via `spawn_agent` and received a delega
 | `sessionId` | The Polygraph session ID                                     |
 | `id`        | The delegation id returned by `spawn_agent` (e.g. `frontend-1`) |
 
+## Two ways to poll
+
+| MCP tool     | CLI equivalent                                                                        |
+| ------------ | ------------------------------------------------------------------------------------- |
+| `show_agent` | `polygraph agent show --session <sessionId> --id <id> --wait-for-transition-ms 300000` |
+
+Prefer 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.
+
+The 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.
+
 ## Loop
 
-Call the `show_agent` tool with exactly these arguments, repeatedly:
+Call `show_agent` with exactly these arguments, repeatedly:
 
 - `sessionId`: the session ID
 - `id`: the delegation id
 - `waitForTransitionMs`: 300000
 
-Never pass `tail`. Never call any other tool. Never read files, transcripts, or logs.
+Never pass `tail`. Apart from the CLI fallback above, never call any other tool, and never read files, transcripts, or logs.
 
 Each call blocks up to 5 minutes, then returns the child's `status` on `children[0]`:
 
-- `in-progress` or `created` → call `show_agent` again with the same arguments.
+- `in-progress` or `created` → poll again with the same arguments.
 - `completed`, `failed`, `cancelled`, `input-required`, or `permission-required` → stop looping and exit with the message below.
 
 If a call errors, retry it once. If it errors again, exit with the error text plus the delegation id and stop.

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

@@ -5,7 +5,7 @@ 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)?_/;
 
@@ -89,18 +89,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.49",
+  "version": "0.4.51",
   "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.