claude_request
Destructive
Run Claude Code CLI requests synchronously, auto-deferring to pollable async jobs when the sync deadline is exceeded. Start by providing a prompt or structured prompt parts.
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). Under mcp_managed, this repository-rule suppression requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| 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. Under mcp_managed, non-empty addDir requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. 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. Under mcp_managed, this repository-rule suppression requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| 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, reuse requires same-host ownership metadata and a matching live Git registration. Named path collisions never reuse manager state. Gateway-managed worktrees require the local file-backed session manager and fail closed with PostgreSQL sessions. The Grok, Devin, and Mistral adapters require an explicit provider-native sessionId; fresh, createNewSession, and resumeLatest-only worktree requests fail closed because they cannot durably reselect the worktree. The request must select a registered workspace explicitly, through caller-owned session metadata, or through the configured default. Worktrees never fall back to the gateway process cwd and cannot be combined with local workingDir, addDir, or includeDirs paths. The gateway spawns the child CLI with `cwd: <worktree-path>`; no `-w`/`--worktree` flag is ever emitted to the underlying CLI. On worktree materialization, the gateway suppresses repository, system, and global Git hooks and configured clean, smudge, and process checkout filters, sparse checkout, and lazy object fetching. Filter-dependent content such as Git LFS remains in its repository representation instead of executing host commands. On session_delete or TTL eviction the gateway hides the session and runs `git worktree remove --force`. Failed removal retains a durable cleanup-pending tombstone which blocks reuse and is retried when the file store is registered on the owning host. The tombstone is finalized only after verified Git removal. Successful responses are prefixed with `[gateway] worktree=<absolute-path>\n` so callers can use the path. For Claude approvalStrategy:mcp_managed, requesting or reusing a worktree requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. Other adapters reject mcp_managed before launch. 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 | |
| workingDir | No | Claude process working directory. The gateway launches Claude in this directory. 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. | |
| 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. Under mcp_managed, an override requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| 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. | |
| providerFlags | No | Flags passed to the provider binary verbatim, keyed exactly as the binary spells them (e.g. {"--best-of-n": "3", "--verbatim": true, "--rules": ["a", "b"]}). Use this for any flag your installed CLI accepts that this schema does not name: the binary decides what it supports, not the gateway. true emits the flag alone; a list REPEATS the flag once per item (pass a joined string if your CLI wants a comma-separated value). Values may not start with '-', and a flag the gateway is already emitting for this request is refused rather than duplicated. LOCAL stdio callers only: remote HTTP/OAuth callers are refused every flag here and should use this tool's declared parameters, which carry their own host-path and approval gates. | |
| 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|auto|bypassPermissions|manual|dontAsk|plan. `default` is a no-op (no flag emitted). Under mcp_managed, bypassPermissions requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| 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 the selected workspace (emits --continue; real CLI continuity). Stable workspace selection is required via workingDir, a registered workspace, or the configured default workspace. | |
| disallowedTools | No | Disallowed tools | |
| strictMcpConfig | No | Restrict Claude to provided MCP config only. mcp_managed always enforces this isolation, even when false is supplied. | |
| approvalStrategy | No | Approval strategy: legacy (default) lets Claude's own flags decide; mcp_managed routes the run through the gateway approval gate and uses acceptEdits by default. An explicit bypassPermissions request requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | 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. Under mcp_managed, an override requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| 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). | |
| requestInstructions | No | Per-request Kit instructions. Available only when [personal_config].enabled = true. | |
| 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. Under mcp_managed, either form requires approval and LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1. | |
| excludeDynamicSystemPromptSections | No | Claude --exclude-dynamic-system-prompt-sections: trim dynamic context blocks from the system prompt. |