Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Anthropic Claude Code CLI provider — stream-json over stdio pipes.
Reference implementation for the `AICliProvider` Protocol. OpenCompany
spawns ``claude`` as a plain subprocess with piped stdin/stdout/stderr
(``ClaudeSessionPool``) and speaks the CLI's stream-json protocol: one
``{"type":"user","message":{...}}`` line per turn on stdin, one JSON
event per line on stdout, ending each turn with ``type == "result"``.
No PTY, no on-disk JSONL parsing. See
``docs-internal/claude_code_interactive_mode.md``.
Subprocess: ``claude --output-format stream-json --input-format
stream-json --verbose --ide [--mcp-config ...] [--strict-mcp-config]
--model <m> [--resume <UUID> | --continue | --session-id <UUID>]
[--allowedTools <list>] --permission-mode <mode>
[--append-system-prompt ...] [--effort ...] [--add-dir ...]
[--disallowedTools ...] [--agent ...]``
**Tools + skills are preserved**:
- ``--mcp-config`` registers OpenCompany's FastMCP server; the spawned
`claude` discovers `mcp__opencompany__*` tools via `tools/list`.
- ``--allowedTools`` carries the explicit allowlist (every wired MCP
tool + OpenCompany's MCP infrastructure tools; Claude built-ins only
when a task opts them in, except ``Skill`` when a skill is wired).
- Skills are materialised under ``<workspace_dir>/.claude/skills/``
(discovered through ``--add-dir <workspace_dir>``) by the shared
:func:`nodes.agent.claude_code_agent._skills.materialise_skills`
helper, called from ``ClaudeSessionPool._spawn`` and
``ClaudeSessionPool._prepare_warm_reuse``; ``Skill`` enters
``--allowedTools`` iff at least one skill is wired.
**Permission mode**: ``dontAsk`` (the config default) never shows a
prompt: a call that would prompt is denied instead, unless it matches
``--allowedTools``. Per ``code.claude.com/docs/en/permission-modes``,
read-only Bash commands still run without a matching rule.
``--allowedTools`` pre-approves tools; it does not remove Claude's
other built-ins from the model's context (that is ``--tools`` /
``--disallowedTools``, neither emitted by default), so the model can
still call them and gets a denial.
Session identity: a cold spawn with no continuity flag gets a
host-minted ``--session-id <UUID>`` (``ClaudeSessionPool._spawn``) so the
UUID is known before the first event; memory-bound runs and crash
recovery pass ``--resume <UUID>``. ``--continue`` is kept on the spec
for callers that ask for it, but the CLI resolves it only against
interactive sessions, so the node never sets it.
Not emitted: ``-p`` / ``--print`` (the Agent SDK does not pass it
either), ``--include-partial-messages``, ``--include-hook-events``,
``--max-turns``, ``--max-budget-usd``, ``--fallback-model`` (print-mode
only; the spec keeps the fields for back-compat), and a positional
prompt (the prompt travels over stdin).
Binary + auth: shared with the auth surface via
``._oauth.claude_binary_path()`` — single managed install of the pinned
``package_version`` under ``<DATA_DIR>/packages/`` and
``CLAUDE_CONFIG_DIR`` set on the spawn env so the agent picks up the
same credentials the Login button wrote.
Final event: ``type == "result"`` on stdout carries ``total_cost_usd``,
``duration_ms``, ``num_turns``, ``session_id``, ``usage`` and the
assistant's ``result`` string. It is stdout-only — the on-disk session
JSONL never contains it — so completion is detected from the stream.
"""
from __future__ import annotations
import json
from pathlib import Path
from typing import Any, Dict, List, Optional
from core.logging import get_logger
from services.cli_agent.config import get_provider_config
from ._oauth import claude_binary_path, OPENCOMPANY_CLAUDE_DIR
from services.cli_agent.protocol import CanonicalUsage
from services.cli_agent.types import ClaudeTaskSpec
logger = get_logger(__name__)
NAME = "claude"
class AnthropicClaudeProvider:
"""`AICliProvider` for Anthropic's Claude Code CLI."""
def __init__(self) -> None:
cfg = get_provider_config(NAME)
if cfg is None:
raise RuntimeError(f"Provider config missing for {NAME!r}. Check ai_cli_providers.json.")
self.name = NAME
self.package_name = cfg.package_name
self.binary_name = cfg.binary_name
self.ide_lock_env_var = cfg.ide_lock_env_var
# IDE lockfile dir: ``<CLAUDE_CONFIG_DIR>/ide/`` per claude's own
# resolution rules — there is no separate "lockfile path" knob.
# We set ``CLAUDE_CONFIG_DIR=OPENCOMPANY_CLAUDE_DIR`` on every
# spawn (``AICliService._run_pooled_turn``, ``_oauth.py``), so
# the dir is ``OPENCOMPANY_CLAUDE_DIR/ide``. The pool path writes
# NO lockfile here (MCP connects through ``--mcp-config``); only
# the generic ``AICliSession._pre_spawn``, which claude no longer
# uses, writes one. The attribute stays for the Protocol and for
# the startup stale-lockfile sweep in ``main.py``.
# ``OPENCOMPANY_CLAUDE_DIR`` is imported at module top from
# ``_oauth`` (the source of truth for this plugin's layout).
self.ide_lockfile_dir = OPENCOMPANY_CLAUDE_DIR / "ide"
self._defaults = cfg.defaults
self._supports = cfg.supports
self._login_argv = cfg.login_argv
self._auth_status_argv = cfg.auth_status_argv
# ---- spawn surface ---------------------------------------------------
def binary_path(self) -> Path:
"""Resolve the project-local `claude` binary.
Delegates to ``._oauth.claude_binary_path`` — same
path used by the credentials Login button. Lazy-installs into
``<DATA_DIR>/packages/`` with ``bun add`` on first miss. Raises
``RuntimeError`` if bun is missing or the install fails, and
``FileNotFoundError`` if the binary is still absent afterwards.
"""
return Path(claude_binary_path())
def interactive_argv(
self,
task: Any, # ClaudeTaskSpec
*,
defaults: Dict[str, Any],
mcp_endpoint_url: Optional[str] = None,
mcp_bearer_token: Optional[str] = None,
connected_tool_names: Optional[List[str]] = None,
connected_skill_names: Optional[List[str]] = None,
include_prompt: bool = True,
) -> List[str]:
"""Build the full argv for one ``claude`` invocation, VSCode-style.
Spawned as a regular subprocess with stdio pipes — NOT a PTY.
Matches the invocation Anthropic's own VSCode extension uses
(read from ``$VSCODE_EXT_DIR/anthropic.claude-code-2.1.140-<platform>/extension.js``
line 156):
``claude --output-format stream-json --input-format stream-json
--verbose --ide [task-flags...]``
User prompts arrive over ``proc.stdin`` as newline-delimited JSON
of shape ``{"type":"user","message":{"role":"user","content":...}}``,
not as an argv positional. Events stream back on ``proc.stdout``
and are parsed there by ``ClaudeSessionPool``; the on-disk
session JSONL is not read at runtime (the ``result`` event is
stdout-only).
Critically NOT emitted:
- ``-p`` / ``--print``: the VSCode extension drives the CLI
without it. The expectation that this keeps usage in the
interactive billing bucket (entrypoint ``claude-vscode``,
not ``sdk-cli``) is unverified: nothing here checks the
entrypoint the CLI reports.
- The positional prompt (``-- "<prompt>"``): the prompt
arrives via ``proc.stdin`` in stream-json input mode.
``include_prompt`` is kept for back-compat but ignored.
``mcp_endpoint_url`` + ``mcp_bearer_token`` (if both set) are
emitted as ``--mcp-config <json>`` so the spawned claude
registers OpenCompany's FastMCP server. Tools allowlist
(``--allowedTools``) lists every wired ``mcp__opencompany__*``
plus OpenCompany's MCP infrastructure tools, the built-in
``Skill`` only when a skill is wired, and any built-ins the task's
``allowed_tools`` opts in. Skills are materialised under
``<workspace_dir>/.claude/skills/`` by the pool before spawn.
"""
if not isinstance(task, ClaudeTaskSpec):
raise TypeError("AnthropicClaudeProvider.interactive_argv requires ClaudeTaskSpec, " f"got {type(task).__name__}")
argv: List[str] = [str(self.binary_path())]
# Stream-json I/O — the VSCode extension pattern. Prompts go via
# ``proc.stdin``, events come back on ``proc.stdout``. Verified
# against
# ``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js:156``
# which spawns claude with exactly these four flags. ``--verbose``
# is required so the stream-json output includes the full event
# detail (without it, only the final result line is emitted).
# ``--ide`` is kept to match the extension's invocation, but the
# pool path writes no IDE lockfile and sets no ``CLAUDE_IDE_LOCK``,
# so there is nothing for it to discover: OpenCompany's MCP
# server is registered only through ``--mcp-config`` below.
argv += [
"--output-format",
"stream-json",
"--input-format",
"stream-json",
"--verbose",
"--ide",
]
# MCP server registration — same shape as the prior headless
# path; the Claude Code MCP doc's ``mcp.json`` example. Works
# identically in interactive mode.
if mcp_endpoint_url and mcp_bearer_token:
# `alwaysLoad: true` opts this server out of MCP tool-search
# deferral so all `mcp__opencompany__*` tools enter context at
# session start instead of waiting for a `ToolSearch` call
# the agent often doesn't make
# (https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search).
mcp_payload = json.dumps(
{
"mcpServers": {
"opencompany": {
"type": "http",
"url": mcp_endpoint_url,
"headers": {
"Authorization": f"Bearer {mcp_bearer_token}",
},
"alwaysLoad": True,
}
}
}
)
argv += ["--mcp-config", mcp_payload, "--strict-mcp-config"]
# Model
model = task.model or defaults.get("default_model") or self._defaults.get("default_model", "claude-sonnet-4-6")
argv += ["--model", model]
# Session continuity. Three flags, mutually exclusive, in this
# precedence order:
# - ``resume_session_id`` set → ``--resume <UUID>``. Memory-bound
# runs set it from the memory node's ``last_session_id``
# (``ClaudeCodeAgentNode.execute_op``); the pool splices it in
# when respawning a crashed session (``ClaudeSessionPool.acquire``).
# - ``continue_session=True`` → ``--continue``. Kept only for
# explicit callers; the node never sets it, because the CLI
# resolves ``--continue`` only against interactively created
# sessions and so never finds the ones this pool creates.
# - ``session_id`` set → ``--session-id <UUID>`` (host-minted
# on cold spawn by ``ClaudeSessionPool._spawn`` so the UUID
# is known before the first event; the CLI requires a valid
# UUID and rejects one that is already in use).
# - None of the three → no flag; claude assigns its own UUID,
# reported on ``system/init``.
if task.resume_session_id:
argv += ["--resume", task.resume_session_id]
elif task.continue_session:
argv += ["--continue"]
elif task.session_id:
argv += ["--session-id", task.session_id]
# Allowed tools — pre-approves what the operator wired through
# ``input-tools`` plus OpenCompany's own MCP infrastructure
# tools. Claude's built-in escape hatches (Read, Edit, Bash,
# Glob, Grep, Write, Skill, WebSearch, WebFetch) are intentionally
# NOT pre-approved (they stay in the model's context, since this
# flag does not remove tools; under ``dontAsk`` calling them is
# denied, except read-only Bash commands, which the CLI runs
# anyway): they let the agent invoke
# capabilities the workflow didn't explicitly grant — equivalent
# filesystem / shell / search functionality is wired via the
# ``fileRead`` / ``fileModify`` / ``fsSearch`` / ``shell`` /
# ``browser`` / ``perplexitySearch`` workflow tools. The one
# exception is ``Skill``, added below only when a skill is wired
# (connected skills are also reachable through OpenCompany's
# ``listSkills`` / ``getSkill`` MCP tools).
#
# Callers can opt specific claude built-ins back in per-task
# via ``ClaudeTaskSpec.allowed_tools`` if they really need them
# (the field is honored verbatim; no auto-merge with workflow
# tools — explicit is better than implicit).
allowed_extra = task.allowed_tools or defaults.get(
"default_allowed_tools",
self._defaults.get("default_allowed_tools", ""),
)
allowed_list: List[str] = [t.strip() for t in allowed_extra.split(",") if t.strip()] if allowed_extra else []
if connected_tool_names:
allowed_list += [f"mcp__opencompany__{name}" for name in connected_tool_names]
# Conditionally enable claude's built-in ``Skill`` tool ONLY
# when at least one skill is wired through ``input-skill``.
# ``ClaudeSessionPool`` materialises connected SKILL.md files
# under ``<workspace_dir>/.claude/skills/`` (reached through
# ``--add-dir``) via the shared
# :func:`nodes.agent.claude_code_agent._skills.materialise_skills`
# helper, so the built-in skill loader has something to
# discover. Skills accessed by name (`Skill <name>`) load
# those materialised files. If no skill is wired, ``Skill``
# stays disabled — strict allowlist invariant holds (see
# ``test_no_claude_builtins_in_default_allowlist``).
if connected_skill_names:
allowed_list.append("Skill")
# OpenCompany's own MCP infrastructure tools — needed for the
# agent to discover connected skills, read its workspace, and
# surface intermediate progress. These are OUR tools, not
# claude's, so they stay regardless.
allowed_list += [
"mcp__opencompany__getWorkspaceFiles",
"mcp__opencompany__listSkills",
"mcp__opencompany__getSkill",
"mcp__opencompany__readSkillResource",
"mcp__opencompany__searchSkillResource",
"mcp__opencompany__getCredential",
"mcp__opencompany__broadcastLog",
]
if allowed_list:
argv += ["--allowedTools", ",".join(allowed_list)]
# Permission mode — ``dontAsk`` is the documented mode for
# "only pre-approved tools, no prompts"
# (https://code.claude.com/docs/en/permission-modes): a call that
# would prompt is denied instead, unless ``--allowedTools``
# matches it; read-only Bash commands still run. The prior
# ``bypassPermissions`` default "skips the permission layer
# entirely" — meaning ``--allowedTools`` and
# ``--disallowedTools`` become documentation-only and claude's
# built-in Read / Edit / Bash / Glob / Grep / Write / Skill /
# WebSearch / WebFetch remain invocable even when not in the
# allowlist. ``acceptEdits`` would prompt for non-Edit tools,
# hanging the headless agent. ``dontAsk`` is the middle: no
# prompts, and a denial for anything not pre-approved (apart
# from read-only Bash). Per-task override still honoured.
perm = task.permission_mode or defaults.get(
"default_permission_mode",
self._defaults.get("default_permission_mode", "dontAsk"),
)
if perm:
argv += ["--permission-mode", perm]
# System prompt — appended to Claude Code's built-in system prompt
if task.system_prompt:
argv += ["--append-system-prompt", task.system_prompt]
logger.info(
"[CC-Agent argv] --append-system-prompt (task) " "length=%d preview=%r",
len(task.system_prompt),
task.system_prompt[:200],
)
# Optional per-task overrides (work in interactive mode per
# code.claude.com/docs/en/cli-reference). ``--max-turns``,
# ``--max-budget-usd``, ``--fallback-model`` are ``-p``-only and
# not emitted; the task spec keeps the fields for back-compat
# but they're silently dropped here.
if task.effort:
argv += ["--effort", task.effort]
for path in task.add_dir:
argv += ["--add-dir", path]
if task.disallowed_tools:
argv += ["--disallowedTools", task.disallowed_tools]
if task.agent:
argv += ["--agent", task.agent]
# Prompt arrives via ``proc.stdin`` as stream-json — NOT as
# an argv positional. ``include_prompt`` is kept on the signature
# for back-compat (older callers pass ``include_prompt=False``)
# but is ignored: stream-json input mode and a positional prompt
# would double-send the first turn. Caller writes prompts to
# ``ClaudeSessionPool.send_turn``'s ``proc.stdin`` instead.
_ = include_prompt
return argv
# ---- native auth -----------------------------------------------------
def login_argv(self) -> List[str]:
return list(self._login_argv) or ["claude", "login"]
def auth_status_argv(self) -> Optional[List[str]]:
return list(self._auth_status_argv) if self._auth_status_argv else None
def detect_auth_error(self, stderr: str, exit_code: int) -> bool:
"""True if stderr/exit_code indicate the user isn't logged in."""
if not stderr and exit_code == 0:
return False
markers = (
"Please run 'claude login'",
"Please run `claude login`",
"Not authenticated",
"Authentication required",
"401 Unauthorized",
"Invalid API key",
)
return any(m in stderr for m in markers)
# ---- streaming output parsing ---------------------------------------
def parse_event(self, line: str) -> Optional[Dict[str, Any]]:
line = line.strip()
if not line:
return None
try:
return json.loads(line)
except json.JSONDecodeError:
return None
def is_final_event(self, event: Dict[str, Any]) -> bool:
return event.get("type") == "result"
def event_to_session_result(
self,
events: List[Dict[str, Any]],
stderr: str,
exit_code: int,
) -> Dict[str, Any]:
"""Reconstruct shared result fields from the event stream."""
final = next(
(e for e in reversed(events) if e.get("type") == "result"),
None,
)
# Session ID can come from `system.init` or `result`
session_id: Optional[str] = None
for evt in events:
sid = evt.get("session_id")
if sid:
session_id = sid
break
tool_calls = sum(
1 for evt in events if evt.get("type") == "tool_use" or (evt.get("type") == "assistant" and self._has_tool_use(evt))
)
provider_data: Dict[str, Any] = {}
for evt in events:
if evt.get("type") == "assistant":
msg = evt.get("message") or {}
rd = msg.get("reasoning_details") or msg.get("thinking")
if rd is not None:
provider_data.setdefault("reasoning_details", rd)
break
success = exit_code == 0 and final is not None
error: Optional[str] = None
if exit_code != 0:
error = stderr.strip()[-2000:] or f"claude exited with code {exit_code}"
elif final is None:
error = "no result event received"
response = ""
cost: Optional[float] = None
duration_ms: Optional[int] = None
num_turns: Optional[int] = None
if final:
response = str(final.get("result") or "")
cost = final.get("total_cost_usd")
duration_ms = final.get("duration_ms")
num_turns = final.get("num_turns")
if final.get("subtype") == "error":
success = False
error = error or response or "result event reports error"
# Surface routable extras on ``provider_data`` so downstream
# workflow nodes can read them off ``tasks[i].provider_data.*``.
# ``canonical_usage`` flattens token counts across all models;
# ``modelUsage`` preserves the per-model breakdown (with the
# per-model ``costUSD`` + ``contextWindow`` + ``maxOutputTokens``
# claude itself reports). The minor fields below either drive
# FE diagnostics (``terminal_reason`` / ``api_error_status``)
# or feed cost analytics (``service_tier`` / ``inference_geo``
# land inside the usage block but aren't propagated by
# ``canonical_usage`` because that struct is per-event, not
# per-result).
for key in (
"modelUsage",
"permission_denials",
"terminal_reason",
"fast_mode_state",
"api_error_status",
):
if key in final and final[key] is not None:
provider_data.setdefault(key, final[key])
# Pull the service-tier / cache-creation / inference-geo bits
# off the usage block so downstream consumers don't have to
# re-iterate the events themselves.
usage_block = final.get("usage") or {}
for key in ("service_tier", "inference_geo"):
v = usage_block.get(key)
if v:
provider_data.setdefault(key, v)
cu = self.canonical_usage(events)
return {
"session_id": session_id,
"response": response,
"cost_usd": cost,
"duration_ms": duration_ms,
"num_turns": num_turns,
"tool_calls": tool_calls,
"canonical_usage": cu,
"provider_data": provider_data,
"success": success,
"error": error,
}
def canonical_usage(self, events: List[Dict[str, Any]]) -> CanonicalUsage:
"""Pull token counts from the `result` event's `usage` block.
Anthropic shape:
{
"input_tokens": int,
"output_tokens": int,
"cache_creation_input_tokens": int,
"cache_read_input_tokens": int,
}
"""
final = next(
(e for e in reversed(events) if e.get("type") == "result"),
None,
)
if not final:
return CanonicalUsage()
usage = final.get("usage") or {}
request_count = int(final.get("num_turns") or 0) or sum(1 for e in events if e.get("type") == "assistant")
return CanonicalUsage(
input_tokens=int(usage.get("input_tokens", 0)),
output_tokens=int(usage.get("output_tokens", 0)),
cache_read=int(usage.get("cache_read_input_tokens", 0)),
cache_write=int(usage.get("cache_creation_input_tokens", 0)),
reasoning_tokens=0, # Claude doesn't expose this separately
request_count=request_count,
)
# ---- feature gating --------------------------------------------------
def supports(self, feature: str) -> bool:
return feature in self._supports
# ---- internals -------------------------------------------------------
@staticmethod
def _has_tool_use(event: Dict[str, Any]) -> bool:
msg = event.get("message") or {}
content = msg.get("content")
if isinstance(content, list):
return any(isinstance(blk, dict) and blk.get("type") == "tool_use" for blk in content)
return False