claude_request_async
Destructive
Submit a Claude Code CLI request as a durable background job. Poll for status and collect results asynchronously.
Instructions
Start a Claude Code CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bare | No | Claude --bare: minimal mode (skip hooks, LSP, plugin sync, attribution, auto-memory, keychain reads, CLAUDE.md auto-discovery). Explicit opt-in. | |
| name | No | Claude --name: display name for this session (shown in pickers/titles). | |
| agent | No | Claude --agent: dispatch to a named single sub-agent. | |
| debug | No | Claude -d/--debug: enable debug mode. true emits a bare --debug; a string emits --debug <filter> (e.g. "api,hooks"). Debug output goes to stderr only. | |
| model | No | Model name or alias (e.g. sonnet, claude-sonnet-4-5-20250929, latest) | |
| tools | No | Claude --tools: restrict the available built-in tool set (distinct from allowedTools permission gating). Pass [""] to disable all tools. | |
| addDir | No | Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance. Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access. | |
| agents | No | Claude --agents: inline JSON map of agent name → { description, prompt, tools?, model? }. | |
| effort | No | Claude --effort: low|medium|high|xhigh|max. | |
| prompt | No | Prompt text for Claude (mutually exclusive with promptParts) | |
| maxTurns | No | Claude --max-turns: cap on agent loop iterations. | |
| safeMode | No | Claude --safe-mode: start with all customizations (CLAUDE.md, skills, plugins, hooks, MCP, commands, agents) disabled for troubleshooting. Explicit opt-in. | |
| settings | No | Claude --settings: path to a settings JSON file or a JSON literal of additional settings. Powerful: settings can define hooks/permissions/model; passed verbatim. | |
| worktree | No | Slice λ: run this request inside a dedicated git worktree owned by the gateway. `true` creates a fresh worktree at `<repoRoot>/.worktrees/<uuid>` branched from HEAD. `{ name?, ref? }` lets the caller supply a sanitized name and/or a git ref (default: HEAD). When the request carries a sessionId and the session already has a worktree, that worktree is reused. The gateway spawns the child CLI with `cwd: <worktree-path>` — no `-w`/`--worktree` flag is ever emitted to the underlying CLI. On session_delete or TTL eviction the gateway runs `git worktree remove --force`. Successful responses are prefixed with `[gateway] worktree=<absolute-path>\n` so callers can use the path. NOTE: callers should `.gitignore` the `.worktrees/` directory in their repo (the gateway does NOT auto-gitignore — see slice λ spec Q4). | |
| debugFile | No | Claude --debug-file: write debug logs to a specific file path (enables debug mode). | |
| pluginDir | No | Claude --plugin-dir: load a plugin from a directory or .zip for this session only. One --plugin-dir instance per entry. | |
| pluginUrl | No | Claude --plugin-url: load a plugin .zip from a URL for this session only. One --plugin-url instance per entry. | |
| sessionId | No | On a fresh request this id is emitted as Claude --session-id <uuid> (must be a valid UUID that does not already exist). Resume the latest cwd conversation with continueSession:true. gw-* ids are not valid Claude --session-id values. | |
| workspace | No | Registered workspace alias for remote HTTP/OAuth provider calls. Do not use this field, workspace_list, or workspace_register_existing_repo as a fallback for stdio/local provider path access; pass workingDir/addDir/includeDirs directly instead. | |
| jsonSchema | No | Claude --json-schema: JSON Schema literal (NOT a path) constraining structured output. Object values are JSON.stringify-d; string values are passed verbatim. Use with outputFormat='json'. Set outputFormat:json so the gateway treats the reply as structured output (skips response optimization and warning injection); the default output format is not json, so pass it explicitly. | |
| mcpServers | No | MCP servers exposed to Claude | |
| forkSession | No | Claude --fork-session: branch from an existing session into a fresh fork. | |
| promptParts | No | Cache-aware structured prompt: { system?, tools?, context?, task, cacheControl? }. Same semantics as claude_request: stable head (system/tools/context) + volatile tail (task). Set `cacheControl: { system?, tools?, context?: boolean }` to opt into explicit Anthropic prefix caching via `--input-format stream-json` (slice κ); requires `outputFormat: 'stream-json'` and hard-codes `ttl='1h'`. Mutually exclusive with `prompt`. Stable prefix hash logged to flight recorder. | |
| allowedTools | No | Allowed tools (['Bash(git:*)','Edit','Write']) | |
| forceRefresh | No | Bypass dedup and force a fresh CLI run even if a recent identical request exists | |
| maxBudgetUsd | No | Claude --max-budget-usd: spend cap for this request in USD. | |
| outputFormat | No | Output format (text|json|stream-json). DEFAULT: stream-json — same rationale as claude_request: keeps usage/cache/cost observable for cache_state aggregates. Override to 'text' only when raw stdout is required (loses observability). | stream-json |
| systemPrompt | No | Claude --system-prompt: replace the system prompt entirely. Mutually exclusive with appendSystemPrompt. | |
| correlationId | No | Request trace ID (auto if omitted) | |
| fallbackModel | No | Claude --fallback-model: model name to auto-fallback to when the default model is overloaded (effective only with --print, which the gateway always uses). | |
| idleTimeoutMs | No | Idle timeout in ms (min 30s, max 1h, omit=CLI default). Idle enforcement applies only when outputFormat is stream-json; it is ignored for text/json. | |
| approvalPolicy | No | Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy. | |
| optimizePrompt | No | Optimize prompt before execution | |
| permissionMode | No | Claude --permission-mode: default|acceptEdits|plan|auto|dontAsk|bypassPermissions. `default` is a no-op. | |
| settingSources | No | Claude --setting-sources: comma-separated setting sources to load (user|project|local) for reproducible/isolated headless runs. | |
| continueSession | No | Continue the most recent Claude conversation in this cwd (emits --continue; real CLI continuity). | |
| disallowedTools | No | Disallowed tools | |
| strictMcpConfig | No | Restrict Claude to provided MCP config only | |
| approvalStrategy | No | Approval strategy: legacy (default) lets the provider CLI's own flags decide; mcp_managed routes the run through the gateway approval gate (required for approvalPolicy and approval_list). Under mcp_managed the caller's permissionMode/alwaysApprove may be overridden by the gate. | legacy |
| compressResponse | No | Compress the response display text when collected via llm_job_result (native compressor; default: [compression].enabled). | |
| createNewSession | No | Force new session | |
| systemPromptFile | No | Claude --system-prompt-file: replace the system prompt from a file path (path variant of systemPrompt). | |
| includeHookEvents | No | Claude --include-hook-events: include all hook lifecycle events in the output stream. Only takes effect with outputFormat=stream-json (the default). | |
| appendSystemPrompt | No | Claude --append-system-prompt: append to the existing system prompt. Mutually exclusive with systemPrompt. | |
| replayUserMessages | No | Claude --replay-user-messages: re-emit user messages from stdin back on stdout for acknowledgment. Only works with input-format=stream-json and outputFormat=stream-json (the cacheControl path). | |
| noSessionPersistence | No | Claude --no-session-persistence: do not write this session to disk (ephemeral one-shot runs; mirrors codex --ephemeral). | |
| appendSystemPromptFile | No | Claude --append-system-prompt-file: append a system prompt from a file path (path variant of appendSystemPrompt). | |
| dangerouslySkipPermissions | No | DEPRECATED: prefer `permissionMode: "bypassPermissions"`. Maps to it when `permissionMode` is unset. | |
| excludeDynamicSystemPromptSections | No | Claude --exclude-dynamic-system-prompt-sections: trim dynamic context blocks from the system prompt. |