@polygraph/claude-plugin 0.4.47 → 0.4.49

package/.claude-plugin/plugin.json

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

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">Polygraph Skills</h1>
 
 <p align="center">
-  AI agent skills and subagents for <a href="https://trypolygraph.com/">Polygraph</a> — the meta-harness for maximum agentic autonomy, giving agents visibility across every repo and memory that survives every session.
+  AI agent skills and subagents for <a href="https://trypolygraph.com/">Polygraph</a> — the agent-agnostic meta-harness for maximum agentic autonomy, giving agents visibility across every repo and memory that survives every session.
 </p>
 
 <p align="center">
@@ -23,7 +23,7 @@
 
 ## What is Polygraph?
 
-Polygraph is a meta-harness for maximum agentic autonomy. It works with the agents you already use and gives them what they're missing: visibility across every repo boundary, and memory that survives every session. Agents discover how repositories relate, coordinate changes across them, and hand off or resume work later with repos, branches, PRs, and logs all preserved.
+Polygraph is the agent-agnostic meta-harness for maximum agentic autonomy. It works with the agents you already use and gives them what they're missing: visibility across every repo boundary, and memory that survives every session. Agents discover how repositories relate, coordinate changes across them, and hand off or resume work later with repos, branches, PRs, and logs all preserved.
 
 ## Setup
 
@@ -35,19 +35,42 @@ polygraph config
 
 It detects your AI agent — Claude Code, Codex, OpenCode, and more — and installs the Polygraph skills and subagents for it. Re-run it any time to add another agent or update an existing install.
 
+### Codex: raising the long-poll ceiling
+
+The delegate subagent polls child agents with `show_agent(waitForTransitionMs: 300000)` — a single 5-minute wait instead of a stream of short polls, which is what keeps delegation cheap. Claude Code and OpenCode honor the full wait. Codex does not by default.
+
+Codex caps every MCP tool call at `tool_timeout_sec = 60`, so long polls effectively cap at 50s. Nothing the plugin ships can change that: a plugin's `.mcp.json` has no timeout field, and `tool_timeout_sec` is only read from `~/.codex/config.toml`. Polling still works at 50s — the MCP resolves the real ceiling per client and returns early rather than erroring — you just pay for more round trips.
+
+To get the full 5-minute wait under Codex, set **both**:
+
+1. `tool_timeout_sec` in `~/.codex/config.toml`:
+
+   ```toml
+   [mcp_servers.polygraph]
+   tool_timeout_sec = 360
+   ```
+
+2. `POLYGRAPH_MCP_MAX_WAIT_MS` in that server's env, if you launch it from the CLI:
+
+   ```sh
+   POLYGRAPH_MCP_MAX_WAIT_MS=300000
+   ```
+
+Neither is required — they are a throughput optimization, not a correctness fix.
+
 ## 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
-- **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
+- **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.
+- **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.
 
 ## Agents
 
-- **polygraph-init-subagent** — Discovers candidate repositories and initializes a Polygraph session
-- **polygraph-delegate-subagent** — Delegates work to a child agent in another repository, polls for completion
-- **session-debrief** — Analyzes the raw logs of past Polygraph sessions and returns a structured, rank-ordered debrief for the current task
+- **polygraph-init-subagent** — Discovers candidate repositories and initializes a Polygraph session.
+- **polygraph-delegate-subagent** — Delegates work to a child agent in another repository, polls for completion.
+- **session-debrief** — Analyzes the raw logs of past Polygraph sessions and returns a structured, rank-ordered debrief for the current task.
 
 ## Development
 
@@ -71,7 +94,7 @@ For the strictest release flow, do not allow direct `npm publish` for the truste
 
 ## Learn More
 
