kuzushi 0.17.1 → 0.19.3

package/README.md

@@ -42,10 +42,89 @@ kuzushi> use sast
 kuzushi/sast> run scan ./repo preset=deep
 kuzushi/sast> back
 kuzushi> tools
-kuzushi> run sast:verify fingerprint=abc123
+kuzushi> run verify:finding fingerprint=abc123
 kuzushi> exit
 ```
 
+#### Common shell flows
+
+```
+# Catalog / module home / tune
+kuzushi> use sast             # focus → module home
+kuzushi/sast> findings        # unified list with filter chips + chain boxing
+kuzushi/sast> open F-0001     # linear deep page for a finding
+kuzushi/sast> tune            # six plain controls + optional "house rules"
+kuzushi/sast> back            # step up one level
+
+# Natural-language planner — English → option diff → y/n apply
+kuzushi/sast> /plan run harder, focus on auth, stop wasting money
+kuzushi/sast> y               # apply the proposed changes
+
+# Prompt editor — per-tool system-prompt override in $EDITOR
+kuzushi/sast> /prompt edit triage          # opens .kuzushi/prompts/sast/triage.md
+kuzushi/sast> /prompt show verify          # show effective prompt + source
+kuzushi/sast> /show prompts                # cross-module audit table
+
+# Replay / trace — re-read the outcome of a past run, no re-exec
+kuzushi> /show runs                        # list recent runs
+kuzushi> /replay 7f3a                      # re-render a past summary
+kuzushi> /trace 7f3a                       # stream the per-event JSONL log
+
+# Threat-model views — five screens over the randori output
+kuzushi> /threats dfd                      # ASCII data flow diagram
+kuzushi> /threats stride                   # element × STRIDE heat matrix
+kuzushi> /threats stories                  # attacker narrative cards
+kuzushi> /threats scope                    # criticality + operator edits
+kuzushi> /threats summary                  # counts, drives, export paths
+# Press 1..5 at any threat view to cycle.
+
+# Short-ID aliases — F-0001 / C-01 resolve through a deterministic map
+kuzushi/sast> /show aliases F-             # filter by prefix
+kuzushi/sast> open F-0003                  # same as typing the fingerprint
+
+# Diff-aware — pivot to "what changed since <ref>" without restarting
+kuzushi> /since main                       # findings + threats scoped to changed files
+kuzushi> /since v1.2.0                     # works with any git ref (tags, SHAs, HEAD~5)
+```
+
+#### Keyboard shortcuts
+
+| Key            | While running                     | At the idle prompt                  |
+| -------------- | --------------------------------- | ----------------------------------- |
+| `Ctrl+C`       | Abort the running tool / turn     | First press arms, second exits (2s) |
+| `Ctrl+D`       | Abort (same as `Ctrl+C`)          | Exits                               |
+| `Enter`        | —                                 | Send input                          |
+| `↑` / `↓`      | —                                 | Previous / next command             |
+| `Esc`          | —                                 | Clear input buffer                  |
+| `1`–`5`        | —                                 | Cycle threat-model sub-views        |
+
+Ctrl+C aborts through four independent paths (Ink `useInput` on raw stdin,
+a byte-level stdin watcher, `SIGINT`, and a dedicated `/dev/tty` reader)
+so long-running LLM tools still cancel cleanly even when a subprocess has
+grabbed the terminal's foreground group. Under abort every Claude Agent
+SDK subprocess (and its descendants) receives `SIGTERM` directly — no
+relying on the SDK's own signal handling.
+
+Set `KUZUSHI_ABORT_DEBUG=1` to trace the abort path to stderr when
+diagnosing Ctrl+C issues.
+
+#### On-disk artefacts
+
+Operators can version-control any of these and have them round-trip with
+the shell — `/prompt edit` and `/tune` write here, and randori / scan runs
+read from here.
+
+| Path                                       | Role                                       |
+| ------------------------------------------ | ------------------------------------------ |
+| `~/.kuzushi/config.json`                   | Global config (`/config`)                  |
+| `.kuzushi/threat-model.json`               | Persistent threat model (editable)         |
+| `.kuzushi/house-rules/<moduleId>.md`       | Operator nudges per module (`/tune`)       |
+| `.kuzushi/prompts/<moduleId>/<verb>.md`    | Per-tool system-prompt override            |
+| `.kuzushi/runs/<runId>/summary.json`       | Run summary (for `/replay`)                |
+| `.kuzushi/runs/<runId>/triage.jsonl`       | Per-event triage audit log (for `/trace`)  |
+| `.kuzushi/runs/<runId>/verify.jsonl`       | Per-event verify audit log (for `/trace`)  |
+| `.kuzushi/findings.sqlite3`                | Findings + pipeline_runs DB                |
+
 ### Scan (headless pipeline)
 
 The full SAST pipeline — 40+ agent tasks orchestrated as a DAG. Semgrep, CodeQL, 30+ agentic detectors, AI triage, verification, PoC generation, patch synthesis. CI/CD-native with SARIF, quality gates, and exit codes.
@@ -63,9 +142,9 @@ Execute a single module tool without the interactive shell. Scriptable, composab
 
 ```sh
 kuzushi run sast:scan ./repo --json
