@polygraph/claude-plugin 0.4.27 → 0.4.29

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/agents/polygraph-delegate-subagent.md

@@ -27,13 +27,12 @@ The main agent provides these parameters in the prompt:
 | `repo`        | Repository to delegate to (e.g., `org/repo-name`)                            |
 | `instruction` | The task instruction for the child agent                                     |
 | `context`     | (Optional) Additional context to pass to the child agent                     |
-| `taskId`      | (Optional) Existing active task to route a user-approved follow-up to; omit on the first call for a new run |
 
 ## Delegating work
 
-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.
+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.
 
-`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: if it already has one, pass `taskId` to route the message to it instead of starting a new run.
+`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.
 
 **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.
 
@@ -42,8 +41,7 @@ spawn_agent(
   sessionId: "<sessionId>",
   repo: "<repo>",
   instruction: "<instruction>",
-  context: "<context>",
-  taskId: "<taskId>"  // optional - pass only for a user-approved follow-up to an active task
+  context: "<context>"
 )
 ```
 
@@ -89,8 +87,6 @@ After calling `spawn_agent`, parse the structured JSON response:
 { "taskId": "…", "message": "…", "status": "delegated" }
 ```
 
-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.
-
 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.
 
 For each child in the response (field: `children[]`), inspect:
@@ -107,7 +103,7 @@ State machine:
    - Read `child.inputRequiredQuestion`.
    - Surface this question verbatim to the parent/user: "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}".
    - Wait for the parent/user to supply an answer.
-   - Call `spawn_agent` again with `instruction: <the answer>` and `taskId: <stored taskId>` so the orchestrator routes the answer to the same active task.
+   - Call `spawn_agent` again with the same `repo` and `instruction: <the answer>` — the orchestrator routes it to the active task automatically.
    - Resume polling.
 
 <!-- Claude and Codex parents handle permission gates via the native MCP elicitation dialog

package/agents/polygraph-init-subagent.md

@@ -22,7 +22,7 @@ These tools are available via MCP and CLI. Use whichever is available in your en
 
 | MCP Tool | CLI Equivalent | Description |
 | --- | --- | --- |
-| `list_repos` | `polygraph repo list` | Discover candidate repositories with descriptions and graph relationships |
+| `list_repos` | `polygraph repo list` | Discover candidate repositories. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a NEW session with selected repositories. Only use when no `sessionId` was provided. |
 | `add_repo` | — | Attach repositories to an EXISTING session. Use when `sessionId` was provided and the session has no repos yet, or when the user wants to add more. |
 | `show_session` | `polygraph session show <id> [--details]` | Get full session details including URL, and use details when session summary, repo IDs, PR URLs, and PR descriptions are needed |