-- **[Polygraph](https://trypolygraph.com/)** — The meta-harness for maximum agentic autonomy
+- **[Polygraph](https://trypolygraph.com/)** — The agent-agnostic meta-harness for maximum agentic autonomy
 - **[@polygraph/mcp](https://www.npmjs.com/package/@polygraph/mcp)** — The MCP server that powers Polygraph tools
 ## License
 

package/agents/polygraph-delegate-subagent.md

@@ -1,167 +1,57 @@
 ---
 
 name: polygraph-delegate-subagent
-description: Delegates work to a child agent in another repository via Polygraph, polls for completion, and returns a structured summary. Runs in the background.
+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.
 model: haiku
 tools:
-  - mcp__plugin_polygraph_polygraph-mcp__spawn_agent
   - mcp__plugin_polygraph_polygraph-mcp__show_agent
-  - mcp__plugin_polygraph_polygraph-mcp__stop_agent
-  - Bash
 
 ---
 
 # Polygraph Delegate Subagent
 
-You are a Polygraph delegation subagent. Your job is to delegate work to a child agent in another repository, poll for completion, and return a structured summary.
+You wait for one Polygraph child agent to finish. You do not read its work.
 
-You run in the background. The main agent checks your output file for progress.
+The 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.
 
-## Input Parameters (from Main Agent)
+## Input (from the main agent)
 
-The main agent provides these parameters in the prompt:
+| Parameter   | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `sessionId` | The Polygraph session ID                                     |
+| `id`        | The delegation id returned by `spawn_agent` (e.g. `frontend-1`) |
 
-| Parameter     | Description                                                                  |
-| ------------- | ---------------------------------------------------------------------------- |
-| `sessionId`   | The Polygraph session ID                                                     |
-| `repo`        | Repository to delegate to (e.g., `org/repo-name`)                            |
-| `instruction` | The task instruction for the child agent                                     |
-| `role`        | (Optional) Agent slot within the repo; omit for the default role and never invent one. Pass the SAME role on every `spawn_agent`/`show_agent`/`stop_agent` call for this delegation. |
-| `context`     | (Optional) Additional context to pass to the child agent                     |
+## Loop
 
-## Delegating work
+Call the `show_agent` tool with exactly these arguments, repeatedly:
 
-Call the `spawn_agent` tool to start a child agent on the repo or to send a follow-up to an active task. Follow-up routing is automatic per (repo, role): if that (repo, role) already has an active child task (working or paused on input), the orchestrator delivers your `instruction` to that task as a follow-up message rather than starting a second run; otherwise it starts a new child run. A repo therefore has at most one active child per role.
+- `sessionId`: the session ID
+- `id`: the delegation id
+- `waitForTransitionMs`: 300000
 
-`repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo.
+Never pass `tail`. Never call any other tool. Never read files, transcripts, or logs.
 
-**Resume/reconstruction is read-only.** If the parent asks you to resume, reconnect, restore, or reconstruct a preserved session without an explicit new change request from the user, do not call `spawn_agent` to continue work. Use `show_agent` only as needed to read status/log context, return a concise restoration summary, and stop. After resuming, wait for explicit user instructions before any child agent makes changes.
+Each call blocks up to 5 minutes, then returns the child's `status` on `children[0]`:
 
-```
-spawn_agent(
-  sessionId: "<sessionId>",
-  repo: "<repo>",
-  instruction: "<instruction>",
-  role: "<role, if any>",
-  context: "<context>"
-)
-```
-
-The call returns immediately — the child agent runs asynchronously.
-
-**Polling with long-poll waits:**
-
-Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
-
-```
-show_agent(
-  sessionId: "<sessionId>",
-  repo: "<repo>",
-  role: "<role, if any>",
-  waitForTransitionMs: 50000
-)
-```
-
-Each call blocks up to ~50 seconds and resolves within ~1 second of a state change. It returns immediately if the child is already terminal, `input-required`, or `permission-required`. Call it back-to-back in a loop.
+- `in-progress` or `created` → call `show_agent` again with the same arguments.
+- `completed`, `failed`, `cancelled`, `input-required`, or `permission-required` → stop looping and exit with the message below.
 
-## Polling the child (multi-turn + input-required)
+If a call errors, retry it once. If it errors again, exit with the error text plus the delegation id and stop.
 
-After calling `spawn_agent`, parse the structured JSON response:
+## Exit message (fixed template)
 
-```json
-{ "taskId": "…", "message": "…", "status": "delegated" }
-```
+Return exactly this, filled in from the last `show_agent` response — nothing more:
 
-Then poll `show_agent` in a loop with `waitForTransitionMs: 50000`. **Do not pass a `tail` argument** — the tool's default is sized for status polling. Only set `tail` if you have a specific reason (e.g., the default truncated output you actually need to inspect, or you are hunting for an earlier failure that scrolled off). Never ratchet `tail` upward across polls; that is what causes the polling loop to flood your context window.
-
-The response's `children[]` array has one entry per agent matching your query. Find YOUR delegation's entry (match on `role`; absent means the default role) and inspect:
-
-- `child.status` — an AcpRunStatus value: one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`). Note `'permission-required'` and `'input-required'` are DIFFERENT states handled by different cases below — do not conflate them.
-- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`; contains the verbatim question the child agent has asked the parent.
-- `child.lastOutputLines` — recent log tail (use for status narration; do not treat as an API surface).
-- `child.repoFullName` — human-facing identifier for which repo is talking.
-
-State machine:
-
-1. `child.status === 'created'` or `'in-progress'` — child is still executing. Call `show_agent` (with `waitForTransitionMs: 50000`) again.
-2. `child.status === 'input-required'` — child is paused waiting for parent input:
-   - Read `child.inputRequiredQuestion`.
-   - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
-   - Wait for the parent/user to supply an answer.
-   - Call `spawn_agent` again with the same `repo`, the same `role`, and `instruction: <the answer>` — the orchestrator routes it to that (repo, role)'s active task automatically.
-   - Resume polling.
-
-<!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
-     rendered by polygraph-mcp's show_agent handler. The dialog targets the parent's main
-     thread, NOT this subagent. From this subagent's perspective the gate is transient: a
-     waited show_agent call returns immediately while the gate is open, but the parent's pick
-     resolves it and a later poll sees the child back in progress. Do nothing here. -->
-3. `child.status === 'permission-required'` — the child opened a permission gate. **This is NOT `input-required`. Do not treat it like case 2.** The parent's native MCP elicitation dialog already renders the prompt in the parent's own UI and routes the decision back to the child through `polygraph-mcp`. Your only job is to stay out of the way and keep polling:
-
-   - **Do NOT return, finish, summarize, relay, or surface this to the parent.** Do NOT describe the child as "needing input", "awaiting approval", "asking for permission", or anything that would make the parent prompt the user — the parent already has its own dialog. Returning here is the bug this case exists to prevent.
-   - **Do NOT read `child.pendingPermission` as a question to answer or forward.** It is for inspection/logging only; it is not your input prompt.
-   - **Do NOT call any tool** (`spawn_agent`, `stop_agent`, `allow_agent`, `deny_agent`) to resolve it.
-   - Treat `permission-required` **like `in-progress`**: just call `show_agent` (with `waitForTransitionMs`) again — the parent's dialog resolves it. Only at a terminal state do you return, per the cases below.
-
-4. `child.status === 'completed'` — child finished successfully. Read `child.lastOutputLines` for the most recent log tail and report outcome.
-5. `child.status === 'failed'` — child failed. Read `child.lastOutputLines` for failure context and report the error.
-6. `child.status === 'cancelled'` — child was stopped via `stop_agent`. Its session is preserved for later context restoration. Do not restart or continue work from that preserved session unless the user explicitly asks for changes.
-
-## Cancelling a running child
-
-To cancel a running child mid-work, call `stop_agent` with the repo (and `role`, per the parameter rule above). Response:
-
-```json
-{
-  "taskId": "…",
-  "state": "cancelled",
-  "sessionPreserved": true,
-  "output": "…",
-  "message": "…"
-}
 ```
+Child agent <id> is done.
 
-Because `sessionPreserved: true`, the session can be restored later for context. After resuming, do not call `spawn_agent` to continue prior work or make changes until the user explicitly asks for changes.
-
-## Returning the summary
-
-When the child agent reaches a terminal status, return a structured summary:
+**Repo:** <repoFullName>
+**Delegation id:** <id>
+**Status:** <status>
 
+Read the result with show_agent (id: "<id>").
 ```
-## Polygraph Delegation Result
-
-**Repo:** <repo>
-**Role:** <role, or "default" when none was given>
-**Status:** <success | failed | cancelled>
-**Session ID:** <sessionId>
-
-### Result
-<result text drawn from child.lastOutputLines>
-```
-
-## Timeout
-
-If polling exceeds **30 minutes**, return with a timeout status:
-
-```
-## Polygraph Delegation Result
-
-**Repo:** <repo>
-**Status:** timeout
-**Session ID:** <sessionId>
-**Elapsed:** <minutes>m
-
-### Suggestions
-- Check child agent status manually via `show_agent`
-- Consider stopping the child agent via `stop_agent`
-```
-
-## Important Notes
 
-- You run in the background — write clear status lines so the main agent can parse your output file
+For `input-required` or `permission-required`, replace "is done." with "needs attention." and keep everything else identical.
 
-- Do NOT make decisions about the work — only delegate and monitor
-- Do NOT call `push_branch` or `create_pr` — those are the main agent's responsibility
-- If `spawn_agent` fails, return the error immediately
-- If `show_agent` returns an error, wait and retry (count as failed poll)
-- After 5 consecutive poll failures, return with `status: error`
+Do not summarize, quote, or describe the child's work. Do not include log lines. The main agent reads the result itself via `show_agent`.

package/hooks/agent-session-finalize.mjs

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
+}
+
+export function buildFinalizeAgentSessionArgs({
+  agentType,
+  agentSessionId,
+  cwd,
+  transcriptPath,
+  source,
+}) {
+  const harnessSession = nonEmptyString(agentSessionId);
+  const hookSource = nonEmptyString(source);
+  if (agentType !== 'claude') throw new Error(`Unsupported agent type: ${agentType}`);
+  if (!harnessSession) throw new Error('agentSessionId is required');
+  if (!hookSource) throw new Error('source is required');
+
+  const args = [
+    '_finalize-agent-session',
+    '--agent-type',
+    agentType,
+    '--agent-session-id',
+    harnessSession,
+  ];
+
+  const workingDirectory = nonEmptyString(cwd);
+  if (workingDirectory) args.push('--cwd', workingDirectory);
+
+  const transcript = nonEmptyString(transcriptPath);
+  if (transcript) args.push('--transcript-path', transcript);
+
+  args.push('--source', hookSource);
+  return args;
+}
+
+export function finalizeAgentSession(claim, spawn = spawnSync, env = process.env) {
+  if (isManagedChildEnvironment(env)) return false;
+
+  const command = nonEmptyString(env?.POLYGRAPH_CLI) ?? 'polygraph';
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+
+  const result = spawn(command, buildFinalizeAgentSessionArgs(claim), {
+    encoding: 'utf8',
+    env: commandEnv,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+
+  if (result?.error) throw result.error;
+  if (result?.status !== 0) {
+    const detail = nonEmptyString(result?.stderr);
+    throw new Error(
+      `polygraph _finalize-agent-session exited with status ${String(result?.status)}` +
+        (detail ? `: ${detail}` : '')
+    );
+  }
+
+  return true;
+}
+
+export function buildCommandHookFinalize(payload, agentType, env = process.env) {
+  if (!payload || typeof payload !== 'object') return undefined;
+  if (isManagedChildEnvironment(env)) return undefined;
+  if (agentType !== 'claude' || payload.hook_event_name !== 'SessionEnd') {
+    return undefined;
+  }
+
+  const agentSessionId = nonEmptyString(payload.session_id);
+  if (!agentSessionId) return undefined;
+
+  return {
+    agentType,
+    agentSessionId,
+    cwd: nonEmptyString(payload.cwd),
+    transcriptPath: nonEmptyString(payload.transcript_path),
+    source: 'hook',
+  };
+}

package/hooks/agent-session-link.mjs

@@ -102,7 +102,12 @@ export function buildCommandHookLink(payload, agentType, env = process.env) {
 
   if (payload.hook_event_name === 'SessionStart') {
     const polygraphSessionId = nonEmptyString(env.POLYGRAPH_SESSION_ID);
-    return polygraphSessionId ? { ...common, polygraphSessionId } : undefined;
+    if (polygraphSessionId) return { ...common, polygraphSessionId };
+
+    // Ordinary sessions of every supported harness are eligible for
+    // speculative capture, so later session searches can find them even when
+    // the session was not launched with Polygraph session evidence.
+    return AGENT_TYPES.has(agentType) ? common : undefined;
   }
 
   if (payload.hook_event_name === 'PostToolUse') {

package/hooks/finalize-agent-session.mjs

@@ -0,0 +1,56 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookFinalize,
+  finalizeAgentSession,
+} from './agent-session-finalize.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  env = process.env,
+  spawn,
+} = {}) {
+  try {
+    const finalize = buildCommandHookFinalize(payload, agentType, env);
+    if (!finalize) return false;
+    return finalizeAgentSession(
+      {
+        ...finalize,
+        cwd: finalize.cwd ?? process.cwd(),
+      },
+      spawn,
+      env
+    );
+  } catch (error) {
+    logHookFailure(`${agentType || 'unknown'}:finalize-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: payload?.session_id,
+    });
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/hooks/hooks.json

