@polygraph/claude-plugin 0.4.43 → 0.4.45

package/.claude-plugin/plugin.json

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

package/agents/polygraph-delegate-subagent.md

@@ -26,12 +26,12 @@ The main agent provides these parameters in the prompt:
 | `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. Pass the SAME role on every `spawn_agent`/`show_agent`/`stop_agent` call for this delegation. |
+| `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                     |
 
 ## Delegating work
 
-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, though agents with different roles can run in the same repo concurrently.
+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.
 
 `repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo.
 

package/hooks/hooks.json

@@ -24,15 +24,6 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/record-session-mapping.mjs claude"
           }
         ]
-      },
-      {
-        "matcher": "startup|resume",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/check-plugin-version.mjs claude"
-          }
-        ]
       }
     ]
   }

package/package.json

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

package/skills/polygraph/SKILL.md

@@ -17,25 +17,9 @@ Polygraph connects repositories and the agent work happening across them. Its ce
 
 ## Sandboxing in Polygraph Sessions
 
-Polygraph launches agent sessions inside an OS-level sandbox by default. Writes are limited to the repository working tree, the session root (`~/.polygraph/sessions/<session-id>/`), the system temp directory, and a few allowlisted directories; network access is restricted to allowlisted hosts. In practice: binding a listening socket is denied (dev servers fail with `EPERM`), localhost servers are unreachable, and writes outside the allowlist are rejected. The user may not know the session is sandboxed.
+Polygraph **may** run an agent session inside an OS-level sandbox, but not every session is sandboxed — whether it is on depends on the user's config. When it is on, writes are limited to the repository working tree and session root, network access is restricted to allowlisted hosts, and binding a listening socket (dev servers) fails with `EPERM`. The user may not know whether this session is sandboxed.
 
-**Recognize sandbox denials — do not retry or work around them.** When a command fails in a sandbox-shaped way (`EPERM` binding a port, a blocked network host, a denied write to an ordinary path), the sandbox blocked it. Do NOT retry variations, escalate through workarounds, or route the command through `!`-prefixed user commands — those run inside the same sandbox. One failure is enough evidence; stop and inform the user.
-
-**Warn before attempting known-blocked operations.** Before starting a dev server, anything else that listens on a port, or an operation that needs writes or network access outside the allowlist, tell the user up front that it will not work while sandboxing is on and offer the options below instead of attempting it.
-
-**What to tell the user.** Explain that Polygraph runs this session in a sandbox, then present both options. Each takes effect on the next agent launch, so the Polygraph session must be relaunched afterwards:
-
-1. **Keep the sandbox on and allow the specific operation** (preferred). The sandbox belongs to the agent harness, so exceptions live in harness settings committed to the repository; array settings merge with Polygraph's generated allowlist rather than replacing it. Add writable paths to `.claude/settings.json` (or `.claude/settings.local.json`):
-
-   ```json
-   { "sandbox": { "filesystem": { "allowWrite": ["<path>"] } } }
-   ```
-
-   The `.claude/` directory is read-only inside the sandbox, so give the user the exact snippet to commit — you cannot apply it yourself.
-
-2. **Turn sandboxing off.** The user quits the agent, runs `polygraph config`, toggles **Agent Options → Claude → sandbox** off (or per-repo under **Repo Options**), and relaunches the Polygraph session. Non-interactive alternative: set `agentOptions.claude.sandbox: false` (or `repoOptions."org/repo".sandbox: false`) in `~/.polygraph/config.json`. Warn that this removes filesystem isolation — the agent can then write anywhere the OS user can.
-
-**Never blame the tooling.** A sandbox denial means the environment blocked the operation — not that the repo, tool, or framework is broken. Do not record conclusions like "X is unusable" in memory, session descriptions, or messages based on sandboxed failures.
+**When something fails in a sandbox-shaped way** — `EPERM` binding a port, a blocked network host, a denied write to an ordinary path — the sandbox blocked it. Do NOT retry variations, work around it, or route the command through `!`-prefixed user commands (those run in the same sandbox); one failure is enough evidence. Stop, and read [`reference/sandboxing.md`](reference/sandboxing.md) for how to warn the user, the two remediation options (allow the specific operation via committed harness settings, or turn sandboxing off), and the exact per-harness config snippets. Never conclude the repo, tool, or framework is broken based on a sandboxed failure.
 
 ## Available Tools
 
@@ -45,29 +29,29 @@ 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 new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, role?, context? }`. Output: `{ taskId, message, status: 'delegated' }`. `role` selects the agent slot within the repo (see "Agent roles"). Follow-up routing is automatic per (repo, role): if that (repo, role) already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. |
-| `show_agent` | — | Poll one repo's child status (`repo` required — one repo per call; pass `role` to narrow to that role's agent). Returns `{ children: [...] }` with one self-describing entry per matching agent, exposing `status`, `lastOutputLines`, `role` (absent for the default role), `inputRequiredQuestion`, etc. Full status enum and the poll/state-machine flow are under "Multi-turn tasks". |
-| `stop_agent` | — | Cancel an in-progress child. Input: `{ sessionId, repo, role? }`. Output: `{ taskId, state: 'cancelled', sessionPreserved: true, output, message }`. Because `sessionPreserved: true`, the preserved agent session can be restored later for context, but resume must wait for explicit user instructions before making changes. |
+| `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. |
 | `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. |
