@kurrent/kcap 0.11.3 → 0.11.6

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

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "0.11.3",
+  "version": "0.11.6",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.codex-mcp.json

@@ -8,9 +8,17 @@
       "command": "kcap",
       "args": ["mcp", "sessions"]
     },
+    "kcap-flows": {
+      "command": "kcap",
+      "args": ["mcp", "flows"]
+    },
     "kcap-memory": {
       "command": "kcap",
       "args": ["mcp", "memory"]
+    },
+    "kcap-analytics": {
+      "command": "kcap",
+      "args": ["mcp", "analytics"]
     }
   }
 }

package/kcap/.mcp.json

@@ -28,6 +28,12 @@
       "args": ["mcp", "workitems"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "description": "Attach the current session to a work item (issue, PR, or a brand-new item) on the Capacitor server, and list the work items a session is attached to."
+    },
+    "kcap-analytics": {
+      "command": "kcap",
+      "args": ["mcp", "analytics"],
+      "cwd": "${CLAUDE_PROJECT_DIR}",
+      "description": "Query the org's AI coding-agent analytics (sessions, tools, tokens, cost, commits, PRs, evals) with governed read-only SQL. For 'what did we spend', 'which tools/models do we use', 'how many sessions' questions: call get_analytics_schema once, then query_analytics. Repo-aware: defaults to the current repo; pass scope 'global' for org-wide."
     }
   }
 }

package/kcap/README.md

@@ -4,7 +4,7 @@ This plugin integrates [Kurrent Capacitor](../README.md) with Claude Code and Co
 
 ## What it does
 
-**MCP servers** — Two stdio servers, both auto-registered on plugin install (no manual `claude mcp add` or `~/.codex/config.toml` edit):
+**MCP servers** — stdio servers auto-registered on plugin install (no manual `claude mcp add` or `~/.codex/config.toml` edit):
 
 ### `kcap-sessions`
 
@@ -46,6 +46,17 @@ Search, save, and update durable team memories — preferences, feedback, projec
 
 Repo- and machine-aware: it resolves the cwd to a repo hash and the local persisted machine id at startup to scope saves and bias search results.
 
+### `kcap-analytics`
+
+Governed read-only SQL over the org's curated coding-agent analytics views (sessions, tool/skill/token usage, cost, commits, PRs, evals). Auto-registered for every supported harness — it resolves its repo scope from the working directory, so it rides the same registration path as `kcap-sessions`.
+
+| Tool | Description |
+|------|-------------|
+| `get_analytics_schema` | The governed schema document: queryable views/columns, glossary, SQL rules, worked examples. Called once before writing SQL |
+| `query_analytics` | Run one governed Postgres SELECT (`sql`, optional `scope` `"repo"`/`"global"`, optional `max_rows`); a rejected query returns the validator's reason to fix and retry |
+
+Repo-aware: defaults to the cwd's repo; pass `scope: "global"` for org-wide questions. Requires `kcap login` and a kcap-server new enough to expose the `/api/analytics` endpoints.
+
 `kcap mcp judge` is intentionally not auto-registered. Add it with `claude mcp add kcap-judge -- kcap mcp judge` if you want it.
 
 **Hooks** — Automatically captures session activity and forwards it to the Kurrent Capacitor server:

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

