@polygraph/claude-plugin 0.4.39 → 0.4.40
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.
|
@@ -47,39 +47,21 @@ spawn_agent(
|
|
|
47
47
|
|
|
48
48
|
The call returns immediately — the child agent runs asynchronously.
|
|
49
49
|
|
|
50
|
-
**
|
|
50
|
+
**Polling with long-poll waits:**
|
|
51
51
|
|
|
52
|
-
|
|
53
|
-
| ------------ | ---------------- |
|
|
54
|
-
| 1st | Immediately |
|
|
55
|
-
| 2nd | 10 seconds |
|
|
56
|
-
| 3rd | 30 seconds |
|
|
57
|
-
| 4th+ | 60 seconds (cap) |
|
|
58
|
-
|
|
59
|
-
Use `sleep` in Bash between polls — this is mandatory, not aspirational. Without it you will hammer `show_agent` every 2-3s, which both wastes calls and floods your own context with repeated polling output. Always run sleep in the **foreground** (never background).
|
|
60
|
-
|
|
61
|
-
### Sleeping between polls on Claude Code
|
|
62
|
-
|
|
63
|
-
**There is exactly one correct pattern. Use it verbatim:**
|
|
52
|
+
Call `show_agent` in a loop, passing `waitForTransitionMs: 50000` on every call:
|
|
64
53
|
|
|
65
54
|
```
|
|
66
|
-
|
|
55
|
+
show_agent(
|
|
56
|
+
sessionId: "<sessionId>",
|
|
57
|
+
repo: "<repo>",
|
|
58
|
+
waitForTransitionMs: 50000
|
|
59
|
+
)
|
|
67
60
|
```
|
|
68
61
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
| Pattern | What happens |
|
|
72
|
-
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
73
|
-
| `sleep 60` (bare, foreground) | Blocked by the Bash tool with `Blocked: standalone sleep 60`. Wastes a tool call. |
|
|
74
|
-
| `sleep 10; sleep 10; sleep 10` (chained) | Detected and blocked. Explicitly prohibited. |
|
|
75
|
-
| `sleep 60 & wait`, `( sleep 60 )`, other shell tricks | Treated as the same standalone-sleep antipattern. Do not use. |
|
|
76
|
-
| `sleep 60` with `run_in_background: true` ← **WORST** | Returns immediately — *no actual delay*. The sleep keeps running as an orphaned background process. When it finally finishes, the harness wakes this subagent with a `<task-notification>`, forcing another turn after you've already returned. Every queued background sleep emits a duplicate `completed` notification to the parent. One mis-step here can produce 10+ duplicate parent notifications and burn the user's tokens. |
|
|
77
|
-
|
|
78
|
-
**Why this matters:** you run as a background Task subagent. Any background Bash command you spawn outlives your turn. Each completion wakes you again and emits another `<status>completed</status>` task-notification to the parent for the *same* parent tool-use ID. The parent has no way to silence it. Use the `until ... break ... done` wrapper — only it produces a real foreground delay.
|
|
79
|
-
|
|
80
|
-
If you ever see `Blocked: standalone sleep N`, the answer is **never** `run_in_background: true`. The answer is the `until` wrapper above.
|
|
62
|
+
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.
|
|
81
63
|
|
|
82
|
-
## Polling the
|
|
64
|
+
## Polling the child (multi-turn + input-required)
|
|
83
65
|
|
|
84
66
|
After calling `spawn_agent`, parse the structured JSON response:
|
|
85
67
|
|
|
@@ -87,9 +69,9 @@ After calling `spawn_agent`, parse the structured JSON response:
|
|
|
87
69
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
88
70
|
```
|
|
89
71
|
|
|
90
|
-
Then poll `show_agent`
|
|
72
|
+
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.
|
|
91
73
|
|
|
92
|
-
|
|
74
|
+
The response's `children[]` array has a single entry — the child for your repo. On it, inspect:
|
|
93
75
|
|
|
94
76
|
- `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.
|
|
95
77
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`; contains the verbatim question the child agent has asked the parent.
|
|
@@ -98,7 +80,7 @@ For each child in the response (field: `children[]`), inspect:
|
|
|
98
80
|
|
|
99
81
|
State machine:
|
|
100
82
|
|
|
101
|
-
1. `child.status === 'created'` or `'in-progress'` — child is still executing.
|
|
83
|
+
1. `child.status === 'created'` or `'in-progress'` — child is still executing. Call `show_agent` (with `waitForTransitionMs: 50000`) again.
|
|
102
84
|
2. `child.status === 'input-required'` — child is paused waiting for parent input:
|
|
103
85
|
- Read `child.inputRequiredQuestion`.
|
|
104
86
|
- Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
|
|
@@ -109,14 +91,14 @@ State machine:
|
|
|
109
91
|
<!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog
|
|
110
92
|
rendered by polygraph-mcp's show_agent handler. The dialog targets the parent's main
|
|
111
93
|
thread, NOT this subagent. From this subagent's perspective the gate is transient: a
|
|
112
|
-
|
|
113
|
-
|
|
94
|
+
waited show_agent call returns immediately while the gate is open, but the parent's pick
|
|
95
|
+
resolves it and a later poll sees the child back in progress. Do nothing here. -->
|
|
114
96
|
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:
|
|
115
97
|
|
|
116
98
|
- **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.
|
|
117
99
|
- **Do NOT read `child.pendingPermission` as a question to answer or forward.** It is for inspection/logging only; it is not your input prompt.
|
|
118
100
|
- **Do NOT call any tool** (`spawn_agent`, `stop_agent`, `allow_agent`, `deny_agent`) to resolve it.
|
|
119
|
-
- Treat `permission-required` **
|
|
101
|
+
- 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.
|
|
120
102
|
|
|
121
103
|
4. `child.status === 'completed'` — child finished successfully. Read `child.lastOutputLines` for the most recent log tail and report outcome.
|
|
122
104
|
5. `child.status === 'failed'` — child failed. Read `child.lastOutputLines` for failure context and report the error.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: polygraph
|
|
3
|
-
description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; or tracing a commit or line of code back to the session that produced it. 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", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame".
|
|
3
|
+
description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; checking CI status and logs; fetching missing git history in a shallow session clone; or tracing a commit or line of code back to the session that produced it. 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", asks about what other repos are doing with shared code/APIs/endpoints, or asks about a "commit sha", "session behind this commit", "which session changed this line", "find session by sha", "git blame", "shallow clone", "missing commit", "bad object", "unshallow", "fetch history".
|
|
4
4
|
|
|
5
5
|
allowed-tools:
|
|
6
6
|
- mcp__plugin_polygraph_polygraph-mcp
|
|
@@ -46,7 +46,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
46
46
|
| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
|
|
47
47
|
| `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
|
|
48
48
|
| `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. |
|
|
49
|
-
| `show_agent` | — | Poll
|
|
49
|
+
| `show_agent` | — | Poll the status of the specified repo's child (`repo` is required — one call covers one repo). Output: `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo; the 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'`. |
|
|
50
50
|
| `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. |
|
|
51
51
|
| `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. |
|
|
52
52
|
| `create_pr` | — | Create draft PRs with session metadata linking related PRs |
|
|
@@ -58,6 +58,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
|
|
|
58
58
|
| `add_repo` | — | Add repositories to a running Polygraph session. For explicit refs, pass the refs directly and skip `list_repos`. |
|
|
59
59
|
| `archive_session` | `polygraph session archive <id>` | Archive a session, hiding it from active lists (it can still be resumed) |
|
|
60
60
|
| `get_ci_logs` | — | Retrieve full plain-text log for a specific CI job |
|
|
61
|
+
| `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". |
|
|
61
62
|
| `login` | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
|
|
62
63
|
| `logout` | `polygraph auth logout` | Log out of Polygraph |
|
|
63
64
|
| `list_sessions` | `polygraph session list` | List sessions. By default only active sessions created by the current git user; pass `recommendedFilters: false` for all sessions. |
|
|
@@ -97,7 +98,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
|
|
|
97
98
|
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.
|
|
98
99
|
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.
|
|
99
100
|
|
|
100
|
-
4. **Monitor child agents** - Use `show_agent` to poll
|
|
101
|
+
4. **Monitor child agents** - Use `show_agent` to poll one repo's child (`repo` is required) and read its `status` and `lastOutputLines` from the single-entry `children[]` array.
|
|
101
102
|
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.
|
|
102
103
|
6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
|
|
103
104
|
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.
|
|
@@ -246,7 +247,7 @@ Use this pattern when the task is well-defined and the child is not expected to
|
|
|
246
247
|
|
|
247
248
|
**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.
|
|
248
249
|
|
|
249
|
-
1. Launch a background `Task` subagent per repo using `polygraph-delegate-subagent`. The subagent calls `spawn_agent`, then polls `show_agent`
|
|
250
|
+
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.
|
|
250
251
|
|
|
251
252
|
```
|
|
252
253
|
Task(
|
|
@@ -266,7 +267,7 @@ Task(
|
|
|
266
267
|
```
|
|
267
268
|
|
|
268
269
|
2. Delegate to multiple repos in parallel by launching multiple background Task subagents at the same time — one delegation per repo at a time. Read the output files later to check progress.
|
|
269
|
-
3.
|
|
270
|
+
3. The subagent watches `child.status` on the single `children[]` entry for its repo and exits when it sees a terminal status — typically `'completed'` or `'failed'` (and `'cancelled'` if it was stopped).
|
|
270
271
|
4. Once all background subagents report a terminal status, continue to `push_branch` + `create_pr`.
|
|
271
272
|
|
|
272
273
|
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.
|
|
@@ -283,7 +284,7 @@ Use this pattern when the child may need clarification, the task is exploratory,
|
|
|
283
284
|
{ "taskId": "…", "message": "…", "status": "delegated" }
|
|
284
285
|
```
|
|
285
286
|
|
|
286
|
-
2. Poll `show_agent
|
|
287
|
+
2. Poll `show_agent` via chained `waitForTransitionMs` long-poll calls (`repo` is required). The response shape is `{ children: PolygraphChildStatusItem[] }` with a single entry for that repo. On it, inspect:
|
|
287
288
|
|
|
288
289
|
- `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
|
|
289
290
|
- `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
|
|
@@ -663,6 +664,10 @@ get_ci_logs(
|
|
|
663
664
|
|
|
664
665
|
**Important:** Logs can be large (100KB+). Only fetch logs for failed or relevant jobs, and read only the sections you need.
|
|
665
666
|
|
|
667
|
+
### Fetching Git History for Shallow Clones
|
|
668
|
+
|
|
669
|
+
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`).
|
|
670
|
+
|
|
666
671
|
### Update Session Description
|
|
667
672
|
|
|
668
673
|
Use this when the user asks to summarize progress, update the session description, or capture the current state.
|