orcastrator 0.2.11 → 0.2.13

package/README.md

@@ -128,6 +128,10 @@ Global:
 - `--spec <path>`
 - `--plan <path>`
 - `--config <path>`
+- `--codex-only` (force Codex executor for this run)
+- `--claude-only` (force Claude executor for this run)
+- `--codex-effort <low|medium|high>`
+- `--claude-effort <low|medium|high|max>`
 - `--on-milestone <cmd>`
 - `--on-task-complete <cmd>`
 - `--on-task-fail <cmd>`
@@ -150,6 +154,10 @@ Global:
 - `--run <run-id>`
 - `--last`
 - `--config <path>`
+- `--codex-only`
+- `--claude-only`
+- `--codex-effort <low|medium|high>`
+- `--claude-effort <low|medium|high|max>`
 
 `orca cancel`:
 
@@ -180,7 +188,7 @@ Global:
 
 - `--anthropic-key <key>`
 - `--openai-key <key>`
-- `--check`
+- `--check` (API key lookup order: CLI flag → process env → `~/.openclaw/openclaw.json` `env.vars` → `~/.claude/.env` → `~/.config/claude/.env` → `./.env`)
 - `--global`
 - `--project`
 

package/dist/agents/claude/session.js

@@ -1,16 +1,114 @@
-import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { parseAgentJson } from "../../utils/agent-json.js";
+const PlannedTaskSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string(),
+    dependencies: z.array(z.string()),
+    acceptance_criteria: z.array(z.string()),
+    status: z.literal("pending"),
+    retries: z.literal(0),
+    maxRetries: z.literal(3),
+}).strict();
+const PlanPayloadSchema = z.object({
+    tasks: z.array(PlannedTaskSchema).min(1),
+}).strict();
+const TaskExecutionPayloadSchema = z
+    .object({
+    outcome: z.enum(["done", "failed"]),
+    error: z.string().optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.outcome === "failed" && !value.error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "error is required when outcome=failed",
+            path: ["error"],
+        });
+    }
+    if (value.outcome === "done" && value.error !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "error must be omitted when outcome=done",
+            path: ["error"],
+        });
+    }
+});
+const PLAN_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["tasks"],
+    properties: {
+        tasks: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "id",
+                    "name",
+                    "description",
+                    "dependencies",
+                    "acceptance_criteria",
+                    "status",
+                    "retries",
+                    "maxRetries",
+                ],
+                properties: {
+                    id: { type: "string", minLength: 1 },
+                    name: { type: "string", minLength: 1 },
+                    description: { type: "string" },
+                    dependencies: { type: "array", items: { type: "string" } },
+                    acceptance_criteria: { type: "array", items: { type: "string" } },
+                    status: { type: "string", enum: ["pending"] },
+                    retries: { type: "number", enum: [0] },
+                    maxRetries: { type: "number", enum: [3] },
+                },
+            },
+        },
+    },
+};
+const EXECUTION_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["outcome"],
+    properties: {
+        outcome: { type: "string", enum: ["done", "failed"] },
+        error: { type: "string" },
+    },
+    // eslint-disable-next-line unicorn/no-thenable
+    allOf: [
+        {
+            if: { properties: { outcome: { const: "failed" } } },
+            // eslint-disable-next-line unicorn/no-thenable
+            then: { required: ["error"] },
+        },
+        {
+            if: { properties: { outcome: { const: "done" } } },
+            // eslint-disable-next-line unicorn/no-thenable
+            then: { not: { required: ["error"] } },
+        },
+    ],
+};
+const PLAN_OUTPUT_FORMAT = {
+    type: "json_schema",
+    schema: PLAN_OUTPUT_SCHEMA,
+};
+const EXECUTION_OUTPUT_FORMAT = {
+    type: "json_schema",
+    schema: EXECUTION_OUTPUT_SCHEMA,
+};
 function buildPlanningPrompt(spec, systemContext) {
     return [
         systemContext,
         "You are decomposing a spec into an ordered task graph.",
-        "Return a JSON array of tasks.",
-        "Each task must include fields: id, name, description, dependencies, acceptance_criteria, status, retries, maxRetries.",
-        "Set status to \"pending\", retries to 0, and maxRetries to 3 for every task.",
-        "dependencies must be an array of task IDs.",
-        "acceptance_criteria must be an array of strings.",
-        "Return ONLY valid JSON. No markdown fences. No explanation.",
+        "Use the configured structured output schema only.",
+        "Do not include prose or markdown.",
         "Spec:",
-        spec
+        spec,
     ].join("\n\n");
 }
 function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
@@ -25,10 +123,8 @@ function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
         task.description,
         "Acceptance Criteria:",
         ...task.acceptance_criteria.map((criterion, index) => `${index + 1}. ${criterion}`),
