kuzushi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shayaun Nejad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,410 @@
+<img src="kuzushi.png" alt="Kuzushi" width="200" />
+
+# Kuzushi — Agentic SAST Orchestrator
+
+Agentic SAST orchestrator. Runs security analysis tasks — scanners, AI triage, exploit verification, and more — as a dependency graph on an event-driven pipeline, then tells you what's actually dangerous.
+
+## Quick Start
+
+Prereqs: Node 22+, an API key for at least one supported LLM provider.
+
+**With Anthropic (default):**
+
+1. Get an API key at https://console.anthropic.com/
+2. Set it: `export ANTHROPIC_API_KEY=sk-ant-...`
+3. Scan: `npx kuzushi /path/to/your/repo`
+
+**With OpenAI, Google, or any pi-ai-supported provider:**
+
+1. Set the provider key: `export OPENAI_API_KEY=sk-...` (or `GEMINI_API_KEY`, etc.)
+2. Scan: `npx kuzushi /path/to/repo --agent-runtime pi-ai --model openai:gpt-4o`
+
+That's it. Kuzushi auto-downloads Opengrep if you don't have a scanner installed. To add CodeQL, see [CodeQL Setup](#codeql-setup).
+
+## What It Does
+
+- **Runs Opengrep/Semgrep** with severity-ranked rule matching
+- **Runs configurable scanners** (`semgrep`, `agentic`, `codeql`) in one orchestration flow
+- **Gathers repo context** — auto-detects language, frameworks, auth patterns, ORMs, and sanitization libraries to enrich AI analysis
+- **Scores and deduplicates** findings by severity, likelihood, impact, and subcategory — cross-scanner normalization merges equivalent findings from different scanners at the same location
+- **AI-triages selected findings** — after dedupe/resume/max filters, agent investigates with repo tools, assigns tp/fp/needs_review with confidence and rationale
+- **Verifies exploitability** — optional post-triage phase constructs concrete proof-of-concept payloads for true positives (e.g., SQL injection strings, XSS vectors)
+- **Generates PoC harnesses** — optional post-verification phase produces runnable exploit scripts (TypeScript, Python, etc.) for verified-exploitable findings
+- **Vendor-agnostic LLM runtime** — swap between Anthropic, OpenAI, Google, and 15+ other providers via the `pi-ai` backend with zero consumer-code changes
+- **Augur integration** — multi-pass CodeQL-based source/sink labeling pipeline with LLM-assisted classification, checkpoint gating, and deterministic library generation
+- **Tracks cost** — per-finding triage, verification, and PoC harness costs are persisted and displayed in the summary
+- **Event-driven pipeline** — pluggable message bus interface (in-process backend implemented; Redis/Google Pub/Sub/NATS adapters are scaffolded)
+- **DAG-based task orchestration** — tasks declare dependencies, run in parallel groups, pass outputs downstream
+- **Extensible agent framework** — `AgentTask` interface for adding new analysis types (threat modeling, binary analysis, etc.)
+- **Persists results** in SQLite — resume interrupted scans, skip already-triaged findings
+- **Resumable runs** — checkpoint pipeline state to SQLite; `--resume` picks up where a crashed or interrupted scan left off
+- **Retry with backoff** — transient agent failures are retried automatically with exponential backoff
+- **Audit logging** — optional JSONL audit trail of every agent decision for debugging and accountability
+- **Markdown reports** — export a shareable `.md` report for CI pipelines and team review
+- **Prints a styled report** showing only what matters: true positives, needs-review items, and verified exploits with PoC payloads
+
+## How It Works
+
+Semgrep/Opengrep catches syntactic patterns but can't verify data flow or intent. LLMs can reason about code but hallucinate when scanning from scratch (95%+ false positive rate). Kuzushi combines both: SAST signal narrows the search space, LLM reasoning eliminates false positives. This hybrid approach matches human researcher agreement rates.
+
+Under the hood, Kuzushi uses an event-driven architecture with a DAG-based task orchestrator:
+
+1. **Context gathering** (optional, enabled by default) — the context-gatherer task analyzes the repo structure (package.json, go.mod, etc.) to identify the tech stack, frameworks, and security-relevant libraries.
+2. **Pipeline starts** — the orchestrator resolves enabled tasks into a dependency graph and groups them into parallel stages.
+3. **Scanners run** — scanner tasks (Semgrep, CodeQL, Agentic, etc.) execute concurrently within their stage, emitting findings as typed events on the message bus.
+4. **Results gate downstream tasks** — the orchestrator waits for each stage to complete before starting dependent stages. Upstream outputs are forwarded to dependent tasks via `TaskContext`.
+5. **Triage stage** — findings are deduplicated (fingerprint + cross-scanner location/CWE/rule normalization), ranked, and sent to an LLM for semantic verification with configurable concurrency. The repo context from step 1 enriches every triage prompt.
+6. **Verification stage** (optional) — triaged findings that pass verification gates (`verifyVerdicts`, scanner-level `scannerConfig.<id>.verify`, and `verifyMinConfidence`) are sent to a verification agent that attempts to construct concrete PoC exploit payloads.
+7. **PoC harness generation** (optional) — verified-exploitable findings are sent to a harness generator that produces runnable exploit scripts with syntax validation.
+8. **Report** — final results are persisted, rendered to terminal, and optionally exported as markdown.
+
+All communication happens through a transport-agnostic `MessageBus` interface. The default in-process bus works out of the box; distributed adapters (Redis, Google Pub/Sub, NATS) are planned and scaffolded behind the same interface.
+
+## Commands
+
+### Scan (default)
+
+```
+kuzushi <repo>                        # scan with defaults
+kuzushi <repo> --scanners codeql
+kuzushi <repo> --scanners semgrep,codeql
+kuzushi <repo> --scanners semgrep,agentic
+kuzushi <repo> --severity ERROR       # only ERROR-level findings
+kuzushi <repo> --max 20               # triage top 20 findings only
+kuzushi <repo> --model claude-opus-4-20250514  # use a different model
+kuzushi <repo> --triage-model claude-opus-4-20250514  # separate model for triage
+kuzushi <repo> --triage-max-turns 15  # triage agent turn budget
+kuzushi <repo> --api-key sk-ant-... --base-url https://basecamp.stark.rubrik.com/
+kuzushi <repo> --fresh                # clear prior results, re-triage everything
+kuzushi <repo> --db ./my.sqlite3      # custom database path
+kuzushi <repo> --resume               # resume the most recent interrupted run
+kuzushi <repo> --resume <run-id>      # resume a specific run by ID
+```
+
+### Vendor-Agnostic Runtime
+
+```
+kuzushi <repo> --agent-runtime pi-ai --model openai:gpt-4o
+kuzushi <repo> --agent-runtime pi-ai --model google:gemini-2.0-flash
+kuzushi <repo> --agent-runtime pi-ai --model anthropic:claude-sonnet-4-20250514
+kuzushi config set agentRuntimeBackend pi-ai
+kuzushi config set model openai:gpt-4o
+```
+
+When `agentRuntimeBackend` is `pi-ai`, model strings use `provider:modelId` format. The pi-ai backend implements its own agentic tool-calling loop with local Read/Glob/Grep tools, structured output enforcement, budget tracking, and abort support. All consumer code (triage, verify, PoC harness, scanners) works unchanged — the `AgentRuntime` abstraction handles it.
+
+### Verification
+
+```
+kuzushi <repo> --verify               # enable exploit verification for TPs
+kuzushi <repo> --verify --verify-model claude-haiku-4-5-20251001  # cheaper model for verification
+kuzushi <repo> --verify --verify-max-turns 20
+kuzushi <repo> --verify --verify-concurrency 3
+kuzushi <repo> --verify --verify-min-confidence 0.7  # skip low-confidence TPs
+```
+
+### PoC Harness Generation
+
+```
+kuzushi <repo> --verify --poc-harness                          # generate exploit scripts for verified findings
+kuzushi <repo> --verify --poc-harness --poc-harness-model claude-haiku-4-5-20251001
+kuzushi <repo> --verify --poc-harness --poc-harness-max-turns 25
+kuzushi <repo> --verify --poc-harness --poc-harness-concurrency 2
+```
+
+### Output & Observability
+
+```
+kuzushi <repo> --output report.md     # export markdown report
+kuzushi <repo> --sarif results.sarif  # export SARIF v2.1.0
+kuzushi <repo> --audit-log            # write agent activity to .kuzushi/runs/{runId}/
+kuzushi <repo> --no-context           # disable repo context gathering
+```
+
+### Retry
+
+```
+kuzushi <repo> --max-triage-retries 3       # retry failed triage calls (default: 2)
+kuzushi <repo> --max-verify-retries 3       # retry failed verification calls (default: 2)
+kuzushi <repo> --retry-backoff-ms 10000     # initial backoff delay (default: 5000)
+```
+
+### Config
+
+```
+kuzushi config get                    # show all config
+kuzushi config get model              # show one key
+kuzushi config set model claude-opus-4-20250514
+kuzushi config set scanners semgrep,agentic
+kuzushi config set scannerConfig.codeql.dbPath ./codeql-db
+kuzushi config set scannerConfig.codeql.suite javascript-security-extended
+kuzushi config set scannerConfig.semgrep.binary opengrep
+kuzushi config set scannerConfig.semgrep.configFlag auto
+kuzushi config set scannerConfig.agentic.model claude-sonnet-4-20250514
+kuzushi config set scannerConfig.agentic.maxFindings 25
+kuzushi config set severity ERROR,WARNING,INFO
+kuzushi config set verify true
+kuzushi config set verifyMinConfidence 0.7
+kuzushi config set auditLog true
+kuzushi config unset model            # reset to default
+kuzushi config path                   # print config file location
+```
+
+Global config lives at `~/.kuzushi/config.json`. Optional project overrides can live at `<repo>/.kuzushi/config.json`. CLI flags override config values.
+
+Security note: `agentRuntimeConfig.apiKey` is stored in plaintext in config files. Prefer `--api-key` for one-off runs or `ANTHROPIC_API_KEY` from your shell/secret manager.
+
+## Configuration
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `model` | `claude-sonnet-4-20250514` | LLM model for scanners and default triage model |
+| `triageModel` | _(uses `model`)_ | Override model used by the triage agent |
+| `triageMaxTurns` | `10` | Max agentic turns per triage call |
+| `scanners` | `["semgrep"]` | Scanner plugins to run, in order |
+| `severity` | `["ERROR","WARNING"]` | Semgrep severity filter |
+| `excludePatterns` | `["test","tests","node_modules",...]` | Directories/globs to skip |
+| `scannerConfig` | `{ semgrep: {...}, agentic: {...}, codeql: {...} }` | Per-scanner config blocks keyed by scanner id |
+| `busBackend` | `"in-process"` | Message bus transport (`in-process`, future: `redis`, `google-pubsub`, `nats`) |
+| `triageConcurrency` | `1` | Parallel LLM triage calls |
+| `scanMode` | `"sequential"` | Scanner execution mode (`sequential` or `concurrent`) |
+| `enabledTasks` | `[]` | Additional agent tasks beyond scanners |
+| `agentRuntimeBackend` | `"claude-sdk"` | Agent runtime backend (`claude-sdk`, `pi-ai`, future: `acp`) |
+| `verify` | `false` | Enable proof-of-exploitability verification |
+| `verifyModel` | _(uses `triageModel` or `model`)_ | Override model for verification agent |
+| `verifyMaxTurns` | `15` | Max turns for verification agent |
+| `verifyConcurrency` | `1` | Parallel verification calls |
+| `verifyVerdicts` | `["tp"]` | Which triage verdicts to verify |
+| `verifyMinConfidence` | `0` | Minimum triage confidence to trigger verification (0-1) |
+| `pocHarness` | `false` | Enable post-verification PoC harness generation (requires `--verify`) |
+| `pocHarnessModel` | _(uses `triageModel` or `model`)_ | Override model for PoC harness agent |
+| `pocHarnessMaxTurns` | `20` | Max turns for PoC harness agent |
+| `pocHarnessConcurrency` | `1` | Parallel PoC harness generation calls |
+| `enableContextGathering` | `true` | Run repo context analysis before triage |
+| `auditLog` | `false` | Write agent activity to JSONL audit files |
+| `reportOutput` | _(unset)_ | Write markdown report output to this path |
+| `sarifOutput` | _(unset)_ | Write SARIF v2.1.0 output to this path |
+| `maxTriageRetries` | `2` | Retry failed triage calls |
+| `maxVerifyRetries` | `2` | Retry failed verification calls |
+| `maxPocHarnessRetries` | `2` | Retry failed PoC harness generation calls |
+| `retryBackoffMs` | `5000` | Initial retry backoff delay in ms |
+| `retryBackoffMultiplier` | `2` | Exponential backoff multiplier |
+
+Example:
+
+```json
+{
+  "scanners": ["semgrep", "codeql", "agentic"],
+  "scanMode": "concurrent",
+  "triageConcurrency": 3,
+  "verify": true,
+  "verifyMinConfidence": 0.7,
+  "auditLog": true,
+  "enabledTasks": [],
+  "scannerConfig": {
+    "codeql": { "dbPath": "./codeql-db", "suite": "javascript-security-extended" },
+    "semgrep": { "binary": "opengrep", "configFlag": "auto" },
+    "agentic": { "model": "claude-sonnet-4-20250514", "maxFindings": 20 }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `ANTHROPIC_API_KEY` | Yes (claude-sdk backend) | Anthropic API key — required when `agentRuntimeBackend` is `claude-sdk` |
+| `OPENAI_API_KEY` | When using `openai:*` models | OpenAI API key for pi-ai backend |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | When using `google:*` models | Google API key for pi-ai backend |
+
+## Scanner Plugins
+
+- `semgrep`: traditional SAST via Opengrep/Semgrep binary
+- `codeql`: semantic dataflow/taint analysis via GitHub CodeQL CLI (SARIF output)
+- `agentic`: AI-driven agentic scanner — LLM with read-only repo tools via any supported runtime
+- `augur`: multi-pass CodeQL source/sink labeling pipeline — runs preflight (database creation, candidate extraction), LLM-assisted labeling with human-in-the-loop checkpoint, and deterministic library/query generation + analysis
+
+## Semgrep Resolution
+
+For the `semgrep` plugin, Kuzushi finds a scanner binary in this order:
+
+1. `opengrep` on your PATH
+2. `semgrep` on your PATH
+3. Previously downloaded binary at `~/.kuzushi/bin/opengrep`
+4. Auto-downloads Opengrep from GitHub releases (~40 MB, cached for future runs)
+
+No pip, no brew, no manual install needed.
+
+## CodeQL Setup
+
+The `codeql` scanner requires the [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases) to be installed separately. Unlike Semgrep, it is **not auto-downloaded** (the CLI is ~500 MB and requires accepting GitHub's license).
+
+Install it:
+
+```sh
+# Via GitHub CLI (recommended):
+gh extension install github/gh-codeql && gh codeql install-stub
+
+# Or download directly from:
+# https://github.com/github/codeql-cli-binaries/releases
+```
+
+Kuzushi finds the CodeQL binary in this order:
+
+1. `codeql` on your PATH
+2. Previously placed binary at `~/.kuzushi/bin/codeql`
+3. Fails with install instructions if not found
+
+CodeQL is **opt-in** — the default scanner list is `["semgrep"]`. To enable it:
+
+```sh
+kuzushi <repo> --scanners codeql              # CodeQL only
+kuzushi <repo> --scanners semgrep,codeql      # both scanners
+kuzushi config set scanners semgrep,codeql    # persist as default
+```
+
+CodeQL builds a database from your source code before running queries. You can skip this step by pointing to a pre-built database:
+
+```sh
+kuzushi config set scannerConfig.codeql.dbPath ./codeql-db
+```
+
+## Pi-AI Runtime
+
+The `pi-ai` backend uses `@mariozechner/pi-ai` to provide vendor-agnostic LLM access. It supports 15+ providers (Anthropic, OpenAI, Google, Groq, Mistral, etc.) through a single interface.
+
+Unlike the Claude SDK backend (which has a built-in agentic loop), the pi-ai backend implements its own:
+
+1. **Tool-calling loop** — call model, parse tool calls, execute tools, feed results back, repeat until stop or max turns
+2. **Local tool implementations** — Read (file reader with line numbers), Glob (Node 22+ `globSync`), Grep (regex search across files)
+3. **Structured output** — system prompt injection + post-hoc JSON extraction from fenced code blocks or raw text
+4. **Safety controls** — max turns, budget enforcement, abort signal, permission gating via `canUseTool`
+
+```sh
+# Use with any supported provider:
+OPENAI_API_KEY=... kuzushi <repo> --agent-runtime pi-ai --model openai:gpt-4o
+GEMINI_API_KEY=... kuzushi <repo> --agent-runtime pi-ai --model google:gemini-2.0-flash
+ANTHROPIC_API_KEY=... kuzushi <repo> --agent-runtime pi-ai --model anthropic:claude-sonnet-4-20250514
+```
+
+## Augur Setup
+
+The `augur` scanner is a multi-pass CodeQL-based pipeline that uses LLM-assisted classification to label sources, sinks, sanitizers, and summaries. It requires:
+
+1. **CodeQL CLI** — same requirement as the `codeql` scanner
+2. **Python 3** — used by Augur's scripts for query generation
+
+Augur's templates, references, and scripts are bundled as the [`@kuzushi/augur`](https://www.npmjs.com/package/@kuzushi/augur) npm package and installed automatically with `pnpm install`. No manual clone or `AUGUR_PATH` setup needed.
+
+```sh
+kuzushi <repo> --scanners augur
+kuzushi <repo> --scanners augur --approve-checkpoint  # auto-approve label review
+kuzushi config set scannerConfig.augur.labelingModel claude-sonnet-4-20250514
+kuzushi config set scannerConfig.augur.passes "[1,2,3,4,5,6]"
+```
+
+To override the bundled augur assets (e.g., for local development), set `AUGUR_PATH` or `scannerConfig.augur.augurPath`:
+
+```sh
+export AUGUR_PATH=/path/to/local/augur
+kuzushi config set scannerConfig.augur.augurPath /path/to/local/augur
+```
+
+Augur runs in three DAG-ordered stages: **preflight** (database creation, candidate extraction), **label** (LLM classification with checkpoint gate), and **analyze** (library generation, query execution, finding extraction). A human-in-the-loop checkpoint pauses after labeling for review — use `--approve-checkpoint` to auto-approve in CI.
+
+## Output
+
+Results are stored in SQLite at `<repo>/.kuzushi/findings.sqlite3`. Each finding includes:
+
+- **verdict**: `tp` (true positive), `fp` (false positive), or `needs_review`
+- **confidence**: 0.0-1.0
+- **rationale**: why the LLM reached that verdict, referencing specific code
+- **verification_steps**: 2-6 steps a human reviewer can follow
+- **fix_patch**: suggested fix (when applicable)
+- **exploitability** (with `--verify`): whether a concrete exploit was constructed, PoC payload, attack vector, and preconditions
+- **cost**: per-finding triage and verification cost in USD
+
+The terminal report shows true positives first, then needs-review items. False positives are counted but hidden. Verified exploitable findings are highlighted with their PoC payloads.
+
+Use `--output report.md` to export a shareable markdown report.
+Use `--sarif results.sarif` to export SARIF v2.1.0 for code scanning platforms.
+
+## SARIF / GitHub Code Scanning
+
+Kuzushi can emit SARIF v2.1.0 directly. GitHub Code Scanning ingests SARIF and creates inline annotations.
+
+```
+kuzushi <repo> --sarif results.sarif
+
+gh api \
+  -X POST \
+  repos/OWNER/REPO/code-scanning/sarifs \
+  -f commit_sha="$(git rev-parse HEAD)" \
+  -f ref="refs/heads/$(git rev-parse --abbrev-ref HEAD)" \
+  -f sarif="$(gzip -c results.sarif | base64 | tr -d '\n')"
+```
+
+## Resume Support
+
+Kuzushi fingerprints every finding (content-based SHA-256 that survives line shifts). Re-running a scan skips already-triaged findings automatically. Use `--fresh` to start over.
+
+For interrupted runs, use `--resume` to pick up where the pipeline left off. Kuzushi checkpoints pipeline state (scan findings, triage progress, verification progress) to SQLite. On resume, completed phases are skipped and only remaining work is executed.
+
+```
+kuzushi <repo> --resume               # resume most recent interrupted run
+kuzushi <repo> --resume abc-123       # resume a specific run by ID
+```
+
+## Audit Logging
+
+With `--audit-log`, Kuzushi writes a structured audit trail to `.kuzushi/runs/{runId}/`:
+
+- `triage.jsonl` — every tool call, reasoning step, and verdict from triage agents
+- `verify.jsonl` — same for verification agents
+- `run.json` — run config and scan options
+- `stats.json` — final pipeline statistics
+
+Use this to debug verdicts, review agent reasoning, or build compliance records.
+
+## Architecture
+
+Kuzushi is built on three core abstractions:
+
+**Message Bus** — A transport-agnostic `MessageBus` interface (`publish`, `subscribe`, `waitFor`) that decouples pipeline stages. The default in-process implementation uses an `EventEmitter`; the interface supports swapping in Redis, Google Pub/Sub, or NATS for distributed setups.
+
+**AgentTask + DAG** — Every unit of work (context gatherer, scanner, future threat modeler, etc.) implements the `AgentTask` interface: an `id`, `dependsOn` list, `outputKind`, and a `run()` method. The `TaskRegistry` resolves enabled tasks into a DAG, groups them into parallel stages, detects cycles, and hands execution to the `PipelineOrchestrator`. Upstream task outputs are forwarded to dependents automatically.
+
+**Pipeline Phases** — After the DAG completes, the orchestrator drives three sequential phases: triage (classify findings), verification (construct PoC exploits), and report (display results). Each phase has its own concurrency control, cost tracking, and checkpoint support.
+
+Existing `ScannerPlugin` implementations (Semgrep, Agentic) are adapted into `AgentTask` via `adaptScannerPlugin()`, so the scanner plugin API remains stable.
+
+See [AGENTS.md](AGENTS.md) for the full developer guide on adding new agent tasks.
+
+## Development
+
+```
+pnpm install                          # install deps
+pnpm dev -- /path/to/repo             # run in dev mode
+pnpm typecheck                        # type check
+pnpm test                             # run tests (214 tests across 31 files)
+pnpm test:coverage                    # tests + coverage (70% threshold)
+pnpm build                            # compile to dist/
+```
+
+Tests are organized by subsystem: `tests/bus/` for orchestrator, workers, and event bus tests, `tests/agents/` for DAG, task registry, and context-gatherer tests, and `tests/` for scanners, triage, verification, store, config, retry, and report.
+
+## Troubleshooting
+
+- **"Error: ANTHROPIC_API_KEY environment variable is required."**: Export your key — `export ANTHROPIC_API_KEY=sk-ant-...` (only required for `claude-sdk` backend; use `--agent-runtime pi-ai` with other providers)
+- **"No findings from scanner. Code looks clean."**: Your code is clean, or try `--severity ERROR,WARNING,INFO` to include lower-severity rules
+- **Scan interrupted**: Re-run the same command (already-triaged findings are skipped), or use `--resume` to continue from the exact checkpoint
+- **Wrong model**: `kuzushi config set model claude-opus-4-20250514` or pass `--model` per-scan
+- **Scanner download fails**: Install Opengrep or Semgrep manually, ensure it's on your PATH
+- **High triage cost**: Use `--triage-model claude-haiku-4-5-20251001` for cheaper triage, or `--max 10` to limit findings
+- **Verification too expensive**: Use `--verify-min-confidence 0.8` to only verify high-confidence TPs, or `--verify-model claude-haiku-4-5-20251001`
+- **pi-ai model not found**: Ensure the model string uses `provider:modelId` format (e.g., `openai:gpt-4o`, not just `gpt-4o`)
+- **Augur checkpoint blocks CI**: Pass `--approve-checkpoint` to auto-approve label review in non-interactive environments
+
+## License
+
+MIT

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

@@ -0,0 +1,8 @@
+import type { AgentRuntimeConfig } from "../types.js";
+import type { AgentMessage, AgentQueryRequest, AgentRuntime } from "./types.js";
+export declare class ClaudeSdkAgentRuntime implements AgentRuntime {
+    readonly id = "claude-sdk";
+    private readonly runtimeConfig?;
+    constructor(runtimeConfig?: AgentRuntimeConfig);
+    query(request: AgentQueryRequest): AsyncIterable<AgentMessage>;
+}

package/dist/agent-runtime/claude.js

@@ -0,0 +1,124 @@
+import { query, } from "@anthropic-ai/claude-agent-sdk";
+import { isRecord } from "../utils.js";
+export class ClaudeSdkAgentRuntime {
+    id = "claude-sdk";
+    runtimeConfig;
+    constructor(runtimeConfig) {
+        this.runtimeConfig = runtimeConfig;
+    }
+    async *query(request) {
+        const canUseTool = request.options.canUseTool
+            ? adaptCanUseTool(request.options.canUseTool)
+            : undefined;
+        const runtimeEnv = buildRuntimeEnv(this.runtimeConfig);
+        for await (const message of query({
+            prompt: request.prompt,
+            options: {
+                cwd: request.options.cwd,
+                model: request.options.model,
+                maxTurns: request.options.maxTurns,
+                allowedTools: request.options.allowedTools,
+                disallowedTools: request.options.disallowedTools,
+                permissionMode: request.options.permissionMode,
+                maxBudgetUsd: request.options.maxBudgetUsd,
+                abortController: request.options.abortController,
+                outputFormat: request.options.outputFormat
+                    ? {
+                        type: "json_schema",
+                        schema: request.options.outputFormat.schema,
+                    }
+                    : undefined,
+                canUseTool,
+                env: runtimeEnv,
+            },
+        })) {
+            yield mapMessage(message);
+        }
+    }
+}
+function buildRuntimeEnv(runtimeConfig) {
+    if (!runtimeConfig?.apiKey && !runtimeConfig?.baseUrl) {
+        return undefined;
+    }
+    return {
+        ...process.env,
+        ANTHROPIC_API_KEY: runtimeConfig.apiKey ?? process.env["ANTHROPIC_API_KEY"],
+        ANTHROPIC_BASE_URL: runtimeConfig.baseUrl ?? process.env["ANTHROPIC_BASE_URL"],
+    };
+}
+function mapMessage(message) {
+    if (message.type === "result") {
+        if (message.subtype === "success") {
+            return {
+                type: "result",
+                subtype: "success",
+                result: message.result,
+                structuredOutput: message.structured_output,
+                durationMs: message.duration_ms,
+                numTurns: message.num_turns,
+                totalCostUsd: message.total_cost_usd,
+            };
+        }
+        return {
+            type: "result",
+            subtype: message.subtype,
+            errors: [...message.errors],
+            durationMs: message.duration_ms,
+            numTurns: message.num_turns,
+            totalCostUsd: message.total_cost_usd,
+        };
+    }
+    if (message.type === "assistant") {
+        const content = Array.isArray(message.message.content)
+            ? message.message.content.filter(isRecord)
+            : [];
+        return {
+            type: "assistant",
+            content,
+        };
+    }
+    if (message.type === "tool_progress") {
+        return {
+            type: "tool-progress",
+            toolUseId: message.tool_use_id,
+            toolName: message.tool_name,
+            elapsedSeconds: message.elapsed_time_seconds,
+        };
+    }
+    if (message.type === "tool_use_summary") {
+        return {
+            type: "tool-summary",
+            summary: message.summary,
+            precedingToolUseIds: [...message.preceding_tool_use_ids],
+        };
+    }
+    return {
+        type: "unknown",
+        raw: message,
+    };
+}
+function adaptCanUseTool(handler) {
+    return async (toolName, input, options) => {
+        const decision = await handler(toolName, input, {
+            signal: options.signal,
+            toolUseId: options.toolUseID,
+            blockedPath: options.blockedPath,
+            decisionReason: options.decisionReason,
+        });
+        return toPermissionResult(decision);
+    };
+}
+function toPermissionResult(decision) {
+    if (decision.behavior === "allow") {
+        return {
+            behavior: "allow",
+            updatedInput: undefined,
+            updatedPermissions: undefined,
+        };
+    }
+    return {
+        behavior: "deny",
+        message: decision.message ?? "Permission denied",
+    };
+}
+//# sourceMappingURL=claude.js.map

package/dist/agent-runtime/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agent-runtime/claude.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,9 @@
+import type { KuzushiConfig } from "../types.js";
+import { ClaudeSdkAgentRuntime } from "./claude.js";
+import { PiAiAgentRuntime } from "./pi-ai.js";
+import type { AgentRuntime } from "./types.js";
+export declare function getAgentRuntime(): AgentRuntime;
+export declare function setAgentRuntime(runtime: AgentRuntime): void;
+export declare function configureAgentRuntime(config: KuzushiConfig): AgentRuntime;
+export * from "./types.js";
+export { ClaudeSdkAgentRuntime, PiAiAgentRuntime };

package/dist/agent-runtime/index.js

@@ -0,0 +1,31 @@
+import { ClaudeSdkAgentRuntime } from "./claude.js";
+import { PiAiAgentRuntime } from "./pi-ai.js";
+const DEFAULT_BACKEND = "claude-sdk";
+let currentRuntime = new ClaudeSdkAgentRuntime();
+export function getAgentRuntime() {
+    return currentRuntime;
+}
+export function setAgentRuntime(runtime) {
+    currentRuntime = runtime;
+}
+export function configureAgentRuntime(config) {
+    const backend = config.agentRuntimeBackend ?? DEFAULT_BACKEND;
+    const runtimeConfig = config.agentRuntimeConfig;
+    if (backend === "claude-sdk") {
+        currentRuntime = new ClaudeSdkAgentRuntime(runtimeConfig);
+        return currentRuntime;
+    }
+    if (backend === "pi-ai") {
+        currentRuntime = new PiAiAgentRuntime(runtimeConfig);
+        return currentRuntime;
+    }
+    if (backend === "acp") {
+        throw new Error("agentRuntimeBackend=acp is not available yet. "
+            + "Use agentRuntimeBackend=claude-sdk or agentRuntimeBackend=pi-ai until ACP runtime adapter is implemented.");
+    }
+    throw new Error(`Unknown agent runtime backend: ${String(backend)}. `
+        + "Expected one of: claude-sdk, pi-ai, acp.");
+}
+export * from "./types.js";
+export { ClaudeSdkAgentRuntime, PiAiAgentRuntime };
+//# sourceMappingURL=index.js.map

package/dist/agent-runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-runtime/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC,IAAI,cAAc,GAAiB,IAAI,qBAAqB,EAAE,CAAC;AAE/D,MAAM,UAAU,eAAe;IAC7B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAqB;IACnD,cAAc,GAAG,OAAO,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,MAAM,OAAO,GAAG,MAAM,CAAC,mBAAmB,IAAI,eAAe,CAAC;IAC9D,MAAM,aAAa,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAEhD,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC7B,cAAc,GAAG,IAAI,qBAAqB,CAAC,aAAa,CAAC,CAAC;QAC1D,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,cAAc,GAAG,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAAC;QACrD,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,gDAAgD;cAC9C,2GAA2G,CAC9G,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CACb,kCAAkC,MAAM,CAAC,OAAO,CAAC,IAAI;UACnD,0CAA0C,CAC7C,CAAC;AACJ,CAAC;AAED,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/agent-runtime/model-spec.d.ts

@@ -0,0 +1,8 @@
+export interface PiAiModelSpec {
+    provider: string;
+    modelId: string;
+}
+/**
+ * Parse a pi-ai model identifier in provider:modelId format.
+ */
+export declare function parsePiAiModelSpec(model: string): PiAiModelSpec;

package/dist/agent-runtime/model-spec.js

@@ -0,0 +1,17 @@
+/**
+ * Parse a pi-ai model identifier in provider:modelId format.
+ */
+export function parsePiAiModelSpec(model) {
+    const value = model.trim();
+    const separatorIndex = value.indexOf(":");
+    if (separatorIndex === -1) {
+        throw new Error(`pi-ai model "${model}" is invalid. Expected format: provider:modelId`);
+    }
+    const provider = value.slice(0, separatorIndex).trim();
+    const modelId = value.slice(separatorIndex + 1).trim();
+    if (!provider || !modelId) {
+        throw new Error(`pi-ai model "${model}" is invalid. Expected format: provider:modelId`);
+    }
+    return { provider, modelId };
+}
+//# sourceMappingURL=model-spec.js.map

package/dist/agent-runtime/model-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-spec.js","sourceRoot":"","sources":["../../src/agent-runtime/model-spec.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAE1C,IAAI,cAAc,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,iDAAiD,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEvD,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,iDAAiD,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC"}

package/dist/agent-runtime/pi-ai.d.ts

@@ -0,0 +1,8 @@
+import type { AgentRuntimeConfig } from "../types.js";
+import type { AgentMessage, AgentQueryRequest, AgentRuntime } from "./types.js";
+export declare class PiAiAgentRuntime implements AgentRuntime {
+    readonly id = "pi-ai";
+    private readonly runtimeConfig?;
+    constructor(runtimeConfig?: AgentRuntimeConfig);
+    query(request: AgentQueryRequest): AsyncIterable<AgentMessage>;
+}