axexec 1.6.1 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # axexec
 
-Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents in complete isolation, and normalizes output to a standard event stream.
+Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents with credential/config isolation (not an OS sandbox), and normalizes output to a standard event stream.
 
 ## What axexec Does
 
@@ -8,7 +8,9 @@ axexec is the **translation layer** between high-level tooling and agent-specifi
 
 - **Input translation**: Credentials → agent-specific files, permissions → config files, model → CLI flags
 - **Output normalization**: Claude JSONL, Codex items, Gemini events, OpenCode SSE → unified `AxexecEvent` stream
-- **Complete isolation**: Agents run in temp directories with no access to user config or global credentials
+- **Credential/config isolation**: Agents are pointed at temp directories instead of your local agent config/credential locations
+
+axexec is **not** a security boundary. It does not restrict filesystem or network access; many adapters run in permissive non-interactive modes to avoid prompts. For real enforcement, run inside an external sandbox (container/VM).
 
 ## Installation
 
@@ -48,12 +50,15 @@ axexec -a gemini "Refactor the utils module"
 axexec -a opencode "Add logging"
 axexec -a copilot "Write tests"
 
+# Run with explicit credentials JSON (from axauth export)
+axexec -a claude --credentials-file ./creds.json "Review this PR"
+
 # Specify a model
 axexec -a claude --model opus "Review this PR"
 axexec -a gemini --model gemini-2.5-pro "Refactor utils"
 
 # Set permissions
-axexec -a claude --allow 'read,glob,bash:git *' "Check git history"
+axexec -a claude --allow 'read,glob,bash:git *' "Check git history"  # best-effort
 
 # Output normalized JSONL event stream
 axexec -a claude -f jsonl "Add tests" | jq 'select(.type == "tool.call")'
@@ -86,11 +91,13 @@ axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
 
 ```
 -a, --agent <id>           Agent to use (claude, codex, gemini, opencode, copilot)
+--cwd <path>               Working directory for the agent process
+--credentials-file <path|-> Read credentials JSON from file (or '-' for stdin)
 -p, --prompt <text>        Prompt text (alternative to positional argument)
 -m, --model <model>        Model to use (agent-specific)
---provider <provider>      Provider for OpenCode (anthropic, openai, google)
---allow <perms>            Permission rules to allow (comma-separated)
---deny <perms>             Permission rules to deny (comma-separated)
+--provider <provider>      Provider for OpenCode (e.g., anthropic, openai, google, opencode)
+--allow <perms>            Allow permissions (best-effort, comma-separated)
+--deny <perms>             Deny permissions (best-effort, comma-separated)
 -f, --format <fmt>         Output format: jsonl, tsv (default: tsv, truncated on TTY)
 --raw-log <file>           Write raw agent output to file
 --debug                    Enable debug mode (logs unknown events)
@@ -103,15 +110,15 @@ axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
 
 ## Supported Agents
 
-| Agent    | Package                   | API Key Env Var       |
-| -------- | ------------------------- | --------------------- |
-| claude   | @anthropic-ai/claude-code | ANTHROPIC_API_KEY     |
-| codex    | @openai/codex             | OPENAI_API_KEY        |
-| gemini   | @google/gemini-cli        | GEMINI_API_KEY        |
-| opencode | opencode-ai               | ANTHROPIC_API_KEY (†) |
-| copilot  | @github/copilot           | GITHUB_TOKEN          |
+| Agent    | Package                   | API Key Env Var         |
+| -------- | ------------------------- | ----------------------- |
+| claude   | @anthropic-ai/claude-code | ANTHROPIC_API_KEY       |
+| codex    | @openai/codex             | OPENAI_API_KEY          |
+| gemini   | @google/gemini-cli        | GEMINI_API_KEY          |
+| opencode | opencode-ai               | AX_OPENCODE_CREDENTIALS |
+| copilot  | @github/copilot           | GITHUB_TOKEN            |
 
-(†) OpenCode supports multiple providers via `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`.
+OpenCode requires `AX_OPENCODE_CREDENTIALS` with provider-specific credentials (see [CI/CD Credentials](#cicd-credentials)).
 
 ## Event Stream
 
@@ -170,8 +177,8 @@ For OpenCode, set `AX_OPENCODE_CREDENTIALS` with your credentials. The `provider
 field must match your `--provider` flag:
 
 ```bash
-# Anthropic (provider defaults to "anthropic" if omitted)
-AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","data":{"apiKey":"sk-ant-..."}}' \
+# Anthropic
+AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"anthropic","data":{"apiKey":"sk-ant-..."}}' \
   axexec -a opencode --provider anthropic -m claude-sonnet-4 "Hello"
 
 # OpenAI (provider must be specified in credentials)
@@ -185,7 +192,7 @@ AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"openco
 
 ## Isolation
 
-axexec provides complete environment isolation:
+axexec provides credential/config isolation:
 
 1. Creates a temp directory for each session
 2. Installs credentials to the temp directory
@@ -193,11 +200,14 @@ axexec provides complete environment isolation:
 4. Sets environment variables to point agents at the temp directory
 5. Cleans up the temp directory after execution
 
-Codex runs with `--dangerously-bypass-approvals-and-sandbox`, so `--allow` /
-`--deny` do not constrain Codex. Run axexec inside an external sandbox if you
-need enforcement.
+axexec is intentionally **permissive** and should not be treated as a sandbox:
+
+- It does not enforce filesystem or network restrictions
+- `--allow` / `--deny` is best-effort and may be ignored or weakened by adapter "YOLO" switches
+- Agent-internal sandbox env vars (`GEMINI_SANDBOX`, `SEATBELT_PROFILE`) are excluded from subprocess environments
+- For enforcement, run axexec inside an external sandbox (container/VM)
 
-Agents **never** access:
+Agents are configured to avoid using your local agent config/credential locations:
 
 - User's home directory config (`~/.claude`, `~/.codex`, `~/.gemini`)
 - System keychain or credential managers
@@ -212,7 +222,7 @@ Add to your `CLAUDE.md` or `AGENTS.md`:
 
 Run `npx -y axexec --help` to learn available options.
 
-Use `axexec` when you need to run a supported agent in a fully isolated environment and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.
+Use `axexec` when you need to run a supported agent with credential/config isolation and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.
 ```
 
 ## License

