@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/runners/git-utils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared git utilities for agent runners.
+ */
+/**
+ * Run a git command in the given directory.
+ *
+ * Always passes `-c core.quotePath=false` so paths containing non-ASCII
+ * characters (e.g. ↔, é, 中) come back as raw UTF-8 instead of git's default
+ * octal-escaped form (`"file with \342\206\224.md"`). Without this, the AISDLC-68
+ * task file (which has ↔ in its name) showed up in `git diff --name-only`
+ * as a quoted+escaped string and the subsequent `git add -- <file>` rejected
+ * with "pathspec did not match".
+ *
+ * Uses `cleanGitEnv()` (AISDLC-72) so git resolves against `workDir`'s own
+ * .git rather than whatever a parent process (husky pre-push hook running
+ * in another worktree) leaked into GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE.
+ */
+export declare function gitExec(workDir: string, args: string[]): Promise<string>;
+export interface DetectedChanges {
+    filesChanged: string[];
+    agentAlreadyCommitted: boolean;
+}
+export interface WorktreeBaseline {
+    /** Set of paths that were untracked BEFORE the agent ran. */
+    untracked: Set<string>;
+    /** Set of paths that had unstaged modifications BEFORE the agent ran. */
+    modified: Set<string>;
+}
+/**
+ * Snapshot the untracked + modified file lists in the worktree. Captured before
+ * the agent runs so detectChangedFiles can subtract pre-existing noise (SQLite
+ * working files, draft RFCs the user hasn't decided to commit yet, in-flight
+ * edits on the previous branch). Without this, `git add -A` sweeps everything
+ * into the agent's commit (the AISDLC-68 incident).
+ *
+ * Failures degrade gracefully to an empty baseline — never block the pipeline
+ * because the snapshot couldn't run.
+ */
+export declare function snapshotWorktree(workDir: string): Promise<WorktreeBaseline>;
+/**
+ * Detect files changed by an agent. Three signals contribute:
+ *
+ *   - **Unstaged working-tree changes** (`git diff --name-only`)
+ *   - **Staged but uncommitted changes** (`git diff --name-only --cached`) — the
+ *     agent sometimes runs `git add` itself before yielding control. Without
+ *     this signal the orchestrator returned "Agent made no changes" and bailed
+ *     even though the agent's work was sitting in the index (the AISDLC-68
+ *     fourth-rerun bug).
+ *   - **Untracked files** (`git ls-files --others`)
+ *
+ * When `baseline` is provided, untracked files that existed BEFORE the agent
+ * ran are excluded — they belong to the user, not the agent's diff.
+ *
+ * Also checks whether the agent self-committed (compares HEAD to merge-base
+ * with origin/main). Self-committed runs short-circuit the orchestrator's
+ * commit step.
+ */
+export declare function detectChangedFiles(workDir: string, baseline?: WorktreeBaseline): Promise<DetectedChanges>;
+export interface CrossRepoWrite {
+    /** Sibling repository absolute path. */
+    repoPath: string;
+    /** Files modified or added in that sibling, relative to its root. */
+    files: string[];
+}
+/**
+ * Detect writes the agent made into sibling git repositories (i.e., directories
+ * adjacent to `workDir` that are themselves git repos). Surfaced as a warning,
+ * not a hard failure — the AISDLC-68 task LEGITIMATELY needed to sync into
+ * `../ai-sdlc-io/`, and we don't want to forbid that. The orchestrator just
+ * needs to surface that the changes exist so the operator knows to commit them
+ * separately in the sibling repo.
+ *
+ * Returns one entry per dirty sibling repo, with the list of changed files.
+ * Empty array when no siblings are dirty (the common case).
+ */
+export declare function detectCrossRepoWrites(workDir: string): Promise<CrossRepoWrite[]>;
+/**
+ * Run lint and format auto-fix commands (best-effort, non-fatal).
+ */
+export declare function runAutoFix(workDir: string, lintCmd?: string, fmtCmd?: string): Promise<void>;
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/runners/git-utils.js