-| `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required). Set the description from a synthesized progress summary or user-provided text. This updates session metadata only; it does not require PR creation or mark-ready. |
+| `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required); metadata only, independent of PR creation or mark-ready. |
 | `link_reference` | — | Link an external reference to a session. |
 | `mark_pr_ready` | — | Mark draft PRs as ready for review |
 | `associate_pr` | — | Associate an existing PR with a session |
-| `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
+| `add_repo` | — | Add repositories to a running session (pass exact refs directly, skipping `list_repos`). See "Add Repositories to a Session". |
 | `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
 | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
-| `git_fetch` | `polygraph git fetch` | Fetch additional git history for a shallow session clone. Use when git operations fail with "bad object" or missing-commit errors; by default fetches the full history of the default branch. Input: `{ sessionId, repo, depth?, refs? }`. See "Fetching Git History for Shallow Clones". |
+| `git_fetch` | `polygraph git fetch` | Fetch git history for a shallow session clone when git fails with "bad object" or missing-commit errors. See "Fetching Git History for Shallow Clones". |
 | `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
 | `logout` | `polygraph auth logout` | Log out of Polygraph |
 | `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
-| `search_sessions` | `polygraph session search` | Find sessions by free-text `query` OR by commit `sha` — pass EXACTLY ONE of the two (they are mutually exclusive). `sha` (CLI: `--sha <sha>`) is an exact lookup of the session(s) linked to a commit, full or partial, 7-40 hex chars; it returns matching sessions newest first, org-scoped, and explicit sessions only (implicit sessions are never returned). Supports `--json` and `--limit` (1-50). See "Finding the Session Behind a Commit or Line". |
+| `search_sessions` | `polygraph session search` | Find sessions by free-text `query` OR by commit `sha` — pass exactly one. See "Finding the Session Behind a Commit or Line". |
 | `list_accounts` | `polygraph account list` | List available organizations |
 | `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 step 0. 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` 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.
 
 ## CLI Statefulness
 
@@ -96,7 +80,7 @@ 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 with those refs 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 in other repositories. 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; a repo can also host multiple concurrent agents under distinct roles (see "Agent roles"). 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** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. 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.
    
 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.
@@ -110,7 +94,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
 
 ## Step-by-Step Guide
 
-### 0. Initialize or Join Polygraph Session
+### Initialize or Join Polygraph Session
 
 There are three cases. Pick exactly one before calling any tool. The case labels are internal routing shorthand — never mention them in anything you show the user.
 
@@ -131,23 +115,7 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
 - The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
 - For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
 
