@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/README.md

@@ -2,7 +2,7 @@
 
 UI-agnostic agent orchestration framework. The headless core of [`code-shell`](https://github.com/cjhyy/codeshell): turn an LLM + a tool registry + a transcript into a multi-turn agent loop, with permissions, hooks, MCP support, and pluggable approval backends.
 
-Compatible with Anthropic and OpenAI-protocol providers (Claude, DeepSeek, GPT, Gemini, Qwen, …). No terminal UI dependencies — embed it in a CLI, a web service, a Slack bot, a desktop app.
+Compatible with Anthropic and OpenAI-protocol providers (Claude, DeepSeek, GPT, Gemini, Qwen, …). No terminal UI dependencies — embed it in a CLI, a web service, a Slack bot, a desktop app. This is a Node.js runtime package, not a browser SDK.
 
 ## Install
 
@@ -12,7 +12,7 @@ npm install @cjhyy/code-shell-core
 bun add @cjhyy/code-shell-core
 ```
 
-Requires Node ≥ 20.10.
+Requires Node ≥ 20.10 and an ESM-capable runtime.
 
 ## Quickstart
 
@@ -29,8 +29,10 @@ const engine = new Engine({
     apiKey: process.env.ANTHROPIC_API_KEY!,
   },
   cwd: process.cwd(),
-  // Headless approval — "approve-all" trusts the model fully; use
-  // "approve-read-only" or a custom ApprovalBackend in production.
+  // Headless approval — "approve-all" trusts the model fully and is
+  // only appropriate for local/trusted prompts. Use "approve-read-only",
+  // explicit permissionMode/tool allowlists, or a custom ApprovalBackend
+  // in production.
   approvalBackend: new HeadlessApprovalBackend("approve-all"),
   headless: true,
 });
@@ -78,7 +80,7 @@ new Engine({
 
 ## Designing for production
 
-- **Approval backend.** `HeadlessApprovalBackend("approve-all")` is fine for trusted prompts. For untrusted input, implement `ApprovalBackend` to gate destructive tools (Write/Edit/Bash) through your own auth.
+- **Approval backend.** `HeadlessApprovalBackend("approve-all")` is fine only for local/trusted prompts. For untrusted input, explicitly set `permissionMode`, restrict tools with `enabledBuiltinTools` / `disabledBuiltinTools`, or implement `ApprovalBackend` to gate destructive tools (Write/Edit/Bash) through your own auth.
 - **Permission rules.** Pass `permissionRules` to the engine for fine-grained allow/deny per tool + args pattern. Bash commands additionally get a built-in safety classifier (dangerous commands like `rm -rf` always require explicit approval).
 - **Hooks** are the right place for audit logging, prompt rewriting, and policy enforcement.
 - **Memory.** The engine ships with an extract-memories + auto-dream pipeline that persists to `~/.code-shell/memory/`. Disable by passing a no-op `MemoryOrchestrator`, or scope to a project by setting `CODE_SHELL_HOME`.
@@ -144,11 +146,12 @@ These exports are covered by the stability promise:
 
 ### Treat as internal
 
-Anything not in the table above — including direct imports from
-`./engine/...`, `./tool-system/...`, `./session/...`, `./hooks/...`
-subpaths and APIs marked `@internal` in their docstrings — may change
-between minor versions without notice. Plan to migrate via the protocol
-surface instead of deep-importing.
+Anything not in the table above — including root-entry exports for
+product/runtime helpers and direct imports from `./engine/...`,
+`./tool-system/...`, `./session/...`, `./hooks/...` subpaths — is
+experimental/internal unless explicitly documented otherwise, and may
+change between minor versions without notice. Plan to migrate via the
+protocol surface instead of deep-importing.
 
 ## Stability
 

package/dist/agent/agent-definition-registry.d.ts

@@ -1,13 +1,31 @@
 import { type AgentDefinition } from "./agent-definition.js";
+export interface AgentSourceDir {
+    dir: string;
+    source: "project" | "user" | "plugin";
+    /** For source === "plugin": the owning plugin name, carried onto each def
+     *  so the spawn layer can namespace bare skill allowlists. */
+    pluginName?: string;
+}
 /**
- * Loads reusable sub-agent role definitions from a directory of `*.md` files.
- * Non-recursive. Malformed files are skipped with a warning rather than
- * failing the whole load — one bad role file must not break the agent system.
+ * Loads reusable sub-agent role definitions from one or more directories
+ * of `*.md` files. Non-recursive. Malformed files are skipped with a
+ * warning rather than failing the whole load — one bad role file must
+ * not break the agent system.
+ *
+ * When multiple dirs define the same role name, the LAST dir wins. This is
+ * pure mechanism — the project>user POLICY lives in the caller's dir ORDER
+ * (loadAgentDefinitionsForCwd passes [user, ...plugins, project] so a repo's
+ * in-tree agent wins; see spec §7.2). The shadowing def is marked
+ * `override: true` and records the sources it shadowed in `shadowedSources`.
+ * Names in `disabled` are filtered out entirely after the merge, so the LLM
+ * never sees them.
  */
 export declare class AgentDefinitionRegistry {
     private defs;
     readonly warnings: string[];
+    /** Back-compat single-dir loader (project source, no disabled filter). */
     static loadFromDir(dir: string): AgentDefinitionRegistry;
+    static loadFromDirs(dirs: AgentSourceDir[], disabled: string[]): AgentDefinitionRegistry;
     has(name: string): boolean;
     get(name: string): AgentDefinition | undefined;
     list(): AgentDefinition[];

package/dist/agent/agent-definition-registry.js

@@ -2,35 +2,66 @@ import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parseAgentDefinition } from "./agent-definition.js";
 /**
- * Loads reusable sub-agent role definitions from a directory of `*.md` files.
- * Non-recursive. Malformed files are skipped with a warning rather than
- * failing the whole load — one bad role file must not break the agent system.
+ * Loads reusable sub-agent role definitions from one or more directories
+ * of `*.md` files. Non-recursive. Malformed files are skipped with a
+ * warning rather than failing the whole load — one bad role file must
+ * not break the agent system.
+ *
+ * When multiple dirs define the same role name, the LAST dir wins. This is
+ * pure mechanism — the project>user POLICY lives in the caller's dir ORDER
+ * (loadAgentDefinitionsForCwd passes [user, ...plugins, project] so a repo's
+ * in-tree agent wins; see spec §7.2). The shadowing def is marked
+ * `override: true` and records the sources it shadowed in `shadowedSources`.
+ * Names in `disabled` are filtered out entirely after the merge, so the LLM
+ * never sees them.
  */
 export class AgentDefinitionRegistry {
     defs = new Map();
     warnings = [];
+    /** Back-compat single-dir loader (project source, no disabled filter). */
     static loadFromDir(dir) {
+        return AgentDefinitionRegistry.loadFromDirs([{ dir, source: "project" }], []);
+    }
+    static loadFromDirs(dirs, disabled) {
         const reg = new AgentDefinitionRegistry();
-        if (!existsSync(dir) || !statSync(dir).isDirectory())
-            return reg;
-        for (const entry of readdirSync(dir).sort()) {
-            if (!entry.endsWith(".md"))
+        for (const { dir, source, pluginName } of dirs) {
+            if (!existsSync(dir) || !statSync(dir).isDirectory())
                 continue;
-            const full = join(dir, entry);
-            try {
-                if (!statSync(full).isFile())
-                    continue;
-                const def = parseAgentDefinition(readFileSync(full, "utf8"), entry);
-                if (reg.defs.has(def.name)) {
-                    reg.warnings.push(`${entry}: duplicate agent name '${def.name}' ignored (first definition wins)`);
+            for (const entry of readdirSync(dir).sort()) {
+                if (!entry.endsWith(".md"))
                     continue;
+                const full = join(dir, entry);
+                try {
+                    if (!statSync(full).isFile())
+                        continue;
+                    const def = parseAgentDefinition(readFileSync(full, "utf8"), entry);
+                    def.source = source;
+                    if (pluginName)
+                        def.pluginName = pluginName;
+                    def.filePath = full;
+                    // A later dir overriding an earlier one. Carry forward the shadowed
+                    // sources (the prev def's own source + anything it already shadowed)
+                    // so a project def that shadows a plugin def that shadowed a user
+                    // def reports both.
+                    const prev = reg.defs.get(def.name);
+                    if (prev) {
+                        def.override = true;
+                        const shadowed = new Set(prev.shadowedSources ?? []);
+                        if (prev.source)
+                            shadowed.add(prev.source);
+                        def.shadowedSources = [...shadowed];
+                    }
+                    reg.defs.set(def.name, def);
+                }
+                catch (err) {
+                    reg.warnings.push(`${entry}: ${err.message}`);
                 }
-                reg.defs.set(def.name, def);
-            }
-            catch (err) {
-                reg.warnings.push(`${entry}: ${err.message}`);
             }
         }
+        // Filter disabled roles after the merge so a user override of a
+        // disabled name is still removed.
+        for (const name of new Set(disabled))
+            reg.defs.delete(name);
         return reg;
     }
     has(name) {

package/dist/agent/agent-definition.d.ts

@@ -10,11 +10,43 @@ export interface AgentDefinition {
     maxTurns?: number;
     /** Optional tool allowlist. Undefined → inherit parent's full tool set. */
     tools?: string[];
+    /**
+     * Optional skill allowlist. Undefined → inherit the parent's full skill
+     * pool (every non-disabled skill in the project). When set, the sub-agent
+     * physically only sees these skills: they're the only ones listed in its
+     * system prompt and the only ones it may invoke. Empty array → no skills.
+     */
+    skills?: string[];
     /** Markdown body — becomes the child Engine's appendSystemPrompt. */
     systemPrompt: string;
+    /** Where this def was loaded from. Runtime-only; never serialized. */
+    source?: "project" | "user" | "plugin";
+    /**
+     * Owning plugin name when source === "plugin" (e.g. "mimi-video"). Runtime-
+     * only; never serialized. Used to namespace this agent's bare skill
+     * allowlist into `<pluginName>:<skill>` at spawn time, since a plugin's
+     * frontmatter references its own skills by bare name (CC convention) but
+     * the scanner registers them namespaced. Undefined for project/user agents.
+     */
+    pluginName?: string;
+    /** Absolute path of the file it came from. Runtime-only. */
+    filePath?: string;
+    /** True when this def shadows a same-named def from a lower-priority dir. */
+    override?: boolean;
+    /** Sources whose same-named def this one shadows (runtime-only). Drives the
+     *  UI "this project overrides your user version" warning (spec §7.2). */
+    shadowedSources?: Array<"project" | "user" | "plugin">;
 }
 /**
  * Parse a Markdown agent-definition file (YAML frontmatter + body).
  * Pure: no filesystem access. `sourceName` is only used in error messages.
  */
 export declare function parseAgentDefinition(raw: string, sourceName: string): AgentDefinition;
+/**
+ * Serialize an AgentDefinition back to a Markdown file body (YAML
+ * frontmatter + system prompt). Inverse of parseAgentDefinition.
+ * Optional fields that are unset are omitted entirely so an inheriting
+ * role (e.g. model undefined → inherit parent) stays clean on disk.
+ * Runtime-only metadata (source/filePath/override) is never written.
+ */
+export declare function serializeAgentDefinition(def: AgentDefinition): string;

package/dist/agent/agent-definition.js

@@ -1,4 +1,23 @@
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+/**
+ * Normalize a frontmatter `tools:` / `skills:` value into a string[].
+ * Accepts both a YAML list (`[a, b]`) and a comma/whitespace-separated
+ * string (`a, b`) — CC-lineage agent files use either form. Returns
+ * undefined when the field is absent or not a usable shape, so the caller
+ * keeps the "inherit parent" default.
+ */
+function normalizeNameList(value) {
+    if (Array.isArray(value)) {
+        return value.filter((t) => typeof t === "string");
+    }
+    if (typeof value === "string") {
+        return value
+            .split(/[,\s]+/)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    return undefined;
+}
 /**
  * Parse a Markdown agent-definition file (YAML frontmatter + body).
  * Pure: no filesystem access. `sourceName` is only used in error messages.
@@ -31,8 +50,34 @@ export function parseAgentDefinition(raw, sourceName) {
         def.model = fm.model.trim();
     if (typeof fm.maxTurns === "number")
         def.maxTurns = fm.maxTurns;
-    if (Array.isArray(fm.tools)) {
-        def.tools = fm.tools.filter((t) => typeof t === "string");
-    }
+    const tools = normalizeNameList(fm.tools);
+    if (tools !== undefined)
+        def.tools = tools;
+    const skills = normalizeNameList(fm.skills);
+    if (skills !== undefined)
+        def.skills = skills;
     return def;
 }
+/**
+ * Serialize an AgentDefinition back to a Markdown file body (YAML
+ * frontmatter + system prompt). Inverse of parseAgentDefinition.
+ * Optional fields that are unset are omitted entirely so an inheriting
+ * role (e.g. model undefined → inherit parent) stays clean on disk.
+ * Runtime-only metadata (source/filePath/override) is never written.
+ */
+export function serializeAgentDefinition(def) {
+    const fm = {
+        name: def.name,
+        description: def.description,
+    };
+    if (def.model !== undefined)
+        fm.model = def.model;
+    if (def.maxTurns !== undefined)
+        fm.maxTurns = def.maxTurns;
+    if (def.tools !== undefined)
+        fm.tools = def.tools;
+    if (def.skills !== undefined)
+        fm.skills = def.skills;
+    const yaml = stringifyYaml(fm).trimEnd();
+    return `---\n${yaml}\n---\n${def.systemPrompt}\n`;
+}

package/dist/arena/arena.js

@@ -28,6 +28,15 @@ import { runDetailExpansion } from "./phases/planning-detail-expansion.js";
 import { withLanguage } from "./strategies/language-wrapper.js";
 import { ArenaLedger } from "./ledger.js";
 import { registerClaims } from "./phases/claim-registry.js";
+/** Bucket claims by status. Shared by the two consensus phases. */
+function summarizeClaims(all) {
+    return {
+        verified: all.filter((c) => c.status === "verified"),
+        contested: all.filter((c) => c.status === "contested"),
+        unresolved: all.filter((c) => c.status === "unresolved"),
+        rejected: all.filter((c) => c.status === "rejected"),
+    };
+}
 export class Arena {
     config;
     strategy;
@@ -192,12 +201,7 @@ export class Arena {
         signal?.throwIfAborted();
         // ─── Roadmap Consensus ───────────────────────────────────
         const allClaims = ledger.getAllClaims();
-        const claimSummary = {
-            verified: allClaims.filter((c) => c.status === "verified"),
-            contested: allClaims.filter((c) => c.status === "contested"),
-            unresolved: allClaims.filter((c) => c.status === "unresolved"),
-            rejected: allClaims.filter((c) => c.status === "rejected"),
-        };
+        const claimSummary = summarizeClaims(allClaims);
         logger.info("arena.planning_consensus_phase", { concluder: concluder.name });
         const consensus = await buildConsensus({
             concluder,
@@ -295,12 +299,7 @@ export class Arena {
         signal?.throwIfAborted();
         // ─── Consensus (claim-aware) ─────────────────────────────
         const allClaims = ledger.getAllClaims();
-        const claimSummary = {
-            verified: allClaims.filter((c) => c.status === "verified"),
-            contested: allClaims.filter((c) => c.status === "contested"),
-            unresolved: allClaims.filter((c) => c.status === "unresolved"),
-            rejected: allClaims.filter((c) => c.status === "rejected"),
-        };
+        const claimSummary = summarizeClaims(allClaims);
         logger.info("arena.consensus_phase", {
             concluder: concluder.name,
             verified: claimSummary.verified.length,

package/dist/arena/context/context-tools.js

@@ -6,9 +6,10 @@
  * to prevent command injection. File paths are validated against the
  * repository boundary to prevent path traversal.
  */
-import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { resolve, join } from "node:path";
+import { resolve, join, dirname, basename } from "node:path";
+import { isWithinRoot } from "./within-root.js";
 export const MAX_TOOL_RESULT = 15_000; // chars per tool call
 // 5 was too generous for thinking-mode models — they'd spend the
 // entire budget on read_file with textLen=0, then need an
@@ -112,10 +113,41 @@ export function executeContextTool(tc) {
  */
 function validatePath(filePath) {
     const resolved = resolve(filePath);
-    if (resolved === REPO_ROOT || resolved.startsWith(REPO_ROOT + "/")) {
-        return resolved;
+    // Realpath both sides so a symlink planted inside the repo that points OUTSIDE
+    // can't pass a lexical containment check (isWithinRoot assumes resolved input
+    // and won't catch a link escape on its own). Matches fs-service's discipline.
+    // Reads are read-only, but a contained-looking symlink would still leak an
+    // out-of-repo file into arena context. Fall back to the lexical check when the
+    // target doesn't exist yet (a read of a missing file fails downstream anyway).
+    let realRoot;
+    try {
+        realRoot = realpathSync(REPO_ROOT);
+    }
+    catch {
+        realRoot = REPO_ROOT;
+    }
+    let realTarget;
+    try {
+        realTarget = realpathSync(resolved);
+    }
+    catch {
+        // Target doesn't exist yet. Compare REAL-vs-REAL by resolving the existing
+        // parent dir's realpath and rejoining the missing leaf — comparing realRoot
+        // (a real path) against a lexical `resolved` would false-reject valid files
+        // whenever REPO_ROOT (or any ancestor) is reached through a symlink.
+        let realParent;
+        try {
+            realParent = realpathSync(dirname(resolved));
+        }
+        catch {
+            // Parent missing too — no realpath available; fall back to lexical-vs-lexical
+            // so both operands share the same (unresolved) mode.
+            return isWithinRoot(resolve(REPO_ROOT), resolved) ? resolved : null;
+        }
+        const candidate = join(realParent, basename(resolved));
+        return isWithinRoot(realRoot, candidate) ? candidate : null;
     }
-    return null;
+    return isWithinRoot(realRoot, realTarget) ? realTarget : null;
 }
 function executeReadFile(args) {
     const filePath = args.path;
@@ -126,7 +158,16 @@ function executeReadFile(args) {
     const raw = readFileSync(filePath, "utf-8");
     const lines = raw.split("\n");
     const offset = Math.max(0, (args.offset ?? 1) - 1);
-    const limit = args.limit ?? 200;
+    // Guard `limit` before slicing: a negative limit makes lines.slice count
+    // "from the end" and silently drop the file's tail (reader thinks the file is
+    // shorter). A missing/NaN limit falls back to the default; a non-positive
+    // limit reads nothing.
+    const rawLimit = args.limit;
+    const limit = rawLimit === undefined || !Number.isFinite(rawLimit)
+        ? 200
+        : rawLimit > 0
+            ? Math.floor(rawLimit)
+            : 0;
     const slice = lines.slice(offset, offset + limit);
     const numbered = slice.map((l, i) => `${offset + i + 1}\t${l}`).join("\n");
     return truncateResult(numbered);

package/dist/arena/context/within-root.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True when `target` is the root itself or a descendant of it. Uses the
+ * platform separator (the old check hardcoded "/", which broke on Windows)
+ * and avoids the sibling-prefix trap (/repo vs /repo-evil). Both inputs are
+ * assumed already resolved to absolute paths.
+ */
+export declare function isWithinRoot(root: string, target: string): boolean;

package/dist/arena/context/within-root.js

@@ -0,0 +1,15 @@
+import * as path from "node:path";
+/**
+ * True when `target` is the root itself or a descendant of it. Uses the
+ * platform separator (the old check hardcoded "/", which broke on Windows)
+ * and avoids the sibling-prefix trap (/repo vs /repo-evil). Both inputs are
+ * assumed already resolved to absolute paths.
+ */
+export function isWithinRoot(root, target) {
+    if (target === root)
+        return true;
+    const rel = path.relative(root, target);
+    // Outside the root iff the relative path climbs out ("..") or is absolute
+    // (different drive on Windows).
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}

package/dist/arena/iterate/phases/argue.js

@@ -61,7 +61,7 @@ export async function runArgueRound(args) {
 // ─── Single-shot argue (no tools) ─────────────────────────────────────
 async function argueSingleShot(args) {
     const { critic, subject, format, draft, idPrefix, signal } = args;
-    const client = await createLLMClient({ ...critic.llm, enableStreaming: false });
+    const client = await createLLMClient(critic.llm, critic.clientDefaults);
     const resp = await client.createMessage({
         systemPrompt: format.argueSystem(format.format),
         messages: [{ role: "user", content: format.argueUser(subject, draft) }],
@@ -78,7 +78,7 @@ async function argueSingleShot(args) {
 // ─── Tool-use argue (with web search) ─────────────────────────────────
 async function argueWithToolLoop(args) {
     const { critic, subject, format, draft, idPrefix, maxToolRounds, signal } = args;
-    const client = await createLLMClient({ ...critic.llm, enableStreaming: false });
+    const client = await createLLMClient(critic.llm, critic.clientDefaults);
     const messages = [
         { role: "user", content: format.argueUser(subject, draft) },
     ];
@@ -149,6 +149,12 @@ async function argueWithToolLoop(args) {
         });
         finalText = resp.text;
     }
+    if (!finalText) {
+        // Both the tool loop and the force-conclude fallback produced no text
+        // (e.g. repeated max-token truncation). Log it — parseCritiquesResponse
+        // will just yield no critiques rather than silently parsing "".
+        logger.warn("arena.iterate.argue_empty_response", { critic: critic.name, toolRounds });
+    }
     const critiques = parseCritiquesResponse(finalText, critic.name, idPrefix);
     logger.info("arena.iterate.argue_toolloop", {
         critic: critic.name,

package/dist/arena/iterate/phases/revise.js

@@ -7,7 +7,7 @@ import { parseReviseResponse } from "../parse.js";
 export async function runRevise(args) {
     const { subject, format, previous, critiques, author, minDraftLength, signal, onProgress } = args;
     onProgress?.({ type: "revise_start", round: previous.version + 1, participant: author.name });
-    const client = await createLLMClient({ ...author.llm, enableStreaming: false });
+    const client = await createLLMClient(author.llm, author.clientDefaults);
     const prompt = format.revisePrompt(subject, previous, critiques, minDraftLength);
     const resp = await client.createMessage({
         systemPrompt: prompt,

package/dist/arena/iterate/phases/tournament.js

@@ -11,7 +11,7 @@ export async function runTournamentCandidates(args) {
     onProgress?.({ type: "v1_tournament_start", data: { count: participants.length } });
     const tasks = participants.map(async (p, idx) => {
         signal?.throwIfAborted();
-        const client = await createLLMClient({ ...p.llm, enableStreaming: false });
+        const client = await createLLMClient(p.llm, p.clientDefaults);
         const prompt = format.draftPrompt(subject, minDraftLength);
         // Long-form generation needs a high output ceiling; the default 8k from
         // LLMClientBase is too low for a substantive PRD or design doc and
@@ -66,7 +66,7 @@ export async function runTournamentCandidates(args) {
 export async function mergeCandidatesToV1(args) {
     const { subject, format, author, candidates, minDraftLength, signal, onProgress } = args;
     onProgress?.({ type: "v1_merge_start", participant: author.name });
-    const client = await createLLMClient({ ...author.llm, enableStreaming: false });
+    const client = await createLLMClient(author.llm, author.clientDefaults);
     const prompt = format.mergePrompt(subject, candidates, minDraftLength);
     const resp = await client.createMessage({
         systemPrompt: prompt,
@@ -95,7 +95,7 @@ export async function mergeCandidatesToV1(args) {
 /** Single-author v1 (tournament disabled) — author writes alone. */
 export async function singleAuthorV1(args) {
     const { subject, format, author, minDraftLength, signal } = args;
-    const client = await createLLMClient({ ...author.llm, enableStreaming: false });
+    const client = await createLLMClient(author.llm, author.clientDefaults);
     const prompt = format.draftPrompt(subject, minDraftLength);
     const resp = await client.createMessage({
         systemPrompt: prompt,

package/dist/arena/ledger.js

@@ -68,11 +68,16 @@ export class ArenaLedger {
     }
     appendChallenge(challenge) {
         this.ledger.challenges.push(challenge);
-        // Also add to the claim's challenges array
+        // Also add to the claim's challenges array. If the claimId doesn't resolve
+        // the challenge still lives in ledger.challenges but is invisible to any
+        // code reading claim.challenges directly — surface that inconsistency.
         const claim = this.index.claimsById.get(challenge.claimId);
         if (claim) {
             claim.challenges.push(challenge);
         }
+        else {
+            logger.warn("arena.challenge_for_unknown_claim", { claimId: challenge.claimId });
+        }
         this.checkGrowth();
         // Register any requested checks
         if (challenge.requestedChecks) {
@@ -94,6 +99,9 @@ export class ArenaLedger {
         if (claim) {
             claim.adjudication = adjudication;
         }
+        else {
+            logger.warn("arena.adjudication_for_unknown_claim", { claimId: adjudication.claimId });
+        }
     }
     // ─── Query operations ───────────────────────────────────────
     /**

package/dist/arena/phases/adjudication.js

@@ -33,10 +33,7 @@ export async function runAdjudication(options) {
         verified: verifiedClaims.length,
     });
     // Adjudicate contested claims via LLM
-    const client = await createLLMClient({
-        ...concluder.llm,
-        enableStreaming: false,
-    });
+    const client = await createLLMClient(concluder.llm, concluder.clientDefaults);
     for (const claim of contestedClaims) {
         signal?.throwIfAborted();
         const digest = buildDigest(ledger, {

package/dist/arena/phases/build-consensus.js

@@ -18,10 +18,7 @@ import { isStrategyV2 } from "../types.js";
 export async function buildConsensus(options) {
     const { concluder, strategy, topic, reports, reviews, claimSummary, signal, onProgress } = options;
     onProgress?.({ type: "consensus_start" });
-    const client = await createLLMClient({
-        ...concluder.llm,
-        enableStreaming: false,
-    });
+    const client = await createLLMClient(concluder.llm, concluder.clientDefaults);
     const systemPrompt = strategy.consensusSystemPrompt();
     // Choose user prompt: claim-aware (V2) or standard (V1)
     let userContent;

package/dist/arena/phases/cross-review.js

@@ -28,10 +28,7 @@ export async function runCrossReview(options) {
             return [];
         if (!myReport)
             return [];
-        const client = await createLLMClient({
-            ...p.llm,
-            enableStreaming: false,
-        });
+        const client = await createLLMClient(p.llm, p.clientDefaults);
         const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
         const userContent = strategy.crossReviewUserPrompt(topic, myReport, otherReports);
         let response = await client.createMessage({
@@ -110,10 +107,7 @@ export async function runVerificationReview(options) {
         const myClaims = claimsToReview.filter((c) => c.owner !== p.name);
         if (myClaims.length === 0)
             return;
-        const client = await createLLMClient({
-            ...p.llm,
-            enableStreaming: false,
-        });
+        const client = await createLLMClient(p.llm, p.clientDefaults);
         const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
         if (v2) {
             // V2 path: claim-aware verification review (or merge review for planning)

package/dist/arena/phases/debate-rounds.js

@@ -75,10 +75,7 @@ async function debateClaim(options) {
         });
         // Each debater produces a turn
         const turnPromises = debaters.map(async (p) => {
-            const client = await createLLMClient({
-                ...p.llm,
-                enableStreaming: false,
-            });
+            const client = await createLLMClient(p.llm, p.clientDefaults);
             const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
             let userContent;
             if (v2) {

package/dist/arena/phases/participant-research.js

@@ -27,10 +27,7 @@ export async function runParticipantResearchWithDossiers(options) {
     const tools = enableContextTools ? (contextTools ?? CONTEXT_TOOLS) : undefined;
     const tasks = participants.map(async (p) => {
         onProgress?.({ type: "research_start", participant: p.name });
-        const client = await createLLMClient({
-            ...p.llm,
-            enableStreaming: false,
-        });
+        const client = await createLLMClient(p.llm, p.clientDefaults);
         const messages = [
             {
                 role: "user",

package/dist/arena/phases/planning-detail-expansion.js

@@ -31,10 +31,7 @@ export async function runDetailExpansion(options) {
     onProgress?.({ type: "roadmap_expansion_start", phaseCount: toExpand.length });
     logger.info("arena.detail_expansion_start", { phaseCount: toExpand.length });
     const details = [];
-    const client = await createLLMClient({
-        ...concluder.llm,
-        enableStreaming: false,
-    });
+    const client = await createLLMClient(concluder.llm, concluder.clientDefaults);
     const systemPrompt = strategy.detailExpansionSystemPrompt();
     // Expand each phase sequentially
     for (const phase of toExpand) {
@@ -45,13 +42,18 @@ export async function runDetailExpansion(options) {
         const userContent = strategy.detailExpansionUserPrompt(topic, phase, digest);
         const messages = [{ role: "user", content: userContent }];
         let finalText = "";
-        // Tool-use loop: allow LLM to verify file paths and interfaces
+        // Tool-use loop: allow LLM to verify file paths and interfaces.
+        // `maxRounds` bounds the number of tool rounds; after the last one we make
+        // one final call (without tools) so the model produces text FROM the tool
+        // results rather than the empty text it emitted alongside the tool calls.
         const maxRounds = tools ? Math.min(MAX_EXPANSION_TOOL_ROUNDS, MAX_TOOL_ROUNDS) : 0;
         for (let round = 0; round <= maxRounds; round++) {
+            // On the final round, stop offering tools so the model must answer.
+            const offerTools = round < maxRounds ? tools : undefined;
             const response = await client.createMessage({
                 systemPrompt,
                 messages,
-                tools,
+                tools: offerTools,
                 signal,
             });
             const hasTools = response.toolCalls && response.toolCalls.length > 0;
@@ -90,10 +92,6 @@ export async function runDetailExpansion(options) {
                 });
             }
             messages.push({ role: "user", content: toolResultBlocks });
-            // Last round: force a text response
-            if (round === maxRounds) {
-                finalText = response.text;
-            }
         }
         // Retry if truncated
         if (!finalText) {