@@ -33,7 +33,18 @@
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude"
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/finalize-agent-session.mjs claude"
           }
         ]
       }

package/hooks/record-session-mapping.mjs

@@ -27,15 +27,18 @@ export function main({
     const link = buildCommandHookLink(payload, agentType, env);
     if (!link) return false;
 
-    return linkAgentSession(
-      {
-        ...link,
-        pid,
-        cwd: link.cwd ?? process.cwd(),
-      },
-      spawn,
-      env
-    );
+    const claim = {
+      ...link,
+      cwd: link.cwd ?? process.cwd(),
+    };
+    // Claude lifecycle hooks deliberately forward only the exact harness
+    // identity, transcript, cwd, and hook source. PID is not identity and can
+    // be stale by the time an asynchronous SessionStart hook runs.
+    if (!(agentType === 'claude' && payload?.hook_event_name === 'SessionStart')) {
+      claim.pid = pid;
+    }
+
+    return linkAgentSession(claim, spawn, env);
   } catch (error) {
     logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
       hookEventName: payload?.hook_event_name,

package/package.json

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

package/skills/await-polygraph-ci/SKILL.md

@@ -166,15 +166,15 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
 
    Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
 
-3. **Monitor investigation progress** — poll `show_agent` to wait for each child agent to complete:
+3. **Monitor investigation progress** — launch one background `polygraph-delegate-subagent` per delegation id and let it do the waiting. When it exits, read that investigation with a single unwaited `show_agent`:
 
    ```
-   show_agent(sessionId: "<session-id>", repo: "frontend")
+   show_agent(sessionId: "<session-id>", id: "<delegation-id>")
    ```
 
-   Poll until the child agent's status indicates completion (pass the same `role` you spawned with, if any). Use the `tail` parameter to retrieve recent output lines containing the investigation results.
+   `result.text` is the child's investigation summary. Never run a waited `show_agent` loop here, and do not pass `tail` unless `result.text` alone is insufficient.
 
-4. Collect each child agent's response from the status output. If a child agent fails or gets stuck, use `stop_agent` to terminate it and skip that repo.
+4. Collect each child agent's response from its unwaited `show_agent` read. If a child agent fails or gets stuck, use `stop_agent` with its delegation id to terminate it and skip that repo.
 
 5. Display failure summary for each repo:
 
@@ -211,5 +211,5 @@ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show
 - All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
 
 - Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`pr.ci.cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via the Nx MCP `ci_information` tool. Job IDs come from `pr.ci.externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
-- `spawn_agent` is **non-blocking** — it starts the child agent and returns immediately. Use `show_agent` to poll for results and `stop_agent` to terminate stuck agents.
+- `spawn_agent` is **non-blocking** — it starts the child agent and returns a delegation id immediately. Waiting on that id belongs in a background poller subagent; an unwaited `show_agent` by id returns the result, and `stop_agent` by id terminates a stuck agent.
 - The `show_session` response is compact and safe to poll from the main agent.

package/skills/polygraph/SKILL.md

@@ -9,11 +9,11 @@ allowed-tools:
 
 # Working with Polygraph
 
-**IMPORTANT:** Polygraph keeps local clones only for *other* repositories in the session. NEVER `cd` into those clones or access their files directly — work in other repositories ALWAYS happens through the Polygraph MCP `spawn_agent` tool, invoked via background `polygraph-delegate-subagent` Tasks.
+**IMPORTANT:** Polygraph keeps local clones only for *other* repositories in the session. NEVER `cd` into those clones or access their files directly — work in other repositories ALWAYS happens through the Polygraph MCP `spawn_agent` tool. Before delegating anything, read [`reference/delegation.md`](reference/delegation.md).
 
 Polygraph connects repos and the agent work happening across them. Its central artifact is the session, which groups the repos, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repos or in a single repoto share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
 
-**Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repos are worked on in separate Polygraph-managed clones via `spawn_agent`.
+**Polygraph operates on the current repo in place.** Starting a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repos are worked on in separate Polygraph-managed clones via `spawn_agent`. Resuming is the one qualified case: a `resume_session` with the explicit `reset` consent force-switches branches inside the session's materialized repositories, and can force-move the current working tree when it is itself one of them. Repositories outside the session folder are never modified. Full contract under "Explore an Existing Session".
 
 ## Sandboxing in Polygraph Sessions
 
@@ -29,9 +29,10 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | --- | --- | --- |
 | `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
-| `spawn_agent` | — | Start a child task, or send a follow-up to an active task, in another repository. A repeat call for the same (repo, role) is delivered to that task as a follow-up; otherwise a new child starts. Roles and resume behavior are under "Multi-turn tasks". |
-| `show_agent` | — | Poll one repo's child status (one repo per call; `role` narrows to that agent). Status enum and the poll/state-machine flow are under "Multi-turn tasks". |
-| `stop_agent` | — | Cancel an in-progress child; its session is preserved for later read-only context restoration. |
+| `resume_session` | `polygraph session resume --session <id> --json` | Join an existing session from this conversation: a tracked adoption that performs the full reconstruct. On divergence it stays local by default; `reset` is an explicit, destructive opt-in. Divergence and post-join behavior are under "Explore an Existing Session". |
+| `spawn_agent` | — | Start a child task, or send a follow-up to an active task, in another repository; returns a delegation id. A repeat call for the same (repo, role) is delivered to that task as a follow-up; otherwise a new child starts. See `reference/delegation.md`. |
+| `show_agent` | — | Poll by repo or delegation id; unwaited reads return the child's result. Waited calls are for the poller subagent, not the main conversation. See `reference/delegation.md`. |
+| `stop_agent` | — | Cancel an in-progress child by delegation id; its session is preserved for later read-only context restoration. |
 | `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. |
 | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
 | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. |
@@ -51,7 +52,7 @@ 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` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`) as described in the delegation sections below — NEVER call them directly in the main conversation. The subagents are plugin-namespaced: pass `subagent_type: "polygraph:polygraph-init-subagent"` / `"polygraph:polygraph-delegate-subagent"`; fall back to the bare name only if the namespaced form is not found.
+**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 (`run_in_background: true`), 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 subagents are plugin-namespaced: pass `subagent_type: "polygraph:polygraph-init-subagent"` / `"polygraph:polygraph-delegate-subagent"`; fall back to the bare name only if the namespaced form is not found.
 
 ## CLI Statefulness
 
@@ -80,10 +81,10 @@ 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.
 
 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** - Use the `polygraph-delegate-subagent` to start child agents. 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). Parallel delegation across repos is encouraged. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