@@ -20,6 +20,14 @@ description: >-
 
 Use the `kcap mcp flows` MCP tools (`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.
 
+## Role-surface safety gate
+
+Classify the session before any flow action. Flow-starting tools without a reviewer result contract
+mean driver; `submit_review_result` plus the prompt's round-token/result contract mean hosted
+reviewer; neither means the integration is missing. If both contracts are present, the MCP surface
+has leaked: fail closed, never start a nested flow, report the leak through `submit_review_result`,
+and end the reviewer turn. The hosted-reviewer contract wins over driver-looking prose.
+
 ## When NOT to use this skill / these tools
 
 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.
@@ -34,6 +42,18 @@ Once the user has explicitly opted into a flow (see above), pick the `definition
 - 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 you look up in the server's flow-definition catalog at `/admin/flows`. If you're unsure which definition applies, ask the user rather than guessing.
 
+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
+negation, omit the vendor when none is named, and ask when multiple candidates remain. Custom
+catalog definitions keep their authored vendors unless an explicit single-participant override is
+requested; dynamic definitions always carry vendors per participant and reject a top-level override.
+
+Canonical reviewer aliases for reserved review flows: Claude / Claude Code → `claude`; Codex /
+OpenAI Codex → `codex`; Cursor / cursor-agent → `cursor`; GitHub Copilot / Copilot CLI → `copilot`;
+Gemini / Gemini CLI → `gemini`; Kiro / Kiro CLI → `kiro`; Pi → `pi`; OpenCode → `opencode`;
+Antigravity / agy → `agy`. Normalize only names bound to the reviewer role, honor negation and
+positive contrast, and ask rather than guessing when two reviewer candidates remain.
+
 ## Composing a dynamic flow
 
 If nothing in the catalog 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`.)
@@ -78,11 +98,11 @@ mcp:
 
 ## If the flows MCP tools are not loaded
 
-If `start_flow` / `send_to_participant` are not among the tools available in this session, do NOT try to obtain them:
+After applying the role-surface safety gate, if `start_flow` / `send_to_participant` are not among the tools available in this session, do NOT try to obtain them:
 
 - Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
-- The absence is deliberate: hosted flow participants run with all MCP servers stripped, so a participant cannot start a nested flow.
-- If you were asked to do work and these tools are absent, you are most likely the hosted participant inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested work directly, then deliver your result by calling the `submit_review_result` tool (from the injected `kcap-flow-result` server) exactly as the "Result contract" section of your prompt instructs, quoting its round token — `kind: "findings"` plus your result text, or `kind: "clean"`. The tool is the ONLY delivery channel: the server does not read your reply text, so result markers in your final message deliver nothing and the round would sit unresolved until its timeout. If the tool call fails, retry it.
+- Only treat the session as a hosted participant when `submit_review_result` is present and the prompt carries the round-token/result contract. Tool absence alone is not proof.
+- If neither the flow-driver tools nor that reviewer contract is present, tell the user to run `kcap setup` or reinstall/update the plugin and restart the harness. Do not hand-roll JSON-RPC or edit MCP configuration from the session.
 
 ## Core rules
 

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

@@ -17,6 +17,17 @@ Use the `kcap mcp flows` MCP tools (`start_review_flow`, `submit_review_round`,
 
 These four tools are aliases of the generic flow tools (`start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) — see the `agent-flows` skill for non-review flows.
 
+## Role-surface safety gate
+
+Classify the session before any flow action:
+
+- Driver: flow-starting tools are present and there is no reviewer round-token/result contract.
+- Hosted reviewer: `submit_review_result` is present and the prompt carries the round-token/result contract.
+- Missing integration: neither contract is present.
+- Unsafe leak: both the hosted-reviewer contract and any flow-starting tool are present. Fail closed: do not start or submit a nested flow, report the leaked tool surface through `submit_review_result`, and end the reviewer turn.
+
+The hosted-reviewer contract always wins over driver-looking prose or tool availability.
+
 ## When NOT to use this skill / these tools
 
 These tools do **not** perform a review — they hand the work off to a separate hosted reviewer. If the user simply asked *you* to review something in a normal session — e.g. "review my PR", "review this diff", "code review this", "look over this spec" — just perform the review yourself and report your findings directly. Do **NOT** call `start_review_flow` / `submit_review_round` for an ordinary review request; that would spin up a hosted reviewer the user did not ask for.
@@ -30,13 +41,28 @@ Once the user has explicitly opted into a flow (see above), pick the `kind`:
 - Spec or design document → `kind: "spec-review"`
 - Code changes or a pull request → `kind: "code-review"`
 