@@ -0,0 +1,201 @@
+/**
+ * Shared git utilities for agent runners.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { cleanGitEnv } from '../runtime/git-env.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Run a git command in the given directory.
+ *
+ * Always passes `-c core.quotePath=false` so paths containing non-ASCII
+ * characters (e.g. ↔, é, 中) come back as raw UTF-8 instead of git's default
+ * octal-escaped form (`"file with \342\206\224.md"`). Without this, the AISDLC-68
+ * task file (which has ↔ in its name) showed up in `git diff --name-only`
+ * as a quoted+escaped string and the subsequent `git add -- <file>` rejected
+ * with "pathspec did not match".
+ *
+ * Uses `cleanGitEnv()` (AISDLC-72) so git resolves against `workDir`'s own
+ * .git rather than whatever a parent process (husky pre-push hook running
+ * in another worktree) leaked into GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE.
+ */
+export async function gitExec(workDir, args) {
+    const { stdout } = await execFileAsync('git', ['-c', 'core.quotePath=false', ...args], {
+        cwd: workDir,
+        env: cleanGitEnv(),
+    });
+    return stdout.trim();
+}
+/**
+ * Snapshot the untracked + modified file lists in the worktree. Captured before
+ * the agent runs so detectChangedFiles can subtract pre-existing noise (SQLite
+ * working files, draft RFCs the user hasn't decided to commit yet, in-flight
+ * edits on the previous branch). Without this, `git add -A` sweeps everything
+ * into the agent's commit (the AISDLC-68 incident).
+ *
+ * Failures degrade gracefully to an empty baseline — never block the pipeline
+ * because the snapshot couldn't run.
+ */
+export async function snapshotWorktree(workDir) {
+    try {
+        const [untrackedOutput, modifiedOutput] = await Promise.all([
+            gitExec(workDir, ['ls-files', '--others', '--exclude-standard']),
+            gitExec(workDir, ['diff', '--name-only']),
+        ]);
+        return {
+            untracked: new Set(untrackedOutput.split('\n').filter(Boolean)),
+            modified: new Set(modifiedOutput.split('\n').filter(Boolean)),
+        };
+    }
+    catch {
+        return { untracked: new Set(), modified: new Set() };
+    }
+}
+/**
+ * Detect files changed by an agent. Three signals contribute:
+ *
+ *   - **Unstaged working-tree changes** (`git diff --name-only`)
+ *   - **Staged but uncommitted changes** (`git diff --name-only --cached`) — the
+ *     agent sometimes runs `git add` itself before yielding control. Without
+ *     this signal the orchestrator returned "Agent made no changes" and bailed
+ *     even though the agent's work was sitting in the index (the AISDLC-68
+ *     fourth-rerun bug).
+ *   - **Untracked files** (`git ls-files --others`)
+ *
+ * When `baseline` is provided, untracked files that existed BEFORE the agent
+ * ran are excluded — they belong to the user, not the agent's diff.
+ *
+ * Also checks whether the agent self-committed (compares HEAD to merge-base
+ * with origin/main). Self-committed runs short-circuit the orchestrator's
+ * commit step.
+ */
+export async function detectChangedFiles(workDir, baseline) {
+    const [diffOutput, stagedOutput, untrackedOutput] = await Promise.all([
+        gitExec(workDir, ['diff', '--name-only']),
+        gitExec(workDir, ['diff', '--name-only', '--cached']),
+        gitExec(workDir, ['ls-files', '--others', '--exclude-standard']),
+    ]);
+    const allUntracked = untrackedOutput.split('\n').filter(Boolean);
+    // Untracked files that existed pre-agent are user state — exclude them.
+    const agentUntracked = baseline
+        ? allUntracked.filter((f) => !baseline.untracked.has(f))
+        : allUntracked;
+    // Combine + dedupe: a file may show up in both unstaged and staged diffs
+    // (partial-stage scenario), and untracked files are mutually exclusive
+    // with diffs but include for completeness.
+    const uncommittedSet = new Set([
+        ...diffOutput.split('\n').filter(Boolean),
+        ...stagedOutput.split('\n').filter(Boolean),
+        ...agentUntracked,
+    ]);
+    const uncommittedFiles = [...uncommittedSet];
+    // Check if agent already committed — compare against merge base with main
+    let committedFiles = [];
+    let agentAlreadyCommitted = false;
+    try {
+        const mergeBase = (await gitExec(workDir, ['merge-base', 'HEAD', 'origin/main'])).trim();
+        if (mergeBase) {
+            const commitDiff = await gitExec(workDir, ['diff', '--name-only', `${mergeBase}..HEAD`]);
+            committedFiles = commitDiff.split('\n').filter(Boolean);
+            agentAlreadyCommitted = committedFiles.length > 0 && uncommittedFiles.length === 0;
+        }
+    }
+    catch {
+        // merge-base may fail if main doesn't exist locally — that's fine
+    }
+    return {
+        filesChanged: agentAlreadyCommitted ? committedFiles : uncommittedFiles,
+        agentAlreadyCommitted,
+    };
+}
+/**
+ * Detect writes the agent made into sibling git repositories (i.e., directories
+ * adjacent to `workDir` that are themselves git repos). Surfaced as a warning,
+ * not a hard failure — the AISDLC-68 task LEGITIMATELY needed to sync into
+ * `../ai-sdlc-io/`, and we don't want to forbid that. The orchestrator just
+ * needs to surface that the changes exist so the operator knows to commit them
+ * separately in the sibling repo.
+ *
+ * Returns one entry per dirty sibling repo, with the list of changed files.
+ * Empty array when no siblings are dirty (the common case).
+ */
+export async function detectCrossRepoWrites(workDir) {
+    const { readdir, stat } = await import('node:fs/promises');
+    const { dirname, join, resolve } = await import('node:path');
+    let workTreeRoot;
+    try {
+        workTreeRoot = await gitExec(workDir, ['rev-parse', '--show-toplevel']);
+    }
+    catch {
+        return [];
+    }
+    const parent = dirname(resolve(workTreeRoot));
+    let entries;
+    try {
+        entries = await readdir(parent);
+    }
+    catch {
+        return [];
+    }
+    const writes = [];
+    for (const entry of entries) {
+        const candidate = join(parent, entry);
+        if (resolve(candidate) === resolve(workTreeRoot))
+            continue; // skip self
+        try {
+            const s = await stat(candidate);
+            if (!s.isDirectory())
+                continue;
+            // Quick git-repo check via `rev-parse --is-inside-work-tree`.
+            await gitExec(candidate, ['rev-parse', '--is-inside-work-tree']);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const status = await gitExec(candidate, ['status', '--porcelain']);
+            if (!status.trim())
+                continue;
+            // Porcelain v1: first 2 chars are status (XY), then 1+ whitespace, then
+            // path. Cannot use slice(3) — gitExec already trimmed the leading space
+            // when X is unmodified ("M " becomes "M" after trim, dropping a column
+            // and eating the first filename character).
+            const files = status
+                .split('\n')
+                .filter(Boolean)
+                .map((line) => {
+                const m = line.match(/^.{1,2}\s+(.+)$/);
+                return m ? m[1] : line;
+            });
+            writes.push({ repoPath: candidate, files });
+        }
+        catch {
+            // Couldn't read status — skip silently.
+        }
+    }
+    return writes;
+}
+/**
+ * Run lint and format auto-fix commands (best-effort, non-fatal).
+ */
+export async function runAutoFix(workDir, lintCmd, fmtCmd) {
+    if (fmtCmd) {
+        try {
+            const [bin, ...args] = fmtCmd.split(' ');
+            await execFileAsync(bin, args, { cwd: workDir });
+        }
+        catch {
+            // Format failures are non-fatal
+        }
+    }
+    if (lintCmd) {
+        try {
+            const [bin, ...args] = lintCmd.split(' ');
+            await execFileAsync(bin, args, { cwd: workDir });
+        }
+        catch {
+            // Lint --fix failures are non-fatal
+        }
+    }
+}
+//# sourceMappingURL=git-utils.js.map