+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** - Use `show_agent` to poll one repo's children (`repo` is required; pass `role` to narrow to one agent) and read each entry's `status` and `lastOutputLines` from the `children[]` array.
-5. **Stop child agents** (if needed) - Use `stop_agent` (with `role` when targeting a non-default agent) 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.
+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.
 6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
 7. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
 8. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
@@ -99,6 +100,8 @@ There are three cases. Pick exactly one before calling any tool. The case labels
 
 **Hard rule: if a session ID is already in scope (e.g., the startup banner says "You're in Polygraph session …", or the user passed one or you are provided one by a reminder hook), that session ID is authoritative for this entire conversation. NEVER call `start_session` — doing so creates a brand-new session and orphans the one the parent harness is pointed at. Reuse the existing session via `show_session` and, if needed, `add_repo`.**
 
+**Hard rule: before doing ad-hoc work in another repository, or reading a session's context untracked, ask whether an existing session already covers this work. If one might and its session ID is not in scope, ask the user for it — never fall back to an ad-hoc clone. To WORK in a session's context, join it via `resume_session` — a tracked adoption. To only read or summarize, `show_session` remains the read path.**
+
 **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely, show the session details (format below), and proceed.
 
 **Case B — Existing session, no repos yet (or user wants to add more).** If the user gives exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, call `add_repo(sessionId, repoIds: [...])` directly with those refs. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT launch the init subagent just to resolve those refs. If the user wants discovery/filtering instead, launch the `polygraph-init-subagent`, passing both the existing `sessionId` and `userContext`. The subagent will discover candidates, select relevant repositories, and call `add_repo` against the existing session — it will NOT call `start_session`.
