axexec 1.6.1 → 2.0.1

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,12 +33,14 @@ 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("-f, --format <fmt>", "Output format: jsonl, tsv (default: tsv, truncated on TTY)")
+    .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 when omitted: truncated tsv on TTY, full tsv otherwise)")
     .option("--raw-log <file>", "Write raw agent output to file")
     .option("--debug", "Enable debug mode")
     .option("--verbose", "Show agent stderr output")
@@ -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);
+    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);
+    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/get-credential-environment.d.ts

@@ -4,12 +4,12 @@
  * Each agent has its own env var requirements. This module extracts
  * the appropriate values from Credentials and returns them as env vars.
  */
-import type { Credentials } from "axshared";
+import type { AgentCli, Credentials } from "axshared";
 /**
  * Gets additional environment variables for credential-based auth.
  *
  * Some agents use environment variables for API keys or OAuth tokens
  * in addition to or instead of file-based credentials.
  */
-declare function getCredentialEnvironment(credentials: Credentials): Record<string, string>;
+declare function getCredentialEnvironment(agentId: AgentCli, credentials: Credentials, provider?: string): Record<string, string>;
 export { getCredentialEnvironment };

package/dist/credentials/get-credential-environment.js

@@ -11,7 +11,7 @@ import { resolveStringField } from "./resolve-string-field.js";
  * Some agents use environment variables for API keys or OAuth tokens
  * in addition to or instead of file-based credentials.
  */