-kuzushi run sast:triage fingerprint=abc123 --json
-kuzushi run sast:verify fingerprint=abc123 --quiet
-kuzushi run sast:findings severity=critical,high --json
+kuzushi run triage:run fingerprint=abc123 --json
+kuzushi run verify:finding fingerprint=abc123 --quiet
+kuzushi run findings:list severity=critical,high --json
 ```
 
 ## Quick Start
@@ -134,16 +213,18 @@ Kuzushi's capabilities come from `CopilotModule`s that expose tools (for shell a
 
 | Module | Category | What It Does | Key Tools |
 |--------|----------|--------------|-----------|
-| **sast** | offense | 40+ task SAST pipeline: Semgrep, CodeQL, agentic detectors, AI triage, verification, PoC, patch | `sast:scan`, `sast:semgrep`, `sast:codeql`, `sast:triage`, `sast:verify`, `sast:patch`, `sast:findings`, `sast:context`, `sast:threat-hunt`, `sast:taint-iris` |
+| **sast** | offense | 40+ task SAST pipeline: Semgrep, CodeQL, agentic detectors, AI triage, verification, PoC, patch | `sast:scan` plus split-module tools `semgrep:scan`, `codeql:scan`, `agentic-sast:scan`, `triage:run`, `verify:finding`, `patch:finding`, `findings:list`, `context:build`, `threat-hunt:run`, `taint-iris:hunt` |
 | **randori** | intel | PASTA threat modeling via the `@kuzushi/randori-plugin` — S1–S4 stages plus narrative synthesis, returning a `ThreatModelDocument` | `randori:pasta`, `randori:threat-model` |
 | **vuln-scout** | offense | Whitebox pentest via the `@kuzushi/vuln-scout` plugin — agentic SAST + taint analysis returning normalized Findings | `vuln-scout:audit` |
 | **tob** | offense | Trail of Bits skills audit via `@kuzushi/tob-skills` — fp-check, sharp-edges, insecure-defaults, static-analysis, variant-analysis, and more | `tob:audit`, `tob:skills` |
 | **shinsa** | governance | ISO 27001 Annex A + NIST SP 800-53 Rev 5 compliance assessment via `shinsa-plugin` — evidence-backed controls mapped to file:line citations | `shinsa:scan`, `shinsa:quick-check`, `shinsa:nist-scan`, `shinsa:nist-quick-check`, `shinsa:frameworks` |
 | **prompt-armor** | offense | LLM red teaming via `promptarmor-plugin` — 80+ attack plugins, 25+ mutation strategies, code-aware remediation (network commands require `authorized: true`) | `prompt-armor:scan`, `prompt-armor:analyze`, `prompt-armor:attack`, `prompt-armor:diff`, `prompt-armor:report`, `prompt-armor:config` |
-| **variant-hunter** | offense | Lifts confirmed findings into portable signatures and hunts for variants across the repo (including vendored deps) | `variant:lift-pattern`, `variant:hunt` |
-| **n-day-diff-hunter** | offense | CVE-diff-based n-day hunting and variant search against a target | `ndiff:fetch-cve`, `ndiff:search-patch-shape`, `ndiff:hunt-variants` |
+| **variant** | offense | Lifts confirmed findings into portable signatures and hunts for variants across the repo (including vendored deps) | `variant:lift-pattern`, `variant:hunt` |
+| **ndiff** | offense | CVE-diff-based n-day hunting and variant search against a target | `ndiff:fetch-cve`, `ndiff:search-patch-shape`, `ndiff:hunt-variants` |
+
+Load with the shell or at startup: `kuzushi shell --load randori,vuln-scout,tob,shinsa,prompt-armor,variant,ndiff` (the bare id works — `builtin:` prefix is optional). Legacy ids `variant-hunter` / `n-day-diff-hunter` still resolve for backward compatibility.
 
-Load with the shell or at startup: `kuzushi shell --load randori,vuln-scout,tob,shinsa,prompt-armor,variant-hunter,n-day-diff-hunter` (the bare id works — `builtin:` prefix is optional).
+Legacy `sast:<action>` aliases for split-module tools still resolve for backward compatibility, but new scripts and docs should use the canonical tool names shown above.
 
 ### External `CopilotModule` packages
 
@@ -173,14 +254,15 @@ These are dependencies consumed by the built-in wrappers above, not directly loa
 kuzushi create-module my-module --template offense   # scaffolds manifest + starter tool + vitest
 ```
 
