@polygraph/codex-plugin 0.4.26 → 0.4.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.codex-plugin/plugin.json +1 -1
  2. package/agents/polygraph-delegate-subagent.toml +5 -7
  3. package/agents/polygraph-init-subagent.toml +2 -2
  4. package/package.json +1 -1
  5. package/skills/polygraph/SKILL.md +48 -49
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygraph",
3
- "version": "0.4.26",
3
+ "version": "0.4.28",
4
4
  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
5
5
  "author": {
6
6
  "name": "Narwhal Technologies Inc",
package/agents/polygraph-delegate-subagent.toml CHANGED
@@ -17,11 +17,12 @@ The main agent provides these parameters in the prompt:
17
17
  | `repo` | Repository to delegate to (e.g., `org/repo-name`) |
18
18
  | `instruction` | The task instruction for the child agent |
19
19
  | `context` | (Optional) Additional context to pass to the child agent |
20
- | `taskId` | (Optional) Existing active task to route a user-approved follow-up to; omit on the first call for a new run |
21
20
 
22
21
  ## Delegating work
23
22
 
24
- Call the `spawn_agent` tool to start a child agent on the repo or to route an explicit follow-up to an active task. If the main agent supplied a `taskId` - meaning this is a user-approved follow-up turn against an already active task - forward it unchanged; otherwise omit `taskId` and a new child run is started.
23
+ 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: if the repo already has an active child task (working or paused on input), the orchestrator delivers your `instruction` to that task as a follow-up message; otherwise it starts a new child run.
24
+
25
+ `repo` must be a repository other than the one the parent agent is working in — never delegate into the parent's own repo. A repo has at most one active child: while one is active, any `spawn_agent` call for that repo is routed to it as a follow-up rather than starting a second run.
25
26
 
26
27
  **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.
27
28
 
@@ -30,8 +31,7 @@ spawn_agent(
30
31
  sessionId: "<sessionId>",
31
32
  repo: "<repo>",
32
33
  instruction: "<instruction>",
33
- context: "<context>",
34
- taskId: "<taskId>" // optional - pass only for a user-approved follow-up to an active task
34
+ context: "<context>"
35
35
  )
36
36
  ```
37
37
 
@@ -60,8 +60,6 @@ After calling `spawn_agent`, parse the structured JSON response:
60
60
  { "taskId": "…", "message": "…", "status": "delegated" }
61
61
  ```
62
62
 
63
- Store the returned `taskId`. You will pass it back to `spawn_agent` on any follow-up turn so the orchestrator routes the message to the same active task instead of starting a new run.
64
-
65
63
  Then poll `show_agent` on a backoff cadence. **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.
66
64
 
67
65
  For each child in the response (field: `children[]`), inspect:
@@ -78,7 +76,7 @@ State machine:
78
76
  - Read `child.inputRequiredQuestion`.
79
77
  - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
80
78
  - Wait for the parent/user to supply an answer.
81
- - Call `spawn_agent` again with `instruction: <the answer>` and `taskId: <stored taskId>` so the orchestrator routes the answer to the same active task.
79
+ - Call `spawn_agent` again with the same `repo` and `instruction: <the answer>` — the orchestrator routes it to the active task automatically.
82
80
  - Resume polling.
83
81
 
84
82
  <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
package/agents/polygraph-init-subagent.toml CHANGED
@@ -28,7 +28,7 @@ The main agent provides these parameters in the prompt:
28
28
 
29
29
  Additionally, the main agent may pass in repos via **MCP resource syntax** (e.g. `polygraph://repos/org/repo-name`).
30
30
 
31
- **Direct-add rule:** If `sessionId` is provided and the prompt names exact repositories to add by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo` directly with those refs in `repoIds`. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT require candidate discovery first. Candidate discovery is account-repo-only; `list_repos` is only for discovery/filtering when the user does not know the exact repo or explicitly wants candidate selection.
31
+ **Direct-add rule:** If `sessionId` is provided and the prompt names exact repositories to add by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo` directly with those refs in `repoIds`. Refs are not limited to organization repos — public open-source repos can be added by `owner/repo` slug or URL, even though they never appear in `list_repos`. Do NOT call `list_repos`, do NOT ask for candidates, and do NOT require candidate discovery first. Candidate discovery is account-repo-only; `list_repos` is only for discovery/filtering when the user does not know the exact repo or explicitly wants candidate selection.
32
32
 
33
33
  ## Workflow
34
34
 
@@ -104,7 +104,7 @@ Call `add_repo` to attach the selected repositories to the existing session —
104
104
  add_repo(sessionId: "<sessionId>", repoIds: [...])
105
105
  ```
106
106
 
107
- `repoIds` may be repository IDs from discovery, or exact refs provided by the user: short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax. For exact user-provided refs, pass the strings directly and do not call `list_repos` first.
107
+ `repoIds` may be repository IDs from discovery, or exact refs provided by the user: short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax — including repos outside the organization, such as public open-source repos. For exact user-provided refs, pass the strings directly and do not call `list_repos` first.
108
108
 
109
109
  ### Step 4: Get Session Details
110
110
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@polygraph/codex-plugin",
3
- "version": "0.4.26",
3
+ "version": "0.4.28",
4
4
  "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
package/skills/polygraph/SKILL.md CHANGED
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: polygraph
3
- description: Guidance for coordinating changes across multiple repositories using Polygraph. Use when working on a feature that affects another repository, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, discovering how code is consumed across repositories, or starting a multi-repo coordination session. TRIGGER when user mentions "polygraph", "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
3
+ description: Guidance for working with Polygraph — repositories, sessions, child agents, PRs, and CI. Use when discovering repositories or how code is consumed across them, starting, joining, resuming, or sharing a Polygraph session, handing off progress, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
4
4
 
5
5
  ---
6
6
 
7
- # Multi-Repo Coordination with Polygraph
7
+ # Working with Polygraph
8
8
 
9
- **IMPORTANT:** NEVER `cd` into cloned repositories or access their files directly. ALWAYS use Codex Polygraph subagents to invoke the Polygraph MCP `spawn_agent` tool for work in other repositories.
9
+ **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 Codex Polygraph subagents.
10
10
 
11
11
  ## Critical Routing Rule (Codex Parent Conversation)
12
12
 
@@ -16,10 +16,12 @@ Read this before the tool table below — it determines which tools are yours to
16
16
  - **For new sessions:** call Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"`. Do NOT call Polygraph MCP `list_repos` or `start_session` directly from this conversation.
17
17
  - **For explicit repo additions to an existing session:** if the user gives exact refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, call Polygraph MCP `add_repo` directly with those refs. Do NOT call `list_repos` or launch candidate discovery first.
18
18
  - **For repo work:** call Codex `spawn_agent` with `agent_type: "polygraph-delegate-subagent"`. Do NOT call Polygraph MCP `spawn_agent` or `show_agent` directly from this conversation; collect results with `wait_agent` when needed.
19
- - **Allowed direct Polygraph MCP calls from the parent:** `whoami`, `login`, `list_accounts`, `select_account`, `show_session` for read-only inspection of an existing session, `update_session_description` for session metadata updates, `link_reference` for linking external references to sessions, and `add_repo` only for explicit repo additions to an existing session.
19
+ - **Allowed direct Polygraph MCP calls from the parent:** `whoami`, `login`, `list_accounts`, `select_account`, `show_session` for read-only inspection of an existing session, `update_session` for session metadata updates, `link_reference` for linking external references to sessions, and `add_repo` only for explicit repo additions to an existing session.
20
20
  - Do NOT pass `fork_context: true` to Codex `spawn_agent` when `agent_type` is a custom agent — Codex rejects it.
21
21
 
22
- This skill provides guidance for working on features that span multiple repositories using Polygraph for coordination.
22
+ Polygraph connects repositories and the agent work happening across them. Its central artifact is the session, which groups the repositories, branches, PRs, and CI status for one piece of work and can be shared and resumed: use it to coordinate changes across multiple repositories, and also on its own to share the session URL with collaborators, hand off progress via the session description, resume prior work, and watch CI across the session's PRs.
23
+
24
+ **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* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`.
23
25
 
24
26
  ## Available Tools
25
27
 
@@ -29,23 +31,25 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
29
31
  | --- | --- | --- |
30
32
  | `list_repos` | `polygraph repo list` | Discover candidate repositories with descriptions and graph relationships |
31
33
  | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
32
- | `spawn_agent` | — | Start a new child task or send an explicit follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context?, taskId? }`. Output: `{ taskId, message, status: 'delegated' }`. Pass the `taskId` returned by a prior call to route a follow-up message to a specific active task; omit to start a new child run. 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. |
33
- | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
34
+ | `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context? }`. Output: `{ taskId, message, status: 'delegated' }`. Follow-up routing is automatic: if the repo already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A repo has at most one active child at a time. 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. |
35
+ | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
34
36
  | `stop_agent` | — | Cancel an in-progress child. 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. |
35
- | `push_branch` | — | Push a local git branch to the remote repository. Requires a session description. |
37
+ | `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. |
36
38
  | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
37
39
  | `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. |
38
- | `update_session_description` | `polygraph session update-description` | Set the current session description from a synthesized progress summary or user-provided text. This updates session metadata only; it does not require PR creation or mark-ready. |
40
+ | `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. |
39
41
  | `link_reference` | — | Link an external reference to a session. |
40
42
  | `mark_pr_ready` | — | Mark draft PRs as ready for review |
41
43
  | `associate_pr` | — | Associate an existing PR with a session |
42
44
  | `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
43
- | `complete_session` | `polygraph session archive <id>` | Mark a session complete |
45
+ | `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
44
46
  | `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
45
- | — | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
46
- | — | `polygraph session list` | List all sessions |
47
- | — | `polygraph account list` / `polygraph account select` | Organization management |
48
- | — | `polygraph whoami` | Show current auth status and org |
47
+ | `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
48
+ | `logout` | `polygraph auth logout` | Log out of Polygraph |
49
+ | `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
50
+ | `list_accounts` | `polygraph account list` | List available organizations |
51
+ | `select_account` | `polygraph account select` | Select the organization that future commands run against |
52
+ | `whoami` | `polygraph whoami` | Show current auth status and org |
49
53
 
50
54
  **Routing reminder:** Per the Critical Routing Rule above, the parent conversation must use Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"` for new sessions and `agent_type: "polygraph-delegate-subagent"` for repo work — not the Polygraph MCP tools shown in the table. `wait_agent` collects results when needed.
51
55
 
@@ -70,28 +74,30 @@ After logging in (or if logged in but no org is selected), use `polygraph accoun
70
74
 
71
75
  ## Workflow Overview
72
76
 
77
+ 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.
78
+
73
79
  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.
74
- 1. **Delegate work to each repo** - Use the `polygraph-delegate-subagent` to start child agents in other repositories. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
80
+ 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, but only one active child per repo. Choose the Simple (fire-and-forget) or Multi-turn (interactive) pattern described below based on whether the child may need clarification.
75
81
 
76
82
  4. **Monitor child agents** - Use `show_agent` to poll progress and read the flat `children[]` array for each child's `status` and `lastOutputLines`.
77
83
  5. **Stop child agents** (if needed) - Use `stop_agent` to cancel an in-progress child agent. The underlying agent session is preserved for later read-only context restoration; after a resume, wait for explicit user instructions before making changes.
78
84
  6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
79
- 7. **Update session description** - Use `update_session_description` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
85
+ 7. **Update session description** - Use `update_session` to update the session description; must follow the Session Description Policy. Independent of PR creation or mark-ready.
80
86
  8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
81
87
  9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
82
88
  10. **Query PR status** - Use `show_session` to check progress.
83
89
  11. **Mark PRs ready** - Use `mark_pr_ready` when work is complete.
84
- 12. **Complete session** - Use `complete_session` to mark the session as completed when the user requests it.
90
+ 12. **Archive session** - Use `archive_session` to archive the session when the user requests it.
85
91
 
86
92
  ## Step-by-Step Guide
87
93
 
88
94
  ### 0. Initialize or Join Polygraph Session
89
95
 
90
- There are three cases. Pick exactly one before calling any tool.
96
+ 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.
91
97
 
92
98
  **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), 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`.**
93
99
 
94
- **Case A — Existing session, already has repos.** Call `show_session` directly with the known session ID. Skip the init subagent entirely. Print the session details (format below) and proceed.
100
+ **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.
95
101
 
96
102
  **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`.
97
103
 
@@ -131,9 +137,9 @@ The subagent will:
131
137
  4. Call `show_session` to retrieve session details
132
138
  5. Return a summary with session URL and repo info
133
139
 
134
- **Case C only — new session just created:** After the init subagent completes and creates the new session, render the session welcome card (skip the session-details block below for this case). Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task).
140
+ **When the init subagent has just created a brand-new session,** render the session welcome card instead of the session-details block below. Prefer the `session_intro` MCP tool — call it with the session ID; it returns the card as markdown. If that tool is unavailable, run `polygraph session intro -s <sessionId>` via the CLI instead. The CLI command is intentionally hidden/internal and may not appear in public command listings, but it remains the correct skill fallback for rendering the welcome card. Either way, print the result to the user verbatim as markdown — do NOT wrap it in a code block or reformat it (the logo is pre-fenced; the rest is live markdown). It needs no other input, and you do not need to call `show_session` first. Then continue (ask the user what they want, or start the requested task).
135
141
 
136
- **After receiving the subagent's summary (Case B) or after calling `show_session` for an existing session (Case A), print the session details:**
142
+ **For an existing session — after `show_session` returns or the init subagent's summary arrives — show the session details:**
137
143
 
138
144
  **Session:** POLYGRAPH_SESSION_URL
139
145
 
@@ -169,7 +175,7 @@ Use this workflow when the user gives a Polygraph session ID and asks to underst
169
175
  - PR description
170
176
  5. If the request was resume/reconnect/reconstruct only, report the restored session context and wait for the user's next instruction.
171
177
  6. If the user explicitly asked to inspect or investigate prior work, use the PR descriptions and session summary to decide whether more repo investigation is needed.
172
- 7. If the repo to investigate is already part of the session, delegate directly to that repo.
178
+ 7. If the repo to investigate is already part of the session, delegate directly to that repo (unless it is the repo you are in — investigate that one directly).
173
179
  8. If the repo to investigate is not currently initialized in the session, and either the user provided an exact repo ref or the repo appears in `<repositories>`, call `add_repo` with that ref or repo `<id>` directly. Do not call `list_repos` just to resolve the repo.
174
180
  9. After `add_repo`, call `show_session` again to verify the repo was added, then delegate to that repo.
175
181
  10. Fall back to `list_repos` only when the desired repo is not an exact ref and is missing from `<repositories>`, or when the details output came from an older Polygraph version that did not include repo IDs.
@@ -212,7 +218,7 @@ spawn_agent(
212
218
  )
213
219
  ```
214
220
 
215
- 2. Delegate to multiple repos in parallel by launching multiple `polygraph-delegate-subagent` instances before waiting for results.
221
+ 2. Delegate to multiple repos in parallel by launching multiple `polygraph-delegate-subagent` instances before waiting for results — one delegation per repo at a time.
216
222
  3. For each child, the subagent watches `child.status` in the flat `children[]` response and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
217
223
  4. Collect completed results with `wait_agent` when the main flow needs them, then continue to `push_branch` + `create_pr`.
218
224
 
@@ -230,11 +236,9 @@ Use this pattern when the child may need clarification, the task is exploratory,
230
236
  { "taskId": "…", "message": "…", "status": "delegated" }
231
237
  ```
232
238
 
233
- Store the returned `taskId`. You will pass it back on any follow-up turn so the orchestrator routes the message to the same active task instead of starting a new run.
234
-
235
239
  2. Poll `show_agent`. The response shape is `{ children: PolygraphChildStatusItem[] }`. For each child, inspect:
236
240
 
237
- - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
241
+ - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
238
242
  - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
239
243
  - `child.lastOutputLines` — recent log tail.
240
244
  - `child.repoFullName` — which repo is talking.
@@ -242,10 +246,11 @@ Use this pattern when the child may need clarification, the task is exploratory,
242
246
  Drive the state machine:
243
247
 
244
248
  - `child.status === 'in-progress'` or `'created'` — continue polling.
245
- - `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 `taskId: <stored taskId>` and `instruction: <answer>`. Continue polling.
249
+ - `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` and `instruction: <answer>` — it is routed to the active task automatically. Continue polling.
246
250
  - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`.
247
251
  - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure.
248
252
  - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below.
253
+ - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below.
249
254
 
250
255
  3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo }`. The response is:
251
256
 
@@ -282,6 +287,8 @@ The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do
282
287
 
283
288
  Once work is complete in a repository, push the branch using `push_branch`. This must be done before creating a PR.
284
289
 
290
+ `push_branch` pushes from the local checkout: for the repo you are in, that is your current working directory with your commits; for delegated repos, it is the Polygraph-managed clone the child agent worked in. There is no separate session copy of the current repo.
291
+
285
292
  **Parameters:**
286
293
 
287
294
  - `sessionId` (required): The Polygraph session ID
@@ -301,7 +308,7 @@ push_branch(
301
308
 
302
309
  `description` is user-facing Polygraph session context.
303
310
 
304
- `description` is required for `push_branch`, `create_pr`, `associate_pr`, and `update_session_description`. (`mark_pr_ready` does not take a description.) Use the canonical structured format:
311
+ `description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) Use the canonical structured format:
305
312
 
306
313
  ```text
307
314
  Goal: <what the session is trying to accomplish>
@@ -548,6 +555,8 @@ Use `add_repo` to add repositories to an existing Polygraph session after it has
548
555
 
549
556
  **Direct-add rule:** When the user provides exact repo refs by ID, short name, full name, GitHub `owner/repo` slug, or URL-like slug, pass those refs directly to `add_repo` and do not call `list_repos` first. Candidate discovery remains account-repo-only and is only for cases where the user does not know the exact repo or asks to choose/filter candidates.
550
557
 
558
+ **Not limited to your organization:** repos outside the org — including public open-source repos — can be added by GitHub `owner/repo` slug or URL. Only `list_repos` discovery is org-scoped, so a repo missing from `list_repos` can still be added directly.
559
+
551
560
  **Parameters:**
552
561
 
553
562
  - `sessionId` (required): The Polygraph session ID
@@ -556,43 +565,33 @@ Use `add_repo` to add repositories to an existing Polygraph session after it has
556
565
  ```
557
566
  add_repo(
558
567
  sessionId: "<session-id>",
559
- repoIds: ["nrwl/ocean"]
568
+ repoIds: ["org/repo-name", "facebook/react"]
560
569
  )
561
570
  ```
562
571
 
563
- ### 8. Complete Session
572
+ ### 8. Archive Session
564
573
 
565
- **IMPORTANT: Only call this tool when the user explicitly asks to complete or close the session.** Do not automatically complete sessions as part of the workflow.
574
+ **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.
566
575
 
567
- **Warning:** Completing a session seals it from further modifications. Only complete a session when the user explicitly confirms they are done coordinating the session.
568
-
569
- Use `complete_session` to mark the session as completed. Completing a session will:
570
-
571
- - **Mark the session as completed** and sealed from further modifications (no new PRs, status changes, etc.)
572
-
573
- This is idempotent — completing an already-completed session returns success.
576
+ 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.
574
577
 
575
578
  **Parameters:**
576
579
 
577
580
  - `sessionId` (required): The Polygraph session ID
578
- - `clean` (optional): Remove local session worktrees after marking the session complete
581
+ - `clean` (optional): Remove the local clones Polygraph created for delegated repos after archiving
579
582
 
580
583
  **Returns:**
581
584
 
582
585
  - `sessionId`: The session ID
583
- - `completed`: Boolean indicating completion status
586
+ - `completed`: Boolean indicating the session is archived
584
587
 
585
588
  ```
586
- complete_session(
589
+ archive_session(
587
590
  sessionId: "<session-id>"
588
591
  )
589
592
  ```
590
593
 
591
- **When to call:**
592
-
593
- - After all cross-repo work is finished
594
- - All PRs have been created and marked ready for review
595
- - The user explicitly confirms they want to close all PRs and seal the session
594
+ **When to call:** all work is finished, PRs are created and marked ready, and the user explicitly confirms they are done with the session.
596
595
 
597
596
  ## Other Capabilities
598
597
 
@@ -645,7 +644,7 @@ Before writing:
645
644
  - If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
646
645
  - If updating or replacing the existing last item, write the resulting state directly.
647
646
 
648
- Write the description using the canonical structured format in the Session Description Policy. Then call `update_session_description` with the resulting summary.
647
+ Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`.
649
648
 
650
649
  ### Print Polygraph Session Details
651
650
 
@@ -678,11 +677,11 @@ If the session has a description timeline, also display:
678
677
  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
679
678
  1. **Link PRs in descriptions** - Reference related PRs in each PR body
680
679
  1. **Keep PRs as drafts** until all repos are ready
681
- 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session_description` — it is required and must follow the Session Description Policy
680
+ 1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy
682
681
  1. **Test integration** before marking PRs ready
683
682
  1. **Coordinate merge order** if there are deployment dependencies
684
683
 
685
684
  1. **NEVER call the Polygraph MCP `spawn_agent` or `show_agent` directly for routine delegation**. These MUST run inside `polygraph-delegate-subagent`.
686
685
 
687
686
  1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed. 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.
688
- 1. **Only complete sessions when asked** — Only call `complete_session` when the user explicitly requests it. Completing a session seals it from further modifications. Do not automatically complete sessions.
687
+ 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.