-function getCredentialEnvironment(credentials) {
+function getCredentialEnvironment(agentId, credentials, provider) {
     const environment = {};
     // Extract API key from credentials data
     const apiKey = resolveStringField(credentials.data, "apiKey", "key");
@@ -19,7 +19,7 @@ function getCredentialEnvironment(credentials) {
     // axauth uses "accessToken", but also check legacy "oauthToken" and "token" keys
     const oauthToken = resolveStringField(credentials.data, "accessToken", "oauthToken") ??
         resolveStringField(credentials.data, "token", "token");
-    switch (credentials.agent) {
+    switch (agentId) {
         case "claude": {
             if (credentials.type === "api-key" && apiKey) {
                 environment["ANTHROPIC_API_KEY"] = apiKey;
@@ -51,7 +51,6 @@ function getCredentialEnvironment(credentials) {
         }
         case "opencode": {
             // OpenCode supports multiple providers, env var depends on provider
-            const provider = credentials.provider;
             if (credentials.type === "api-key" && apiKey) {
                 switch (provider) {
                     case "anthropic": {
@@ -71,6 +70,9 @@ function getCredentialEnvironment(credentials) {
                         environment["OPENCODE_API_KEY"] = apiKey;
                         break;
                     }
+                    case undefined: {
+                        break;
+                    }
                 }
             }
             break;

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";
@@ -19,7 +19,7 @@ type WarningWriter = (message: string) => void;
  *
  * The caller is responsible for cleaning up the temp directory after use.
  */
-declare function installCredentials(agentId: AgentCli, credentials?: Credentials, warn?: WarningWriter): Promise<InstallResult>;
+declare function installCredentials(agentId: AgentCli, credentials?: Credentials, provider?: string, warn?: WarningWriter): Promise<InstallResult>;
 /**
  * Cleanup for use in finally blocks.
  */

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";
@@ -42,7 +42,7 @@ async function createTemporaryDirectories(agentId) {
 /**
  * Installs agent-specific credentials to the appropriate directory.
  */
-function installAgentCredentials(agentId, configDirectory, dataDirectory, credentials, warn) {
+function installAgentCredentials(agentId, configDirectory, dataDirectory, credentials, provider, warn) {
     switch (agentId) {
         case "claude": {
             installClaudeCredentials(configDirectory, credentials);
@@ -57,8 +57,8 @@ function installAgentCredentials(agentId, configDirectory, dataDirectory, creden
             break;
         }
         case "opencode": {
-            if (credentials.agent === "opencode") {
-                installOpenCodeCredentials(dataDirectory, credentials, warn);
+            if (provider) {
+                installOpenCodeCredentials(dataDirectory, credentials, provider, warn);
             }
             break;
         }
@@ -78,15 +78,15 @@ function installAgentCredentials(agentId, configDirectory, dataDirectory, creden
  *
  * The caller is responsible for cleaning up the temp directory after use.
  */
-async function installCredentials(agentId, credentials, warn) {
+async function installCredentials(agentId, credentials, provider, warn) {
     const { baseDirectory, configDirectory, dataDirectory } = await createTemporaryDirectories(agentId);
     try {
         if (credentials) {
-            installAgentCredentials(agentId, configDirectory, dataDirectory, credentials, warn);
+            installAgentCredentials(agentId, configDirectory, dataDirectory, credentials, provider, warn);
         }
         const runtimeEnvironment = buildAgentRuntimeEnvironment(agentId, configDirectory, dataDirectory);
         const credentialEnvironment = credentials
-            ? getCredentialEnvironment(credentials)
+            ? getCredentialEnvironment(agentId, credentials, provider)
             : {};
         return {
             env: { ...runtimeEnvironment, ...credentialEnvironment },

package/dist/credentials/write-agent-credentials.d.ts

@@ -54,7 +54,5 @@ declare function installGeminiCredentials(configDirectory: string, credentials:
  * - oauth-credentials: Written as { [provider]: { type: "oauth", ...data } }
  * - api-key: Written as { [provider]: { type: "api", key: "..." } }
  */
-declare function installOpenCodeCredentials(dataDirectory: string, credentials: Extract<Credentials, {
-    agent: "opencode";
-}>, warn?: WarningWriter): void;
+declare function installOpenCodeCredentials(dataDirectory: string, credentials: Credentials, provider: string, warn?: WarningWriter): void;
 export { installClaudeCredentials, installCodexCredentials, installGeminiCredentials, installOpenCodeCredentials, };

package/dist/credentials/write-agent-credentials.js

@@ -100,9 +100,8 @@ function installGeminiCredentials(configDirectory, credentials) {
  * - oauth-credentials: Written as { [provider]: { type: "oauth", ...data } }
  * - api-key: Written as { [provider]: { type: "api", key: "..." } }
  */
-function installOpenCodeCredentials(dataDirectory, credentials, warn = defaultWarningWriter) {
+function installOpenCodeCredentials(dataDirectory, credentials, provider, warn = defaultWarningWriter) {
     const authPath = path.join(dataDirectory, "auth.json");
-    const provider = credentials.provider;
     switch (credentials.type) {
         case "oauth-credentials": {
             saveJsonFile(authPath, {

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.
  *
@@ -32,14 +25,6 @@ function parseCredentialsFromEnvironment(agentId) {
             const parsed = JSON.parse(credEnvironmentValue);
             const parseResult = parseCredentialsResult(parsed);
             if (parseResult.ok) {
-                if (parseResult.value.agent !== agentId) {
-                    return {
-                        ok: false,
-                        exitCode: 2,
-                        message: `Error: ${credEnvironmentVariable} agent mismatch. ` +
-                            `Expected ${agentId}, got ${parseResult.value.agent}.`,
-                    };
-                }
                 return { ok: true, credentials: parseResult.value };
             }
             return {
@@ -74,7 +59,6 @@ function parseApiKeyFromEnvironment(agentId) {
                 return {
                     ok: true,
                     credentials: {
-                        agent: agentId,
                         type: "oauth-token",
                         data: { oauthToken },
                     },
@@ -109,7 +93,6 @@ function parseApiKeyFromEnvironment(agentId) {
     return {
         ok: true,
         credentials: {
-            agent: agentId,
             type: "api-key",
             data: { apiKey },
         },

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>): Promise<ReadCredentialsResult>;
+export { readCredentialsFile };

package/dist/read-credentials-file.js

@@ -0,0 +1,33 @@
+/**
+ * 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) {
+    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)}`,
+        };
+    }
+    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,20 @@
+/**
+ * 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
+ * @returns Credentials or undefined if no file specified
+ */
+declare function resolveCredentials(credentialsFile: string | undefined, readStdin: () => Promise<string>): Promise<ResolveCredentialsResult>;
+export { resolveCredentials };

package/dist/resolve-credentials.js

@@ -0,0 +1,22 @@
+/**
+ * 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
+ * @returns Credentials or undefined if no file specified
+ */
+async function resolveCredentials(credentialsFile, readStdin) {
+    if (!credentialsFile) {
+        return { ok: true, credentials: undefined };
+    }
+    const result = await readCredentialsFile(credentialsFile, readStdin);
+    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