@@ -139,11 +142,11 @@ The subagent will:
 
 Use this workflow when the user gives a Polygraph session ID and asks to understand, resume, inspect, or investigate prior work.
 
-**Resume is not a work command.** If the user's intent is to resume, reconnect, or reconstruct a prior Polygraph session, fetch and summarize the restored context, then stop. Do not edit files, push branches, add repos, delegate new work, or continue previous changes until the user explicitly asks for changes. Treat "resume" as context restoration followed by waiting for user instructions.
+**Resume is not a work command.** If the user's intent is to resume, reconnect, or reconstruct a prior Polygraph session, join it via `resume_session`, summarize the restored context it returns, then stop. Do not edit files, push branches, add repos, delegate new work, or continue previous changes until the user explicitly asks for changes. Recording the join in the session's history is not making changes to the work. Treat "resume" as context restoration followed by waiting for user instructions.
 
-1. Fetch detailed session context:
-   - Prefer `show_session` with `details: true` 
-   - Otherwise run `polygraph session show --details <session-id>`.
+1. Fetch session context by intent:
+   - To continue work in the session from this conversation, join it via `resume_session` (CLI: `polygraph session resume --session <id> --json`) — a tracked adoption that performs the full reconstruct; the restored session context comes back in the tool result. On a divergent session the join stays on the local conversation by default and returns the divergence evidence; adopting the selected path requires the explicit `reset` consent, a destructive opt-in that force-switches branches in the session's materialized repositories (discarding uncommitted tracked changes there, untracked files survive) and deletes this machine's local session logs.
+   - To only read, inspect, or summarize without joining, prefer `show_session` with `details: true`; otherwise run `polygraph session show --details <session-id>`. This is the read-only path and records nothing.
 2. Treat the detailed output as authoritative context. It should include:
    - `<summary>` — the session summary.
    - `<repositories>` — relevant repos, including each repo's `<id>` and `<name>`.
