claude_request
Destructive
Execute Claude Code CLI requests synchronously, with automatic deferral to pollable async jobs when needed. Accepts plain prompts or cache-aware structured prompt parts for efficiency.
Instructions
Run a Claude Code CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.
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? }. Use for repeated calls that share a stable prefix — `system`/`tools`/`context` are the stable head; `task` is the volatile tail (never marked). Set `cacheControl: { system?: boolean, tools?: boolean, context?: boolean }` to opt into explicit Anthropic prefix caching via `--input-format stream-json` (slice κ). Requires `outputFormat: 'stream-json'` and hard-codes `ttl='1h'` (Anthropic rejects 5m blocks after Claude Code's 1h-marked session-wrap content). Mutually exclusive with `prompt`. The stable prefix hash is logged to the flight recorder for cache_state aggregates. | |
| 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 — the gateway parses NDJSON usage events to extract input/output/cache_read/cache_creation tokens + cost + model, persists them to the flight recorder for cache_state aggregates, and still returns the assistant text. Override to 'text' only when you truly want unparsed stdout (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 (no flag emitted). | |
| 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 via the native compressor (default: [compression].enabled in config.toml, off unless opted in). Skipped for structured output. | |
| createNewSession | No | Force new session | |
| optimizeResponse | No | Optimize response output | |
| 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. |