-The scaffolder emits `module.manifest.json`, a TypeScript starter tool, and a vitest skeleton. Import types and test helpers from the SDK subpaths:
+The scaffolder emits `module.manifest.json` (with `kuzushiSdkVersion` and `$schema`), a TypeScript starter using `defineModule`/`defineTool`, and a vitest skeleton using `kuzushi/testing`. Import surface:
 
 ```ts
-import type { CopilotModule, ModuleTool, ToolResult } from "kuzushi/modules"
-import { createMockToolContext, createMockBus, noopRuntime } from "kuzushi/testing"
+import { defineModule, defineTool, ModuleLoadError } from "kuzushi/modules"
+import type { CopilotModule, ToolExecutionContext, ToolResult } from "kuzushi/modules"
+import { createMockToolContext, assertToolResult, expectModuleShape } from "kuzushi/testing"
 ```
 
-Load a local build with `--load file:///abs/path/to/my-module`, or a published package with `--load package:@scope/name`. MCP servers can be bridged with `--load mcp:<spec>` (stdio or HTTP Streamable). See [CLAUDE.md](CLAUDE.md) for the full module authoring guide.
+Load a local build with `--load file:///abs/path/to/my-module`, a published package with `--load package:@scope/name`, or an MCP server with `--load mcp:<spec>`. The full authoring guide — manifest, `ToolExecutionContext` reference, capability probes, load errors, testing, MCP bridging — lives in **[docs/modules.md](docs/modules.md)**.
 
 ## The SAST Pipeline
 
@@ -238,12 +320,41 @@ jobs:
 
 Exit codes: `0` clean, `1` findings (or task failures), `2` usage/config/auth, `3` unexpected crash. See `.github/workflows/kuzushi-reference.yml` for a reference workflow with SARIF upload, JUnit publish, and PR sticky comment.
 
+#### `--ci` stream mode
+
+`--ci` disables the Ink TUI and attaches a plain-text stream formatter
+that writes one line per meaningful pipeline event. Log-renderer-friendly,
+grep-friendly, and free of ANSI control codes:
+
+```sh
+kuzushi scan ./repo --ci --sarif results.sarif
+```
+
+```
+[2026-04-20T14:20:01Z] scan: ./repo started
+[2026-04-20T14:20:01Z] phase: (init) → scanning
+[2026-04-20T14:20:12Z] stage: scan → done [8.3s]
+[2026-04-20T14:20:12Z] stage: triage → active (15 findings)
+[2026-04-20T14:20:45Z] finding: abc123def456 tp 92% $0.0041
+[2026-04-20T14:21:20Z] summary: 4 tp · 10 fp · $0.87 · 1m 18s
+```
+
+Honoured from a TTY too — `kuzushi scan … --ci | tee run.log` works.
+
+#### PR comments
+
+`buildPrComment(summary, { repoName, runUrl })` (in `src/report-pr-comment.ts`)
+renders a GitHub-markdown block suitable for `gh pr comment -F -`. Includes
+verdict counts, exploitable badge, cost + duration, and a top-10 TP table
+with severity emojis.
+
 ### Quality Gates
 
 ```sh
 kuzushi scan <repo> --quality-gate         # fail CI on threshold violations
 kuzushi scan <repo> --fail-on-tp           # fail if any high/critical TP is found
 kuzushi scan <repo> --sarif results.sarif  # export SARIF for GitHub Code Scanning
+kuzushi scan <repo> --ci                   # plain-text stream mode (no Ink)
 ```
 
 ## Scan Presets