@@ -185,71 +188,9 @@ Inspect the PR commits/diff and investigate the requested behavior. Report findi
 Use this workflow when the user asks which Polygraph session produced, is behind, or changed a particular commit — or a particular line of code. 
 **Read [`reference/session-by-commit.md`](reference/session-by-commit.md) before running any lookup.** That reference file holds clear, reliable steps for answering questions related to this.
 
-## Agent roles
-
-A repository in a session can host multiple child agents at once, distinguished by **role**:
-
-- **Omit by default.** Set a `role` only when the user very explicitly asked for a named one, or when a skill the user invoked prescribes one (e.g. `adversarial-review` uses `reviewer`). Never pick one yourself.
-- **Purpose.** Roles let independent streams of work run concurrently in one repo — e.g. a default agent implementing a feature while a `reviewer` or `ci-investigator` runs alongside. Each (repo, role) pair has at most one active child.
-- **Default role.** An omitted `role` means the default role: `spawn_agent` without `role` starts or follows up with the repo's default-role agent.
-- **Logs.** Only default-role agents upload logs to the cloud and appear in the multiplexed log stream (`polygraph session logs`). Inspect non-default agents locally with `polygraph agent attach --role <role>`.
-
-## Simple tasks (fire-and-forget)
-
-Use this pattern when the task is well-defined and the child is not expected to need clarification. It is a single-round delegation: kick it off, poll until terminal, then push branch + create PR.
-
-Delegate through a background `Task` subagent rather than calling `spawn_agent`/`show_agent` in the main conversation — direct calls flood the context with polling noise. This is a hard requirement, not a suggestion.
-
-1. Launch one background `Task` per repo with `subagent_type: "polygraph:polygraph-delegate-subagent"` and `run_in_background: true`, passing `sessionId`, `repo`, `instruction`, and optional `role`/`context`. The subagent calls `spawn_agent`, then polls `show_agent` via chained `waitForTransitionMs` long-poll calls until terminal.
-2. Delegate to several repos in parallel by launching multiple background Tasks at once — one delegation per (repo, role). Read their output files later for progress.
-3. Each subagent watches `child.status` on its `children[]` entry (matching its repo and role) and exits at a terminal status — `'completed'`, `'failed'`, or `'cancelled'`.
-4. Once all report terminal, continue to `push_branch` + `create_pr`.
-
-To debug a stuck subagent you can call `show_agent` as a one-off, but routine polling belongs in the background subagents.
-
-Use Simple when the task is well-defined and the child will not need clarification.
-
-## Multi-turn tasks (interactive)
-
-Use this pattern when the child may need clarification, the task is exploratory, or interactive collaboration is desired. The orchestrator exposes paused children via the `'input-required'` status.
-
-1. Call `spawn_agent` with the initial `instruction` (and optionally `role`). Parse the response:
-
-   ```json
-   { "taskId": "…", "message": "…", "status": "delegated" }
-   ```
-
-2. Poll `show_agent` via chained `waitForTransitionMs` long-poll calls (`repo` is required; pass the same `role` you spawned with to narrow to that agent). The response shape is `{ children: PolygraphChildStatusItem[] }` with one entry per matching agent in that repo. On your delegation's entry, inspect:
-
-   - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
-   - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
-   - `child.lastOutputLines` — recent log tail.
-   - `child.repoFullName` — which repo is talking.
-
-   Drive the state machine:
-
-   - `child.status === 'in-progress'` or `'created'` — continue polling.
-   - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with the same `repo`, the same `role`, and `instruction: <answer>` — it is routed to that (repo, role)'s active task automatically. Continue polling.
-   - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`.
-   - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure.
-   - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below.
-   - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below.
-
-3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo, role? }`. The response is:
-
-   ```json
-   {
-     "taskId": "…",
-     "state": "cancelled",
-     "sessionPreserved": true,
-     "output": "…",
-     "message": "…"
-   }
-   ```
-
-   Because `sessionPreserved: true`, the stopped agent's session can be restored later for context. After resuming, do not make changes or continue prior work until the user explicitly asks for changes.
+## Delegating to other repos
 
