Health check for the Claude Code CLI binary.

Verifies the claude binary is on PATH, captures its --version output, and reports auth status (whether ~/.claude.json has an OAuth token). Use this as the first call in any orchestration session to validate the environment.

Optional fields: - expected_version (str): if set, returns ok=false on version mismatch

Returns: - claude_path, claude_version, ok, auth_status, notes

Run a single Claude task synchronously (bounded by FastMCP's 600s wrapper cap).

Required: workspace_path, prompt. Common options: model (alias from Settings.claude_model_aliases), fallback_model, permission_mode, options.timeout_s (default 300, max 600), capture_changes.

Estimated cost depends on model and prompt size — check total_cost_usd in the response. Typical ranges: haiku ~$0.02, sonnet ~$0.50, opus ~$1.50.

For tasks that may exceed 600s (architecture, migration, large refactors), use claude_start_task (async) instead. For timeout routing, call the claude_timeout_help prompt first.

Returns: ClaudeRunTaskResponse with result, stdout/stderr, exit_code, timed_out, total_cost_usd, model_usage, and (if capture_changes=true) a unified git diff of workspace changes.

Start a Claude Code CLI task asynchronously (up to 3600s).

Returns immediately with a run_id. The subprocess continues running in the background; use claude_poll_task to monitor and claude_cancel_task to stop. Use this for any task that may exceed 600s (architecture, migration, large multi-file refactors, long-running data agents).

Required: workspace_path, prompt. Optional: model, fallback_model, permission_mode, options.timeout_s (default 300, max 3600 for async), capture_changes.

Concurrent run limit: bounded by Settings.max_concurrent_runs. New calls beyond that limit return MAX_CONCURRENT_RUNS_EXCEEDED.

Poll an asynchronous task.

Two polling modes: - drain=false (default): returns immediately with current state (new messages, stdout/stderr byte counts, elapsed time). Use for tight control loops with explicit backoff. - drain=true: blocks until status is no longer 'running' (fire-and-wait). Note: this is bounded by your MCP client's request timeout, not the async task's timeout_s. For long blocks, prefer async drain with orchestrator-level polling.

Returns: ClaudePollTaskResponse with status (running|done|error|timeout|cancelled), new_messages, stdout_len/stderr_len, elapsed_seconds, and (once terminal) the full result with total_cost_usd, model_usage, and changes.

Cancel a running task.

Two escalation levels: - force=false (default): sends SIGTERM (graceful). The subprocess has ~5s to clean up before the OS escalates. Try this first. - force=true: sends SIGKILL (immediate). Use only if the subprocess doesn't respond to SIGTERM within ~5s.

Returns: ClaudeCancelTaskResponse with canceled (bool) and status ("cancelled" if actively stopped, "already_done" if run finished naturally, "not_found" if run_id is unknown).

List recent runs (active + recently completed).

Returns ClaudeRunSummary entries ordered newest-first, with active claude_start_task runs at the top followed by completed/cancelled/ timed-out runs from the in-memory store (bounded by Settings.max_runs).

Use this for recovery after orchestrator restart: active async runs survive across MCP client restarts and can be polled/cancelled via claude_poll_task and claude_cancel_task using the run_id from this listing.

Initialize the persistence directory and seed the three markdown files.

Idempotent: re-running without force=true is a no-op if files already exist. Creates the directory at the location resolved by Settings.resolve_persistence_base_dir() and writes AGENTS.md, PROJECTS.md, MEMORY.md (unless they already exist).

Optional fields: - force (bool): re-create files even if they exist - seed_templates (bool|None): whether to seed the default templates

Read one of the three persistence files (agents | projects | memory).

Optional fields: - file (str): which file to read (default: memory) - offset (int): start reading from line N (0-indexed) - limit (int|None): max lines to return (None = no limit)

Large files are automatically truncated at Settings.persistence_max_file_bytes; the response includes a truncated flag if this happens.

Append content to one of the persistence files.

Required: file (agents|projects|memory), content. Optional: section_header (str|None) — if provided, the append is placed under a heading; otherwise content is appended at the end of the file.

Safe-mode constraint: in Settings.mode == "safe", updating AGENTS.md requires confirm=true. The same applies to update_persistence.

Do not store secrets, credentials, or full file dumps — keep entries small and high-signal.

Replace or append to a section in one of the persistence files.

Required: file, section_anchor, new_content. Optional: mode (replace|append) — replace the entire section vs append inside it (default replace).

Safe-mode constraint: in Settings.mode == "safe", updating AGENTS.md requires confirm=true. Returns matched=true when the section_anchor was found; matched=false when the anchor was not found and no edit happened (so you can detect typos before silent appending).

Load the persistence files as context for the current session.

Returns head+tail excerpts of each file (head_ratio controlled by Settings.persistence_truncation_head_ratio). Use this at the start of each session to hydrate orchestrator memory before dispatching tasks.

Optional fields: - include (list[str]|None): subset of files to load (agents|projects|memory). None = all three. - max_chars_per_file (int): per-file char cap (default from settings).

Inspect every registered tool's input schema and report robustness.

This is a metadata-only check — no tools are actually invoked.

Args shape: The MCP client MUST pass arguments wrapped in a req object: {"req": {"include": ["claude_health"], "only_show_tolerant": true}} For backwards-compatibility, the server also accepts args={}.