-**Launch the init subagent** (cases B and C — skip in case A):
-
-```
-Task(
-  subagent_type: "polygraph:polygraph-init-subagent",
-  description: "Init Polygraph session",
-  prompt: """
-    Parameters:
-    - sessionId: "<existing-session-id-or-omit-for-new-session>"
-    - userContext: "<description of what the user wants to do>"
-
-    If sessionId is provided, reuse that session and use add_repo to attach repositories — do NOT call start_session. If exact repo refs were provided, pass them directly to add_repo and do NOT call list_repos. If discovery is needed, discover candidates and select relevant repos. If sessionId is omitted, create a new session via start_session. Return a structured summary.
-  """
-)
-```
-
-Omit the `sessionId` line for case C. Include it (with the existing session ID) for case B.
+**Launch the init subagent** (cases B and C — skip in case A) as a `Task` with `subagent_type: "polygraph:polygraph-init-subagent"`. Pass `userContext` (what the user wants to do); for case B also pass the existing `sessionId`. Instruct it: with a `sessionId`, reuse that session and attach repos via `add_repo`, never `start_session`; if exact repo refs were given, pass them straight to `add_repo` without `list_repos`; if discovery is needed, discover and select candidates; with no `sessionId`, create the session via `start_session`. It returns a structured summary.
 
 The subagent will:
 
@@ -245,6 +213,7 @@ polygraph session search --sha a1b2c3d
 
 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>`.
@@ -253,33 +222,14 @@ A repository in a session can host multiple child agents at once, distinguished
 
 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.
 
-**CRITICAL:** `spawn_agent` and `show_agent` MUST ALWAYS be called via background Task subagents (`run_in_background: true`), NEVER directly from the main conversation. Direct calls flood the context window with polling noise and degrade the user experience. This is a hard requirement, not a suggestion.
-
-1. Launch a background `Task` subagent per repo using `polygraph-delegate-subagent`. The subagent calls `spawn_agent`, then polls `show_agent` via chained `waitForTransitionMs` long-poll calls until terminal.
+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.
 
-```
-Task(
-  subagent_type: "polygraph:polygraph-delegate-subagent",
-  run_in_background: true,
-  description: "Delegate to <repo-name>",
-  prompt: """
-    Parameters:
-    - sessionId: "<session-id>"
-    - repo: "<org/repo-name>"
-    - instruction: "<the task instruction>"
-    - role: "<optional role>"
-    - context: "<optional context>"
-
-    Delegate the work, poll for completion, and return a structured summary.
-  """
-)
-```
+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`.
 
-2. Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time — one delegation per (repo, role) at a time. Read the output files later to check progress.
-3. The subagent watches `child.status` on its delegation's `children[]` entry — the one matching its repo and role — and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
-4. Once all background subagents report a terminal status, continue to `push_branch` + `create_pr`.
-
-In rare cases where you need to check the raw child agent status directly (e.g., debugging a stuck subagent), you may call `show_agent` as a one-off tool call. Do NOT use this for regular polling — that MUST happen in background subagents.
+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.
 
@@ -340,7 +290,9 @@ If you call `allow_agent` while the dialog is already open, you create a race: t
 
 The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do NOT advertise elicitation capability (opencode TUI today). They are not part of your flow.
 
-### 2. Publish Changes (Push Branches, Create PRs, Mark Ready)
+## Publishing and Session Management
+
+### Publish Changes (Push Branches, Create PRs, Mark Ready)
 
 Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), and `associate_pr` (link PRs created outside Polygraph).
 
@@ -352,7 +304,7 @@ Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must
 
 **Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy: the canonical Markdown-heading template (`## Goal` / `## Current progress` / `## What worked` / `## Next steps`), the dual-audience guidance (humans in the web UI now, agents reconstructing history later), and the formatting building blocks the app renders (callouts, tables, mermaid, links, `link_reference`).
 
-### 3. Get Current Polygraph Session
+### Get Current Polygraph Session
 
 Check the details of a session using `show_session` or `polygraph session show --details <session-id>`. Returns the full session state — basic metadata like id, url & description timeline, plus the connected repositories, `pullRequests[]`, per-PR `ciStatus`, and `session.linkedReferences`.
 