-Use Multi-turn when the child may need clarification, the task is exploratory, or interactive collaboration is desired. Otherwise use Simple.
+Working across more than one repo, or delegating any task? Read [`reference/delegation.md`](reference/delegation.md) first — required. Delegation is the only way to act on other repos, and the reference holds the contract that keeps it cheap and trackable: skipping it leads to re-pasting briefs, polling in the main conversation, and touching other repos' clones directly — each of which burns tokens or breaks session tracking.
 
 <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
      rendered by polygraph-mcp's show_agent handler. The dialog targets the parent harness's
@@ -351,13 +292,14 @@ If the session has a description timeline, also display:
 
 ## Best Practices
 
-1. **Delegate via background subagents** — run every `spawn_agent`/`show_agent` through `Task(run_in_background: true)`; direct calls flood the context with polling noise.
+1. **Wait in background subagents** — `spawn_agent` is fine to call directly, but every waited `show_agent` poll belongs in a `Task(run_in_background: true)`; inline polling floods the context with status noise.
    
-1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) via `show_agent` before pushing branches or creating PRs
+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
 1. **Link PRs in descriptions** - Reference related PRs in each PR body
 1. **Keep PRs as drafts** until all repos are ready
 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy
 1. **Test integration** before marking PRs ready
 1. **Coordinate merge order** if there are deployment dependencies
    
-1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed (pass `role` to target a non-default agent). 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.
+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

