claude_code
Start a background coding session with Claude Code that returns a session ID for asynchronous polling. Use it to run autonomous tasks, handle permission requests, and track progress via subsequent checks.
Instructions
Start a background Claude Code run and return sessionId immediately. No final result is returned here. Main loop: call claude_code_check(action='poll'), store nextCursor, and keep polling until status becomes idle, error, or cancelled. If actions[] contains permission requests, answer them with claude_code_check(action='respond_permission'). respond_user_input is not supported. Adjust polling cadence to progress: poll faster while new events/actions are arriving, and slower when the session is quietly thinking. Long-running work is normal: Claude Code can keep working for 10+ minutes, especially with high/max effort, so wait for polling to settle before assuming it is stuck. If you want to continue after a run pauses or finishes, use claude_code_reply with the same sessionId instead of starting a new claude_code session. For runtime-authoritative tool names, call claude_code_check with pollOptions.includeTools=true.
Internal tools (runtime list when includeTools=true):
[agent]
Task: Spawn subagent (must be in allowedTools)
TaskOutput: Get subagent output
TaskStop: Cancel subagent
TeamDelete: Delete team (may need shutdown_approved first)
TodoWrite: Task/todo checklist
[execute]
Bash: Run shell commands
[file_read]
Glob: Find files by glob pattern
Grep: Search file contents (regex)
Read: Read file contents (large files: use offset/limit or Grep)
[file_write]
Edit: Targeted edits (replace_all is substring-based)
NotebookEdit: Edit Jupyter notebook cells (Windows paths normalized)
Write: Create or overwrite files
[interaction]
AskUserQuestion: Ask user a question
[mcp]
SubscribeMcpResource: Subscribe to an MCP resource stream
SubscribePolling: Subscribe to periodic polling
UnsubscribeMcpResource: Unsubscribe from an MCP resource stream
UnsubscribePolling: Unsubscribe from periodic polling
[network]
WebFetch: Fetch web page or API content
WebSearch: Web search
Permission control: allowedTools pre-approves tools but is not a strict allowlist unless strictAllowedTools=true; disallowedTools always denies; other tools may require approval.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working dir. Default: server cwd | |
| model | No | Default: SDK | |
| effort | No | Effort string: 'low' | 'medium' | 'high' | 'max'. Default: SDK | |
| prompt | Yes | Prompt for a new background run. The final result arrives later via claude_code_check, not this call. Store nextCursor from polls and reuse sessionId with claude_code_reply if you want to continue later. | |
| advanced | No | Default: none | |
| maxTurns | No | Default: SDK | |
| thinking | No | Thinking config object, not a string. Use {type:'adaptive'} | {type:'enabled', budgetTokens?:N} | {type:'disabled'}. Default: SDK | |
| allowedTools | No | Pre-approved tool names. Default: []. This is not a strict allowlist unless strictAllowedTools=true. | |
| systemPrompt | No | System prompt config: string, {type:'preset',preset:'claude_code'}, or {type:'preset',preset:'claude_code',append:'...'}. Default: SDK | |
| disallowedTools | No | Always-denied tool names. Default: [] | |
| strictAllowedTools | No | Default: false. When true, tools outside allowedTools are denied. | |
| permissionRequestTimeoutMs | No | Server permission wait timeout in ms; not forwarded to SDK Options. Default: 60000, clamped to 300000 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| status | Yes | ||
| sessionId | Yes | ||
| resumeToken | No | ||
| pollInterval | No | ||
| compatWarnings | No |