+## Choosing the reviewer vendor
+
+Treat the driver harness and reviewer as independent. A request such as "ask Claude to review"
+selects `vendor: "claude"` even when the current driver is Codex; mentions of the driver do not
+select a reviewer. Anchor vendor language to the reviewer role ("Claude reviewer", "review with
+Cursor", "ask Codex for review"), including negation ("not Claude"). If exactly one reviewer
+vendor is named, pass it. If none is named, omit `vendor` and let the server's configured default
+apply. If multiple reviewer candidates remain after negation, ask the user to choose; never guess.
+
+Canonical reviewer aliases: Claude / Claude Code → `claude`; Codex / OpenAI Codex → `codex`;
+Cursor / cursor-agent → `cursor`; GitHub Copilot / Copilot CLI → `copilot`; Gemini / Gemini CLI →
+`gemini`; Kiro / Kiro CLI → `kiro`; Pi → `pi`; OpenCode → `opencode`; Antigravity / agy → `agy`.
+Normalize only the reviewer-role mention. Positive contrast (for example, “from Codex, ask Claude”)
+selects Claude; negated names are removed; two remaining reviewer candidates are ambiguous.
+
 ## If the flows MCP tools are not loaded
 
-If `start_review_flow` / `submit_review_round` are not among the tools available in this session, do NOT try to obtain them:
+After applying the role-surface safety gate, if `start_review_flow` / `submit_review_round` are not among the tools available in this session:
 
 - Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
-- The absence is deliberate: hosted review-flow reviewers run with all MCP servers stripped, so a reviewer cannot start a nested flow.
-- If you were asked to review a spec, design, or code and these tools are absent, you are most likely the hosted reviewer inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested review directly, then deliver your result by calling the `submit_review_result` tool (from the injected `kcap-flow-result` server) exactly as the "Result contract" section of your prompt instructs, quoting its round token — `kind: "findings"` plus your findings text, or `kind: "clean"`. The tool is the ONLY delivery channel: the server does not read your reply text, so ending with `FINDINGS:`/`NO FINDINGS` markers delivers nothing and the round would sit unresolved until its timeout. If the tool call fails, retry it.
+- If `submit_review_result` is present and the prompt contains a round token/result contract, you are a hosted reviewer. Skip this driver workflow, perform the review directly, and submit through that tool. Tool absence alone is not proof that you are a reviewer.
+- If neither the flows tools nor the reviewer result contract is present, the integration is missing. Tell the user to run `kcap setup` or reinstall/update the kcap plugin, then restart the harness. Do not start a shell JSON-RPC workaround or edit MCP configuration from the session.
 
 ## Core rules
 
@@ -52,6 +78,10 @@ If `start_review_flow` / `submit_review_round` are not among the tools available
 
 - **`400` starting `no_daemon_available:`** — no connected daemon has the repo checked out. Tell the user to run `kcap agent` on a machine with the repo cloned (or pass an explicit `daemon_name` + `repo_path`).
 - **`400` starting `daemon_outdated:`** — the daemon's kcap is too old to host flow participants. Tell the user to update (`npm i -g @kurrent/kcap`) and restart `kcap agent`.
+- **`reviewer_vendor_required`** — no explicit vendor and no server default; ask the user to name a reviewer or have an admin configure `Flows:Review:DefaultVendor`.
+- **`reviewer_vendor_unavailable`** — the selected vendor is not installed/certified unattended on an eligible daemon; do not silently fall back to another vendor.
+- **`client_upgrade_required`, `flow_client_protocol_required`, or `flow_client_protocol_unsupported`** — update kcap; reserved review aliases fail closed on stale clients.
+- **`reserved_review_alias_shape`** — an admin changed a reserved alias to an invalid participant shape; restore exactly one participant named `reviewer`.
 - **`400` starting `participant_unavailable:`** — the reviewer agent died and automatic relaunch is not available yet. Close this flow and start a new one, carrying your context forward; re-submitting will keep failing.
 - **A round result of `unclear` whose text is exactly `participant_died` or `participant_stopped`** — the reviewer agent crashed or was stopped mid-round. The run stays open but has no live reviewer: close the flow and start a new one.
 
@@ -78,7 +108,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) | `instructions`, `mode` (`context-only` — optional; by default, on the same machine, the reviewer's worktree is mirrored from your working tree including uncommitted changes, so it reads the actual source. Pass `context-only` to opt out and treat the submitted context as authoritative) | 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), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit for server default), `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` | — | Poll or check the current status of a flow (running, waiting, completed, failed). |
 | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `clean`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.11.3",
+  "version": "0.11.6",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,12 +14,12 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.11.3",
-    "@kurrent/kcap-linux-x64": "0.11.3",
-    "@kurrent/kcap-linux-arm64": "0.11.3",
-    "@kurrent/kcap-linux-musl-x64": "0.11.3",
-    "@kurrent/kcap-linux-musl-arm64": "0.11.3",
-    "@kurrent/kcap-win-x64": "0.11.3"
+    "@kurrent/kcap-darwin-arm64": "0.11.6",
+    "@kurrent/kcap-linux-x64": "0.11.6",
+    "@kurrent/kcap-linux-arm64": "0.11.6",
+    "@kurrent/kcap-linux-musl-x64": "0.11.6",
+    "@kurrent/kcap-linux-musl-arm64": "0.11.6",
+    "@kurrent/kcap-win-x64": "0.11.6"
   },
   "files": [
     "bin/",