package/dist/runners/index.d.ts

@@ -1,5 +1,7 @@
 export type { AgentRunner, AgentContext, AgentResult, AgentProgressEvent, TokenUsage, } from './types.js';
 export { ClaudeCodeRunner, GitHubActionsRunner } from './claude-code.js';
+export { ClaudeCodeSdkRunner } from './claude-code-sdk.js';
+export { gitExec, detectChangedFiles, runAutoFix, type DetectedChanges } from './git-utils.js';
 export { GenericLLMRunner, type GenericLLMConfig, type ChatCompletionResponse, } from './generic-llm.js';
 export { CopilotRunner } from './copilot.js';
 export { CursorRunner } from './cursor.js';
@@ -7,4 +9,5 @@ export { CodexRunner } from './codex.js';
 export { RunnerRegistry, createRunnerRegistry, type RegisteredRunner } from './runner-registry.js';
 export { SecurityTriageRunner, type SecurityTriageConfig, type TriageVerdict, TRIAGE_SYSTEM_PROMPT, } from './security-triage.js';
 export { ReviewAgentRunner, REVIEW_PROMPTS, type ReviewAgentConfig, type ReviewType, type ReviewFinding, type ReviewVerdict, } from './review-agent.js';
+export { runParallelSdkReviews, DEFAULT_REVIEW_CONFIGS, type SdkReviewConfig, type SdkParallelReviewOptions, type SdkParallelReviewResult, } from './sdk-review-runner.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runners/index.js