package/dist/agents/claude-code/types.d.ts

@@ -77,8 +77,8 @@ type ClaudeUserEvent = z.infer<typeof ClaudeUserEvent>;
 declare const ClaudeResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"result">;
     subtype: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
         cancelled: "cancelled";
     }>;
     timestamp: z.ZodOptional<z.ZodString>;
@@ -153,8 +153,8 @@ declare const ClaudeEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"result">;
     subtype: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
         cancelled: "cancelled";
     }>;
     timestamp: z.ZodOptional<z.ZodString>;

package/dist/agents/copilot/stream-session.js

@@ -23,13 +23,9 @@ async function main() {
     const copilotArguments = [
         "-p",
         prompt,
-        "--allow-all-tools",
-        // Enable network access without confirmation prompts.
-        // Copilot requires user approval for URL access by default, but other
-        // agents (Gemini, OpenCode) allow it by default. For unified behavior,
-        // enable it. This matches how --allow-all-tools works for other operations.
-        // See: copilot-cli-decompiled/copilot-source/index.js line 418918
-        "--allow-all-urls",
+        // Always run in "YOLO" mode (no prompts). This is equivalent to
+        // --allow-all-tools --allow-all-paths --allow-all-urls.
+        "--yolo",
         ...extraArguments,
     ];
     // Record existing session files
@@ -55,6 +51,11 @@ async function main() {
         const copilotBin = process.env["AXEXEC_COPILOT_PATH"] ?? "copilot";
         const child = spawn(copilotBin, copilotArguments, {
             stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                // Auto-trust folders (avoids interactive trust prompts).
+                COPILOT_ALLOW_ALL: "true",
+            },
         });
         copilotProcess = child;
         // Pipe Copilot's stdout/stderr to our stderr (for debugging)

package/dist/agents/copilot/watch-session.js

@@ -13,7 +13,9 @@ import { existsSync, readdirSync, statSync, watch, } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 /** Copilot session state directory */
-const SESSION_STATE_DIR = path.join(homedir(), ".copilot", "session-state");
+const SESSION_STATE_DIR = process.env["XDG_STATE_HOME"]
+    ? path.join(process.env["XDG_STATE_HOME"], ".copilot", "session-state")
+    : path.join(homedir(), ".copilot", "session-state");
 /** Session events filename inside session directories (new format) */
 const SESSION_EVENTS_FILE = "events.jsonl";
 /**

package/dist/agents/gemini/types.d.ts

@@ -41,8 +41,8 @@ declare const GeminiToolResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"tool_result">;
     tool_id: z.ZodString;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     output: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodObject<{
@@ -67,8 +67,8 @@ type GeminiErrorEvent = z.infer<typeof GeminiErrorEvent>;
 declare const GeminiResultEvent: z.ZodObject<{
     type: z.ZodLiteral<"result">;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     error: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;
@@ -109,8 +109,8 @@ declare const GeminiEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"tool_result">;
     tool_id: z.ZodString;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     output: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodObject<{
@@ -129,8 +129,8 @@ declare const GeminiEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"result">;
     status: z.ZodEnum<{
-        success: "success";
         error: "error";
+        success: "success";
     }>;
     error: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;

package/dist/agents/opencode/adapter.js

@@ -14,6 +14,7 @@
  * 7. Clean up server on completion
  */
 import { registerAdapter } from "../registry.js";
+import { buildPermissionEnvironment } from "./build-permission-environment.js";
 import { cleanupSession } from "./cleanup-session.js";
 import { createSessionStartEvent } from "./create-session-start-event.js";
 import { determineSessionSuccess } from "../../determine-session-success.js";
@@ -49,7 +50,13 @@ async function* streamSession(options) {
     process.on("SIGTERM", forwardSignal);
     try {
         // 1. Spawn server
-        const server = await spawnServer({ cwd, signal, env: options.configEnv });
+        const configEnvironment = options.configEnv ?? {};
+        const permissionEnvironment = buildPermissionEnvironment(configEnvironment);
+        const server = await spawnServer({
+            cwd,
+            signal,
+            env: { ...configEnvironment, ...permissionEnvironment },
+        });
         serverProcess = server.process;
         serverUrl = server.url;
         // 2. Connect to SSE and start streaming

package/dist/agents/opencode/build-permission-environment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Builds permissive OpenCode environment variables for headless execution.
+ *
+ * When axconfig hasn't generated an explicit OPENCODE_CONFIG_DIR (via
+ * --allow/--deny), this injects allow-all permissions to avoid interactive
+ * prompts. OpenCode's default config includes "ask" permissions that would
+ * block headless execution.
+ */
+/**
+ * Returns environment variables for permissive OpenCode execution.
+ *
+ * Returns an empty object (don't override) if:
+ * - `OPENCODE_CONFIG_DIR` is set (axconfig's explicit permissions via --allow/--deny)
+ * - `OPENCODE_PERMISSION` is already set (caller's explicit permissions)
+ */
+declare function buildPermissionEnvironment(configEnvironment: Record<string, string>): Record<string, string>;
+export { buildPermissionEnvironment };

package/dist/agents/opencode/build-permission-environment.js

@@ -0,0 +1,31 @@
+/**
+ * Builds permissive OpenCode environment variables for headless execution.
+ *
+ * When axconfig hasn't generated an explicit OPENCODE_CONFIG_DIR (via
+ * --allow/--deny), this injects allow-all permissions to avoid interactive
+ * prompts. OpenCode's default config includes "ask" permissions that would
+ * block headless execution.
+ */
+/**
+ * Returns environment variables for permissive OpenCode execution.
+ *
+ * Returns an empty object (don't override) if:
+ * - `OPENCODE_CONFIG_DIR` is set (axconfig's explicit permissions via --allow/--deny)
+ * - `OPENCODE_PERMISSION` is already set (caller's explicit permissions)
+ */
+function buildPermissionEnvironment(configEnvironment) {
+    if (configEnvironment["OPENCODE_CONFIG_DIR"] !== undefined ||
+        configEnvironment["OPENCODE_PERMISSION"] !== undefined) {
+        return {};
+    }
+    return {
+        OPENCODE_PERMISSION: JSON.stringify({
+            "*": "allow",
+            doom_loop: "allow",
+            external_directory: "allow",
+            read: "allow",
+            question: "allow",
+        }),
+    };
+}
+export { buildPermissionEnvironment };

package/dist/agents/opencode/parse-sse-event.js

@@ -110,7 +110,9 @@ function parseSSEEvent(event, state) {
             {
                 type: "session.error",
                 code: "PERMISSION_REQUIRED",
-                message: `OpenCode requires permission: ${tool}. ${title}. Pre-configure permissions in OpenCode settings.`,
+                message: `OpenCode requires permission: ${tool}. ${title}. ` +
+                    `axexec runs OpenCode non-interactively, so permission prompts are treated as errors. ` +
+                    `Use axexec --allow/--deny to pre-configure permissions.`,
                 timestamp: Date.now(),
             },
         ];

package/dist/agents/opencode/spawn-server.js

@@ -4,6 +4,7 @@
  * Handles spawning the OpenCode server process and waiting for it to start.
  */
 import { spawn } from "node:child_process";
+import { buildBaseEnvironment } from "../../build-agent-environment.js";
 import { resolveBinary } from "../../resolve-binary.js";
 /** Error thrown when server fails to start */
 class ServerStartError extends Error {
@@ -27,10 +28,20 @@ async function spawnServer(options) {
             environmentVariable: "AXEXEC_OPENCODE_PATH",
             installHint: "npm install -g opencode-ai",
         });
+        // OpenCode supports several env-based configuration overrides (OPENCODE_*).
+        // Exclude them from the host environment so axexec can run with isolated
+        // temp config/data directories instead of inheriting user settings.
+        const baseEnvironment = buildBaseEnvironment([
+            "OPENCODE_CONFIG",
+            "OPENCODE_CONFIG_CONTENT",
+            "OPENCODE_CONFIG_DIR",
+            "OPENCODE_DATA_DIR",
+            "OPENCODE_PERMISSION",
+        ]);
         const child = spawn(bin, ["serve", "--port", "0"], {
             cwd,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, ...env },
+            env: { ...baseEnvironment, ...env },
         });
         let stderrBuffer = "";
         let resolved = false;

package/dist/build-agent-environment.js

@@ -1,10 +1,18 @@
 const VAULT_ENV_EXCLUSIONS = ["AXVAULT", "AXVAULT_URL", "AXVAULT_API_KEY"];
+// Prevent upstream CLIs from enabling their own internal sandboxing based on
+// host environment variables. axexec is intentionally insecure-by-default and
+// does not rely on agent-internal sandboxing for enforcement.
+const AGENT_INTERNAL_SANDBOX_ENV_EXCLUSIONS = [
+    "GEMINI_SANDBOX",
+    "SEATBELT_PROFILE",
+];
 function isAxCredentialEnvironment(key) {
     return key.startsWith("AX_") && key.endsWith("_CREDENTIALS");
 }
 function buildBaseEnvironment(additionalExclusions = []) {
     const allExclusions = new Set([
         ...VAULT_ENV_EXCLUSIONS,
+        ...AGENT_INTERNAL_SANDBOX_ENV_EXCLUSIONS,
         ...additionalExclusions,
     ]);
     const entries = Object.entries(process.env).flatMap(([key, value]) => {

package/dist/cli.d.ts

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 /**
- * axexec CLI - Unified agent execution with isolation.
+ * axexec CLI - Unified agent execution with credential/config isolation.
  *
- * Executes AI coding agents with complete environment isolation:
- * - Credentials written to temp directory
- * - Config/permissions written to temp directory
- * - Agent pointed at temp directory via env vars
- * - Normalized event stream output
+ * axexec is a headless runner and normalization layer. It isolates agent
+ * credentials/config from your local environment via temp directories, but it
+ * is not an OS sandbox and is intentionally permissive/non-interactive by
+ * default. Use an external sandbox (container/VM) for real enforcement.
  */
 import "./agents/claude-code/adapter.js";
 import "./agents/codex/adapter.js";

package/dist/cli.js

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 /**
- * axexec CLI - Unified agent execution with isolation.
+ * axexec CLI - Unified agent execution with credential/config isolation.
  *
- * Executes AI coding agents with complete environment isolation:
- * - Credentials written to temp directory
- * - Config/permissions written to temp directory
- * - Agent pointed at temp directory via env vars
- * - Normalized event stream output
+ * axexec is a headless runner and normalization layer. It isolates agent
+ * credentials/config from your local environment via temp directories, but it
+ * is not an OS sandbox and is intentionally permissive/non-interactive by
+ * default. Use an external sandbox (container/VM) for real enforcement.
  */
 import { Command } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
@@ -17,14 +16,15 @@ import "./agents/gemini/adapter.js";
 import "./agents/opencode/adapter.js";
 import "./agents/copilot/adapter.js";
 import { listAdapters } from "./agents/registry.js";
+import { readStdin } from "./read-stdin.js";
+import { resolveCredentials } from "./resolve-credentials.js";
+import { parseOutputFormat } from "./resolve-output-mode.js";
+import { resolvePrompt } from "./resolve-prompt.js";
 import { runAgent } from "./run-agent.js";
-async function readStdin() {
-    let data = "";
-    for await (const chunk of process.stdin) {
-        data += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    }
-    return data.trimEnd();
-}
+import { validateAgent } from "./validate-agent.js";
+import { validateCwd } from "./validate-cwd.js";
+import { validateProviderOptions } from "./validate-opencode-options.js";
+import { validateStdinUsage } from "./validate-stdin-usage.js";
 const program = new Command()
     .name(packageJson.name)
     .description(packageJson.description)
@@ -33,11 +33,13 @@ const program = new Command()
     .showSuggestionAfterError()
     .option("--list-agents", "List available agents")
     .option("-a, --agent <id>", "Agent to use (required)")
+    .option("--cwd <path>", "Working directory for the agent process")
+    .option("--credentials-file <path|->", "Read credentials JSON from file (or '-' for stdin)")
     .option("-p, --prompt <text>", "Prompt text")
     .option("-m, --model <model>", "Model to use")
     .option("--provider <provider>", "Provider for OpenCode (required for OpenCode)")
-    .option("--allow <perms>", "Permission rules to allow (comma-separated)")
-    .option("--deny <perms>", "Permission rules to deny (comma-separated)")
+    .option("--allow <perms>", "Allow permissions (best-effort, comma-separated)")
+    .option("--deny <perms>", "Deny permissions (best-effort, comma-separated)")
     .option("-f, --format <fmt>", "Output format: jsonl, tsv (default: tsv, truncated on TTY)")
     .option("--raw-log <file>", "Write raw agent output to file")
     .option("--debug", "Enable debug mode")
@@ -48,9 +50,11 @@ const program = new Command()
 Requirements:
   Install the agent CLIs you plan to use: claude, codex, gemini, opencode, copilot.
   Override paths: AXEXEC_CLAUDE_PATH, AXEXEC_CODEX_PATH, AXEXEC_GEMINI_PATH, AXEXEC_OPENCODE_PATH, AXEXEC_COPILOT_PATH
+  Security: axexec is not a sandbox. Run inside an external sandbox for enforcement.
 
 Examples:
   axexec -a claude "Refactor auth flow"
+  axexec -a claude --credentials-file ./creds.json "Review this PR"
   axexec -a opencode --provider anthropic -m claude-sonnet-4 "Hello"
   axexec -a claude -f jsonl "Audit deps" | jq 'select(.type=="tool.call")'
   axexec --list-agents | tail -n +2 | cut -f1
@@ -65,71 +69,89 @@ Examples:
         }
         return;
     }
-    // Get prompt from flag, positional argument, or stdin (in priority order)
-    // Only read stdin if no prompt was provided via CLI arguments to avoid
-    // blocking in CI environments with open but unused stdin.
-    const needsStdinPrompt = !options.prompt && !positionalPrompt;
-    const stdinPrompt = needsStdinPrompt && !process.stdin.isTTY ? await readStdin() : undefined;
-    const prompt = (options.prompt ??
-        positionalPrompt ??
-        stdinPrompt)?.trimEnd();
-    if (!prompt) {
-        process.stderr.write("Error: prompt is required\n");
+    if (!options.agent) {
+        process.stderr.write("Error: --agent is required\n");
         process.stderr.write("Usage: axexec --agent <id> <prompt>\n");
         process.stderr.write("Try 'axexec --help' for more information.\n");
         process.exitCode = 2;
         return;
     }
-    if (!options.agent) {
-        process.stderr.write("Error: --agent is required\n");
-        process.stderr.write("Usage: axexec --agent <id> <prompt>\n");
-        process.stderr.write("Try 'axexec --help' for more information.\n");
+    // Validate agent ID early to provide clear error before processing credentials
+    const agentValidation = validateAgent(options.agent);
+    if (!agentValidation.ok) {
+        process.stderr.write(`${agentValidation.message}\n`);
+        process.exitCode = agentValidation.exitCode;
+        return;
+    }
+    // Validate --cwd if provided
+    if (options.cwd) {
+        const cwdResult = await validateCwd(options.cwd);
+        if (!cwdResult.ok) {
+            process.stderr.write(`Error: ${cwdResult.error}\n`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    const needsStdinPrompt = !options.prompt && !positionalPrompt;
+    const stdinResult = validateStdinUsage(options.credentialsFile, needsStdinPrompt, process.stdin.isTTY);
+    if (!stdinResult.ok) {
+        process.stderr.write(`Error: ${stdinResult.error}\n`);
         process.exitCode = 2;
         return;
     }
+    // Get prompt from flag, positional argument, or stdin (in priority order)
+    // Only read stdin if no prompt was provided via CLI arguments to avoid
+    // blocking in CI environments with open but unused stdin.
+    const stdinPrompt = needsStdinPrompt &&
+        !process.stdin.isTTY &&
+        options.credentialsFile !== "-"
+        ? await readStdin()
+        : undefined;
+    const promptResult = resolvePrompt({
+        promptFlag: options.prompt,
+        positionalPrompt,
+        stdinPrompt,
+    });
+    if (!promptResult.ok) {
+        process.stderr.write(`Error: ${promptResult.error}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const { prompt } = promptResult;
     // Validate format option
     let format;
     if (options.format) {
-        if (options.format === "jsonl" || options.format === "tsv") {
-            format = options.format;
-        }
-        else {
-            process.stderr.write(`Error: Invalid format '${options.format}'\n`);
-            process.stderr.write("Valid formats: jsonl, tsv\n");
+        const formatResult = parseOutputFormat(options.format);
+        if (!formatResult.ok) {
+            process.stderr.write(`Error: ${formatResult.error}\n`);
             process.exitCode = 2;
             return;
         }
+        format = formatResult.format;
     }
-    // Validate --provider is only used with OpenCode
-    if (options.provider && options.agent !== "opencode") {
-        process.stderr.write("Error: --provider is only supported for OpenCode agent\n");
+    // Resolve credentials from --credentials-file if specified.
+    const credentialsResult = await resolveCredentials(options.credentialsFile, readStdin, options.agent);
+    if (!credentialsResult.ok) {
+        process.stderr.write(`Error: ${credentialsResult.error}\n`);
         process.exitCode = 2;
         return;
     }
-    // Validate OpenCode requires --provider
-    if (options.agent === "opencode") {
-        // Check for deprecated provider/model format
-        if (options.model?.includes("/")) {
-            const [provider, model] = options.model.split("/", 2);
-            process.stderr.write("Error: Model format 'provider/model' is no longer supported\n");
-            process.stderr.write("Use separate --provider and --model flags:\n");
-            process.stderr.write(`  axexec -a opencode --provider ${provider} -m ${model} ...\n`);
-            process.exitCode = 2;
-            return;
-        }
-        // Require --provider for OpenCode
-        if (!options.provider) {
-            process.stderr.write("Error: OpenCode requires --provider\n");
-            process.stderr.write("  axexec -a opencode --provider anthropic -m claude-sonnet-4 ...\n");
-            process.exitCode = 2;
-            return;
-        }
+    const { credentials } = credentialsResult;
+    // Validate provider options
+    const providerResult = validateProviderOptions(options.agent, options.model, options.provider, credentials);
+    if (!providerResult.ok) {
+        process.stderr.write(`Error: ${providerResult.error}\n`);
+        process.exitCode = 2;
+        return;
     }
+    const { normalizedProvider } = providerResult;
     // Run agent
     const result = await runAgent(options.agent, {
         prompt,
+        cwd: options.cwd,
+        credentials,
         model: options.model,
-        provider: options.provider,
+        provider: normalizedProvider,
         allow: options.allow,
         deny: options.deny,
         format,
@@ -138,9 +160,8 @@ Examples:
         verbose: options.verbose,
         preserveGithubSha: options.preserveGithubSha,
     });
-    // Set exit code based on success
-    if (!result.success) {
-        // eslint-disable-next-line require-atomic-updates
+    // Set exit code based on success (only if not already set to a more specific code)
+    if (!result.success && process.exitCode === undefined) {
         process.exitCode = 1;
     }
 });

package/dist/credentials/install-credentials.d.ts

@@ -3,8 +3,8 @@
  *
  * Writes credentials to a temporary directory in agent-specific formats,
  * then returns the environment variables needed to point the agent at that
- * directory. This ensures complete isolation - agents never discover or use
- * locally installed credentials.
+ * directory. This ensures credential isolation: agents don't discover or use
+ * locally installed credentials/config.
  */
 import { type AgentCli, type Credentials } from "axshared";
 import type { InstallResult } from "./types.js";

package/dist/credentials/install-credentials.js

@@ -3,8 +3,8 @@
  *
  * Writes credentials to a temporary directory in agent-specific formats,
  * then returns the environment variables needed to point the agent at that
- * directory. This ensures complete isolation - agents never discover or use
- * locally installed credentials.
+ * directory. This ensures credential isolation: agents don't discover or use
+ * locally installed credentials/config.
  */
 import { mkdirSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";

package/dist/execute-agent.js

@@ -12,6 +12,7 @@ async function executeAgent(agentId, adapter, options, configEnvironment, creden
     const runOptions = {
         prompt: options.prompt,
         verbose: options.verbose ?? false,
+        cwd: options.cwd,
         model: options.model,
         provider: options.provider,
         rawLogPath: options.rawLog,

package/dist/format-zod-error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Format Zod validation errors for human-readable display.
+ */
+import type { ZodError } from "zod";
+declare function formatZodError(error: ZodError): string;
+export { formatZodError };

package/dist/format-zod-error.js

@@ -0,0 +1,12 @@
+/**
+ * Format Zod validation errors for human-readable display.
+ */
+function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "root";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+export { formatZodError };

package/dist/parse-credentials.js

@@ -6,14 +6,7 @@
  */
 import { parseCredentialsResult, } from "axshared";
 import { getEnvironmentTrimmed } from "./credentials/get-environment-trimmed.js";
-function formatZodError(error) {
-    return error.issues
-        .map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "root";
-        return `${path}: ${issue.message}`;
-    })
-        .join("; ");
-}
+import { formatZodError } from "./format-zod-error.js";
 /**
  * Parses credentials from environment variables.
  *

package/dist/read-credentials-file.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read and parse credentials from a file or stdin.
+ */
+import { type Credentials } from "axshared";
+type ReadCredentialsResult = {
+    ok: true;
+    credentials: Credentials;
+} | {
+    ok: false;
+    error: string;
+};
+declare function readCredentialsFile(path: string, readStdin: () => Promise<string>, expectedAgent: string): Promise<ReadCredentialsResult>;
+export { readCredentialsFile };

package/dist/read-credentials-file.js

@@ -0,0 +1,39 @@
+/**
+ * Read and parse credentials from a file or stdin.
+ */
+import { readFile } from "node:fs/promises";
+import { parseCredentialsResult } from "axshared";
+import { formatZodError } from "./format-zod-error.js";
+async function readCredentialsFile(path, readStdin, expectedAgent) {
+    let raw;
+    try {
+        raw = path === "-" ? await readStdin() : await readFile(path, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Failed to read credentials file: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Failed to parse credentials JSON: ${message}` };
+    }
+    const parseResult = parseCredentialsResult(parsed);
+    if (!parseResult.ok) {
+        return {
+            ok: false,
+            error: `Invalid credentials format: ${formatZodError(parseResult.error)}`,
+        };
+    }
+    if (parseResult.value.agent !== expectedAgent) {
+        return {
+            ok: false,
+            error: `Credentials agent mismatch. Expected ${expectedAgent}, got ${parseResult.value.agent}.`,
+        };
+    }
+    return { ok: true, credentials: parseResult.value };
+}
+export { readCredentialsFile };

package/dist/read-stdin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Read all data from stdin as a string.
+ */
+declare function readStdin(): Promise<string>;
+export { readStdin };

package/dist/read-stdin.js

@@ -0,0 +1,11 @@
+/**
+ * Read all data from stdin as a string.
+ */
+async function readStdin() {
+    let data = "";
+    for await (const chunk of process.stdin) {
+        data += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return data.trimEnd();
+}
+export { readStdin };

package/dist/resolve-credentials.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolve credentials from --credentials-file option.
+ */
+import type { Credentials } from "axshared";
+type ResolveCredentialsResult = {
+    ok: true;
+    credentials: Credentials | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve credentials from --credentials-file if specified.
+ *
+ * @param credentialsFile - Path to credentials file or "-" for stdin
+ * @param readStdin - Function to read stdin
+ * @param agentId - Expected agent ID for validation
+ * @returns Credentials or undefined if no file specified
+ */
+declare function resolveCredentials(credentialsFile: string | undefined, readStdin: () => Promise<string>, agentId: string): Promise<ResolveCredentialsResult>;
+export { resolveCredentials };

package/dist/resolve-credentials.js

@@ -0,0 +1,23 @@
+/**
+ * Resolve credentials from --credentials-file option.
+ */
+import { readCredentialsFile } from "./read-credentials-file.js";
+/**
+ * Resolve credentials from --credentials-file if specified.
+ *
+ * @param credentialsFile - Path to credentials file or "-" for stdin
+ * @param readStdin - Function to read stdin
+ * @param agentId - Expected agent ID for validation
+ * @returns Credentials or undefined if no file specified
+ */
+async function resolveCredentials(credentialsFile, readStdin, agentId) {
+    if (!credentialsFile) {
+        return { ok: true, credentials: undefined };
+    }
+    const result = await readCredentialsFile(credentialsFile, readStdin, agentId);
+    if (!result.ok) {
+        return { ok: false, error: result.error };
+    }
+    return { ok: true, credentials: result.credentials };
+}
+export { resolveCredentials };

package/dist/resolve-output-mode.d.ts

@@ -35,5 +35,19 @@ type OutputMode = "jsonl" | "tsv" | "tsv-truncated";
  * resolveOutputMode(undefined, false)  // → "tsv"
  */
 declare function resolveOutputMode(format: OutputFormat | undefined, isTTY: boolean): OutputMode;
-export { resolveOutputMode };
+type ParseFormatResult = {
+    ok: true;
+    format: OutputFormat;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse and validate a format string from CLI input.
+ *
+ * @param input - Raw format string from --format flag
+ * @returns Result with validated format or error message
+ */
+declare function parseOutputFormat(input: string): ParseFormatResult;
+export { resolveOutputMode, parseOutputFormat };
 export type { OutputFormat, OutputMode };

package/dist/resolve-output-mode.js

@@ -36,4 +36,19 @@ function resolveOutputMode(format, isTTY) {
     // Auto-detect based on TTY
     return isTTY ? "tsv-truncated" : "tsv";
 }
-export { resolveOutputMode };
+/**
+ * Parse and validate a format string from CLI input.
+ *
+ * @param input - Raw format string from --format flag
+ * @returns Result with validated format or error message
+ */
+function parseOutputFormat(input) {
+    if (input === "jsonl" || input === "tsv") {
+        return { ok: true, format: input };
+    }
+    return {
+        ok: false,
+        error: `Invalid format '${input}'\nValid formats: jsonl, tsv`,
+    };
+}
+export { resolveOutputMode, parseOutputFormat };

package/dist/resolve-prompt.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve prompt from CLI options, positional argument, or stdin.
+ */
+type ResolvePromptResult = {
+    ok: true;
+    prompt: string;
+} | {
+    ok: false;
+    error: string;
+};
+interface ResolvePromptOptions {
+    promptFlag: string | undefined;
+    positionalPrompt: string | undefined;
+    stdinPrompt: string | undefined;
+}
+/**
+ * Resolve prompt from multiple sources in priority order.
+ *
+ * Priority: --prompt flag > positional argument > stdin
+ */
+declare function resolvePrompt(options: ResolvePromptOptions): ResolvePromptResult;
+export { resolvePrompt };

package/dist/resolve-prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Resolve prompt from CLI options, positional argument, or stdin.
+ */
+/**
+ * Resolve prompt from multiple sources in priority order.
+ *
+ * Priority: --prompt flag > positional argument > stdin
+ */
+function resolvePrompt(options) {
+    const prompt = (options.promptFlag ??
+        options.positionalPrompt ??
+        options.stdinPrompt)?.trimEnd();
+    if (!prompt) {
+        return {
+            ok: false,
+            error: "prompt is required\n" +
+                "Usage: axexec --agent <id> <prompt>\n" +
+                "Try 'axexec --help' for more information.",
+        };
+    }
+    return { ok: true, prompt };
+}
+export { resolvePrompt };

package/dist/run-agent.d.ts

@@ -3,7 +3,10 @@
  */
 import type { RunAgentOptions, RunResult } from "./types/run-result.js";
 /**
- * Runs an agent with full isolation.
+ * Runs an agent with credential/config isolation.
+ *
+ * Note: axexec is not an OS sandbox. It runs agents in a non-interactive,
+ * permissive mode by default and should not be treated as a security boundary.
  *
  * 1. Validates the agent ID
  * 2. Uses provided credentials or parses from environment

package/dist/run-agent.js

@@ -4,12 +4,16 @@
 import { installCredentials, cleanupCredentials, } from "./credentials/install-credentials.js";
 import { buildPermissionsConfig } from "./build-permissions-config.js";
 import { validateAgent } from "./validate-agent.js";
+import { validateCwd } from "./validate-cwd.js";
 import { parseCredentialsFromEnvironment } from "./parse-credentials.js";
 import { buildExecutionMetadata } from "./build-execution-metadata.js";
 import { executeAgent } from "./execute-agent.js";
 import { resolveDiagnostics, resolveExitCodeSetter, } from "./resolve-run-diagnostics.js";
 /**
- * Runs an agent with full isolation.
+ * Runs an agent with credential/config isolation.
+ *
+ * Note: axexec is not an OS sandbox. It runs agents in a non-interactive,
+ * permissive mode by default and should not be treated as a security boundary.
  *
  * 1. Validates the agent ID
  * 2. Uses provided credentials or parses from environment
@@ -35,12 +39,28 @@ async function runAgent(agentId, options) {
         };
     }
     const { adapter } = validation;
-    // Validate --model format for OpenCode (reject "provider/model" format)
-    if (validation.agentId === "opencode" && options.model?.includes("/")) {
-        const [provider, model] = options.model.split("/", 2);
+    // Validate cwd if provided (for programmatic API consumers)
+    if (options.cwd) {
+        const cwdValidation = await validateCwd(options.cwd);
+        if (!cwdValidation.ok) {
+            diagnostics.error(`Error: ${cwdValidation.error}`);
+            setExitCode(2);
+            return {
+                events: [],
+                success: false,
+                execution: { agent: validation.agentId, model: options.model },
+            };
+        }
+    }
+    // Validate --model format for OpenCode (reject "provider/model" format only when --provider is missing).
+    // Many legitimate model IDs contain slashes (e.g., nvidia/nemotron, google/gemma).
+    if (validation.agentId === "opencode" &&
+        !options.provider &&
+        options.model?.includes("/")) {
+        const [providerPart, modelPart] = options.model.split("/", 2);
         diagnostics.error(`Error: Model format 'provider/model' is no longer supported.\n` +
             `Use separate --provider and --model flags instead:\n` +
-            `  --provider ${provider} --model ${model}`);
+            `  --provider ${providerPart} --model ${modelPart}`);
         setExitCode(2);
         return {
             events: [],
@@ -73,6 +93,27 @@ async function runAgent(agentId, options) {
             execution: { agent: validation.agentId, model: options.model },
         };
     }
+    // Validate OpenCode credentials provider matches the requested provider.
+    // This duplicates validation in validateOpenCodeOptions() (CLI layer) but is
+    // necessary for programmatic API consumers who call runAgent() directly.
+    if (validation.agentId === "opencode" &&
+        credentials?.agent === "opencode" &&
+        options.provider &&
+        credentials.provider.toLowerCase() !== options.provider.toLowerCase()) {
+        diagnostics.error("Error: Credentials provider mismatch. " +
+            `Expected ${options.provider}, got ${credentials.provider}.`);
+        setExitCode(2);
+        return {
+            events: [],
+            success: false,
+            execution: { agent: validation.agentId, model: options.model },
+        };
+    }
+    // Normalize provider to lowercase for OpenCode (all OpenCode provider IDs are lowercase).
+    // This ensures consistent behavior for both CLI and programmatic API users.
+    const normalizedOptions = validation.agentId === "opencode" && options.provider
+        ? { ...options, provider: options.provider.toLowerCase() }
+        : options;
     // Always create isolated runtime directories; install credentials if provided.
     let credentialResult;
     try {
@@ -112,6 +153,6 @@ async function runAgent(agentId, options) {
         configEnvironment = configResult.env;
     }
     // Execute agent
-    return executeAgent(validation.agentId, adapter, options, configEnvironment, credentialResult, credentials, preserveConfigDirectory, diagnostics.error);
+    return executeAgent(validation.agentId, adapter, normalizedOptions, configEnvironment, credentialResult, credentials, preserveConfigDirectory, diagnostics.error);
 }
 export { runAgent };

package/dist/types/run-result.d.ts

@@ -10,6 +10,10 @@ interface RunAgentDiagnostics {
 }
 interface RunAgentOptions {
     prompt: string;
+    /**
+     * Working directory for the agent process.
+     */
+    cwd?: string;
     /**
      * Credentials to use. If not provided, parses from environment variables.
      * Accepts the canonical Credentials shape shared across ax* packages.

package/dist/validate-cwd.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validate --cwd option points to an existing directory.
+ */
+type ValidateCwdResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+declare function validateCwd(cwd: string): Promise<ValidateCwdResult>;
+export { validateCwd };

package/dist/validate-cwd.js

@@ -0,0 +1,24 @@
+/**
+ * Validate --cwd option points to an existing directory.
+ */
+import { stat } from "node:fs/promises";
+async function validateCwd(cwd) {
+    try {
+        const stats = await stat(cwd);
+        if (!stats.isDirectory()) {
+            return {
+                ok: false,
+                error: `--cwd path is not a directory: ${cwd}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: `--cwd directory error: ${message}`,
+        };
+    }
+}
+export { validateCwd };

package/dist/validate-opencode-options.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validate OpenCode-specific CLI options.
+ */
+import type { Credentials } from "axshared";
+type ProviderValidationResult = {
+    ok: true;
+    normalizedProvider: string | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate provider usage and OpenCode-specific options.
+ *
+ * - For non-OpenCode agents: provider must not be specified
+ * - For OpenCode: validates model format, requires provider, checks credentials
+ */
+declare function validateProviderOptions(agentId: string, model: string | undefined, provider: string | undefined, credentials: Credentials | undefined): ProviderValidationResult;
+export { validateProviderOptions };

package/dist/validate-opencode-options.js

@@ -0,0 +1,58 @@
+/**
+ * Validate OpenCode-specific CLI options.
+ */
+/**
+ * Validate provider usage and OpenCode-specific options.
+ *
+ * - For non-OpenCode agents: provider must not be specified
+ * - For OpenCode: validates model format, requires provider, checks credentials
+ */
+function validateProviderOptions(agentId, model, provider, credentials) {
+    // --provider is only valid for OpenCode
+    if (provider && agentId !== "opencode") {
+        return {
+            ok: false,
+            error: "--provider is only supported for OpenCode agent",
+        };
+    }
+    // Non-OpenCode agents don't need further validation
+    if (agentId !== "opencode") {
+        return { ok: true, normalizedProvider: undefined };
+    }
+    // OpenCode-specific validation
+    return validateOpenCodeOptions(model, provider, credentials);
+}
+function validateOpenCodeOptions(model, provider, credentials) {
+    // Require --provider for OpenCode
+    if (!provider) {
+        // If model contains "/" and no provider given, suggest they might be using
+        // the old provider/model format, but primarily tell them --provider is required.
+        if (model?.includes("/")) {
+            const [providerPart, modelPart] = model.split("/", 2);
+            return {
+                ok: false,
+                error: `OpenCode requires --provider\n` +
+                    `If using the old 'provider/model' format, use separate flags:\n` +
+                    `  axexec -a opencode --provider ${providerPart} -m ${modelPart} ...`,
+            };
+        }
+        return {
+            ok: false,
+            error: `OpenCode requires --provider\n` +
+                `  axexec -a opencode --provider anthropic -m claude-sonnet-4 ...`,
+        };
+    }
+    // Normalize to lowercase to match OpenCode's provider ID format.
+    // OpenCode stores all provider IDs in lowercase (anthropic, openai, etc).
+    const normalizedProvider = provider.toLowerCase();
+    // Validate credentials provider matches
+    if (credentials?.agent === "opencode" &&
+        credentials.provider.toLowerCase() !== normalizedProvider) {
+        return {
+            ok: false,
+            error: `Credentials provider mismatch. Expected ${normalizedProvider}, got ${credentials.provider}.`,
+        };
+    }
+    return { ok: true, normalizedProvider };
+}
+export { validateProviderOptions };

package/dist/validate-stdin-usage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Validate stdin usage when credentials and prompt may both need stdin.
+ */
+type ValidateStdinResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validates that stdin usage is not conflicting.
+ *
+ * Returns an error if:
+ * - --credentials-file - is used with no prompt (both would read stdin)
+ * - --credentials-file - is used in interactive TTY mode (requires piping)
+ */
+declare function validateStdinUsage(credentialsFile: string | undefined, needsStdinPrompt: boolean, isTTY: boolean | undefined): ValidateStdinResult;
+export { validateStdinUsage };

package/dist/validate-stdin-usage.js

@@ -0,0 +1,28 @@
+/**
+ * Validate stdin usage when credentials and prompt may both need stdin.
+ */
+/**
+ * Validates that stdin usage is not conflicting.
+ *
+ * Returns an error if:
+ * - --credentials-file - is used with no prompt (both would read stdin)
+ * - --credentials-file - is used in interactive TTY mode (requires piping)
+ */
+function validateStdinUsage(credentialsFile, needsStdinPrompt, isTTY) {
+    if (credentialsFile === "-" && needsStdinPrompt) {
+        return {
+            ok: false,
+            error: "Cannot read both prompt and credentials from stdin\n" +
+                "Provide the prompt via --prompt or positional argument when using --credentials-file -",
+        };
+    }
+    if (credentialsFile === "-" && isTTY) {
+        return {
+            ok: false,
+            error: "Cannot read credentials from stdin in interactive mode\n" +
+                "Pipe credentials JSON to stdin or use a file path instead of '-'",
+        };
+    }
+    return { ok: true };
+}
+export { validateStdinUsage };

package/package.json

@@ -2,7 +2,7 @@
   "name": "axexec",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Unified CLI runner for AI coding agents with normalized event streaming",
   "repository": {
     "type": "git",