patchwork-os 0.2.0-alpha.0

package/dist/ccPermissions.js

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function loadCcPermissions(workspace, deps = {}) {
+    const read = deps.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const ex = deps.exists ?? existsSync;
+    // Managed path (if provided) is prepended — its deny rules are absolute
+    // because deny already wins over all other layers in evaluateRules.
+    const paths = [
+        ...(deps.managedPath ? [deps.managedPath] : []),
+        join(workspace, ".claude", "settings.local.json"),
+        join(workspace, ".claude", "settings.json"),
+        join(homedir(), ".claude", "settings.json"),
+    ];
+    const merged = { allow: [], ask: [], deny: [] };
+    for (const p of paths) {
+        if (!ex(p))
+            continue;
+        try {
+            const parsed = JSON.parse(read(p));
+            const r = parsed.permissions ?? {};
+            if (Array.isArray(r.allow))
+                merged.allow.push(...r.allow);
+            if (Array.isArray(r.ask))
+                merged.ask.push(...r.ask);
+            if (Array.isArray(r.deny))
+                merged.deny.push(...r.deny);
+        }
+        catch {
+            // silently skip — malformed settings shouldn't block the bridge
+        }
+    }
+    return merged;
+}
+/**
+ * Like loadCcPermissions but tags each rule with its originating source file
+ * so the dashboard can render per-rule attribution badges.
+ */
+export function loadCcPermissionsAttributed(workspace, deps = {}) {
+    const read = deps.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const ex = deps.exists ?? existsSync;
+    const sources = [
+        ...(deps.managedPath
+            ? [{ path: deps.managedPath, source: "managed" }]
+            : []),
+        {
+            path: join(workspace, ".claude", "settings.local.json"),
+            source: "project-local",
+        },
+        {
+            path: join(workspace, ".claude", "settings.json"),
+            source: "project",
+        },
+        {
+            path: join(homedir(), ".claude", "settings.json"),
+            source: "user",
+        },
+    ];
+    const merged = { allow: [], ask: [], deny: [] };
+    for (const { path: p, source } of sources) {
+        if (!ex(p))
+            continue;
+        try {
+            const parsed = JSON.parse(read(p));
+            const r = parsed.permissions ?? {};
+            if (Array.isArray(r.allow))
+                merged.allow.push(...r.allow.map((pattern) => ({ pattern, source })));
+            if (Array.isArray(r.ask))
+                merged.ask.push(...r.ask.map((pattern) => ({ pattern, source })));
+            if (Array.isArray(r.deny))
+                merged.deny.push(...r.deny.map((pattern) => ({ pattern, source })));
+        }
+        catch {
+            // silently skip — malformed settings shouldn't block the bridge
+        }
+    }
+    return merged;
+}
+/**
+ * Classify a tool call against CC rules using deny → ask → allow precedence.
+ *
+ * Specifier patterns follow CC's glob syntax:
+ *   - Tool name only:           "Read"
+ *   - Exact specifier:          "Bash(git status)"
+ *   - Glob specifier:           "Bash(npm run *)", "WebFetch(https://api.example.com/*)"
+ *   - Legacy colon-star:        "Bash(git:*)"
+ *   - Full wildcard:            "Bash(*)"
+ *
+ * Path-glob rules (Read/Edit with file patterns) are forwarded to allow
+ * so CC's own runtime can apply the finer-grained check.
+ */
+export function evaluateRules(toolName, specifier, rules) {
+    if (anyMatch(toolName, specifier, rules.deny))
+        return "deny";
+    if (anyMatch(toolName, specifier, rules.ask))
+        return "ask";
+    if (anyMatch(toolName, specifier, rules.allow))
+        return "allow";
+    return "none";
+}
+function anyMatch(toolName, specifier, patterns) {
+    for (const pat of patterns) {
+        if (matchRule(toolName, specifier, pat))
+            return true;
+    }
+    return false;
+}
+function matchRule(toolName, specifier, rule) {
+    // Tool-name-only rule — no specifier constraint.
+    if (!rule.includes("("))
+        return rule === toolName;
+    const open = rule.indexOf("(");
+    const close = rule.lastIndexOf(")");
+    if (close === -1)
+        return false;
+    const tool = rule.slice(0, open);
+    const pat = rule.slice(open + 1, close);
+    if (tool !== toolName)
+        return false;
+    // Full wildcard — matches any specifier (or no specifier).
+    if (pat === "*")
+        return true;
+    // No specifier on call — only the bare wildcards match.
+    if (!specifier)
+        return pat === "" || pat === ":*";
+    // Legacy colon-star form: "git:*" means "git" or "git <anything>".
+    // Normalize to space-star so the glob engine handles it uniformly.
+    const normalized = pat.endsWith(":*") ? `${pat.slice(0, -2)} *` : pat;
+    return globMatch(normalized, specifier);
+}
+/**
+ * Minimal glob matcher supporting `*` (any sequence) and `?` (any char).
+ * No path semantics — `*` matches across separators, which is what CC
+ * uses for command specifiers like "npm run *" or "https://example.com/*".
+ */
+function globMatch(pattern, str) {
+    // Fast path: no wildcards.
+    if (!pattern.includes("*") && !pattern.includes("?")) {
+        return pattern === str;
+    }
+    // dp[i][j] = pattern[0..i) matches str[0..j)
+    const p = pattern.length;
+    const s = str.length;
+    const dp = Array.from({ length: p + 1 }, () => new Array(s + 1).fill(false));
+    dp[0][0] = true;
+    // Leading stars match empty string.
+    for (let i = 1; i <= p; i++) {
+        if (pattern[i - 1] === "*")
+            dp[i][0] = dp[i - 1][0];
+    }
+    for (let i = 1; i <= p; i++) {
+        for (let j = 1; j <= s; j++) {
+            if (pattern[i - 1] === "*") {
+                dp[i][j] = dp[i - 1][j] || dp[i][j - 1];
+            }
+            else if (pattern[i - 1] === "?" || pattern[i - 1] === str[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+        }
+    }
+    return dp[p][s];
+}
+//# sourceMappingURL=ccPermissions.js.map

package/dist/ccPermissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccPermissions.js","sourceRoot":"","sources":["../src/ccPermissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAiDjC,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,OAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC;IAErC,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,qBAAqB,CAAC;QACjD,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,CAAC;KAC5C,CAAC;IAEF,MAAM,MAAM,GAAoB,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACjE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAAE,SAAS;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAiB,CAAC;YACnD,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;YACnC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;YAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACpD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAAiB,EACjB,OAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC;IAErC,MAAM,OAAO,GAAgD;QAC3D,GAAG,CAAC,IAAI,CAAC,WAAW;YAClB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,SAAuB,EAAE,CAAC;YAC/D,CAAC,CAAC,EAAE,CAAC;QACP;YACE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,qBAAqB,CAAC;YACvD,MAAM,EAAE,eAA6B;SACtC;QACD;YACE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,CAAC;YACjD,MAAM,EAAE,SAAuB;SAChC;QACD;YACE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,eAAe,CAAC;YACjD,MAAM,EAAE,MAAoB;SAC7B;KACF,CAAC;IAEF,MAAM,MAAM,GAA8B,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC3E,KAAK,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QAC1C,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAAE,SAAS;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAiB,CAAC;YACnD,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;YACnC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBACxB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACxE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;gBACtB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACpE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,SAA6B,EAC7B,KAAsB;IAEtB,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAC7D,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,QAAQ,CACf,QAAgB,EAChB,SAA6B,EAC7B,QAAkB;IAElB,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACvD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAChB,QAAgB,EAChB,SAA6B,EAC7B,IAAY;IAEZ,iDAAiD;IACjD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,KAAK,QAAQ,CAAC;IAElD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEpC,2DAA2D;IAC3D,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAE7B,wDAAwD;IACxD,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,IAAI,CAAC;IAElD,mEAAmE;IACnE,mEAAmE;IACnE,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IAEtE,OAAO,SAAS,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,OAAe,EAAE,GAAW;IAC7C,2BAA2B;IAC3B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO,OAAO,KAAK,GAAG,CAAC;IACzB,CAAC;IAED,6CAA6C;IAC7C,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IACrB,MAAM,EAAE,GAAgB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,CACzD,IAAI,KAAK,CAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CACtC,CAAC;IACF,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEjB,oCAAoC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG;YAAE,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,CAAE,CAAC;IACzD,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC3B,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;YAC/C,CAAC;iBAAM,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACnE,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAE,CAAC;AACpB,CAAC"}

package/dist/claudeDriver.d.ts

@@ -0,0 +1,129 @@
+export interface ClaudeTaskInput {
+    prompt: string;
+    contextFiles?: string[];
+    workspace: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+    onChunk?: (chunk: string) => void;
+    /** Optional model override, e.g. "claude-haiku-4-5-20251001". Passed as --model to the subprocess. */
+    model?: string;
+    /** Effort level for the task (low/medium/high/max). Passed as --effort to the subprocess. */
+    effort?: "low" | "medium" | "high" | "max";
+    /** Fallback model when the primary is overloaded. Passed as --fallback-model. */
+    fallbackModel?: string;
+    /** Maximum spend cap in USD for this task. Passed as --max-budget-usd. */
+    maxBudgetUsd?: number;
+    /** Abort the task if no assistant output arrives within this many ms of spawn. */
+    startupTimeoutMs?: number;
+    /** Custom system prompt passed via --system-prompt to the subprocess. */
+    systemPrompt?: string;
+    /** If true, spawn the ant binary instead of claude. */
+    useAnt?: boolean;
+}
+/**
+ * @deprecated Use ClaudeTaskOutcome instead for discriminated-union pattern.
+ * Kept for backward compat — existing ClaudeTask fields reference these fields.
+ */
+export interface ClaudeTaskOutput {
+    text: string;
+    exitCode: number;
+    durationMs: number;
+    /** Last ~2KB of stderr, if any. Used for investigating timeouts and crashes. */
+    stderrTail?: string;
+    /** True if the subprocess was aborted (timeout or explicit cancel). */
+    wasAborted?: boolean;
+    /** True if the task was aborted because no assistant output arrived within startupTimeoutMs. */
+    startupTimedOut?: boolean;
+    /** Milliseconds from spawn to first assistant output event. Undefined if no output arrived before timeout. */
+    startupMs?: number;
+}
+/**
+ * Discriminated-union replacement for ClaudeTaskOutput.
+ * Use toClaudeTaskOutcome() to convert a ClaudeTaskOutput.
+ */
+export type ClaudeTaskOutcome = {
+    outcome: "done";
+    text: string;
+    durationMs: number;
+    startupMs?: number;
+} | {
+    outcome: "error";
+    text: string;
+    exitCode: number;
+    stderrTail?: string;
+    durationMs: number;
+} | {
+    outcome: "aborted";
+    text: string;
+    cancelKind: "startup_timeout" | "timeout" | "user";
+    stderrTail?: string;
+    durationMs: number;
+};
+/**
+ * Map a ClaudeTaskOutput flat struct to the ClaudeTaskOutcome discriminated union.
+ *
+ * @param output     Flat output from ClaudeDriver.run().
+ * @param cancelReason  Optional cancelReason from the ClaudeTask record (set by
+ *                   the orchestrator after run() returns).  When provided,
+ *                   "timeout" and "startup_timeout" cancelKinds are reachable.
+ *                   Without it, aborted tasks default to cancelKind "user".
+ */
+export declare function toClaudeTaskOutcome(output: ClaudeTaskOutput, cancelReason?: "timeout" | "startup_timeout" | "user" | "shutdown"): ClaudeTaskOutcome;
+export interface IClaudeDriver {
+    readonly name: string;
+    run(input: ClaudeTaskInput): Promise<ClaudeTaskOutput>;
+    /** Optional lifecycle hooks — no-op in SubprocessDriver. */
+    spawnForSession?(sessionId: string): Promise<void>;
+    killForSession?(sessionId: string): void;
+    /**
+     * Optional: run and return a ClaudeTaskOutcome discriminated union.
+     * Default implementation wraps run() via toClaudeTaskOutcome().
+     */
+    runOutcome?(input: ClaudeTaskInput): Promise<ClaudeTaskOutcome>;
+}
+export declare class SubprocessDriver implements IClaudeDriver {
+    private readonly binary;
+    private readonly antBinary;
+    private readonly log;
+    readonly name = "subprocess";
+    private readonly settingsPath;
+    private readonly settingsContent;
+    constructor(binary: string, antBinary: string, log: (msg: string) => void);
+    private _writeSettings;
+    run(input: ClaudeTaskInput): Promise<ClaudeTaskOutput>;
+    runOutcome(input: ClaudeTaskInput): Promise<ClaudeTaskOutcome>;
+}
+/**
+ * ApiDriver — uses @anthropic-ai/sdk directly.
+ * Requires ANTHROPIC_API_KEY env var and @anthropic-ai/sdk package.
+ * Full implementation is a separate concern; this stub fails fast with a clear error.
+ */
+export declare class ApiDriver implements IClaudeDriver {
+    private readonly log;
+    readonly name = "api";
+    constructor(log: (msg: string) => void);
+    run(_input: ClaudeTaskInput): Promise<ClaudeTaskOutput>;
+}
+/**
+ * ServerModeDriver — future adapter for `claude --server` stdio JSON-RPC API.
+ * Stub: documents the exact extension point; throws immediately if instantiated.
+ *
+ * When `claude --server` is confirmed and documented:
+ * 1. Spawn: `const child = spawn(binary, ["--server"], { stdio: "pipe", ... })`
+ * 2. Write JSON-RPC requests to child.stdin
+ * 3. Read JSON-RPC responses from child.stdout (readline + JSON.parse)
+ * 4. Map streaming partial responses to onChunk callbacks
+ * 5. Implement spawnForSession / killForSession for persistent-per-session lifecycle
+ */
+export declare class ServerModeDriver implements IClaudeDriver {
+    readonly name = "server";
+    constructor(_binary: string, _log: (msg: string) => void);
+    run(_input: ClaudeTaskInput): Promise<ClaudeTaskOutput>;
+}
+/**
+ * Scrub secrets from a string before storing or surfacing it.
+ * Exported for testability.
+ */
+export declare function scrubSecrets(text: string): string;
+/** Factory: creates the appropriate driver from a config mode string. */
+export declare function createDriver(mode: "subprocess" | "api" | "none", binary: string, antBinary: string, log: (msg: string) => void): IClaudeDriver | null;