@@ -65,16 +65,22 @@ Call `list_repos` to discover available candidate repositories:
 list_repos()
 ```
 
+`list_repos` accepts these optional parameters; set whichever apply. Refer to the tool schema for each parameter.
+
+- `connectedTo`: repo ID, name, or full name (e.g. `nrwl/ocean`); pair with `connectionType`
+- `connectionType`: `directly-upstream` | `directly-downstream` | `directly-both` (default) | `upstream` | `downstream` | `both`
+- `publishedPackages`, `consumedPackages`, `publishedApis`, `consumedApis`: arrays of package names / API paths
+- `nameFilter`: array of repo name patterns (e.g. `nrwl/*`)
+- `semanticQuery`: free-text description of the repositories you want
+
 This returns:
 
-- **`initiator`**: The current repository, or `null` if not running from a specific repo
-- **`candidates`**: Candidate account repositories, each with:
+- **`repos`**: Candidate account repositories, each with:
   - `id`: Repository ID
   - `name`: Repository name
+  - `repository`: Full repo name (e.g., `org/repo`)
+  - `provider`: VCS provider (e.g., `GITHUB`)
   - `description`: AI-generated description of what the repository does (may be null)
-  - `vcsConfiguration.repositoryFullName`: Full repo name (e.g., `org/repo`)
-  - `graphRelationship`: How this repository relates to the initiator (`distance`, `direction`, `path`), or `null` if the repository is not in the dependency graph. When `initiator` is null, `graphRelationship` will be null for all candidates.
-- **`dependencyGraph`**: Graph of repository dependency `edges` (always available, independent of initiator)
 
 ### Step 2: Select Relevant Repos
 
@@ -84,14 +90,11 @@ If `selectedRepoIds` or exact repo refs were provided by the main agent, use tho
 
 Otherwise, analyze the candidates using the `userContext` to determine which repos are relevant:
 
-1. Read each candidate's `description` and `graphRelationship`
-2. Match against the `userContext` — consider:
-   - Repository descriptions that mention relevant functionality
-   - Graph relationships (closer repos are more likely relevant); note that `graphRelationship` may be `null` for repositories not in the dependency graph — use their `description` to assess relevance
-   - When `graphRelationship` is null for all candidates (no initiator), rely on `description` fields and the raw `dependencyGraph` edges for selection instead
-   - Direction (upstream/downstream based on the nature of the change)
-3. Select only the repos that are clearly relevant to the task
-4. If uncertain which repos are relevant, include all candidates (safe default)
+1. Read each repo's `description`
+2. Match repo descriptions against the `userContext` to identify relevant repos
+3. Select the repos that are relevant to the task
+4. When uncertain, include all candidates
+5. When the user described the task in natural language and the result is large, re-query with `semanticQuery` set to that description
 
 ### Step 3: Initialize Polygraph Session or Attach Repos
 
@@ -147,11 +150,6 @@ Return a structured summary in this format:
 | Repo | Repository ID | Description | Selected |
 | --- | --- | --- | --- |
 | REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | Yes/No |
-
-### Initiator
-(Only include this section if `list_repos` was called and `initiator` is non-null)
-- **Name:** <initiator name>
-- **Repo:** <initiator repo full name>
 ```
 
 ## Important Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/SKILL.md

@@ -21,25 +21,27 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 
 | MCP Tool | CLI Equivalent | Description |
 | --- | --- | --- |
-| `list_repos` | `polygraph repo list` | Discover candidate repositories with descriptions and graph relationships |
+| `list_repos` | `polygraph repo list` | Discover candidate repositories. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
-| `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 repo has at most one active child at a time: while a task is active in a repo, pass `taskId` to follow up — never start a second concurrent run in the same repo. 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 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'`. |
+| `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. |
+| `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'`. |
 | `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. |
 | `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_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. |
+| `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. |
 | `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`. |
 | `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 |
-| — | `polygraph auth login [--token]` | Authenticate with Polygraph (use `--token` for headless/CI) |
-| — | `polygraph session list` | List all sessions |
-| — | `polygraph account list` / `polygraph account select` | Organization management |
-| — | `polygraph whoami` | Show current auth status and org |
+| `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. |
+| `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.
 
@@ -72,7 +74,7 @@ The delegate/monitor/stop steps apply only when working across repos. A single-r
 4. **Monitor child agents** - Use `show_agent` to poll progress and read the flat `children[]` array for each child's `status` and `lastOutputLines`.
 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.
 6. **Push branches** - Use `push_branch` after making commits. A required `description` must follow the Session Description Policy.
-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.
+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.
 8. **Create draft PRs** - Use `create_pr` to create linked draft PRs. Always pass `description` following the Session Description Policy.
 9. **Associate existing PRs** (optional) - Use `associate_pr` to link PRs created outside Polygraph.
 10. **Query PR status** - Use `show_session` to check progress.
@@ -227,11 +229,9 @@ Use this pattern when the child may need clarification, the task is exploratory,
    { "taskId": "…", "message": "…", "status": "delegated" }
    ```
 
-   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.
-
 2. Poll `show_agent`. The response shape is `{ children: PolygraphChildStatusItem[] }`. For each child, inspect:
 
-   - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
+   - `child.status` — one of `'created'`, `'in-progress'`, `'input-required'`, `'permission-required'`, `'completed'`, `'failed'`, `'cancelled'` (British double-L on `'cancelled'`).
    - `child.inputRequiredQuestion` — populated only when `child.status === 'input-required'`.
    - `child.lastOutputLines` — recent log tail.
    - `child.repoFullName` — which repo is talking.
@@ -239,10 +239,11 @@ Use this pattern when the child may need clarification, the task is exploratory,
    Drive the state machine:
 
    - `child.status === 'in-progress'` or `'created'` — continue polling.
-   - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with `taskId: <stored taskId>` and `instruction: <answer>`. Continue polling.
+   - `child.status === 'input-required'` — read `child.inputRequiredQuestion`, surface it to the user verbatim (e.g. "The child agent in `{child.repoFullName}` needs input: {child.inputRequiredQuestion}"), get the answer, then call `spawn_agent` again with the same `repo` and `instruction: <answer>` — it is routed to the active task automatically. Continue polling.
    - `child.status === 'completed'` — read `child.lastOutputLines`, proceed to `push_branch` + `create_pr`.
    - `child.status === 'failed'` — read `child.lastOutputLines`, surface the failure.
    - `child.status === 'cancelled'` — the child was stopped via `stop_agent`; see below.
+   - `child.status === 'permission-required'` — the child is waiting on a permission decision; see "Handling permission requests" below.
 
 3. To abort mid-flight, call `stop_agent` with `{ sessionId, repo }`. The response is:
 
@@ -300,7 +301,7 @@ push_branch(
 
 `description` is user-facing Polygraph session context.
 
-`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:
+`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:
 
 ```text
 Goal: <what the session is trying to accomplish>
@@ -636,7 +637,7 @@ Before writing:
 - 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.
 - If updating or replacing the existing last item, write the resulting state directly.
 
-Write the description using the canonical structured format in the Session Description Policy. Then call `update_session_description` with the resulting summary.
+Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`.
 
 ### Print Polygraph Session Details
 
@@ -669,7 +670,7 @@ If the session has a description timeline, also display:
 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
 1. **Keep PRs as drafts** until all repos are ready
-1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session_description` — it is required and must follow the Session Description Policy
+1. **Always pass `description`** when calling `create_pr`, `associate_pr`, or `update_session` — it is required and must follow the Session Description Policy
 1. **Test integration** before marking PRs ready
 1. **Coordinate merge order** if there are deployment dependencies