@@ -0,0 +1,105 @@
+# Delegation Reference
+
+Delegation is the only way to act on a repository other than the one you are in. Polygraph keeps local clones of the other repos in the session, but they are not yours to touch: never `cd` into them, read their files, or run git in them. Everything happens through `spawn_agent` and `show_agent`.
+
+The flow is **pointer-based**. `spawn_agent` hands you a delegation id. A cheap background subagent watches that id and tells you when it stops moving. You then read the answer yourself, once. Nothing re-pastes the brief, and no log lines pass through a middleman.
+
+## The delegation id
+
+`spawn_agent` returns a short id (e.g. `frontend-1`) that names one child run. It is the handle for everything afterwards — polling, reading the result, following up, stopping. The id pins the repo AND the role, so once you have it you never re-specify either.
+
+Keep every id you are given. Losing one means falling back to `repo` + `role` lookups, which are ambiguous the moment a repo hosts more than one agent.
+
+## Spawning
+
+Call `spawn_agent` directly from the main conversation. This is a fast, non-blocking call that returns an id — it is not polling and does not belong in a subagent.
+
+```
+spawn_agent(
+  sessionId: "<sessionId>",
+  repo: "<org/repo-name>",
+  instruction: "<the task instruction>",
+  role: "<optional role>",
+  context: "<optional context>"
+)
+```
+
+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.
+
+**Own-repo rule.** With the default role, `repo` must be a repository other than the one you are working in — never delegate into your own repo with the default role; work on it directly (ordinary local subagents are fine for that). Delegating into your own repo IS allowed with an explicit non-default `role`, because each (repo, role) pair is a separate agent slot and the child then runs alongside your own default-role work without colliding with it.
+
+## Waiting
+
+For each id, launch one background poller subagent whose entire job is to block until that child stops moving. Give it the `sessionId` and the `id`, and nothing else.
+
+- **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`.
+
+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.
+
+**Routine polling never happens in the main conversation.** A waited `show_agent` loop run inline floods your context with status noise and is the single largest avoidable cost in a multi-repo session. That is what the poller exists to absorb.
+
+## Reading the result
+
+When a poller exits, read the child's answer yourself with a single **unwaited** `show_agent` — no `waitForTransitionMs`, no `tail`:
+
+```
+show_agent(sessionId: "<sessionId>", id: "<id>")
+```
+
+`result.text` is the child's final message: what it did, what it found, what it wants you to know. This is the payload. Read it once, in the main conversation, and act on it.
+
+One-off unwaited reads like this are cheap and expected inline. It is the *waiting* that belongs in a subagent, not the reading.
+
+## When the result is not enough
+
+Only if `result.text` is missing, truncated, or the child failed in a way you cannot explain from it:
+
+- Pass an explicit `tail` to `show_agent` to pull recent log lines.
+- Page further back with the `page` param: `tail: 5, page: 2` returns the 5 lines before the newest 5, `page: 3` the window before that.
+- If the user wants to watch the run live, point them at `polygraph agent attach <repo>` (plus `--role <role>` for a non-default agent) — an interactive terminal view for humans, not a command for you to run.
+
+These are deliberate, targeted follow-ups. None of them belongs in a polling loop, and none of them is a reason to go looking at transcript files, `~/.polygraph/sessions`, or anything a harness saved to disk because a tool result was too large. `show_agent` is the supported interface.
+
+## Follow-ups
+
+To send a child more work, call `spawn_agent` again with the SAME `repo` and the SAME `role`. If that (repo, role) still has a live task — working, or paused waiting on you — the orchestrator delivers your instruction to it as a follow-up instead of starting a second run. A (repo, role) pair therefore has at most one active child at a time.
+
+A follow-up returns a **new** delegation id, linked to the previous one by a `continues` reference. The new id is the live handle: poll it, read it, follow up on it. The old id still addresses the earlier turn if you need to look back at it.
+
+After a follow-up, launch a fresh poller subagent for the new id. The old poller has already exited; it does not resume.
+
+## Input-required
+
+When a child needs an answer from you, it stops and the poller exits with status `input-required` and "needs attention."
+
+Read the child with an unwaited `show_agent` as usual. `inputRequiredQuestion` carries the child's verbatim question. Surface it to the user as the child asked it — do not paraphrase or answer on the user's behalf — then send the answer back as an ordinary follow-up `spawn_agent` for the same (repo, role). Poll the new id it returns.
+
+`permission-required` is a different state and is not yours to resolve here; see "Handling permission requests" in the skill.
+
+## Roles
+
+A repository in a session can host several child agents at once, distinguished by **role**:
+
+- **Omit by default.** Set a `role` only when the user very explicitly asked for a named one, or when a skill the user invoked prescribes one (e.g. `adversarial-review` uses `reviewer`). Never invent one.
+- **Purpose.** Roles let independent streams of work run concurrently in one repo — a default agent implementing a feature while a `reviewer` or `ci-investigator` runs alongside. Each (repo, role) pair has at most one active child.
+- **Default role.** An omitted `role` means the default role: `spawn_agent` without `role` starts or follows up with that repo's default-role agent.
+- **Ids pin the role.** A delegation id already identifies one (repo, role) pair, so `show_agent` and `stop_agent` by id need no `role` argument. Pass `role` only when addressing an agent by `repo` instead of by id.
+- **Logs.** Only default-role agents upload logs to the cloud and appear in the multiplexed stream (`polygraph session logs`). A non-default agent's transcript stays on this machine — the user can watch it with `polygraph agent attach <repo> --role <role>`.
+
+## Stopping
+
+Cancel a running child by id:
+
+```
+stop_agent(sessionId: "<sessionId>", id: "<id>")
+```
+
+The response reports `sessionPreserved: true`: the stopped agent's session is kept so its context can be restored later. Restoring is read-only. After a resume, do not continue the prior work or make further changes until the user explicitly asks for them.
+
+## Before publishing
+
+Every delegation must reach a terminal status — `completed`, `failed`, or `cancelled` — before you push branches or open PRs. A poller exiting on `input-required` is not terminal; it means the child is still waiting on you.

package/skills/session-start/SKILL.md

@@ -32,7 +32,7 @@ For a fresh Codex Desktop conversation started with `/polygraph:session-start`,
 
 Pick one path before using tools.
 
-1. **Existing session with repos** - If a Polygraph session ID is already in scope and the user did not ask to add repositories, call `show_session` to inspect it and print the session details. Do not create a new session.
+1. **Existing session with repos** - If a Polygraph session ID is already in scope and the user did not ask to add repositories, pick by intent: to continue the session's work from this conversation, join it via `resume_session`; to only inspect it, call `show_session` and print the session details. Do not create a new session.
 2. **Existing session, adding exact repository refs** - If a session ID is in scope and the user provided exact refs by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo(sessionId, repoIds: [...])` directly. Do not run discovery.
 3. **Existing session, discovery needed** - If a session ID is in scope but repos need to be discovered or selected, launch `polygraph-init-subagent` with the existing `sessionId` and `userContext`. The subagent must use `add_repo`, not `start_session`.
 4. **No session in scope** - Launch `polygraph-init-subagent` with `userContext` and no `sessionId`. The subagent will discover related repositories when needed and call `start_session`.