@kurrent/kcap 1.3.0-beta.5 → 1.3.0-beta.7

package/bin/refresh.js

@@ -1,6 +1,6 @@
-// Refreshes kcap's user-scope coding-agent installs so users pick up new or updated
-// skills, Codex/Cursor/Copilot hook commands, the Pi live-ingest extension, and
-// Claude plugin registration.
+// Refreshes kcap's user-scope coding-agent installs after an install or upgrade, by running
+// `kcap refresh` — the native binary owns the refresh list and the Claude plugin's .mcp.json patch,
+// so every installer (npm, the install scripts, a script install's `kcap update`) runs the same one.
 //
 // Shared by:
 // - postinstall.js — runs after `npm install -g @kurrent/kcap` (incl. upgrades),
@@ -10,150 +10,34 @@
 //
 // This file must never require kcap.js: during `kcap update`, runUpdate executes
 // before kcap.js's final module.exports assignment, so it would observe partial
-// exports. Shared platform/binary resolution lives in resolve.js instead.
+// exports.
 
 const { spawnSync } = require("child_process");
-const path = require("path");
-const fs = require("fs");
 
-// One entry per agent. Order is independent — each refresh is gated by its own
-// marker via `--if-installed`, which no-ops unless the user has previously
-// opted in (marker file present OR pre-marker install detected). A vendor entry
-// also refreshes the shared ~/.agents/skills tree, but only tops up one that is
-// already there: `plugin remove --skills` must survive an upgrade.
-const REFRESHES = [
-  ["plugin", "install", "--skills",  "--if-installed"],
-  ["plugin", "install", "--codex",   "--if-installed"],
-  ["plugin", "install", "--cursor",  "--if-installed"],
-  ["plugin", "install", "--copilot", "--if-installed"],
-  ["plugin", "install", "--pi",      "--if-installed"], // Pi extension (~/.pi/agent/extensions/kcap.ts)
-  ["plugin", "install", "--opencode", "--if-installed"], // OpenCode plugin (~/.config/opencode/plugins/kcap.ts)
-  ["plugin", "install", "--gemini",  "--if-installed"], // Gemini hooks/MCP/instructions (~/.gemini)
-  ["plugin", "install", "--kiro",    "--if-installed"], // Kiro agent hooks (~/.kiro/agents/kcap.json)
-  ["plugin", "install", "--antigravity", "--if-installed"], // Antigravity hooks (~/.gemini/config/plugins/kcap)
-  ["plugin", "install",              "--if-installed"], // Claude
-];
+// Above the binary's own worst case: eleven steps, each bounded at 60s.
+const REFRESH_TIMEOUT_MS = 15 * 60_000;
 