@@ -355,9 +466,9 @@ kuzushi runs show <runId> --json           # JSON output for tooling
 
 ```
 kuzushi run sast:scan ./repo --json
-kuzushi run sast:triage fingerprint=abc123 --json
-kuzushi run sast:verify fingerprint=abc123 --quiet
-kuzushi run sast:findings severity=critical,high --json
+kuzushi run triage:run fingerprint=abc123 --json
+kuzushi run verify:finding fingerprint=abc123 --quiet
+kuzushi run findings:list severity=critical,high --json
 ```
 
 ### Patch

package/dist/agent-runtime/claude.d.ts

@@ -1,20 +1,60 @@
 import type { MessageBus } from "../bus/types.js";
-import type { AgentRuntimeConfig } from "../types.js";
+import type { AgentRuntimeCredentials } from "../types.js";
 import type { AgentQueryExecutionResult } from "./execution.js";
-import type { AgentBatchRequest, AgentMessage, AgentQueryOptions, AgentQueryRequest, AgentRuntime, AgentSession } from "./types.js";
+import type { AgentActivityPhase, AgentBatchRequest, AgentMessage, AgentQueryOptions, AgentQueryRequest, AgentRuntime, AgentSession } from "./types.js";
+/**
+ * Nuclear option for Ctrl+C — SIGTERM every tracked Claude subprocess
+ * regardless of which session/query spawned it, then escalate survivors
+ * to SIGKILL after the normal grace window. Called from the shell's
+ * SIGINT handler BEFORE the abort-controller chain runs, so the
+ * subprocess is guaranteed to stop even if an abort listener was never
+ * installed, raced with the spawn, or was blocked by a stuck await.
+ *
+ * Returns the number of processes that received SIGTERM, so callers
+ * can log / diagnose.
+ */
+export declare function killAllClaudeSubprocesses(): number;
+/**
+ * Emit `task:activity` (always — drives the spinner subtitle) and
+ * `${phase}:agent-activity` (only when both `phase` and `fingerprint` are
+ * set — drives the "N agents active" counter) for any tool-use blocks
+ * inside an SDK assistant message.
+ *
+ * Best-effort: every publish is wrapped in the helpers' own try/catch so a
+ * broken subscriber never takes down the SDK loop.
+ */
+declare function emitActivityForAssistant(bus: MessageBus | null, contentBlocks: unknown, ctx: {
+    runId?: string | null;
+    taskId?: string;
+    fingerprint?: string;
+    phase?: AgentActivityPhase;
+}): void;
+/**
+ * Emit a terminal `${phase}:agent-activity` envelope so the report-worker
+ * clears the fingerprint from the agents-active map (`done: true`).
+ */
+declare function emitActivityDone(bus: MessageBus | null, ctx: {
+    fingerprint?: string;
+    phase?: AgentActivityPhase;
+}): void;
 /** Exported for tests only — observes internal semaphore state. */
 export declare function __getSemaphoreState(): {
     active: number;
     leaked: number;
     waiting: number;
 };
+/** Exported for tests only — direct access to the SDK-message activity helpers. */
+export declare const __activityInternals: {
+    emitActivityForAssistant: typeof emitActivityForAssistant;
+    emitActivityDone: typeof emitActivityDone;
+};
 export declare class ClaudeAgentRuntime implements AgentRuntime {
     readonly id = "claude";
     private readonly config;
     private readonly client;
     bus: MessageBus | null;
     runId: string | null;
-    constructor(config?: AgentRuntimeConfig);
+    constructor(config?: AgentRuntimeCredentials);
     createSession(baseOptions: AgentQueryOptions): AgentSession;
     /**
      * Submit multiple tool-less prompts as a single Anthropic Batch API call.
@@ -35,3 +75,4 @@ export declare class ClaudeAgentRuntime implements AgentRuntime {
     private queryDirect;
     query(request: AgentQueryRequest): AsyncIterable<AgentMessage>;
 }
+export {};