@@ -410,7 +362,7 @@ link_reference({
 
 The canonical MCP parameters are `{ sessionId, reference }`. There is no unlink command.
 
-### 4. Add Repositories to a Session
+### Add Repositories to a Session
 
 Use `add_repo` to add repositories to an existing Polygraph session after it has already started.
 
@@ -430,27 +382,11 @@ add_repo(
 )
 ```
 
-### 5. Archive Session
+### Archive Session
 
 **IMPORTANT: Only call this tool when the user explicitly asks to archive or close the session.** Do not archive sessions automatically as part of the workflow.
 
-Use `archive_session` (CLI: `polygraph session archive <id>`) to archive the session. Archiving only hides the session from active lists — it can still be resumed and interacted with afterwards. It is idempotent — archiving an already-archived session returns success.
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `clean` (optional): Remove the local clones Polygraph created for delegated repos after archiving
-
-**Returns:**
-
-- `sessionId`: The session ID
-- `completed`: Boolean indicating the session is archived
-
-```
-archive_session(
-  sessionId: "<session-id>"
-)
-```
+Use `archive_session` (CLI: `polygraph session archive <id>`) to archive the session. Archiving only hides the session from active lists — it can still be resumed and interacted with afterwards. It is idempotent — archiving an already-archived session returns success. Pass the optional `clean` flag to also remove the local clones Polygraph created for delegated repos.
 
 **When to call:** all work is finished, PRs are created and marked ready, and the user explicitly confirms they are done with the session.
 
@@ -458,46 +394,13 @@ archive_session(
 
 ### Retrieving CI Job Logs
 
-Use `get_ci_logs` to retrieve the full plain-text log for a specific CI job. This is the drill-in tool for investigating CI failures after identifying a failed job from the session's CI status.
-
-**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via the Nx MCP `ci_information` tool — do NOT call `get_ci_logs`, and do NOT fetch or poll the `cipeUrl` over HTTP (it is a browser link for the user, not an API). This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
-
-**Parameters:**
-
-- `sessionId` (required): The Polygraph session ID
-- `repoId` (required): Repository ID (MongoDB ObjectId hex string, from the session repository entry)
-- `jobId` (required): GitHub Actions job ID (from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response)
+`get_ci_logs` retrieves the full plain-text log for a specific CI job — the drill-in tool for investigating a failed job. **ONLY use it when NO CIPE (CI Pipeline Execution) exists for the PR** (`ciStatus[prId].cipeUrl` is null); when a CIPE exists, use the Nx MCP `ci_information` tool instead, and do NOT fetch or poll the `cipeUrl` over HTTP.
 
-**Returns:**
-
-- On success: `{ success: true, jobId: number, logFile: string, sizeBytes: number }`
-- On failure: `{ success: false, error: string }`
-
-The tool saves the log to a local temp file and returns the path in `logFile`. Use the `Read` tool to examine the file contents. For large logs, use `offset` and `limit` parameters to read specific sections.
-
-```
-get_ci_logs(
-  sessionId: "<session-id>",
-  repoId: "<repo-id>",
-  jobId: 12345678
-)
-// Returns: { success: true, jobId: 12345678, logFile: "/tmp/ci-logs/job-12345678.log", sizeBytes: 152340 }
-// Then: Read(logFile) to examine the log
-```
-
-**Typical flow:**
-
-1. Use `show_session` to see PR CI status
-2. Check `ciStatus[prId].cipeUrl` — if a CIPE exists, use `ci_information` for logs and skip this tool
-3. If NO CIPE exists, check `ciStatus[prId].externalCIRuns` — examine runs and jobs directly from the session data
-4. For a failed job, call `get_ci_logs(sessionId, repoId, jobId)` to save the log to a file
-5. Use `Read(logFile)` to examine the log content — use `offset`/`limit` for large files
-
-**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.
+When you need to fetch and read a failed job's log, read [`reference/ci-job-logs.md`](reference/ci-job-logs.md) for the parameters, return shape, and the full flow (identify the job from `externalCIRuns`, call `get_ci_logs`, then `Read` the saved log file).
 
 ### Fetching Git History for Shallow Clones
 
-Session repos are shallow (`--depth 1`) clones and plain `git fetch --unshallow` fails on private repos (the clone-time credential is not retained). When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` (CLI: `polygraph git fetch <repo> --session <id> --json`), then retry. Defaults fetch the default branch's full history; pass `depth` for a bounded fetch or `refs` for extra branches. Safe to call redundantly (`alreadyComplete: true`).
+Session repos are shallow (`--depth 1`) clones. When git fails on missing history (`bad object` from `git revert`, `git log`, `git blame`, etc.), call `git_fetch({ sessionId, repo })` and retry. Read [`reference/shallow-clone-history.md`](reference/shallow-clone-history.md) for the CLI form, the `depth`/`refs` options, and the redundant-call behavior.
 
 ### Update Session Description
 
@@ -533,7 +436,7 @@ If the session has a description timeline, also display:
 
 ## Best Practices
 
-1. **MUST delegate via background subagents** — You MUST use `Task(run_in_background: true)` for every `spawn_agent` and `show_agent` call. NEVER call these directly in the main conversation — it floods the context window with polling noise.
+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. **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. **Link PRs in descriptions** - Reference related PRs in each PR body
@@ -542,8 +445,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 call `spawn_agent` or `show_agent` directly**. These MUST ALWAYS go through background Task subagents (`run_in_background: true`).
-   
 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. **Only archive sessions when asked** — Only call `archive_session` when the user explicitly requests it. Archiving hides the session from active lists; it can still be resumed later.
    

package/skills/polygraph/reference/ci-job-logs.md

@@ -0,0 +1,38 @@
+# Retrieving CI Job Logs
+
+Use `get_ci_logs` to retrieve the full plain-text log for a specific CI job. This is the drill-in tool for investigating CI failures after identifying a failed job from the session's CI status.
+
+**ONLY use this tool when NO CIPE (CI Pipeline Execution) exists for the PR.** When a CIPE exists (`ciStatus[prId].cipeUrl` is non-null), logs and failure data are available through the CIPE system (Nx Cloud) via the Nx MCP `ci_information` tool — do NOT call `get_ci_logs`, and do NOT fetch or poll the `cipeUrl` over HTTP (it is a browser link for the user, not an API). This tool is specifically for PRs where only external CI runs exist (e.g., GitHub Actions runs without an Nx Cloud CIPE).
+
+**Parameters:**
+
+- `sessionId` (required): The Polygraph session ID
+- `repoId` (required): Repository ID (MongoDB ObjectId hex string, from the session repository entry)
+- `jobId` (required): GitHub Actions job ID (from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response)
+
+**Returns:**
+
+- On success: `{ success: true, jobId: number, logFile: string, sizeBytes: number }`
+- On failure: `{ success: false, error: string }`
+
+The tool saves the log to a local temp file and returns the path in `logFile`. Use the `Read` tool to examine the file contents. For large logs, use `offset` and `limit` parameters to read specific sections.
+
+```
+get_ci_logs(
+  sessionId: "<session-id>",
+  repoId: "<repo-id>",
+  jobId: 12345678
+)
+// Returns: { success: true, jobId: 12345678, logFile: "/tmp/ci-logs/job-12345678.log", sizeBytes: 152340 }
+// Then: Read(logFile) to examine the log
+```
+
+**Typical flow:**
+
+1. Use `show_session` to see PR CI status
+2. Check `ciStatus[prId].cipeUrl` — if a CIPE exists, use `ci_information` for logs and skip this tool
+3. If NO CIPE exists, check `ciStatus[prId].externalCIRuns` — examine runs and jobs directly from the session data
+4. For a failed job, call `get_ci_logs(sessionId, repoId, jobId)` to save the log to a file
+5. Use `Read(logFile)` to examine the log content — use `offset`/`limit` for large files
+
+**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.

package/skills/polygraph/reference/sandboxing.md

@@ -0,0 +1,33 @@
+# Sandboxing in Polygraph Sessions
+
+Polygraph may run an agent session inside an OS-level sandbox, but not every session is sandboxed — whether it is on depends on the user's config (globally, per-agent, or per-repo). When it is on, writes are limited to the repository working tree, the session root (`~/.polygraph/sessions/<session-id>/`), the system temp directory, and a few allowlisted directories; network access is restricted to allowlisted hosts. In practice: binding a listening socket is denied (dev servers fail with `EPERM`), localhost servers are unreachable, and writes outside the allowlist are rejected. The user may not know whether this session is sandboxed.
+
+**Recognize sandbox denials — do not retry or work around them.** When a command fails in a sandbox-shaped way (`EPERM` binding a port, a blocked network host, a denied write to an ordinary path), the sandbox blocked it. Do NOT retry variations, escalate through workarounds, or route the command through `!`-prefixed user commands — those run inside the same sandbox. One failure is enough evidence; stop and inform the user.
+
+**Warn before attempting known-blocked operations.** Before starting a dev server, anything else that listens on a port, or an operation that needs writes or network access outside the allowlist, tell the user up front that it will not work while sandboxing is on and offer the options below instead of attempting it.
+
+**What to tell the user.** Explain that Polygraph runs this session in a sandbox, then present both options. Each takes effect on the next agent launch, so the Polygraph session must be relaunched afterwards:
+
+1. **Keep the sandbox on and allow the specific operation** (preferred). The sandbox belongs to the agent harness, so exceptions live in harness settings committed to the repository; array settings merge with Polygraph's generated allowlist rather than replacing it.
+
+   **If you are the Claude parent** — add writable paths to `.claude/settings.json` (or `.claude/settings.local.json`):
+
+   ```json
+   { "sandbox": { "filesystem": { "allowWrite": ["<path>"] } } }
+   ```
+
+   The `.claude/` directory is read-only inside the sandbox, so give the user the exact snippet to commit — you cannot apply it yourself.
+
+   **If you are the Codex parent** — add writable roots or network access to `.codex/config.toml`:
+
+   ```toml
+   [sandbox_workspace_write]
+   network_access = true
+   writable_roots = ["<path>"]
+   ```
+
+   The `.codex/` directory is read-only inside the sandbox, so give the user the exact snippet to commit — you cannot apply it yourself.
+
+2. **Turn sandboxing off.** The user quits the agent, runs `polygraph config`, toggles **Agent Options → Claude** (or **→ Codex**) **→ sandbox** off (or per-repo under **Repo Options**), and relaunches the Polygraph session. Non-interactive alternative: set `agentOptions.claude.sandbox: false` (or `agentOptions.codex.sandbox: false`, or `repoOptions."org/repo".sandbox: false`) in `~/.polygraph/config.json`. Warn that this removes filesystem isolation — the agent can then write anywhere the OS user can.
+
+**Never blame the tooling.** A sandbox denial means the environment blocked the operation — not that the repo, tool, or framework is broken. Do not record conclusions like "X is unusable" in memory, session descriptions, or messages based on sandboxed failures.

package/skills/polygraph/reference/shallow-clone-history.md

@@ -0,0 +1,9 @@
+# Fetching Git History for Shallow Clones
+
+Session repos are shallow (`--depth 1`) clones, and plain `git fetch --unshallow` fails on private repos (the clone-time credential is not retained).
+
+When git fails on missing history — `bad object` from `git revert`, `git log`, `git blame`, etc. — call `git_fetch({ sessionId, repo })` (CLI: `polygraph git fetch <repo> --session <id> --json`), then retry the git command.
+
+- Defaults fetch the default branch's full history.
+- Pass `depth` for a bounded fetch, or `refs` to include extra branches.
+- Safe to call redundantly — returns `alreadyComplete: true` when the history is already present.

package/hooks/check-plugin-version.mjs

@@ -1,294 +0,0 @@
-// SessionStart hook — checks whether the installed Polygraph plugin is
-// outdated and, when it is, emits a single stdout message so the agent
-// surfaces the problem to the user. Stale plugin versions have silently
-// caused incorrect Polygraph behavior in the past; this makes it visible
-// for agent launches that bypass the polygraph CLI (e.g. desktop apps).
-//
-// Unlike the sibling hooks, this one deliberately writes to stdout — but
-// ONLY when the plugin is outdated. When current, unknown, offline, or on
-// any error it prints nothing and exits 0.
-//
-// The harness ('claude' | 'codex') is passed as the first CLI argument so
-// the same script ships in both plugin artifacts.
-
-import {
-  appendFileSync,
-  mkdirSync,
-  readFileSync,
-  realpathSync,
-  renameSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
-const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-const FETCH_TIMEOUT_MS = 3000;
-const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
-
-const PACKAGE_BY_HARNESS = {
-  claude: '@polygraph/claude-plugin',
-  codex: '@polygraph/codex-plugin',
-};
-
-const REMEDIATION_BY_HARNESS = {
-  claude: 'run `claude plugins update polygraph@polygraph-plugins`',
-  codex:
-    'run `npx --prefer-online @polygraph/codex-plugin@latest install` then `codex plugin add polygraph@polygraph-plugins`',
-};
-
-// Append a one-line JSON record of a hook failure to ~/.polygraph/logs/hooks.log.
-// This hook swallows its errors silently, so this on-disk log is the only
-// record that something went wrong. The logger is itself failure-proof.
-function logHookFailure(
-  hook,
-  error,
-  meta = {},
-  home = process.env.HOME?.trim() || homedir()
-) {
-  try {
-    const logsDir = join(home, '.polygraph', 'logs');
-    mkdirSync(logsDir, { recursive: true });
-    const logFile = join(logsDir, 'hooks.log');
-
-    try {
-      if (statSync(logFile).size > HOOK_LOG_MAX_BYTES) {
-        renameSync(logFile, `${logFile}.1`);
-      }
-    } catch {
-      // no prior log, or rotation failed — ignore
-    }
-
-    const entry = {
-      time: new Date().toISOString(),
-      hook,
-      pid: process.pid,
-      ...meta,
-      error: error instanceof Error ? error.message : String(error),
-      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
-    };
-    appendFileSync(logFile, JSON.stringify(entry) + '\n');
-  } catch {
-    // Logging must never throw — a failing logger must not break the hook.
-  }
-}
-
-function tryParseJson(str) {
-  try {
-    return JSON.parse(str);
-  } catch {
-    return null;
-  }
-}
-
-function parseSemver(version) {
-  if (typeof version !== 'string') return null;
-  const match = version
-    .trim()
-    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
-  if (!match) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] ? match[4].split('.') : [],
-  };
-}
-
-// Returns -1, 0, or 1 when a is lower than, equal to, or higher than b.
-// Returns null when either version is unparseable.
-export function compareSemver(a, b) {
-  const pa = parseSemver(a);
-  const pb = parseSemver(b);
-  if (!pa || !pb) return null;
-
-  for (const key of ['major', 'minor', 'patch']) {
-    if (pa[key] !== pb[key]) return pa[key] < pb[key] ? -1 : 1;
-  }
-
-  // Same core version: a prerelease sorts below a release.
-  if (pa.prerelease.length && !pb.prerelease.length) return -1;
-  if (!pa.prerelease.length && pb.prerelease.length) return 1;
-
-  const len = Math.max(pa.prerelease.length, pb.prerelease.length);
-  for (let i = 0; i < len; i++) {
-    const ia = pa.prerelease[i];
-    const ib = pb.prerelease[i];
-    if (ia === undefined) return -1;
-    if (ib === undefined) return 1;
-    if (ia === ib) continue;
-    const na = /^\d+$/.test(ia) ? Number(ia) : null;
-    const nb = /^\d+$/.test(ib) ? Number(ib) : null;
-    if (na !== null && nb !== null) return na < nb ? -1 : 1;
-    if (na !== null) return -1; // numeric identifiers sort below alphanumeric
-    if (nb !== null) return 1;
-    return ia < ib ? -1 : 1;
-  }
-  return 0;
-}
-
-// Resolve the installed plugin version from the manifest shipped alongside
-// this script: <pluginRoot>/hooks/check-plugin-version.mjs sits next to
-// .claude-plugin/plugin.json (Claude), .codex-plugin/plugin.json (Codex),
-// or package.json.
-export function resolveInstalledVersion(pluginRoot) {
-  const manifests = [
-    join(pluginRoot, '.claude-plugin', 'plugin.json'),
-    join(pluginRoot, '.codex-plugin', 'plugin.json'),
-    join(pluginRoot, 'package.json'),
-  ];
-  for (const manifestPath of manifests) {
-    let raw;
-    try {
-      raw = readFileSync(manifestPath, 'utf8');
-    } catch {
-      continue;
-    }
-    const parsed = tryParseJson(raw);
-    if (parsed && parseSemver(parsed.version)) return parsed.version.trim();
-  }
-  return null;
-}
-
-function cachePath(harness, home) {
-  return join(home, '.polygraph', 'logs', `plugin-version-check-${harness}.json`);
-}
-
-export function readCache(harness, home) {
-  try {
-    return tryParseJson(readFileSync(cachePath(harness, home), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// A cache entry is only trusted when it is recent, was recorded for the
-// currently installed version (updating the plugin invalidates it), and holds
-// either a parseable latest version or null (a negatively-cached failed
-// fetch, so an offline machine does not re-stall on every session start).
-export function isCacheFresh(cache, installed, now) {
-  return Boolean(
-    cache &&
-      Number.isFinite(cache.checkedAt) &&
-      now - cache.checkedAt >= 0 &&
-      now - cache.checkedAt < CACHE_MAX_AGE_MS &&
-      cache.installed === installed &&
-      (cache.latest === null || parseSemver(cache.latest))
-  );
-}
-
-function writeCache(harness, home, entry) {
-  const path = cachePath(harness, home);
-  mkdirSync(dirname(path), { recursive: true });
-  const tmpPath = `${path}.tmp-${process.pid}`;
-  writeFileSync(tmpPath, JSON.stringify(entry) + '\n');
-  renameSync(tmpPath, path);
-}
-
-async function fetchLatestVersion(packageName, fetchImpl) {
-  const registry = (process.env.npm_config_registry?.trim() || DEFAULT_REGISTRY)
-    .replace(/\/+$/, '');
-  const url = `${registry}/-/package/${packageName.replace('/', '%2f')}/dist-tags`;
-  const response = await fetchImpl(url, {
-    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-  });
-  if (!response.ok) throw new Error(`registry responded ${response.status}`);
-  const distTags = await response.json();
-  return typeof distTags?.latest === 'string' ? distTags.latest : null;
-}
-
-export function buildOutdatedMessage(harness, installed, latest) {
-  return (
-    `The Polygraph plugin is outdated: ${installed} installed, ${latest} latest. ` +
-    'Stale plugin versions cause incorrect Polygraph behavior. ' +
-    `Tell the user to update it now: ${REMEDIATION_BY_HARNESS[harness]} ` +
-    '(or re-run `polygraph config`), then restart the agent session.'
-  );
-}
-
-/**
- * Check whether the installed plugin is outdated.
- *
- * @param {object} opts
- * @param {string} opts.harness     'claude' | 'codex'
- * @param {string} opts.pluginRoot  Directory containing the plugin manifest.
- * @param {string} [opts.home]      Override HOME for testing.
- * @param {Function} [opts.fetchImpl] Override fetch for testing.
- * @param {number} [opts.now]       Override the clock for testing.
- * @returns {Promise<string|null>} The message to emit, or null to stay silent.
- */
-export async function checkPluginVersion({
-  harness,
-  pluginRoot,
-  home = process.env.HOME?.trim() || homedir(),
-  fetchImpl = fetch,
-  now = Date.now(),
-}) {
-  const packageName = PACKAGE_BY_HARNESS[harness];
-  if (!packageName) return null;
-
-  const installed = resolveInstalledVersion(pluginRoot);
-  if (!installed) return null;
-
-  let latest;
-  const cache = readCache(harness, home);
-  if (isCacheFresh(cache, installed, now)) {
-    if (cache.latest === null) return null;
-    latest = cache.latest;
-  } else {
-    try {
-      latest = await fetchLatestVersion(packageName, fetchImpl);
-    } catch (error) {
-      // Negative cache: remember the failed fetch so an offline machine
-      // does not re-stall for the fetch timeout on every session start.
-      writeCache(harness, home, { checkedAt: now, installed, latest: null });
-      throw error;
-    }
-    if (!parseSemver(latest)) {
-      writeCache(harness, home, { checkedAt: now, installed, latest: null });
-      return null;
-    }
-    writeCache(harness, home, { checkedAt: now, installed, latest });
-  }
-
-  if (compareSemver(installed, latest) === -1) {
-    return buildOutdatedMessage(harness, installed, latest);
-  }
-  return null;
-}
-
-export async function main() {
-  const harness = process.argv[2];
-  try {
-    const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-    const message = await checkPluginVersion({ harness, pluginRoot });
-    if (message) process.stdout.write(message + '\n');
-  } catch (error) {
-    // Offline or broken registry must never block or pollute the session,
-    // but record it so failures are not invisible.
-    logHookFailure(`${harness || 'unknown'}:check-plugin-version`, error);
-  }
-  process.exitCode = 0;
-}
-
-// Run only when executed directly as a hook, not when imported (e.g. by tests).
-// realpathSync both sides so the check holds when the plugin lives under a
-// symlinked path (e.g. macOS /tmp -> /private/tmp).
-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();
-}