-// Runs each refresh via the given launcher (an absolute path to kcap.js).
-// Each refresh runs independently: a failure, timeout, or unexpected exit code
-// from one never prevents the others and never throws to the caller — a failed
-// refresh must never break `npm install` or report `kcap update` as failed.
-function runRefreshes(launcherPath) {
-  // Point the shipped Claude plugin's MCP entries at the native binary. Runs
-  // here because runRefreshes fires at exactly the two moments the plugin dir
-  // has just been (re)written by npm: postinstall and `kcap update`.
-  patchPluginMcpConfig(launcherPath);
-
-  for (const argv of REFRESHES) {
-    try {
-      spawnSync(process.execPath, [launcherPath, ...argv], {
-        stdio: "ignore",
-        env: process.env,
-        // Hard ceiling so a stalled child can never hang the caller.
-        timeout: 60_000,
-        killSignal: "SIGKILL",
-        windowsHide: true,
-      });
-    } catch {
-      // Never fail the caller.
-    }
-  }
-}
-
-// ── Claude plugin .mcp.json patch ───────────────────────────────────────────
-//
-// The plugin ships `"command": "kcap"`, which resolves to the node wrapper —
-// one resident Node runtime per MCP server per open Claude session (~25 MB
-// idle each). Rewriting the command to the resolved native binary makes Claude
-// spawn the binary directly. Best-effort: on any failure the shipped value
-// stays in place, which still works via the wrapper.
-
-// The servers shipped in the plugin's .mcp.json, keyed by canonical
-// `["mcp", <suffix>]` args. Only these exact name/args pairs are patched —
-// anything else in the file is preserved verbatim.
-const PLUGIN_MCP_SERVERS = {
-  "kcap-review":    "review",
-  "kcap-sessions":  "sessions",
-  "kcap-flows":     "flows",
-  "kcap-memory":    "memory",
-  "kcap-workitems": "workitems",
-  "kcap-plans":     "plans",
-  "kcap-artefacts": "artefacts",
-  "kcap-analytics": "analytics",
-  "kcap-knowledge": "knowledge",
-  "kcap-handoff":   "handoff",
-};
-
-// A command this patcher may rewrite: the shipped literal "kcap", or an
-// absolute path whose basename is the kcap binary (a previous patch that has
-// gone stale after an npm re-layout). Handles both path flavors so a stale
-// Windows path is still recognized. Anything else is a customization → keep.
-function isPatchableKcapCommand(command) {
-  if (command === "kcap") return true;
-  if (typeof command !== "string") return false;
-  if (!path.posix.isAbsolute(command) && !path.win32.isAbsolute(command)) return false;
-  const base = command.split(/[\\/]/).pop().toLowerCase();
-  return base === "kcap" || base === "kcap.exe";
-}
-
-// Pure: rewrites in place the canonical plugin entries of `cfg` whose command
-// is patchable, returning whether anything changed. Throws on a shape that
-// isn't the plugin config (caller turns that into the single warning).
-function patchPluginMcpServers(cfg, binaryPath) {
-  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
-    throw new Error("config is not an object");
-  }
-  const servers = cfg.mcpServers;
-  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
-    throw new Error("mcpServers is not an object");
-  }
-
-  let changed = false;
-  for (const [name, suffix] of Object.entries(PLUGIN_MCP_SERVERS)) {
-    const entry = servers[name];
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-    if (!Array.isArray(entry.args) || entry.args.length !== 2 ||
-        entry.args[0] !== "mcp" || entry.args[1] !== suffix) continue; // customized args → keep
-    if (!isPatchableKcapCommand(entry.command)) continue;              // customized command → keep
-    if (entry.command === binaryPath) continue;                        // already current
-    entry.command = binaryPath;
-    changed = true;
-  }
-  return changed;
-}
-
-// Rewrites the plugin's shipped .mcp.json (a sibling `kcap/` dir of the
-// launcher's `bin/`) so Claude spawns the native binary directly. Validates
-// before writing, writes a sibling temp file, then renames atomically — the
-// original survives any pre-rename failure. Never throws; on failure it emits
-// ONE concise warning and leaves the shipped `"command": "kcap"` in place.
-// `binaryPath` is a test seam; real callers let it resolve.
-function patchPluginMcpConfig(launcherPath, binaryPath) {
-  let mcpJsonPath;
+// Runs `kcap refresh` through the given launcher (an absolute path to kcap.js), so the NEW
+// launcher and the NEW binary run it after an upgrade. Never throws and never fails the caller:
+// a failed refresh must never break `npm install` or report `kcap update` as failed. Its stderr
+// (which steps failed, a plugin patch that could not be written) is passed on through `warn`.
+function runRefreshes(launcherPath, warn = console.warn) {
   try {
-    binaryPath = binaryPath || require("./resolve").resolveNativeBinary();
-    if (!binaryPath) return; // unsupported platform / package missing — wrapper keeps working
-
-    mcpJsonPath = path.join(path.dirname(launcherPath), "..", "kcap", ".mcp.json");
-    if (!fs.existsSync(mcpJsonPath)) return; // dev checkout / plugin not shipped
-
-    const cfg = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
-    if (!patchPluginMcpServers(cfg, binaryPath)) return; // already patched / nothing canonical
-
-    const tmp = `${mcpJsonPath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
-      fs.renameSync(tmp, mcpJsonPath);
-    } catch (e) {
-      try { fs.unlinkSync(tmp); } catch {}
-      throw e;
-    }
-  } catch (e) {
-    console.warn(
-      `kcap: could not point the Claude plugin MCP entries at the native binary` +
-      ` (${e && e.message ? e.message : e}); they will keep launching via the node wrapper.`,
-    );
+    const result = spawnSync(process.execPath, [launcherPath, "refresh"], {
+      stdio: ["ignore", "ignore", "pipe"],
+      encoding: "utf8",
+      env: process.env,
+      timeout: REFRESH_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    });
+    const stderr = (result.stderr || "").trim();
+    if (stderr) warn(stderr);
+    if (result.status !== 0)
+      warn("kcap: some agent integrations were not refreshed; run `kcap refresh` to retry.");
+  } catch {
+    // Never fail the caller.
   }
 }
 
-module.exports = { runRefreshes, patchPluginMcpConfig, patchPluginMcpServers, isPatchableKcapCommand };
+module.exports = { runRefreshes };

package/bin/resolve.js

@@ -1,10 +1,5 @@
-// Side-effect-free platform/native-binary resolution, shared by kcap.js (the
-// launcher) and refresh.js (postinstall / `kcap update` refresh).
-//
-// This lives in its OWN module — refresh.js must never require kcap.js: during
-// `kcap update`, runUpdate executes BEFORE kcap.js's final module.exports
-// assignment, so a refresh.js → kcap.js require would observe partial exports
-// exactly on that path. Requiring this module has no side effects.
+// Side-effect-free platform/native-binary resolution for kcap.js (the launcher).
+// Requiring this module has no side effects.
 
 const path = require("path");
 const fs = require("fs");

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "1.3.0-beta.5",
+  "version": "1.3.0-beta.7",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.mcp.json

@@ -15,7 +15,7 @@
       "command": "kcap",
       "args": ["mcp", "flows"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
-      "description": "Structured AI agent flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow (review-specific) plus their generic equivalents start_flow, send_to_participant, get_flow_status, close_flow (any flow-definition catalog id). Launches a SEPARATE hosted participant agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use only when the user explicitly asks for a review flow / agent flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools."
+      "description": "Structured AI agent flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow (review-specific) plus their generic equivalents start_flow, send_to_participant, get_flow_status, close_flow (any flow-definition catalog id). Launches a SEPARATE hosted participant agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use the flow tools only when the user explicitly asks for a review flow / agent flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools. Also list_start_agent_options and start_agent: when the user asks to start a separate hosted agent that works on its own, use these — not your harness's own subagent tool, a flow, or the `kcap agent start` CLI."
     },
     "kcap-memory": {
       "command": "kcap",

package/kcap/README.md

@@ -20,6 +20,7 @@ Search and recall past Kurrent Capacitor sessions from inside the agent.
 | `get_session_transcript` | Speaker-tagged transcript window, with `around_event` drill-in for search hits |
 | `list_repo_plans` | List a repository's declared plans you can see, most recently touched first |
 | `get_declared_plans` | A plan's documents and full task list, by `plan_id` or `session_id` |
+| `get_session_evals` | Eval state and scores for up to 25 sessions by id; works on every plan |
 
 Repo-aware: it resolves the cwd to a repo hash at startup, so `search_sessions` defaults to *this* repo.
 

package/kcap/hooks/hooks.json

@@ -79,6 +79,16 @@
             "async": true
           }
         ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap hook --claude --plan-read --no-update-check",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [

package/kcap/skills/agent-flows/SKILL.md

@@ -1,24 +1,23 @@
 ---
 name: agent-flows
 description: >-
-  This skill should be used ONLY when the user explicitly asks to run a
-  structured agent *flow* by name or definition id — e.g. "start a flow",
-  "run the code-review flow", "run the X flow", "use flow definition X",
-  "kick off an agent flow", or wants an iterative loop run by a separate
-  hosted participant agent that continues until sign-off. It covers the same
-  underlying tools as the `review-flows` skill (`start_review_flow` etc. are
-  aliases of the generic tools documented here) — use `review-flows` for the
-  two built-in review kinds (`spec-review`, `code-review`) and this skill for
-  any other flow definition, or when the user names a `definition_id`
-  explicitly. Do NOT use this skill (and do NOT call the flows MCP tools) for
-  an ordinary request such as "review my PR", "do X for me", or "check this
-  over" where the user just wants you to do the work yourself — perform that
-  work directly instead.
+  Use this skill to drive a structured agent *flow*: a separate hosted
+  participant agent runs a definition from the server's flow catalogue and
+  iterates with you until sign-off. Use it when the user names a flow or
+  definition id ("run the code-review flow", "start a flow", "use flow
+  definition X"), when the user accepts a flow you offered, or when you are
+  about to offer one listed under "Flows you may offer" in your session
+  context because its when-to-use applies. Before starting a flow, call
+  get_flow_definition and follow its guide. Do NOT use this skill (and do NOT
+  call the flows MCP tools) for an ordinary request such as "review my PR",
+  "do X for me", or "check this over" where the user wants you to do the work
+  yourself — do it directly instead. To start a hosted agent that works on its
+  own, use `start-agents`.
 ---
 
 # Agent Flows
 
-Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
+Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `get_flow_definition`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it when the user asks for a flow or accepts one you offered, never on your own initiative.
 
 ## Long rounds are normal
 
@@ -38,15 +37,14 @@ and end the reviewer turn. The hosted-reviewer contract wins over driver-looking
 
 These tools do **not** perform the work themselves — they hand it off to a separate hosted participant agent running a named flow definition. If the user simply asked *you* to do something in a normal session — e.g. "review my PR", "review this diff", "check this spec", "do X" — just do it yourself and report the result directly. Do **NOT** call `start_flow` / `send_to_participant` for an ordinary request; that would spin up a hosted agent the user did not ask for.
 
-Only start a flow when the user explicitly asks for a flow — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow.
+Only start a flow when the user explicitly asks for one — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow — or accepts a flow you offered. Offer a flow only when your session context lists it under **Flows you may offer** and its when-to-use applies to what just happened; ask, and never start it before the user says yes. Skip the offer when the user asked you to do the work yourself, or while you are mid-task.
 
 ## Choosing the flow definition
 
-Once the user has explicitly opted into a flow (see above), pick the `definition_id`:
+Once the user has asked for a flow or accepted one you offered (see above), pick the `definition_id`:
 
-- Spec or design document → `definition_id: "spec-review"` (built-in; same as `review-flows`' `spec-review` kind)
-- Code changes or a pull request → `definition_id: "code-review"` (built-in; same as `review-flows`' `code-review` kind)
-- Anything else → the definition id the user named, or one from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
+- The flow the user named, or the one you offered and they accepted.
+- If the user has not named one → choose from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
 
 For the reserved `spec-review` and `code-review` aliases, reviewer-vendor language is role-bound:
 pass the one vendor explicitly named as the reviewer, ignore driver-harness mentions, honor
@@ -87,6 +85,10 @@ vendor supports this: the daemon must advertise a runtime model resolver for the
 (Claude and Codex today; other vendors keep vendor-only overrides with no model choice) or the
 server rejects the override outright.
 
+## Read the flow's guide first
+
+Before a catalogue start (`definition_id`), call `get_flow_definition(definition_id)`. The guide is written by whoever published the flow: what to put in `context`, which target to name, how to iterate on its results and when to close. Where it differs from the generic rules below, follow the guide. A server that does not publish guides says so; then work from the definition's description and the rules below. A flow started with an inline `definition_yaml` has no catalogue id and no guide: drive it by the generic rules and its own YAML.
+
 ## Composing a dynamic flow
 
 If nothing `list_flow_definitions` shows fits — no `definition_id` covers the roles or workflow you need — compose one inline instead: pass `definition_yaml` to `start_flow` in place of `definition_id`. Provide exactly one of the two, never both. (`start_review_flow` / `submit_review_round` stay catalog-only — this only applies to the generic `start_flow`.)
@@ -146,7 +148,7 @@ After applying the role-surface safety gate, if `start_flow` / `send_to_particip
 5. **If participant output is unclear or requires user input**, pause and ask the user before proceeding.
 6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
 7. **Address each role independently.** A flow definition declares one or more participant roles in its `participants` map (single-participant definitions use `reviewer`). A multi-participant `start_flow` returns no round — nothing has launched yet. Call `send_to_participant(flow_run_id, participant=<role>, message=…)` naming the role you want to address; its first message launches that role's agent lazily. Only one round is in flight per role at a time — sending to a role that's still working on a round gets a `409` naming the busy round — but every OTHER role stays addressable in the meantime. Sending an unknown role is rejected by the server, which names the valid roles in its error.
-8. **For a code review flow (`definition_id: "code-review"`), do NOT ask the participant to run tests.** CI covers test execution; participant feedback is on correctness, design, and adherence to conventions.
+8. **Ask the participant only for what the flow's guide allows.** If the guide says CI covers tests, do not ask the participant to run them; participant feedback is on what the flow exists to judge.
 9. **State where your changes live.** The participant's worktree is mirrored from **this session's project directory**, not from the directory you are working in, and no tool parameter can redirect it. So if you changed directory, are a subagent in another checkout, or the changeset lives in another worktree/repo/machine, the participant will NOT see it: say so in `context`/`message`, give it an explicit commit range (never `git diff origin/main...HEAD`), and inline the diffs — or pass `mode: "context-only"` to make your context the sole source of truth. The participant flags referenced changes it cannot find; incomplete context wastes a full round.
 
 ## Pending messages
@@ -169,10 +171,17 @@ The server enforces per-run budgets; watch for these in tool error responses:
 
 ## Workflow
 
+A catalogue flow (`definition_id`) starts with its guide; an inline `definition_yaml` flow skips this step:
+
+```
+get_flow_definition(definition_id)
+  → read the driver guide; prepare the context it asks for
+```
+
 Single-participant definitions start eagerly — round 1 runs as part of `start_flow`:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → participant returns a result: kind findings (with the result text) | kind clean
 
 if clean:
@@ -191,7 +200,7 @@ if findings:
 Multi-participant definitions start round-less — you address each role yourself, and the run is clean only in aggregate:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → no round yet — roles have not launched
 
 send_to_participant(flow_run_id, participant="reviewer", message=…)
@@ -217,7 +226,8 @@ report completion to user
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
 | `list_flow_definitions` | — | — | Before `start_flow`, whenever the user has not named a definition or named one you have not seen listed. Read-only: returns each runnable definition's id, version, description, whether it is single- or multi-participant, and its participants' role, authored vendor and model. A `server_catching_up` error is retryable — do not read it as an empty catalog. |
-| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
+| `get_flow_definition` | `definition_id` | — | Before every catalogue (`definition_id`) `start_flow`. Read-only: returns the definition's participants and when to use it, then its authored driver guide (what to submit, how to iterate, when to close). An unknown, disabled or deleted id is an error; an older server reports that it publishes no guides. |
+| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `session_title` (the participant session's title: a short phrase naming this piece of work, specific enough to tell it apart from other sessions — it replaces the definition's generic opening instruction as the name), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
 | `send_to_participant` | `flow_run_id`, `participant` (role name declared in the flow definition's `participants` map; single-participant definitions use `reviewer` — an unknown role is rejected, naming the valid ones), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result for that role, or to launch a role for the first time. Pass the same `flow_run_id`, the role's name, and the updated message. |
 | `get_flow_status` | — | `flow_run_id` (omit to read the newest open flow this session started, or on a harness without a session identity the newest one started from this workspace; several open flows are listed instead), `session_id` (look up another session's flows; defaults to this session), `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow run (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself, and omit `flow_run_id` to recover a flow whose id you never received or lost. |
 | `close_flow` | `flow_run_id` | — | Only after the definition's clean signal — or when abandoning the task early; the run otherwise stays open until closed. |
@@ -225,13 +235,14 @@ report completion to user
 ## Example (custom definition)
 
 ```
-# Step 1 — start (all five required args required; the participant sees a mirror of THIS SESSION's
+# Step 1 — start (all six args required; the participant sees a mirror of THIS SESSION's
 # project directory, not of the directory you are working in — pass mode="context-only" to opt out)
 start_flow(
   definition_id="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review the null check on user input",
   context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"
@@ -260,6 +271,7 @@ start_flow(
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review and test the null check on user input",
   context="Review the diff on this branch and write/run tests for the new code path."
 )
 # → returns flow_run_id, e.g. "flow_xyz789"; no round in the response

package/kcap/skills/eval-watch/SKILL.md

@@ -4,38 +4,31 @@ description: >-
   Follow a kcap import that setup just started and the evals landing on it —
   "Follow my kcap import" (the prompt `kcap setup` hands to your agent), "watch my
   import", "how is my import going", "are my evals done yet". Reads the handoff file
-  setup wrote, polls Capacitor analytics for exactly the sessions that import
-  created, waits for the sessions that imported while the user watched to be
-  evaluated, summarizes their evals, links to the results and offers the guided
-  tour. Not for browsing evals in general — that is the analytics or guided-tour
-  skill.
+  setup wrote, polls the eval state of exactly the sessions that import created,
+  waits for the sessions that imported while the user watched to be evaluated,
+  summarizes their evals, links to the results and offers the guided tour. Works on
+  every plan. Not for browsing evals in general — that is the guided-tour skill.
 ---
 
 # Eval watch
 
-You follow ONE import: the sessions listed in a handoff file `kcap setup` wrote. Every query you
-issue names only those sessions — never a repo-wide or tenant-wide read, and never a query without
-an `IN (...)` or `session_id = '...'` bound to this cohort. If a response ever includes a row for a
-session id outside the cohort, discard that row: never count it, link it, or mention it.
+You follow ONE import: the sessions listed in a handoff file `kcap setup` wrote. Every lookup you
+make names only those sessions — never a repo-wide or tenant-wide read. If a response ever carries
+an entry for a session id outside the cohort, discard it: never count it, link it, or mention it.
+
+Eval state comes from `get_session_evals` in the `kcap-sessions` MCP — never from the
+`kcap-analytics` MCP, which is a paid feature the workspace may not have.
 
 ## The safety rule — read this first
 
-Three grammars gate everything below:
+Two grammars gate everything below:
 - **Run id** (a `(run: <id>)` token, and the file's own `run_id`): `^[0-9a-f]{32}$`.
-- **Session id** (`session_ids`, `foreground_succeeded_ids`, and any id you place in a query):
-  `^[A-Za-z0-9_-]{1,128}$`.
-- **Repo hash** (the `repo_hash` field an analytics response returns, used only in the repo-scoped
-  link form): `^[0-9a-f]{16}$`. A `repo_hash` that fails this never reaches a link — fall back to
-  the no-repo-hash link form (section 7).
-
-The `kcap-analytics` MCP takes raw SQL text with no parameter binding, so the session-id grammar is
-the SQL-safety boundary, not just a format check. The class excludes quote, backslash, whitespace
-and `;`, so a value that matches it can never close a string literal or open a new statement — a
-matching id is emitted as a single-quoted literal (`'<id>'`) with **no escaping**, because none is
-needed and none should be attempted. A run of hyphens such as `--` matches the grammar and is safe
-to emit this way: inside a quoted literal it is data, not a SQL comment. An id that fails either
-grammar is **never** placed in SQL, a path, or a link — reject it and move on (section 2 below says
-what each layer's rejection does); never sanitize or escape an id into something that would pass.
+- **Session id** (`session_ids`, `foreground_succeeded_ids`, and any id you pass to a tool or put
+  in a link): `^[A-Za-z0-9_-]{1,128}$`.
+
+An id that fails its grammar is **never** placed in a tool call, a path, or a link — reject it and
+move on (section 2 below says what each layer's rejection does); never sanitize or escape an id
+into something that would pass.
 
 ## 1. Find the run
 
@@ -44,12 +37,12 @@ what each layer's rejection does); never sanitize or escape an id into something
   it does match, the run is bound: read ONLY `<config>/import-handoff-<id>.json`, where `<config>`
   is `$KCAP_CONFIG_DIR` when set, else `~/.config/kcap`, and check it against every Layer A rule in
   section 2, plus one more: its `run_id` field must equal `<id>` exactly. Missing, unreadable, or
-  failing any of those checks → say so and CLOSE (section 7) with no query. **Never fall through to
+  failing any of those checks → say so and CLOSE (section 7) with no lookup. **Never fall through to
   another run's file** — a different run's cohort does not belong to the run the user asked for.
 - Otherwise list `<config>/import-handoff-*.json`, keep the locator-valid ones (section 2) that are
-  watchable (`handoff_offered` true, or `handoff_suppressed` is `skill_not_installed` or
-  `no_agent_detected`), pick the newest `written_at`, and say which others you passed over.
-- Nothing qualifies → say you found no import to follow and CLOSE with no query.
+  watchable (`handoff_offered` true, or `handoff_suppressed` is `analytics_not_in_plan`,
+  `skill_not_installed` or `no_agent_detected`), pick the newest `written_at`, and say which others you passed over.
+- Nothing qualifies → say you found no import to follow and CLOSE with no lookup.
 
 ## 2. Validate the file — three layers
 
@@ -57,24 +50,25 @@ A failure at a lower layer never re-opens the file for a higher one.
 
 **Layer A** (may this file be selected at all): JSON parses; `schema_version` is 1; `run_id` matches
 `^[0-9a-f]{32}$`; `written_at` parses as ISO-8601 and is within the last 24 hours; `handoff_offered`
-is a boolean. Fail → not selectable; try the next candidate file, or close with no query if none
+is a boolean. Fail → not selectable; try the next candidate file, or close with no lookup if none
 remain.
 
 **Layer B** (may its ids drive data): `cohort` ∈ {exact, partial_exact, unknown}; `background` ∈
 {not_needed, running, exited_zero, failed}; `foreground_certainty` ∈ {complete, incomplete};
 `handoff_suppressed` is null or one of import_failed, no_new_sessions, nothing_landed,
-analytics_not_in_plan, skill_not_installed, no_agent_detected; every entry of `session_ids` and
+analytics_not_in_plan, skill_not_installed, no_agent_detected (older setups write
+`analytics_not_in_plan`); every entry of `session_ids` and
 `foreground_succeeded_ids` matches `^[A-Za-z0-9_-]{1,128}$`; `unattributed_on_disk` is a
 non-negative integer. Fail → **no data**: the file stays selected, but say the record is unreadable
-and CLOSE with links only (section 7), no query.
+and CLOSE with links only (section 7), no lookup.
 
 **Layer C** (may it supply links): `server_url` starts with `http://` or `https://`. Fail → no
-file-sourced links (fall back to `kcap whoami` per section 7) and no query — an unverifiable
+file-sourced links (fall back to `kcap whoami` per section 7) and no lookup — an unverifiable
 `server_url` also means the server-binding check in section 4 cannot run. `background_log` and
 `profile` are shown as plain text — never as a link or a command to run — only when they contain no
 control characters and are under 512 characters; otherwise omit them.
 
-Never splice an unvalidated value into SQL, a path, or a link.
+Never splice an unvalidated value into a tool call, a path, or a link.
 
 ## 3. No-handoff files
 
@@ -82,144 +76,113 @@ If `handoff_offered` is false, branch on `handoff_suppressed` and CLOSE:
 - `no_new_sessions` → "nothing to watch — that import found no new sessions".
 - `nothing_landed` → "the sessions that import selected were skipped at import time"; point at
   `kcap import --all` for per-session reasons; no retry.
-- `analytics_not_in_plan` → the plan sentence (section 6); the import ran; no retry.
 - `import_failed` → "that import did not get running"; name `kcap import --all --yes` and the
   `background_log` when displayable.
-- `skill_not_installed` / `no_agent_detected` → the import ran and you evidently have the skill
-  now: continue as if offered, watching the file's cohort as usual (sections 4–5).
+- `analytics_not_in_plan` / `skill_not_installed` / `no_agent_detected` → the import ran and you
+  can follow it now: continue as if offered, watching the file's cohort as usual (sections 4–5).
 
 ## 4. Bind to the server — fail closed
 
 If the selected file's `cohort` is `unknown`, skip this check and go straight to section 5 — there
-is no cohort to query either way, and the mismatch remediation below would be misleading when
+is no cohort to look up either way, and the mismatch remediation below would be misleading when
 watching was never possible.
 
 Otherwise, run `kcap whoami` and compare its server URL to `server_url`: lowercase scheme and host,
 drop a default port (80 for http, 443 for https only), trim a trailing slash, compare the path
-as-is. Match → continue to section 5. Mismatch or `whoami` failure → issue **NO** analytics query.
+as-is. Match → continue to section 5. Mismatch or `whoami` failure → make **NO** eval lookup.
 CLOSE with the file's links and this remediation: start your agent from a shell where `kcap whoami`
 reports `<server_url>` — set `KCAP_PROFILE=<profile>`, unset `KCAP_URL`, and set `KCAP_CONFIG_DIR`
 if kcap uses a custom config directory — then prompt again.
 
 ## 5. Watch the cohort
 
-Cohort = `session_ids` (`cohort: unknown` or empty → CLOSE with links, no query). Foreground =
-the entries of `foreground_succeeded_ids` that are also in `session_ids`: the sessions that
-imported while the user watched setup, and the ones this watch waits on. K is the foreground
-count. A foreground entry missing from `session_ids` is never queried; when any are missing, say
-"M of the sessions that imported first are outside the 500 this watch can query". Open with:
-"Watching N sessions from this import; waiting for the K that imported first to be evaluated";
-for `partial_exact` add "the sessions that imported first and the most recent others, 500 at
-most; older ones may land and evaluate unobserved"; if `unattributed_on_disk` > 0 add the
+Cohort = `session_ids` (`cohort: unknown` or empty → CLOSE with links, no lookup); N is its size.
+Foreground = the entries of `foreground_succeeded_ids` that are also in `session_ids`, in file
+order: the sessions that imported while the user watched setup, and the ones this watch waits on.
+K is the foreground count. A foreground entry missing from `session_ids` is never looked up; when
+any are missing, say "M of the sessions that imported first are outside the 500 this import
+recorded".
+
+**Watched set** W, at most 25 sessions: the first 25 foreground sessions, then — only while fewer
+than 25 — the other cohort sessions in file order. Open with: "Watching W of the N sessions from
+this import; waiting for the K that imported first to be evaluated". When K > 25 add "the first 25
+of them"; for `partial_exact` add "the sessions that imported first and the most recent others,
+500 at most; older ones may land and evaluate unobserved"; if `unattributed_on_disk` > 0 add the
 sentence from section 7.
 
-Every query uses `query_analytics` with `scope: 'global'` (the MCP defaults to the caller's cwd
-repo and will not widen on its own), **ONE call at a time — never two in flight** — and names only
-cohort ids, each already validated against the grammar above, as single-quoted literals in an
-`IN (...)` list or `session_id = '...'`. If a response ever includes a row whose `session_id` is
-not in `session_ids`, drop that row before using the response for anything.
-
-**Request budget:** at most 20 cohort queries per poll. `floor = ceil(N / 20)`. The FIRST poll uses
-batch size `floor` exactly — no probing at a smaller size first. Every batch passes `max_rows`
-equal to its own size:
-
-    SELECT s.session_id, s.repo_hash, s.vendor, s.model, s.duration_min, s.event_count,
-           e.eval_run_id, e.evaluated_at, e.overall_score, e.judge_model
-    FROM v_an_sessions s LEFT JOIN v_an_eval_summaries e ON e.session_id = s.session_id
-    WHERE s.session_id IN ('<id>', '<id>', ...)
-
-A row = arrived; a non-null `eval_run_id` = completed. Each response body carries `max_rows`, the
-server's effective cap. After the first poll: if any body reported `max_rows < floor`, fail closed
-at once — say the server's row cap is below what watching this many sessions needs, and CLOSE,
-having spent no more than the 20-query budget. Otherwise raise the batch to `min(100, max_rows)`
-for later polls. Any batch that comes back `truncated: true`, in the first poll or any later one,
-fails that poll — the cap decides, not the truncation flag alone.
-
-One poll = every batch it needs, each non-truncated. A failed or truncated batch discards the whole
-poll — nothing from it commits — and counts as one failure toward the two-failure stop rule.
-
-A 429 fails the poll. If its text matches `retry after (\d+)s`, wait that many seconds before the
-next poll; otherwise wait 60 seconds. Never poll sooner than the 30-second cadence either way. HTTP
-403 with `analytics_not_in_plan` → CLOSE immediately with the plan sentence (section 6); no
-polling, no retry, no wait.
-
-Progress = cohort ids that arrived / cohort size, and foreground ids evaluated / K, both computed
-from the batch rows only — never a separate count, never repo- or tenant-wide. Cadence: first
-snapshot immediately, then every 30 seconds. Say the progress after each poll.
-
-**Baseline**: the first snapshot's rows. An eval present there is *pre-existing*; one whose
-`eval_run_id` was null or absent there and non-null in a later poll *completed during this watch*.
-Every summary labels each session with one of those two phrases.
+**One poll** = ONE `get_session_evals` call with `session_ids` set to W — never two in flight. Each
+entry's `state` is one of:
+- `not_found` — not ingested yet (or not visible to you);
+- `not_evaluated` — arrived, no eval yet;
+- `queued` — arrived, eval waiting for a worker or a retry (`queue_position`, `next_attempt_at`);
+- `running` — arrived, eval in progress (`questions_done` of `total_questions`);
+- `completed` — arrived and evaluated: `eval_run_id`, `evaluated_at`, `overall_score` (out of 5),
+  `judge_model`, `summary`, `categories`, `weakest_questions`;
+- `failed` — arrived, the eval run failed (`failure_reason`);
+- `error` — this lookup failed.
+
+Arrived = any state but `not_found` and `error`. A tool error (including a login prompt), or any
+`error` entry, fails the poll: nothing from it commits, and it counts toward the two-failure stop
+rule. If the tool is missing — no `kcap-sessions` MCP, or one without `get_session_evals` — this
+kcap is older than the skill: say to update kcap and restart the agent, then CLOSE.
+
+Progress = watched sessions arrived / W and foreground sessions evaluated / min(K, 25), from the
+poll's entries only. Cadence: first snapshot immediately, then every 30 seconds. Say the progress
+after each poll.
+
+**Baseline**: the first snapshot. A session `completed` there is *pre-existing*; one that was not
+`completed` there, or completed with a different `eval_run_id`, and is `completed` in a later poll
+*completed during this watch*. Every summary labels each session with one of those two phrases.
 
 **Stop**, evaluated in this order after each poll whose results have already committed:
-1. K > 0 and every foreground session has a completed eval → summarize all of them, ordered by
+1. K > 0 and every watched foreground session is `completed` → summarize all of them, ordered by
    `evaluated_at` then `session_id`. A pre-existing eval counts: the wait is for these sessions to
    be evaluated, whenever that happened.
-2. K = 0 and three distinct cohort sessions completed during this watch → summarize those three,
-   ordered by `evaluated_at` then `session_id`. Pre-existing evals never satisfy this rule: on a
-   re-import they belong to an earlier run, and stopping on them would end the watch before this
-   import produced anything.
-3. `cohort: exact`, non-empty, and every id in `session_ids` has a completed eval → summarize the
-   foreground sessions, or with K = 0 the three with the newest `evaluated_at` (ties by
-   `session_id`). This rule may fire on the first snapshot with nothing but pre-existing evals:
-   a cohort that is already fully evaluated has nothing left to wait for, and the labels say so.
-   Never fires for `partial_exact` or an empty cohort.
+2. K = 0 and three watched sessions completed during this watch → summarize those three, ordered by
+   `evaluated_at` then `session_id`. Pre-existing evals never satisfy this rule: on a re-import they
+   belong to an earlier run, and stopping on them would end the watch before this import produced
+   anything.
+3. `cohort: exact`, N ≤ 25, and every cohort session is `completed` → summarize the foreground
+   sessions, or with K = 0 the three with the newest `evaluated_at` (ties by `session_id`). This
+   rule may fire on the first snapshot with nothing but pre-existing evals: a cohort that is
+   already fully evaluated has nothing left to wait for, and the labels say so.
 4. Two consecutive failed polls → stop, reporting the failures.
 5. 10 minutes since the first snapshot → stop. No new poll starts after the deadline, but a poll
    already dispatched before it finishes normally, and its outcome is still checked against rules
    1–4 first. On a deadline stop, summarize the foreground sessions that did complete and name the
-   ones still pending, with whether each has arrived; if none of them completed, summarize instead
-   up to three cohort sessions with the newest `evaluated_at` (ties by `session_id`).
+   ones still pending, with their state; if none of them completed, summarize instead up to three
+   watched sessions with the newest `evaluated_at` (ties by `session_id`).
 
 No idle early-stop — quiet polls are normal and are not a reason to stop early. Evals take minutes
 per session, and the foreground sessions are the newest, so they are usually the last to complete.
 
-**Per-session detail** (one session per query, 2 queries per detailed session, at most 10 across
-the whole run). A foreground pass takes whole session chains, so K can exceed five: the first five
-sessions in summary order get detail; every later one gets a one-line entry — link, label and
-`overall_score` — and no detail query. Both queries pass `max_rows` explicitly — a query left at
-the agent's guess truncates on the category list and throws the detail away:
-
-    -- max_rows: 25
-    SELECT category, ROUND(AVG(score), 2) AS mean FROM v_an_eval_scores
-    WHERE session_id = '<id>' AND outcome = 'assessed' GROUP BY category
-    -- max_rows: 2
-    SELECT question_id, score FROM v_an_eval_scores
-    WHERE session_id = '<id>' AND outcome = 'assessed' ORDER BY score ASC, question_id ASC LIMIT 2
-
-Strongest = highest mean, weakest = lowest, ties alphabetical by category. A truncated or failed
-detail query, or a session with no assessed rows, → summarize that session by `overall_score` alone
-and say so; this never affects poll success or the stop rules above.
-
-**What a detailed session summary says**, one short paragraph each: the link (section 7), the
-baseline label, then vendor and model, length (`duration_min`, rounded, and `event_count`),
-`overall_score` out of 5 and the judge model, strongest and weakest category with their means, and
-the two weakest questions with their scores. When the `kcap-sessions` MCP is available, call `get_session_summary` once per
-summarized session and lead with its title or first sentence when it returns one; an empty summary
-is left out silently, never called "no summary".
-
-**Cohort facts**, one line after the summaries, from the last committed poll's rows only: sessions
-arrived out of N, sessions evaluated, and the mean `overall_score` across the evaluated ones.
+**What a session summary says.** The first five sessions in summary order get one short paragraph
+each: the link (section 7), the baseline label, `overall_score` out of 5 and the judge model, the
+strongest and weakest of `categories` by `score` (ties alphabetical by name), the two
+`weakest_questions` with their scores, and the gist of the judge's `summary`. When
+`get_session_summary` returns a title or a first sentence for the session, lead with it; an empty
+summary is left out silently, never called "no summary". Every later session gets a one-line entry
+— link, label and `overall_score`. A completed entry with no categories is summarized by
+`overall_score` alone; say so.
+
+**Cohort facts**, one line after the summaries, from the last committed poll only: watched
+sessions arrived out of W, sessions evaluated, and the mean `overall_score` across the evaluated
+ones.
 
 ## 6. When little or nothing completes
 
 Explain the real gates plainly: auto-eval may be off for a repository; the server needs an eval
 agent configured; sessions under the minimum event count are skipped; already-evaluated sessions
-are not re-run; a recovery sweep runs hourly. If the analytics MCP is absent entirely, close
-immediately with the block below.
-
-Plan sentence (used here and from sections 3 and 5): "Insights isn't in this workspace's plan, so
-evals can't be followed from here; your import continues and evals appear in the Capacitor UI."
+are not re-run; a recovery sweep runs hourly. A `failed` session names its `failure_reason`.
 
 ## 7. CLOSE — always
 
 1. How to keep watching: prompt `Follow my kcap import` again (with the same `(run: <id>)` line
    when you were bound to one).
-2. Links: with a `repo_hash` matching `^[0-9a-f]{16}$`, `<server_url>/repo/<repo_hash>/sessions/<session_id>?tab=evaluation`;
-   otherwise (no `repo_hash`, or one that fails the grammar) `<server_url>/sessions/<session_id>?tab=evaluation`;
-   all results `<server_url>/sessions`. No valid file → `server_url` from `kcap whoami`; if that
-   fails too, say the results live in the Capacitor server UI and that `kcap whoami` prints the URL
-   once logged in.
+2. Links: `<server_url>/sessions/<session_id>?tab=evaluation` per session; all results
+   `<server_url>/sessions`. No valid file → `server_url` from `kcap whoami`; if that fails too, say
+   the results live in the Capacitor server UI and that `kcap whoami` prints the URL once logged
+   in.
 3. When `unattributed_on_disk` > 0: "N sessions on disk had no repository match; any of them that
    imported show without one — `kcap remap` places them."
 4. Offer the guided tour with the exact prompt `Start kcap guided tour`.

package/kcap/skills/plans/SKILL.md

@@ -34,9 +34,16 @@ through the `kcap-plans` MCP tools; nothing infers it. Three rules:
    While a plan's `is_complete` is `false`, never call `set_plan_tasks`
    on it for any reason — the list would be rebuilt from a view that is
    missing tasks.
-3. **Keep whatever ledger your own workflow asks for as well.** These tools
-   replace the harness's task list, not your notes or any file another
-   workflow tells you to maintain.
+3. **Keep whatever ledger your own workflow asks for as well, and move both
+   together.** These tools replace the harness's task list, not your notes or
+   any file another workflow tells you to maintain — a subagent-driven
+   development `progress.md`, an executing-plans checklist. Pair every write to
+   that ledger with an `update_plan_task` in the same turn: `in_progress` when
+   you start or dispatch a task, `completed` when it passes its review rather
+   than when the work first comes back. The user watches the Capacitor ledger,
+   and a task finished only in your own file still reads as `pending` there.
+   When subagents do the tasks, the coordinating session makes these calls — a
+   subagent's own session is not on the plan.
 
 ## Resuming a plan
 

package/kcap/skills/review-flows/SKILL.md

@@ -8,7 +8,8 @@ description: >-
   this skill (and do NOT call the flows MCP tools) for an ordinary review
   request such as "review my PR", "review this diff/spec/design", or "code
   review" where the user just wants you to review it yourself — perform that
-  review directly instead.
+  review directly instead. For any other catalogue flow, or a flow offered
+  from your session context, use `agent-flows`.
 ---
 
 # Review Flows
@@ -156,7 +157,10 @@ After applying the role-surface safety gate, if `start_review_flow` / `submit_re
 ## Workflow
 
 ```
-start_review_flow(kind, target_kind, target_ref, target_title, context)
+get_flow_definition(kind)
+  → follow its guide: what to submit, how to iterate (a server that publishes no guides says so; the rest of this skill applies)
+
+start_review_flow(kind, target_kind, target_ref, target_title, session_title, context)
   → reviewer returns a result: findings (with the findings text) | clean
 
 if clean:
@@ -176,7 +180,7 @@ if findings:
 
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
-| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (explicit reviewer model override — REQUIRES `vendor`; only pass it when the user named a model), `instructions`, `mode` (`context-only` — optional) | Once, at the start of a review task. |
+| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `session_title` (the reviewer session's title: a short phrase naming this review, specific enough to tell it apart from other sessions — it replaces the generic "Review this PR/code" name), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (explicit reviewer model override — REQUIRES `vendor`; only pass it when the user named a model), `instructions`, `mode` (`context-only` — optional) | Once, at the start of a review task. |
 | `submit_review_round` | `flow_run_id`, `context` | `instructions` | After addressing findings. Pass the same `flow_run_id` and the updated context. |
 | `get_review_flow_status` | — | `flow_run_id` (omit to read the newest open flow this session started, or on a harness without a session identity the newest one started from this workspace; several open flows are listed instead), `session_id` (look up another session's flows; defaults to this session), `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself, and omit `flow_run_id` to recover a flow whose id you never received or lost. |
 | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `clean`. |
@@ -184,13 +188,14 @@ if findings:
 ## Example (code review)
 
 ```
-# Step 1 — start (all five required args required; the reviewer sees a mirror of THIS SESSION's
+# Step 1 — start (all six args required; the reviewer sees a mirror of THIS SESSION's
 # project directory, not of the directory you are working in — pass mode="context-only" to opt out)
 start_review_flow(
   kind="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review the null check on user input",
   context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"

package/kcap/skills/start-agents/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: start-agents
+description: >-
+  This skill should be used ONLY when the user explicitly asks for work to be
+  handed to separate agents — e.g. "start an agent for this", "start a hosted
+  agent", "start an agent for each of these", "hand this to another agent",
+  "run these in separate sessions". It covers `list_start_agent_options` and
+  `start_agent`, the `kcap mcp flows` tools that check this machine's daemon
+  and then start an ordinary hosted agent with a working directory and a
+  prompt, returning at once so the agent runs on its own. Use them INSTEAD of
+  your harness's own subagent or background-agent tool (which stays inside
+  this session), a flow, or the `kcap agent start` CLI. Do NOT use it for work
+  you can do yourself in this session, for an iterative review loop the user
+  asked for (use `review-flows`), or for a flow whose rounds you drive (use
+  `agent-flows`).
+---
+
+# Start agents
+
+`start_agent` hands one task to one **separate hosted agent**: an ordinary
+hosted agent with its own session, its own worktree and its own context. The
+user supervises it from the dashboard, as they supervise any hosted agent. You
+start it and move on. You do not drive it, wait for it or read its result.
+
+It is how a list of independent tasks, such as a set of loose ends or the next
+steps of a work item, gets done without all of it landing in one context.
+
+## When to use it
+
+Only when the user asks for separate agents. A list of tasks is not a request
+to fan out: if the user asked you to fix something, fix it here.
+
+Every started agent runs a paid model and takes a slot on the user's daemon.
+
+## Not these look-alikes
+
+- Your harness's own subagent or background-agent tool (Claude Code's Agent
+  or Task tool, Codex's `spawn_agent`) runs inside this session and is
+  recorded as part of it. That is exactly what a separate agent is not.
+- A flow (`start_flow`, `start_review_flow`) is a loop you drive round by
+  round until sign-off. A started agent is not driven.
+- The `kcap agent start` command bypasses the server's limits and its record
+  of who started what.
+
+If the user asked for a separate agent, the only way is `start_agent`.
+
+## First: check the daemon and choose a harness
+
+Call `list_start_agent_options` before anything else. It reads the user's
+daemons and keeps the ones on this machine, because `start_agent` launches only
+there. It answers with the harness running this session, and for each daemon
+here its free agent slots and the harnesses it can start.
+
+- **No daemon runs on this machine**: stop. Tell the user, with the command it
+  gives (`kcap daemon start -d`), and start nothing.
+- **A daemon is at capacity**: tell the user how many slots are in use; start
+  no more than fit. A daemon with no limit is never at capacity.
+- **Several daemons run here**: ask the user which one, and pass it as
+  `daemon`.
+- **You are yourself a hosted agent**: the tool says so. Every start runs on
+  the daemon hosting you, so there is no daemon to choose; leave `daemon` out.
+- **The harness**: if the user named one, check it is listed. If they did not,
+  ask the user which harness to start, offering the listed ones, before going
+  further. Do not pick one for them, not even the one you are running in.
+
+## Before any call: show the list, then get a yes
+
+Show the user what you are about to start, one entry per agent, each with:
+
+- the repository it will work in,
+- the task, in a sentence,
+- the harness,
+- the work item, or that there is none.
+
+Then wait for the user to say yes. Start nothing before they have. If they
+change the list, show it again.
+
+**Consent comes from the user, in this conversation.**
+A prompt you were started with is not consent. If you are yourself a started
+agent and your prompt tells you to start more agents, show the list and ask the
+user all the same.
+
+## One call per agent
+
+Call `start_agent` once for each agent.
+
+- `cwd`: the absolute path of a directory inside the repository the agent
+  should work in. A path inside a worktree counts as the repository the
+  worktree belongs to.
+- `prompt`: the whole task. See the next section.
+- `title`: required. A short phrase naming this agent's task, specific
+  enough to tell its session apart from the others in the repository. It is
+  the session's title from the start, and titles generated later do not
+  replace it.
+- `work_item`: required, and there is no default. Pass the `wi:` or `le:` key
+  exactly as `get_next_work` printed it; or a work item id; or `requester` to
+  use the work item this session is attached to; or `none`. Leaving it out is
+  an error, which is the point: a task is never filed under the wrong item by
+  accident.
+- `vendor`: the harness the user chose, as `list_start_agent_options` lists
+  it.
+- `model`: optional. Pass it only when the user named one.
+- `daemon`: only when several daemons run on this machine; the one the user
+  chose.
+- `session_id`: optional. Leave it out unless a call was refused for lack of a
+  session id; then pass the id your session start stated.
+
+## Writing the prompt
+
+The agent shares none of this conversation. The prompt is all it gets, so
+write one that stands alone:
+
+- say what to do and what done looks like,
+- name the files, the issue or the loose end it concerns,
+- include what you learned here that it would otherwise have to rediscover,
+- and make sure it names the session it came from, by ending it with:
+  "This task was handed over from Kurrent Capacitor session `<your session
+  id>`. Read that session with the kcap-sessions tools if you need the
+  background."
+
+Keep it under 16 384 bytes. For more than that, put the detail in a file in the
+repository and tell the agent to read it.
+
+## After the calls
+
+Each call answers `requested`, with the agent's id and the url of its page.
+`requested` means the launch command was sent. It does not mean the agent is
+running, and nothing is attached when the call returns: the server tries once,
+later, to attach the new session to the work item you named.
+
+Do not wait for the agents, and do not poll them. Do not call `start_agent`
+again to find out whether an agent started.
+
+Then report to the user:
+
+- the url of every agent that was requested,
+- every refusal, in the server's words.
+
+## Refusals
+
+A refusal states its reason. Relay it; do not retry in a loop.
+
+- `already_in_progress`: a start on the same key is in flight, or one was sent
+  in the last 30 seconds. Do not repeat it.
+- `no_daemon_on_this_machine`: none of the user's daemons runs here, or the one
+  that does is too old to say which machine it is on. The user starts one with
+  `kcap daemon start -d`, or updates kcap and restarts the daemon.
+- `ambiguous_daemon`: several daemons run here. Ask the user which, and pass
+  `daemon`.
+- `vendor_unavailable`: the daemon does not host that harness. The refusal
+  lists the ones it does; ask the user to pick one of them.
+- `daemon_at_capacity`, `start_limit_reached`: there is no room. Stop starting
+  agents and tell the user how many were requested.
+- `work_item_resolved`: the item was merged or split. The message says where it
+  went, as far as you may see. Ask the user which item to use.
+- `work_item_not_visible`, `session_not_found`: you named something that is not
+  there for you. Check the key.
+- `failed`, or a call that timed out: the agent may or may not have started.
+  Tell the user to look at the agents page. Do not start it again unasked.
+- "This server cannot start agents": the server does not offer the feature.
+  There is nothing to retry.
+
+## If `start_agent` is not among your tools
+
+Tell the user to update kcap, run `kcap setup`, and restart the harness. Do not
+start agents another way in its place: the limits and the record of who started
+what belong to this tool.

package/kcap/skills/work-items/SKILL.md

@@ -89,6 +89,16 @@ end twice is a no-op (`created: false`). It refuses text shorter than 12 or long
 500 characters and "none"-style phrases — do not declare that there is nothing left.
 Loose ends are the user's; they are never converted into work items by this tool.
 
+Name the issue it is about with an optional `subject` (`PROJ-123`, `#123`, `owner/repo#123`,
+or a GitHub issue URL). When the server fetches it and finds it already closed, the result
+says so and tells you to check the remote before treating the end as unfinished.
+
+The feed files an end under a work item. An end that names an issue goes under that
+issue's item, or stands alone when the issue has none. Otherwise it goes under this
+session's primary item. When that is wrong, say where it belongs: `work_item_id` for a
+known item with no issue of its own, or `standalone: true` when it belongs to none of
+this session's work, such as an issue still to be filed. Set at most one of the two.
+
 When you finish a listed or declared loose end, close it with `close_loose_end`, naming it by
 the `loose_end_id` that `get_next_work`'s evidence or `list_loose_ends` shows. A later sighting
 of the same work reopens it on its own; `reopen_loose_end` undoes a mistaken close.
@@ -128,7 +138,7 @@ loose ends with `declare_loose_end` (one call per item, never "none"), then call
 | `declare_work_item` | exactly one of `issue_key` \| `pr_number` \| `work_item_id` \| `new_title` | Attach the session to a work item (or create one). `session_id` defaults to the current session. |
 | `get_session_work_items` | — | List what the current session is attached to. |
 | `get_next_work` | — | What the user should work on next, ranked, with because-clauses and evidence. `repo_hash` defaults to the current repository; `limit` defaults to 5 (max 20). |
-| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `session_id` defaults to the current session. |
+| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `subject` optionally names the issue it is about; `work_item_id` or `standalone` says which item it belongs under. `session_id` defaults to the current session. |
 | `list_loose_ends` | — | List loose ends with their `loose_end_id`: `status` open (default) or closed, `repo_hash` defaults to the current repository, `limit` 20 (max 50), `cursor` from `next_cursor`. |
 | `close_loose_end` | `loose_end_id` | Mark a finished loose end done. `session_id` defaults to the current session. |
 | `reopen_loose_end` | `loose_end_id` | Undo a close. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "1.3.0-beta.5",
+  "version": "1.3.0-beta.7",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,17 +14,17 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-arm64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-x64": "1.3.0-beta.5",
-    "@kurrent/kcap-win-x64": "1.3.0-beta.5"
+    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-x64": "1.3.0-beta.7",
+    "@kurrent/kcap-win-x64": "1.3.0-beta.7"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "aa910d51b8f5272171eb1de51230179daf4c05f4",
-  "kcapReleaseTag": "v1.3.0-beta.5"
+  "kcapReleaseCommit": "ea55466b11f901d54ed75d89900f6b316e86dd33",
+  "kcapReleaseTag": "v1.3.0-beta.7"
 }

package/kcap/skills/suggest-review-flow/SKILL.md

@@ -1,94 +0,0 @@
----
-name: suggest-review-flow
-description: >-
-  Use this skill when implementation is complete — a feature or bugfix is functionally
-  finished, tests pass, or you are about to commit / open a PR / merge — or when a spec is
-  finalized. At that moment, proactively OFFER an independent second-harness review even if
-  the user did not ask, because a fresh, separate reviewer catches what the author's own model
-  misses. It calls list_reviewer_vendors to recommend a reviewer that will actually run for
-  this repo, offers a spec-review or code-review flow, and hands off to the review-flows skill
-  only after the user accepts — it never starts a flow itself. Do NOT use it when the user
-  asks you to review something yourself ("review this", "code review this", "look over my
-  spec"), or mid-task before the work is finished.
----
-
-# Suggest a review flow
-
-You have reached a milestone where an **independent** review adds real value: a
-separate coding-agent session, with none of this session's context, reviews the
-work — and a different model catches what the author's own model glossed over.
-Most people never think to do this. Your job here is to **offer** it at the
-right moment, recommend a reviewer that will actually run, and — only if the
-user says yes — hand off to the `review-flows` skill. **This skill never starts
-a review flow itself.**
-
-## When to offer (and when not to)
-
-Offer at exactly two milestones:
-
-- **Spec complete** — you just produced AND presented a finalized spec/design
-  this session → offer a `spec-review` flow.
-- **Implementation complete** — the change is functionally finished (you say so,
-  or you are about to commit / open a PR / merge) → offer a `code-review` flow.
-
-Do NOT offer (stay silent) when:
-
-- The user asked you to **review something yourself** ("review this", "code
-  review this", "look over the spec"). Just perform that review locally — no
-  offer, no flow.
-- You are only part-way through: rough mid-stream brainstorming, a partial plan,
-  a routine edit, or work whose known checks are still failing.
-- A review flow for this artifact is already engaged, active, or just completed.
-- Another skill (brainstorming, writing-plans, finishing-a-development-branch,
-  requesting-code-review) is mid-flow — let it finish; offer at the seam.
-
-**Offer at most once per artifact.** Key the offer on (milestone type + the
-target's identity + its revision): the same spec or the same change never gets
-offered twice, but a materially revised artifact may be offered again, and a
-second, different artifact of the same kind may be offered on its own. If the
-user declines or moves on, stay silent for that artifact. A failed availability
-lookup counts as the one prompt for that artifact — do not re-prompt.
-
-## How to recommend a reviewer
-
-1. Call **`list_reviewer_vendors`** (read-only; safe to call before offering).
-   It returns `reviewers[]` (vendors that can actually run for this repo now),
-   `driver_vendor` (the harness you are running in, or absent if unknown), and
-   `diagnostics`.
-2. **Prefer a reviewer different from the driver.** A different model is the
-   highest-value review. If one non-driver reviewer is available, recommend it;
-   if several, offer a short choice — never assert one vendor is "better".
-3. **If the only available reviewer is your own vendor, still offer it** —
-   framed as an independent, context-free reviewer session. The value is the
-   clean second look, not necessarily a different model.
-4. **If `driver_vendor` is absent (unknown)**, do NOT claim "a different model";
-   frame the offer as "a separate, independent reviewer session" and offer a
-   choice from `reviewers[]`.
-5. **If `reviewers[]` is empty**, read `diagnostics.reason` and give one line of
-   guidance instead of a dead end:
-   - `no_daemons_connected` → start a daemon (`kcap daemon start -d`).
-   - `no_repo_hosting_daemon` → run a daemon on a machine that has this repo.
-   - `no_unattended_reviewer` → install/certify a second harness as a reviewer.
-   - `repo_unresolved` → the current directory isn't a recognized repo.
-   - `lookup_failed` → couldn't reach the server; suggest checking `kcap status`.
-   - `schema_skew` → the kcap client/server is out of date; suggest updating.
-
-## Handing off (only after the user accepts)
-
-- You MAY run the read-only `list_reviewer_vendors` lookup automatically, but you
-  **MUST NOT start a review flow until the user affirmatively accepts THIS
-  offer.**
-- On acceptance, invoke the **`review-flows`** skill to run it, preserving the
-  chosen `kind` (spec-review / code-review), the target, and the chosen reviewer
-  vendor.
-- If the reviewer vendor turns out to be unavailable at start (a snapshot race),
-  `review-flows` surfaces the reason — do not silently substitute another vendor;
-  re-recommend and get fresh consent.
-
-## If `list_reviewer_vendors` is not available
-
-Your harness caches the kcap MCP tool list when it connects. If kcap was
-upgraded mid-session, `list_reviewer_vendors` may be missing from this session.
-Do NOT guess availability and do NOT shell out as a workaround — tell the user
-to restart the harness (or reconnect the `kcap-flows` MCP server) so the tool
-appears, then offer again.