-        "Execute this task and return ONLY JSON.",
-        "JSON schema:",
-        "{\"outcome\":\"done\"|\"failed\",\"error\"?:\"string\"}",
-        "If you cannot complete the task, return outcome=failed with a short error reason."
+        "Use the configured structured output schema only.",
+        "If you cannot complete the task, set outcome=failed and provide a concise error.",
     ].join("\n\n");
 }
 function extractAssistantText(message) {
@@ -50,107 +146,154 @@ function extractAssistantText(message) {
         .trim();
     return text.length > 0 ? text : null;
 }
+function formatSchemaError(prefix, error) {
+    const details = error.issues
+        .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`)
+        .join("; ");
+    return new Error(`${prefix}. ${details}`);
+}
 export function parseTaskArray(raw) {
-    // Strip markdown fences if present (defensive fallback)
-    const stripped = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```\s*$/i, "");
-    const parsed = JSON.parse(stripped);
-    if (!Array.isArray(parsed)) {
-        throw new Error("Claude plan response was not a JSON array");
-    }
-    // Coerce numeric task IDs and dependency refs to strings.
-    // LLMs sometimes emit numeric IDs (1, 2, 3) even when we ask for strings.
-    return parsed.map((task) => ({
-        ...task,
-        id: String(task.id),
-        dependencies: Array.isArray(task.dependencies)
-            ? task.dependencies.map(String)
-            : [],
-        // Apply sensible defaults for required fields the LLM may have omitted.
-        name: typeof task.name === "string" && task.name.length > 0 ? task.name : "Unnamed task",
-        description: typeof task.description === "string" ? task.description : "",
-        acceptance_criteria: Array.isArray(task.acceptance_criteria) ? task.acceptance_criteria : [],
-        status: typeof task.status === "string" && task.status.length > 0 ? task.status : "pending",
-        retries: typeof task.retries === "number" ? task.retries : 0,
-        maxRetries: typeof task.maxRetries === "number" ? task.maxRetries : 3,
-    }));
+    const parsed = parseAgentJson(raw);
+    const normalized = Array.isArray(parsed) ? { tasks: parsed } : parsed;
+    const result = PlanPayloadSchema.safeParse(normalized);
+    if (!result.success) {
+        throw formatSchemaError("Claude plan response failed schema validation", result.error);
+    }
+    return result.data.tasks;
 }
 export function parseTaskExecution(raw) {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("Claude task response was not a JSON object");
+    const parsed = parseAgentJson(raw);
+    const result = TaskExecutionPayloadSchema.safeParse(parsed);
+    if (!result.success) {
+        throw formatSchemaError("Claude task response failed schema validation", result.error);
     }
-    const candidate = parsed;
-    if (candidate.outcome !== "done" && candidate.outcome !== "failed") {
-        throw new Error("Claude task response missing valid outcome");
+    return {
+        outcome: result.data.outcome,
+        rawResponse: raw,
+        ...(result.data.error ? { error: result.data.error } : {}),
+    };
+}
+export function parseStructuredPlanPayload(payload) {
+    const result = PlanPayloadSchema.safeParse(payload);
+    if (!result.success) {
+        throw formatSchemaError("Claude structured plan payload failed schema validation", result.error);
     }
-    if (candidate.error !== undefined && typeof candidate.error !== "string") {
-        throw new Error("Claude task response error must be a string");
+    return result.data.tasks;
+}
+export function parseStructuredTaskExecutionPayload(payload, rawResponse = "") {
+    const result = TaskExecutionPayloadSchema.safeParse(payload);
+    if (!result.success) {
+        throw formatSchemaError("Claude structured task payload failed schema validation", result.error);
     }
     return {
-        outcome: candidate.outcome,
-        rawResponse: raw,
-        ...(typeof candidate.error === "string" ? { error: candidate.error } : {})
+        outcome: result.data.outcome,
+        rawResponse,
+        ...(result.data.error ? { error: result.data.error } : {}),
     };
 }
-async function collectSessionResult(session) {
+async function collectSessionResult(claudeQuery) {
     const assistantMessages = [];
     let resultText = null;
-    for await (const message of session.stream()) {
+    let structuredOutput;
+    for await (const message of claudeQuery) {
         const assistantText = extractAssistantText(message);
         if (assistantText) {
             assistantMessages.push(assistantText);
         }
-        if (message.type === "result" &&
-            message.subtype === "success" &&
-            typeof message.result === "string") {
-            resultText = message.result;
+        if (message.type === "result" && message.subtype === "success") {
+            if (typeof message.result === "string") {
+                resultText = message.result;
+            }
+            if ("structured_output" in message) {
+                structuredOutput = message.structured_output;
+            }
         }
         if (message.type === "result" && message.subtype !== "success") {
             const details = "errors" in message ? message.errors.join("; ") : "unknown error";
             throw new Error(`Claude session failed (${message.subtype}): ${details}`);
         }
     }
-    const rawResponse = assistantMessages.length > 0
-        ? assistantMessages[assistantMessages.length - 1]
-        : resultText;
-    if (!rawResponse) {
+    const rawResponse = assistantMessages.length > 0 ? assistantMessages[assistantMessages.length - 1] : resultText;
+    if (!rawResponse && structuredOutput === undefined) {
         throw new Error("Claude response was empty");
     }
-    return rawResponse;
+    return {
+        rawResponse: rawResponse ?? "",
+        structuredOutput,
+    };
 }
 function getModel(config) {
     return config?.claude?.model ?? process.env.ORCA_CLAUDE_MODEL ?? "claude-sonnet-4-5";
 }
-export async function planSpec(spec, systemContext, config) {
-    const session = unstable_v2_createSession({
+function getEffort(config) {
+    return config?.claude?.effort;
+}
+function buildClaudeQueryOptions(config, outputFormat) {
+    const options = {
         model: getModel(config),
         permissionMode: "bypassPermissions",
+        outputFormat,
+    };
+    const effort = getEffort(config);
+    if (effort) {
+        options.effortValue = effort;
+    }
+    return options;
+}
+function shouldAllowTextJsonFallback(config) {
+    if (config?.claude?.allowTextJsonFallback !== undefined) {
+        return config.claude.allowTextJsonFallback;
+    }
+    const env = process.env.ORCA_CLAUDE_ALLOW_TEXT_JSON_FALLBACK;
+    return env === "1" || env === "true";
+}
+function throwMissingStructuredOutput(kind) {
+    throw new Error(`Claude structured_output missing for ${kind}. Refusing freeform JSON parsing on critical path. ` +
+        "Set ORCA_CLAUDE_ALLOW_TEXT_JSON_FALLBACK=1 (or config.claude.allowTextJsonFallback=true) to temporarily enable fallback.");
+}
+export async function planSpec(spec, systemContext, config) {
+    const claudeQuery = query({
+        prompt: buildPlanningPrompt(spec, systemContext),
+        options: buildClaudeQueryOptions(config, PLAN_OUTPUT_FORMAT),
     });
     try {
-        const streamPromise = collectSessionResult(session);
-        await session.send(buildPlanningPrompt(spec, systemContext));
-        const rawResponse = await streamPromise;
+        const { rawResponse, structuredOutput } = await collectSessionResult(claudeQuery);
+        if (structuredOutput !== undefined) {
+            return {
+                tasks: parseStructuredPlanPayload(structuredOutput),
+                rawResponse,
+            };
+        }
+        if (!shouldAllowTextJsonFallback(config)) {
+            throwMissingStructuredOutput("planner");
+        }
+        console.warn("[orca][claude] structured_output missing for planner; fallback text JSON parser enabled via explicit flag");
         return {
             tasks: parseTaskArray(rawResponse),
-            rawResponse
+            rawResponse,
         };
     }
     finally {
-        session.close();
+        claudeQuery.close();
     }
 }
 export async function executeTask(task, runId, config, systemContext) {
-    const session = unstable_v2_createSession({
-        model: getModel(config),
-        permissionMode: "bypassPermissions",
+    const claudeQuery = query({
+        prompt: buildTaskExecutionPrompt(task, runId, process.cwd(), systemContext),
+        options: buildClaudeQueryOptions(config, EXECUTION_OUTPUT_FORMAT),
     });
     try {
-        const streamPromise = collectSessionResult(session);
-        await session.send(buildTaskExecutionPrompt(task, runId, process.cwd(), systemContext));
-        const rawResponse = await streamPromise;
+        const { rawResponse, structuredOutput } = await collectSessionResult(claudeQuery);
+        if (structuredOutput !== undefined) {
+            return parseStructuredTaskExecutionPayload(structuredOutput, rawResponse);
+        }
+        if (!shouldAllowTextJsonFallback(config)) {
+            throwMissingStructuredOutput("task execution");
+        }
+        console.warn("[orca][claude] structured_output missing for task execution; fallback text JSON parser enabled via explicit flag");
         return parseTaskExecution(rawResponse);
     }
     finally {
-        session.close();
+        claudeQuery.close();
     }
 }

package/dist/agents/codex/session.js

@@ -158,6 +158,9 @@ function getCodexPath() {
     return (process.env.ORCA_CODEX_PATH ??
         `${process.env.HOME}/.nvm/versions/node/v22.22.0/bin/codex`);
 }
+function getEffort(config) {
+    return config?.codex?.effort;
+}
 export async function createCodexSession(cwd, config) {
     const client = new CodexClient({
         codexPath: getCodexPath(),
@@ -172,10 +175,17 @@ export async function createCodexSession(cwd, config) {
     return {
         threadId,
         async planSpec(spec, systemContext) {
-            const result = await client.runTurn({
-                threadId,
-                input: [{ type: "text", text: buildPlanningPrompt(spec, systemContext) }],
-            });
+            const effort = getEffort(config);
+            const result = effort
+                ? await client.runTurn({
+                    threadId,
+                    effort,
+                    input: [{ type: "text", text: buildPlanningPrompt(spec, systemContext) }],
+                })
+                : await client.runTurn({
+                    threadId,
+                    input: [{ type: "text", text: buildPlanningPrompt(spec, systemContext) }],
+                });
             const rawResponse = extractAgentText(result);
             return {
                 tasks: parseTaskArray(rawResponse),
@@ -183,15 +193,27 @@ export async function createCodexSession(cwd, config) {
             };
         },
         async executeTask(task, runId, systemContext) {
-            const result = await client.runTurn({
-                threadId,
-                input: [
-                    {
-                        type: "text",
-                        text: buildTaskExecutionPrompt(task, runId, cwd, systemContext),
-                    },
-                ],
-            });
+            const effort = getEffort(config);
+            const result = effort
+                ? await client.runTurn({
+                    threadId,
+                    effort,
+                    input: [
+                        {
+                            type: "text",
+                            text: buildTaskExecutionPrompt(task, runId, cwd, systemContext),
+                        },
+                    ],
+                })
+                : await client.runTurn({
+                    threadId,
+                    input: [
+                        {
+                            type: "text",
+                            text: buildTaskExecutionPrompt(task, runId, cwd, systemContext),
+                        },
+                    ],
+                });
             const rawResponse = extractAgentText(result);
             // Primary signal: use the SDK's structured turn status.
             const status = result.turn.status;
@@ -226,10 +248,17 @@ export async function createCodexSession(cwd, config) {
                 "Task graph:",
                 taskGraphJson,
             ].join("\n");
-            const result = await client.runTurn({
-                threadId,
-                input: [{ type: "text", text: prompt }],
-            });
+            const effort = getEffort(config);
+            const result = effort
+                ? await client.runTurn({
+                    threadId,
+                    effort,
+                    input: [{ type: "text", text: prompt }],
+                })
+                : await client.runTurn({
+                    threadId,
+                    input: [{ type: "text", text: prompt }],
+                });
             const rawResponse = extractAgentText(result);
             const json = extractJson(rawResponse);
             const parsed = JSON.parse(json);

package/dist/cli/commands/help.js

@@ -45,6 +45,22 @@ function printStyledHelpPage() {
             command: "--config <path>",
             description: "explicit config file (auto-discovered by default)"
         },
+        {
+            command: "--codex-only",
+            description: "override executor to Codex for the current run"
+        },
+        {
+            command: "--claude-only",
+            description: "override executor to Claude for the current run"
+        },
+        {
+            command: "--codex-effort <value>",
+            description: "override Codex effort for the current run"
+        },
+        {
+            command: "--claude-effort <value>",
+            description: "override Claude effort for the current run"
+        },
         { command: "--full-auto", description: "skip all questions, proceed autonomously" },
         { command: "--on-complete <cmd>", description: "shell hook on run complete" },
         { command: "--on-error <cmd>", description: "shell hook on run error" },

package/dist/cli/commands/resume.js

@@ -1,5 +1,8 @@
+import { InvalidArgumentError } from "commander";
+import { resolveConfig } from "../../core/config-loader.js";
 import { runTaskRunner } from "../../core/task-runner.js";
 import { RunStore } from "../../state/store.js";
+import { parseClaudeEffort, parseCodexEffort } from "../../types/effort.js";
 import { getLastRun } from "../../utils/last-run.js";
 function createStore() {
     const runsDir = process.env.ORCA_RUNS_DIR;
@@ -14,8 +17,45 @@ function formatRunIds(runs) {
 function getActiveRuns(runs) {
     return runs.filter((run) => run.overallStatus === "planning" || run.overallStatus === "running");
 }
+function parseCodexEffortOption(value) {
+    try {
+        return parseCodexEffort(value);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+    }
+}
+function parseClaudeEffortOption(value) {
+    try {
+        return parseClaudeEffort(value);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+    }
+}
+function applyExecutorOverrideForResume(config, options) {
+    const nextConfig = { ...config };
+    if (options.codexOnly || options.claudeOnly) {
+        nextConfig.executor = options.codexOnly ? "codex" : "claude";
+    }
+    if (options.codexEffort !== undefined) {
+        nextConfig.codex = { ...nextConfig.codex, effort: options.codexEffort };
+    }
+    if (options.claudeEffort !== undefined) {
+        nextConfig.claude = { ...nextConfig.claude, effort: options.claudeEffort };
+    }
+    if (config === undefined && Object.keys(nextConfig).length === 0) {
+        return undefined;
+    }
+    return nextConfig;
+}
 export async function resumeCommandHandler(options) {
+    if (options.codexOnly && options.claudeOnly) {
+        throw new Error("--codex-only and --claude-only are mutually exclusive; choose only one executor override.");
+    }
     const store = createStore();
+    const resolvedConfig = await resolveConfig(options.config);
+    const effectiveConfig = applyExecutorOverrideForResume(resolvedConfig, options);
     if (options.last) {
         const lastRun = await getLastRun(store);
         if (!lastRun) {
@@ -59,7 +99,8 @@ export async function resumeCommandHandler(options) {
     });
     await runTaskRunner({
         runId: run.runId,
-        store
+        store,
+        ...(effectiveConfig ? { config: effectiveConfig } : {})
     });
     const refreshed = await store.getRun(run.runId);
     if (!refreshed) {
@@ -74,5 +115,17 @@ export function registerResumeCommand(program) {
         .option("--run <run-id>", "Run ID to resume")
         .option("--last", "Use the most recent run")
         .option("--config <path>", "Path to orca config file")
-        .action(async (options) => resumeCommandHandler(options));
+        .option("--codex-only", "Force Codex executor for this resumed run (overrides config)")
+        .option("--claude-only", "Force Claude executor for this resumed run (overrides config)")
+        .option("--codex-effort <value>", "Codex effort override for this resumed run", parseCodexEffortOption)
+        .option("--claude-effort <value>", "Claude effort override for this resumed run", parseClaudeEffortOption)
+        .action(async (options) => {
+        try {
+            await resumeCommandHandler(options);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/cli/commands/run.js

@@ -3,6 +3,7 @@ import { access, unlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { InvalidArgumentError } from "commander";
 import { createCodexSession } from "../../agents/codex/session.js";
 import { ensureCodexMultiAgent } from "../../core/codex-config.js";
 import { resolveConfig } from "../../core/config-loader.js";
@@ -12,6 +13,7 @@ import { createOpenclawHookHandler, detectOpenclawAvailability } from "../../hoo
 import { createStdoutHookHandler } from "../../hooks/adapters/stdout.js";
 import { HookDispatcher } from "../../hooks/dispatcher.js";
 import { RunStore } from "../../state/store.js";
+import { parseClaudeEffort, parseCodexEffort } from "../../types/effort.js";
 import { generateRunId } from "../../utils/ids.js";
 const ALL_HOOKS = [
     "onMilestone",
@@ -30,6 +32,22 @@ const VALID_HOOK_NAMES = new Set([
 function isHookName(value) {
     return VALID_HOOK_NAMES.has(value);
 }
+function parseCodexEffortOption(value) {
+    try {
+        return parseCodexEffort(value);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+    }
+}
+function parseClaudeEffortOption(value) {
+    try {
+        return parseClaudeEffort(value);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+    }
+}
 function createStore() {
     const runsDir = process.env.ORCA_RUNS_DIR;
     return runsDir ? new RunStore(runsDir) : new RunStore();
@@ -49,7 +67,26 @@ function buildCliCommandHooks(options) {
         ...(options.onError ? { onError: options.onError } : {})
     };
 }
+function applyExecutorOverrideForRun(config, options) {
+    const nextConfig = { ...config };
+    if (options.codexOnly || options.claudeOnly) {
+        nextConfig.executor = options.codexOnly ? "codex" : "claude";
+    }
+    if (options.codexEffort !== undefined) {
+        nextConfig.codex = { ...nextConfig.codex, effort: options.codexEffort };
+    }
+    if (options.claudeEffort !== undefined) {
+        nextConfig.claude = { ...nextConfig.claude, effort: options.claudeEffort };
+    }
+    if (config === undefined && Object.keys(nextConfig).length === 0) {
+        return undefined;
+    }
+    return nextConfig;
+}
 export async function runCommandHandler(options) {
+    if (options.codexOnly && options.claudeOnly) {
+        throw new Error("--codex-only and --claude-only are mutually exclusive; choose only one executor override.");
+    }
     const inlineTask = options.task ?? options.prompt ?? options.goal;
     const inputSpecPath = options.spec ?? options.plan;
     if (options.goal !== undefined && (options.task || options.prompt)) {
@@ -76,11 +113,12 @@ export async function runCommandHandler(options) {
             throw new Error(`Spec file not found or not readable: ${specPath}`);
         });
         const orcaConfig = await resolveConfig(options.config);
+        const effectiveConfig = applyExecutorOverrideForRun(orcaConfig, options);
         const runId = generateRunId(specPath);
         console.log(`Run ID: ${runId}`);
         const store = createStore();
         await store.createRun(runId, specPath);
-        await runPlanner(specPath, store, runId, orcaConfig);
+        await runPlanner(specPath, store, runId, effectiveConfig);
         await store.updateRun(runId, {
             mode: "run",
             overallStatus: "running"
@@ -124,45 +162,57 @@ export async function runCommandHandler(options) {
         const emitHook = async (event) => {
             await dispatcher.dispatch(event);
         };
-        const cwd = process.cwd();
-        const multiAgentResult = await ensureCodexMultiAgent(orcaConfig ?? undefined);
-        if (multiAgentResult.action === "created" || multiAgentResult.action === "appended") {
-            console.log(`Multi-agent: enabled (updated ${multiAgentResult.path})`);
-        }
-        const codexSession = await createCodexSession(cwd, orcaConfig ?? undefined);
-        try {
-            // Phase 4: Codex consults the task graph before execution begins.
-            const plannedRun = await store.getRun(runId);
-            if (!plannedRun) {
-                throw new Error(`Run not found after planning: ${runId}`);
+        const executor = effectiveConfig?.executor ?? "codex";
+        if (executor === "codex") {
+            const cwd = process.cwd();
+            const multiAgentResult = await ensureCodexMultiAgent(effectiveConfig);
+            if (multiAgentResult.action === "created" || multiAgentResult.action === "appended") {
+                console.log(`Multi-agent: enabled (updated ${multiAgentResult.path})`);
             }
-            console.log("Phase 4: Codex reviewing task graph...");
-            const consultation = await codexSession.consultTaskGraph(plannedRun.tasks);
-            if (consultation.issues.length > 0) {
-                console.log("Codex consultation issues:");
-                for (const issue of consultation.issues) {
-                    console.log(`  - ${issue}`);
+            const codexSession = await createCodexSession(cwd, effectiveConfig);
+            try {
+                // Phase 4: Codex consults the task graph before execution begins.
+                const plannedRun = await store.getRun(runId);
+                if (!plannedRun) {
+                    throw new Error(`Run not found after planning: ${runId}`);
                 }
+                console.log("Phase 4: Codex reviewing task graph...");
+                const consultation = await codexSession.consultTaskGraph(plannedRun.tasks);
+                if (consultation.issues.length > 0) {
+                    console.log("Codex consultation issues:");
+                    for (const issue of consultation.issues) {
+                        console.log(`  - ${issue}`);
+                    }
+                }
+                if (!consultation.ok) {
+                    console.error("Codex flagged the task graph as not OK. Aborting.");
+                    await store.updateRun(runId, { overallStatus: "failed" });
+                    return;
+                }
+                console.log("Codex consultation passed. Starting execution...");
+                await runTaskRunner({
+                    runId,
+                    store,
+                    ...(effectiveConfig ? { config: effectiveConfig } : {}),
+                    emitHook,
+                    executeTask: (task, taskRunId, _config, systemContext) => codexSession.executeTask(task, taskRunId, systemContext),
+                });
+                const reviewText = await codexSession.reviewChanges();
+                console.log("Codex post-execution review:");
+                console.log(reviewText);
             }
-            if (!consultation.ok) {
-                console.error("Codex flagged the task graph as not OK. Aborting.");
-                await store.updateRun(runId, { overallStatus: "failed" });
-                return;
+            finally {
+                await codexSession.disconnect();
             }
-            console.log("Codex consultation passed. Starting execution...");
+        }
+        else {
+            console.log("Phase 4: Skipping Codex consultation because executor is set to Claude.");
             await runTaskRunner({
                 runId,
                 store,
-                ...(orcaConfig ? { config: orcaConfig } : {}),
-                emitHook,
-                executeTask: (task, runId, _config, systemContext) => codexSession.executeTask(task, runId, systemContext),
+                ...(effectiveConfig ? { config: effectiveConfig } : {}),
+                emitHook
             });
-            const reviewText = await codexSession.reviewChanges();
-            console.log("Codex post-execution review:");
-            console.log(reviewText);
-        }
-        finally {
-            await codexSession.disconnect();
         }
         const run = await store.getRun(runId);
         if (!run) {
@@ -196,6 +246,10 @@ export function registerRunCommand(program) {
         .option("--task <text>", "Inline task text (alternative to --spec)")
         .option("-p, --prompt <text>", "Inline task text (alias for --task)")
         .option("--config <path>", "Path to orca config file")
+        .option("--codex-only", "Force Codex executor for this run (overrides config)")
+        .option("--claude-only", "Force Claude executor for this run (overrides config)")
+        .option("--codex-effort <value>", "Codex effort override for this run", parseCodexEffortOption)
+        .option("--claude-effort <value>", "Claude effort override for this run", parseClaudeEffortOption)
         .option("--on-milestone <cmd>", "Shell hook command for onMilestone")
         .option("--on-task-complete <cmd>", "Shell hook command for onTaskComplete")
         .option("--on-task-fail <cmd>", "Shell hook command for onTaskFail")
@@ -207,6 +261,11 @@ export function registerRunCommand(program) {
                 ...commandOptions,
                 ...(goal !== undefined ? { goal } : {})
             };
+            if (normalizedOptions.codexOnly && normalizedOptions.claudeOnly) {
+                console.error("Error: --codex-only and --claude-only are mutually exclusive; choose only one.");
+                process.exitCode = 1;
+                return;
+            }
             const inlineTask = normalizedOptions.task ?? normalizedOptions.prompt ?? normalizedOptions.goal;
             const inputSpecPath = normalizedOptions.spec ?? normalizedOptions.plan;
             if (normalizedOptions.goal !== undefined && (normalizedOptions.task || normalizedOptions.prompt)) {

package/dist/cli/commands/setup.js

@@ -1,5 +1,5 @@
 import { execSync, spawnSync } from "node:child_process";
-import { constants as fsConstants } from "node:fs";
+import { constants as fsConstants, readFileSync } from "node:fs";
 import { access, mkdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -48,7 +48,7 @@ function commandExists(command) {
     const result = spawnSync("which", [command], { stdio: "ignore" });
     return result.status === 0;
 }
-export function resolveApiKey(flagValue, envVarName) {
+export function resolveApiKey(flagValue, envVarName, openclawConfigPathOrOptions, maybeOptions) {
     if (flagValue && flagValue.trim().length > 0) {
         return flagValue.trim();
     }
@@ -56,8 +56,138 @@ export function resolveApiKey(flagValue, envVarName) {
     if (envValue && envValue.trim().length > 0) {
         return envValue.trim();
     }
+    const options = typeof openclawConfigPathOrOptions === "string"
+        ? { ...(maybeOptions ?? {}), openclawConfigPath: openclawConfigPathOrOptions }
+        : (openclawConfigPathOrOptions ?? {});
+    const homedir = options.homedir ?? os.homedir();
+    const openclawValue = readOpenclawEnvVar(envVarName, options.openclawConfigPath, homedir);
+    if (openclawValue) {
+        return openclawValue;
+    }
+    const dotenvValue = readDotEnvFallback(envVarName, {
+        cwd: options.cwd ?? process.cwd(),
+        homedir
+    });
+    if (dotenvValue) {
+        return dotenvValue;
+    }
     return undefined;
 }
+function readOpenclawEnvVar(envVarName, openclawConfigPath, homedir = os.homedir()) {
+    const configPath = openclawConfigPath ?? path.join(homedir, ".openclaw", "openclaw.json");
+    try {
+        const fileText = readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(fileText);
+        const value = parsed.env?.vars?.[envVarName];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+        if (value && typeof value === "object") {
+            const candidateObject = value;
+            for (const candidate of [
+                candidateObject.value,
+                candidateObject.ref,
+                candidateObject.opRef,
+                candidateObject.reference
+            ]) {
+                if (typeof candidate === "string" && candidate.trim().length > 0) {
+                    return candidate.trim();
+                }
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function readDotEnvFallback(envVarName, options) {
+    const candidatePaths = [
+        path.join(options.homedir, ".claude", ".env"),
+        path.join(options.homedir, ".config", "claude", ".env"),
+        path.join(options.cwd, ".env")
+    ];
+    for (const candidatePath of candidatePaths) {
+        const value = readEnvVarFromDotEnvFile(candidatePath, envVarName);
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readEnvVarFromDotEnvFile(filePath, envVarName) {
+    try {
+        const parsed = parseDotEnv(readFileSync(filePath, "utf8"));
+        const value = parsed[envVarName];
+        if (value !== undefined && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function parseDotEnv(text) {
+    const values = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const normalized = line.startsWith("export ") ? line.slice(7).trimStart() : line;
+        const separatorIndex = normalized.indexOf("=");
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = normalized.slice(0, separatorIndex).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            continue;
+        }
+        let rawValue = normalized.slice(separatorIndex + 1).trim();
+        if (!rawValue) {
+            values[key] = "";
+            continue;
+        }
+        if (rawValue.startsWith('"') || rawValue.startsWith("'")) {
+            const quote = rawValue.charAt(0);
+            const closingQuoteIndex = findClosingQuote(rawValue, quote);
+            if (closingQuoteIndex > 0) {
+                rawValue = rawValue.slice(1, closingQuoteIndex);
+            }
+            else {
+                rawValue = rawValue.slice(1);
+            }
+            values[key] = quote === '"' ? unescapeDoubleQuoted(rawValue) : unescapeSingleQuoted(rawValue);
+            continue;
+        }
+        const commentStart = rawValue.search(/\s#/);
+        if (commentStart >= 0) {
+            rawValue = rawValue.slice(0, commentStart).trimEnd();
+        }
+        values[key] = rawValue;
+    }
+    return values;
+}
+function findClosingQuote(value, quote) {
+    for (let i = 1; i < value.length; i += 1) {
+        if (value[i] === quote && value[i - 1] !== "\\") {
+            return i;
+        }
+    }
+    return -1;
+}
+function unescapeDoubleQuoted(value) {
+    return value
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, "\\");
+}
+function unescapeSingleQuoted(value) {
+    return value.replace(/\\'/g, "'").replace(/\\\\/g, "\\");
+}
 export function detectPackageManager(exists = commandExists) {
     if (exists("brew")) {
         return "brew";
@@ -228,7 +358,7 @@ export async function setupCommandHandler(options) {
                 console.log(chalk.green("✓ Anthropic API key found"));
         }
         else {
-            results.push({ name: "ANTHROPIC_API_KEY", status: "warn", detail: checkMode ? "not configured" : "not set" });
+            results.push({ name: "ANTHROPIC_API_KEY", status: "warn", detail: "not set" });
             if (!checkMode)
                 console.log(chalk.yellow("! ANTHROPIC_API_KEY not set"));
         }
@@ -241,7 +371,7 @@ export async function setupCommandHandler(options) {
                 console.log(chalk.green("✓ OpenAI API key found"));
         }
         else {
-            results.push({ name: "OPENAI_API_KEY", status: "warn", detail: checkMode ? "not configured" : "not set" });
+            results.push({ name: "OPENAI_API_KEY", status: "warn", detail: "not set" });
             if (!checkMode)
                 console.log(chalk.yellow("! OPENAI_API_KEY not set"));
         }

package/dist/cli/commands/skills.js

@@ -0,0 +1,75 @@
+import os from "node:os";
+import path from "node:path";
+import { resolveConfig } from "../../core/config-loader.js";
+import { loadSkills } from "../../utils/skill-loader.js";
+function pad(value, width) {
+    return value.padEnd(width, " ");
+}
+function formatTable(headers, rows) {
+    const widths = headers.map((header, index) => {
+        const rowWidths = rows.map((row) => row[index]?.length ?? 0);
+        return Math.max(header.length, ...rowWidths);
+    });
+    const headerLine = headers.map((header, index) => pad(header, widths[index] ?? header.length)).join("  ");
+    const separator = widths.map((width) => "-".repeat(width)).join("  ");
+    const body = rows.map((row) => row.map((cell, index) => pad(cell, widths[index] ?? cell.length)).join("  "));
+    return [headerLine, separator, ...body].join("\n");
+}
+function expandHome(inputPath) {
+    if (inputPath === "~") {
+        return os.homedir();
+    }
+    if (inputPath.startsWith("~/") || inputPath.startsWith("~\\")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+function resolveConfigSkillDir(inputPath) {
+    return path.resolve(expandHome(inputPath));
+}
+function pathWithin(targetPath, parentPath) {
+    const relative = path.relative(parentPath, targetPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function detectSkillSource(skill, configSkillDirs) {
+    if (configSkillDirs.has(skill.dirPath)) {
+        return "config";
+    }
+    const projectSkillsRoot = path.join(process.cwd(), ".orca", "skills");
+    if (pathWithin(skill.dirPath, projectSkillsRoot)) {
+        return "project";
+    }
+    const globalSkillsRoot = path.join(os.homedir(), ".orca", "skills");
+    if (pathWithin(skill.dirPath, globalSkillsRoot)) {
+        return "global";
+    }
+    // loadSkills currently only returns config/project/global entries.
+    return "config";
+}
+function formatSkillsTable(skills, configSkillDirs) {
+    const headers = ["Name", "Description", "Source", "Path"];
+    const rows = skills.map((skill) => [
+        skill.name,
+        skill.description,
+        detectSkillSource(skill, configSkillDirs),
+        skill.dirPath
+    ]);
+    return formatTable(headers, rows);
+}
+export async function skillsCommandHandler(options) {
+    const config = await resolveConfig(options.config);
+    const configSkillDirs = new Set((config?.skills ?? []).map((skillPath) => resolveConfigSkillDir(skillPath)));
+    const skills = await loadSkills(config);
+    if (skills.length === 0) {
+        console.log("No skills found.");
+        return;
+    }
+    console.log(formatSkillsTable(skills, configSkillDirs));
+}
+export function registerSkillsCommand(program) {
+    program
+        .command("skills")
+        .description("List available skills")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => skillsCommandHandler(options));
+}

package/dist/cli/index.js

@@ -13,6 +13,7 @@ import { registerPrFinalizeCommand } from "./commands/pr-finalize.js";
 import { registerResumeCommand } from "./commands/resume.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerSetupCommand } from "./commands/setup.js";
+import { registerSkillsCommand } from "./commands/skills.js";
 import { registerStatusCommand } from "./commands/status.js";
 const program = new Command();
 program.name("orca").description("Orca CLI: coordinated agent run harness").version(version);
@@ -21,6 +22,7 @@ registerAnswerCommand(program);
 registerPlanCommand(program);
 registerStatusCommand(program);
 registerListCommand(program);
+registerSkillsCommand(program);
 registerResumeCommand(program);
 registerCancelCommand(program);
 registerPrCommand(program);

package/dist/core/config-loader.js

@@ -3,6 +3,7 @@ import { access } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parseClaudeEffort, parseCodexEffort } from "../types/effort.js";
 function isObject(value) {
     return typeof value === "object" && value !== null;
 }
@@ -54,6 +55,28 @@ function coerceConfig(candidate) {
             throw new Error(`Config.executor must be 'claude' or 'codex', got ${String(candidate.executor)}`);
         }
     }
+    if ("claude" in candidate && candidate.claude !== undefined) {
+        if (!isObject(candidate.claude)) {
+            throw new Error(`Config.claude must be an object, got ${describeType(candidate.claude)}`);
+        }
+        if ("effort" in candidate.claude && candidate.claude.effort !== undefined) {
+            if (typeof candidate.claude.effort !== "string") {
+                throw new Error(`Config.claude.effort must be a string, got ${describeType(candidate.claude.effort)}`);
+            }
+            parseClaudeEffort(candidate.claude.effort);
+        }
+    }
+    if ("codex" in candidate && candidate.codex !== undefined) {
+        if (!isObject(candidate.codex)) {
+            throw new Error(`Config.codex must be an object, got ${describeType(candidate.codex)}`);
+        }
+        if ("effort" in candidate.codex && candidate.codex.effort !== undefined) {
+            if (typeof candidate.codex.effort !== "string") {
+                throw new Error(`Config.codex.effort must be a string, got ${describeType(candidate.codex.effort)}`);
+            }
+            parseCodexEffort(candidate.codex.effort);
+        }
+    }
     return candidate;
 }
 export async function loadConfig(configPath) {

package/dist/core/planner.js

@@ -1,12 +1,20 @@
 import { promises as fs } from "node:fs";
-import { planSpec } from "../agents/claude/session.js";
+import { planSpec as planSpecWithClaude } from "../agents/claude/session.js";
+import { planSpec as planSpecWithCodex } from "../agents/codex/session.js";
 import { logger } from "../utils/logger.js";
 import { loadSkills } from "../utils/skill-loader.js";
 import { validateDAG } from "./dependency-graph.js";
 const DEFAULT_SYSTEM_CONTEXT = "You are Orca planner.";
-let planSpecImpl = planSpec;
+let testPlanSpecOverride = null;
 export function setPlanSpecForTests(fn) {
-    planSpecImpl = fn ?? planSpec;
+    testPlanSpecOverride = fn;
+}
+function resolvePlanSpecImpl(config) {
+    if (testPlanSpecOverride) {
+        return testPlanSpecOverride;
+    }
+    const executor = config?.executor ?? "codex";
+    return executor === "claude" ? planSpecWithClaude : planSpecWithCodex;
 }
 function formatSkillsSection(skills) {
     const formattedSkills = skills.map((skill) => [
@@ -24,6 +32,7 @@ export async function runPlanner(specPath, store, runId, config) {
     const systemContext = skills.length === 0
         ? DEFAULT_SYSTEM_CONTEXT
         : `${DEFAULT_SYSTEM_CONTEXT}\n\n${formatSkillsSection(skills)}`;
+    const planSpecImpl = resolvePlanSpecImpl(config);
     const result = await planSpecImpl(spec, systemContext, config);
     validateDAG(result.tasks);
     await store.writeTasks(runId, result.tasks);

package/dist/types/effort.js

@@ -0,0 +1,17 @@
+export const CODEX_EFFORT_VALUES = ["low", "medium", "high"];
+export const CLAUDE_EFFORT_VALUES = ["low", "medium", "high", "max"];
+function formatAllowed(values) {
+    return values.map((value) => `'${value}'`).join(", ");
+}
+function parseEffort(raw, allowed, label) {
+    if (allowed.includes(raw)) {
+        return raw;
+    }
+    throw new Error(`${label} must be one of ${formatAllowed(allowed)}, got '${raw}'`);
+}
+export function parseCodexEffort(raw) {
+    return parseEffort(raw, CODEX_EFFORT_VALUES, "Codex effort");
+}
+export function parseClaudeEffort(raw) {
+    return parseEffort(raw, CLAUDE_EFFORT_VALUES, "Claude effort");
+}

package/dist/utils/agent-json.js

@@ -0,0 +1,84 @@
+function tryParseJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return null;
+    }
+}
+function extractFencedCandidates(text) {
+    const candidates = [];
+    const fenceRegex = /```(?:json)?\s*\n?([\s\S]*?)\n?```/gi;
+    for (const match of text.matchAll(fenceRegex)) {
+        const body = match[1]?.trim();
+        if (body) {
+            candidates.push(body);
+        }
+    }
+    return candidates;
+}
+function extractFirstJsonObjectOrArray(text) {
+    for (let start = 0; start < text.length; start += 1) {
+        const first = text[start];
+        if (first !== "{" && first !== "[") {
+            continue;
+        }
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let end = start; end < text.length; end += 1) {
+            const ch = text[end];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                    continue;
+                }
+                if (ch === "\\") {
+                    escaped = true;
+                    continue;
+                }
+                if (ch === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+                continue;
+            }
+            if (ch === "{" || ch === "[") {
+                depth += 1;
+                continue;
+            }
+            if (ch === "}" || ch === "]") {
+                depth -= 1;
+                if (depth === 0) {
+                    const candidate = text.slice(start, end + 1).trim();
+                    if (tryParseJson(candidate) !== null) {
+                        return candidate;
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    return null;
+}
+export function parseAgentJson(raw) {
+    const text = raw.trim();
+    const candidates = [
+        text,
+        ...extractFencedCandidates(text),
+    ];
+    const extracted = extractFirstJsonObjectOrArray(text);
+    if (extracted) {
+        candidates.push(extracted);
+    }
+    for (const candidate of candidates) {
+        const parsed = tryParseJson(candidate);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    throw new Error("Response did not contain valid JSON object/array");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcastrator",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "type": "module",
   "bin": {
     "orca": "dist/cli/index.js"