@@ -1,4 +1,6 @@
 export { ClaudeCodeRunner, GitHubActionsRunner } from './claude-code.js';
+export { ClaudeCodeSdkRunner } from './claude-code-sdk.js';
+export { gitExec, detectChangedFiles, runAutoFix } from './git-utils.js';
 export { GenericLLMRunner, } from './generic-llm.js';
 export { CopilotRunner } from './copilot.js';
 export { CursorRunner } from './cursor.js';
@@ -6,4 +8,5 @@ export { CodexRunner } from './codex.js';
 export { RunnerRegistry, createRunnerRegistry } from './runner-registry.js';
 export { SecurityTriageRunner, TRIAGE_SYSTEM_PROMPT, } from './security-triage.js';
 export { ReviewAgentRunner, REVIEW_PROMPTS, } from './review-agent.js';
+export { runParallelSdkReviews, DEFAULT_REVIEW_CONFIGS, } from './sdk-review-runner.js';
 //# sourceMappingURL=index.js.map

package/dist/runners/review-agent.d.ts

@@ -13,6 +13,15 @@ export interface ReviewFinding {
     file?: string;
     line?: number;
     message: string;
+    /** Self-assessed confidence score (0-1). Findings below 0.5 are suppressed. */
+    confidence?: number;
+    /** Category of the finding. */
+    category?: 'logic-error' | 'security' | 'design' | 'performance' | 'testing' | 'other';
+    /** Evidence supporting the finding. Required for critical/major. */
+    evidence?: {
+        codePathTraced?: string;
+        failureScenario?: string;
+    };
 }
 export interface ReviewVerdict {
     type: ReviewType;
@@ -27,6 +36,17 @@ export interface ReviewAgentConfig {
     apiKey?: string;
     /** Model to use. Defaults to claude-sonnet-4-5. */
     model?: string;
+    /**
+     * Model to escalate to when the input exceeds the large-context threshold.
+     * Defaults to AI_SDLC_REVIEW_LARGE_MODEL env var, then claude-opus-4-7.
+     */
+    largeContextModel?: string;
+    /**
+     * Char-count threshold above which the runner switches to `largeContextModel`
+     * and sets the Anthropic 1M-context beta header. Default ~150k tokens
+     * (the standard Anthropic context limit) at the 4-chars-per-token heuristic.
+     */
+    largeContextThresholdChars?: number;
     /** Request timeout in ms. Defaults to 120_000. */
     timeoutMs?: number;
     /** Which review perspective to use. */

package/dist/runners/review-agent.js

@@ -7,59 +7,140 @@
  * pattern exactly.
  */
 import { DEFAULT_ANTHROPIC_API_URL, DEFAULT_ANTHROPIC_MODEL, DEFAULT_LLM_TIMEOUT_MS, } from '../defaults.js';
+/** Minimum confidence to include a finding in the verdict. */
+const CONFIDENCE_THRESHOLD = 0.5;
+/**
+ * Default escalation threshold. Anthropic's standard context window is 200k tokens;
+ * we leave headroom for the system prompt + response and trigger escalation around
+ * 150k tokens (≈ 600k chars at the 4-char/token heuristic). The user's recurring
+ * "PR too large for review" failure on PR #67 happened above this threshold.
+ */
+const DEFAULT_LARGE_CONTEXT_THRESHOLD_CHARS = 600_000;
+const DEFAULT_LARGE_CONTEXT_MODEL = process.env.AI_SDLC_REVIEW_LARGE_MODEL ?? 'claude-opus-4-7';
+/** Anthropic 1M-context beta header. Required when sending > 200k tokens. */
+const ANTHROPIC_LONG_CONTEXT_BETA = 'context-1m-2025-08-07';
+// ── CI boundary ─────────────────────────────────────────────────────
+/**
+ * Declarative CI boundary — tells review agents what CI already validates.
+ * Agents MUST NOT duplicate findings for issues CI catches deterministically.
+ * Prepended to every REVIEW_PROMPTS entry.
+ */
+const CI_BOUNDARY_PREAMBLE = `## CI Boundary — What You Must NOT Flag
+
+The following checks run deterministically in CI on every PR. They are authoritative.
+Do NOT flag issues that these checks catch — they run independently and will pass or fail
+on their own. If CI covers it, it is OUT OF YOUR SCOPE.
+
+**CI checks (deterministic, authoritative):**
+- **Lint (ESLint)**: All lint violations, unused imports, naming conventions
+- **Format (Prettier)**: All formatting — whitespace, semicolons, commas, line length
+- **TypeScript typecheck (pnpm build)**: Type errors, missing types, generics
+- **Unit tests (Vitest)**: Test failures, broken assertions
+- **Coverage (Codecov patch)**: Line coverage on changed code (80% patch target)
+- **Schema validation**: YAML/JSON schema conformance
+
+**Your job is to find issues CI CANNOT catch:**
+- Logic errors that pass type checking but produce wrong results
+- Security vulnerabilities (injection, auth bypass, credential exposure)
+- Missing error handling for edge cases that tests don't cover
+- Design problems (wrong abstraction, pattern violations)
+- Race conditions and concurrency issues
+- Performance anti-patterns (N+1 queries, unbounded allocations)
+- Acceptance criteria not addressed by the implementation
+
+**If unsure whether CI catches something, do NOT flag it.**
+
+`;
 // ── System prompts ───────────────────────────────────────────────────
 const REVIEW_PROMPTS = {
-    testing: `You are a testing review agent analyzing a pull request diff. Your job is to verify that the changes are well-tested and that acceptance criteria are met.
+    testing: `${CI_BOUNDARY_PREAMBLE}You are a testing review agent analyzing a pull request diff. Your job is to verify that the changes are well-tested and that acceptance criteria are met.
 
 Analyze the diff and any provided acceptance criteria. Check for:
-1. **Test coverage**: Are new/changed code paths covered by tests?
+1. **Untested logic paths**: Are there logic branches that existing tests don't exercise? (Do NOT flag coverage percentages — Codecov handles that.)
 2. **Acceptance criteria**: If provided, are all acceptance criteria addressed?
 3. **Edge cases**: Are boundary conditions and error paths tested?
 4. **Test quality**: Are tests meaningful (not just asserting true)?
-5. **Missing tests**: Are there obvious test gaps for the changed code?
+5. **Missing edge-case tests**: Are there missing tests for error paths and boundary conditions that the test suite cannot catch?
+
+Do NOT flag: coverage percentages, missing tests for config/YAML files, type-only files, or barrel exports. Codecov and CI handle these.
+
+## Structured Output Format
 
-Respond with ONLY a JSON object (no markdown, no code fences):
+Respond with ONLY a JSON object (no markdown, no code fences).
+
+Each finding MUST include a confidence score (0.0-1.0) and a category.
+For critical/major findings, you MUST include evidence with a concrete failure scenario.
+**No evidence = no critical/major finding.** If you cannot trace the code path to a failure, downgrade to minor/suggestion.
+Findings below 0.5 confidence will be automatically suppressed.
 
 {
   "approved": true/false,
   "findings": [
-    {"severity": "critical|major|minor|suggestion", "file": "path/to/file.ts", "line": 42, "message": "description"}
+    {
+      "severity": "critical|major|minor|suggestion",
+      "confidence": 0.0-1.0,
+      "category": "testing|logic-error|security|design|performance|other",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "evidence": {
+        "codePathTraced": "Function X calls Y which can return null when Z",
+        "failureScenario": "When input is empty, line 42 throws TypeError"
+      },
+      "message": "Concise description of the issue"
+    }
   ],
   "summary": "1-2 sentence overall assessment"
 }
 
 Severity guide:
-- critical: Missing tests for critical paths, acceptance criteria not met
-- major: Significant test gaps for changed code
+- critical: Missing tests for critical logic paths, acceptance criteria not met. MUST have failureScenario.
+- major: Significant untested logic branches. MUST have failureScenario.
 - minor: Minor test improvements possible
 - suggestion: Nice-to-have test additions`,
-    critic: `You are a code quality review agent analyzing a pull request diff. Your job is to identify code quality issues, logic errors, and design problems.
+    critic: `${CI_BOUNDARY_PREAMBLE}You are a code quality review agent analyzing a pull request diff. Your job is to identify logic errors and design problems.
 
 Analyze the diff for:
 1. **Logic errors**: Incorrect conditions, off-by-one errors, race conditions
-2. **Code quality**: Naming, readability, unnecessary complexity
-3. **Error handling**: Missing error cases, swallowed exceptions
-4. **Design patterns**: Violations of existing project patterns/conventions
-5. **Performance**: Obvious inefficiencies (N+1 queries, unnecessary allocations)
+2. **Design issues**: Wrong abstraction, unnecessary complexity, pattern violations
+3. **Error handling**: Missing error cases at system boundaries
+4. **Performance**: Obvious inefficiencies (N+1 queries, unbounded allocations)
+
+Do NOT flag: style issues (formatting, whitespace, import order), type errors, lint violations, or naming conventions. ESLint, Prettier, and TypeScript handle these deterministically.
 
-Do NOT flag style-only issues (formatting, trailing whitespace). Focus on substantive issues.
+## Structured Output Format
 
-Respond with ONLY a JSON object (no markdown, no code fences):
+Respond with ONLY a JSON object (no markdown, no code fences).
+
+Each finding MUST include a confidence score (0.0-1.0) and a category.
+For critical/major findings, you MUST include evidence with a concrete failure scenario.
+**No evidence = no critical/major finding.** If you cannot trace the code path to a failure, downgrade to minor/suggestion.
+Findings below 0.5 confidence will be automatically suppressed.
 
 {
   "approved": true/false,
   "findings": [
-    {"severity": "critical|major|minor|suggestion", "file": "path/to/file.ts", "line": 42, "message": "description"}
+    {
+      "severity": "critical|major|minor|suggestion",
+      "confidence": 0.0-1.0,
+      "category": "logic-error|design|performance|other",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "evidence": {
+        "codePathTraced": "Function X calls Y which can return null when Z",
+        "failureScenario": "When input is empty, line 42 throws TypeError"
+      },
+      "message": "Concise description of the issue"
+    }
   ],
   "summary": "1-2 sentence overall assessment"
 }
 
 Severity guide:
-- critical: Logic errors, data loss risks, broken functionality
-- major: Significant quality issues that should be fixed before merge
+- critical: Logic errors, data loss risks, broken functionality. MUST have failureScenario.
+- major: Significant design issues that should be fixed before merge. MUST have failureScenario.
 - minor: Improvements that would make the code better
 - suggestion: Optional enhancements`,
-    security: `You are a security review agent analyzing a pull request diff. Your job is to identify security vulnerabilities in the changed code.
+    security: `${CI_BOUNDARY_PREAMBLE}You are a security review agent analyzing a pull request diff. Your job is to identify security vulnerabilities in the changed code.
 
 Analyze the diff for:
 1. **Injection vulnerabilities**: SQL injection, command injection, XSS, template injection
@@ -68,21 +149,40 @@ Analyze the diff for:
 4. **Path traversal**: Unsanitized file paths, directory traversal
 5. **Unsafe deserialization**: JSON.parse on untrusted input without validation
 6. **Dependency issues**: Known vulnerable patterns, unsafe API usage
-7. **Information disclosure**: Verbose error messages, stack traces in responses
 
-Respond with ONLY a JSON object (no markdown, no code fences):
+Do NOT flag: type safety issues (TypeScript handles these), or issues in trusted internal code paths (config files, env vars set by the platform).
+
+## Structured Output Format
+
+Respond with ONLY a JSON object (no markdown, no code fences).
+
+Each finding MUST include a confidence score (0.0-1.0) and a category.
+For critical/major findings, you MUST include evidence with a concrete failure scenario.
+**No evidence = no critical/major finding.** If you cannot describe a realistic attack vector, downgrade to minor/suggestion.
+Findings below 0.5 confidence will be automatically suppressed.
 
 {
   "approved": true/false,
   "findings": [
-    {"severity": "critical|major|minor|suggestion", "file": "path/to/file.ts", "line": 42, "message": "description"}
+    {
+      "severity": "critical|major|minor|suggestion",
+      "confidence": 0.0-1.0,
+      "category": "security|other",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "evidence": {
+        "codePathTraced": "User input flows from X to Y without sanitization",
+        "failureScenario": "Attacker sends malicious input via Z, causing command injection at line 42"
+      },
+      "message": "Concise description of the vulnerability"
+    }
   ],
   "summary": "1-2 sentence overall assessment"
 }
 
 Severity guide:
-- critical: Exploitable vulnerability (injection, credential leak, auth bypass)
-- major: Security weakness that should be fixed (missing validation, unsafe patterns)
+- critical: Exploitable vulnerability (injection, credential leak, auth bypass). MUST have failureScenario with attack vector.
+- major: Security weakness that should be fixed (missing validation, unsafe patterns). MUST have failureScenario.
 - minor: Defense-in-depth improvement
 - suggestion: Security hardening opportunity`,
 };
@@ -135,24 +235,37 @@ export class ReviewAgentRunner {
     }
     async callAPI(apiKey, userContent) {
         const apiUrl = this.config.apiUrl ?? DEFAULT_ANTHROPIC_API_URL;
-        const model = this.config.model ?? DEFAULT_ANTHROPIC_MODEL;
+        const baseModel = this.config.model ?? DEFAULT_ANTHROPIC_MODEL;
         const timeoutMs = this.config.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS;
+        const system = this.config.reviewPolicy
+            ? `${this.config.reviewPolicy}\n\n---\n\n${REVIEW_PROMPTS[this.config.reviewType]}`
+            : REVIEW_PROMPTS[this.config.reviewType];
+        // Escalate to a 1M-context model when the input is large enough to risk
+        // overflowing the standard 200k-token window. The signal we use is char count
+        // of (system + user) since precise tokenization isn't available client-side.
+        const threshold = this.config.largeContextThresholdChars ?? DEFAULT_LARGE_CONTEXT_THRESHOLD_CHARS;
+        const inputChars = system.length + userContent.length;
+        const escalate = inputChars > threshold;
+        const model = escalate
+            ? (this.config.largeContextModel ?? DEFAULT_LARGE_CONTEXT_MODEL)
+            : baseModel;
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
+            const headers = {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01',
+            };
+            if (escalate)
+                headers['anthropic-beta'] = ANTHROPIC_LONG_CONTEXT_BETA;
             const res = await fetch(apiUrl, {
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': apiKey,
-                    'anthropic-version': '2023-06-01',
-                },
+                headers,
                 body: JSON.stringify({
                     model,
                     max_tokens: 4096,
-                    system: this.config.reviewPolicy
-                        ? `${this.config.reviewPolicy}\n\n---\n\n${REVIEW_PROMPTS[this.config.reviewType]}`
-                        : REVIEW_PROMPTS[this.config.reviewType],
+                    system,
                     messages: [{ role: 'user', content: userContent }],
                 }),
                 signal: controller.signal,
@@ -182,16 +295,33 @@ export class ReviewAgentRunner {
         const cleaned = text.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '');
         try {
             const parsed = JSON.parse(cleaned);
-            const findings = Array.isArray(parsed.findings)
-                ? parsed.findings.map((f) => ({
-                    severity: ['critical', 'major', 'minor', 'suggestion'].includes(String(f.severity))
-                        ? String(f.severity)
-                        : 'minor',
-                    file: f.file ? String(f.file) : undefined,
-                    line: typeof f.line === 'number' ? f.line : undefined,
-                    message: String(f.message ?? ''),
-                }))
+            const rawFindings = Array.isArray(parsed.findings)
+                ? parsed.findings.map((f) => {
+                    const evidence = f.evidence;
+                    return {
+                        severity: ['critical', 'major', 'minor', 'suggestion'].includes(String(f.severity))
+                            ? String(f.severity)
+                            : 'minor',
+                        file: f.file ? String(f.file) : undefined,
+                        line: typeof f.line === 'number' ? f.line : undefined,
+                        message: String(f.message ?? ''),
+                        confidence: typeof f.confidence === 'number' ? f.confidence : undefined,
+                        category: f.category ? String(f.category) : undefined,
+                        evidence: evidence
+                            ? {
+                                codePathTraced: evidence.codePathTraced
+                                    ? String(evidence.codePathTraced)
+                                    : undefined,
+                                failureScenario: evidence.failureScenario
+                                    ? String(evidence.failureScenario)
+                                    : undefined,
+                            }
+                            : undefined,
+                    };
+                })
                 : [];
+            // Filter out low-confidence findings
+            const findings = rawFindings.filter((f) => f.confidence === undefined || f.confidence >= CONFIDENCE_THRESHOLD);
             return {
                 type: this.config.reviewType,
                 approved: Boolean(parsed.approved),

package/dist/runners/runner-registry.js

@@ -4,6 +4,7 @@
  * Design decision D4: Registry auto-discovers available runners from environment.
  */
 import { ClaudeCodeRunner } from './claude-code.js';
+import { ClaudeCodeSdkRunner } from './claude-code-sdk.js';
 import { GenericLLMRunner } from './generic-llm.js';
 import { CopilotRunner } from './copilot.js';
 import { CursorRunner } from './cursor.js';
@@ -70,6 +71,15 @@ export class RunnerRegistry {
                 source: 'built-in',
             });
         }
+        // Claude Code SDK runner — available when @anthropic-ai/claude-agent-sdk is installed
+        if (!this.runners.has('claude-code-sdk')) {
+            this.runners.set('claude-code-sdk', {
+                name: 'claude-code-sdk',
+                runner: new ClaudeCodeSdkRunner(),
+                available: true,
+                source: 'built-in',
+            });
+        }
         // OpenAI-compatible runner from env
         const openaiKey = env.OPENAI_API_KEY;
         if (openaiKey && !this.runners.has('openai')) {