Skip to content

Self-improving AI Employees for everyone

docs(claude-code): update OpenCompany notes in the CLI snapshots

trohitg16670839da74
diff --git a/docs-internal/claude_code_cli_reference.md b/docs-internal/claude_code_cli_reference.md
index ea27ac5a..a5effcf2 100644
--- a/docs-internal/claude_code_cli_reference.md
+++ b/docs-internal/claude_code_cli_reference.md
@@ -187,16 +187,16 @@ Quick cross-reference for the OpenCompany `claude_code_agent` integration:
| `--output-format stream-json` | always | NDJSON event stream consumed by `_pool.py` |
| `--input-format stream-json` | always | prompts are written to the long-lived subprocess over stdin |
| `--verbose` | always | include complete stream-json event detail |
-| `--ide` | always | discover the per-process IDE lockfile used for MCP connectivity |
+| `--ide` | always | matches the VSCode extension's argv; OpenCompany writes no IDE lockfile and sets no `CLAUDE_IDE_LOCK`, so the MCP connection comes only from `--mcp-config` |
| `--model <id>` | always | from `ClaudeTaskSpec.model` / config default |
-| `--permission-mode <mode>` | normally | defaults to `dontAsk` so the explicit allowlist remains authoritative without interactive prompts |
-| `--allowedTools <csv>` | always | connected workflow tools plus OpenCompany MCP infrastructure tools; Claude built-ins are opt-in, except `Skill` when a skill is connected |
+| `--permission-mode <mode>` | normally | defaults to `dontAsk`: a call that is not pre-approved is denied instead of prompting (read-only Bash commands still run) |
+| `--allowedTools <csv>` | always | pre-approves connected workflow tools plus OpenCompany MCP infrastructure tools; Claude built-ins are opt-in, except `Skill` when a skill is connected. Pre-approval only: per the table above it does not restrict which tools the model sees (that is `--tools`, not emitted) |
| `--mcp-config <json>` | when MCP wired | inline JSON with `{mcpServers: {opencompany: {type: http, url, headers, alwaysLoad: true}}}` |
| `--strict-mcp-config` | when MCP wired | blocks user-level `~/.claude.json` MCP entries |
| `--append-system-prompt <text>` | when `system_prompt` is set | append the task prompt to Claude Code's built-in system prompt |
| `--session-id <UUID>` | cold spawn with no continuity flag | host-minted `uuid4` so the session UUID is known before the first event (must be a valid UUID; rejected if already in use) |
-| `--resume <UUID>` | memory-bound runs (`last_session_id` from the memory node) and pooled-process crash or reap recovery | resume by UUID; works from any directory since 2.1.223 |
-| `--continue` | never set by the node | the reference says it skips sessions created non-interactively (`-p` / stream-json), i.e. every session the pool creates; kept on `ClaudeTaskSpec` for explicit callers only |
+| `--resume <UUID>` | memory-bound runs (`last_session_id` from the memory node) and pooled-process crash recovery | resume by UUID; works from any directory since 2.1.223. An idle reap or LRU eviction drops the pool entry and its UUID, so it is not resumed from the pool |
+| `--continue` | not set by the node's continuity logic; emitted when a task sets `continue_session: true` | the reference says it skips sessions created non-interactively (`-p` / stream-json), i.e. every session the pool creates |
| `--effort <level>` | optional per-task override | reasoning effort |
| `--add-dir <path>*` | optional per-task override | grant extra working dirs |
| `--disallowedTools <csv>` | optional per-task override | remove tools from context |
diff --git a/docs-internal/claude_code_env_vars_reference.md b/docs-internal/claude_code_env_vars_reference.md
index c13377f4..94509fbe 100644
--- a/docs-internal/claude_code_env_vars_reference.md
+++ b/docs-internal/claude_code_env_vars_reference.md
@@ -119,7 +119,7 @@ sets or relies on.
| Variable | Purpose |
|---|---|
-| `CLAUDE_CONFIG_DIR` | Override the root config directory. Defaults to `~/.claude/`. **OpenCompany sets this** to `<DATA_DIR>/claude/` (= `~/.opencompany/claude/` by default) so credentials are project-local and isolated from the user's own `~/.claude/` session — see `nodes/agent/claude_code_agent/_oauth.py:OPENCOMPANY_CLAUDE_DIR` (`= data_path("claude")`). This is the directory under which claude's session JSONL lives at `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. The npm-installed CLI binary is separate, in the shared tree at `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`. |
+| `CLAUDE_CONFIG_DIR` | Override the root config directory. Defaults to `~/.claude/`. **OpenCompany sets this** to `<DATA_DIR>/claude/` (= `~/.opencompany/claude/` by default) so credentials are project-local and isolated from the user's own `~/.claude/` session — see `nodes/agent/claude_code_agent/_oauth.py:OPENCOMPANY_CLAUDE_DIR` (`= data_path("claude")`). This is the directory under which claude's session JSONL lives at `<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. The CLI itself is separate: `bun add`ed into the shared tree, with its shim at `<DATA_DIR>/packages/node_modules/.bin/claude` (`claude.exe` on Windows). |
| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Default prefix for auto-generated Remote Control session names. |
## Timeouts
@@ -139,11 +139,20 @@ sets or relies on.
## Env vars OpenCompany explicitly sets on the spawn env
-From [`services/cli_agent/session.py:env()`](../server/services/cli_agent/session.py):
+For Claude, the pooled spawn env is built in `AICliService._run_pooled_turn`
+([`services/cli_agent/service.py`](../server/services/cli_agent/service.py)).
+It starts from the backend's whole `os.environ`, removes nothing, and adds:
| Variable | Set to | Reason |
|---|---|---|
| `PYTHONUNBUFFERED` | `1` | Line-buffered output (we parse stream-json line by line). |
-| `CLAUDE_CONFIG_DIR` | `OPENCOMPANY_CLAUDE_DIR` (claude provider only) | Project-local credential isolation; also where claude writes its session JSONL — load-bearing for the memory bridge (`<key>/projects/<cwd-encoded>/<session_id>.jsonl`). |
-| `<provider.ide_lock_env_var>` | path to per-spawn lockfile | VSCode-style IDE auto-discovery. |
-| `OPENCOMPANY_PARENT_RUN_ID` | `<workflow_id>:<node_id>:<batch_token[:8]>` | Composio-style parent-run-id for MCP correlation. |
+| `CLAUDE_CONFIG_DIR` | `OPENCOMPANY_CLAUDE_DIR` | Project-local credential isolation; also where claude writes its session JSONL — load-bearing for the memory bridge (`<key>/projects/<cwd-encoded>/<session_id>.jsonl`). |
+| `OPENCOMPANY_PARENT_RUN_ID` (and the legacy `MACHINA_PARENT_RUN_ID`) | `<workflow_id>:<session_key>:<batch_token[:8]>` | Composio-style parent-run-id for MCP correlation. |
+
+No IDE-lock variable is set on this path. The generic `AICliSession.env()`
+in [`services/cli_agent/session.py`](../server/services/cli_agent/session.py)
+(not used for Claude) also sets `<provider.ide_lock_env_var>` to the
+lockfile it wrote. Because the whole backend environment is inherited,
+variables from the shell that started the backend (an editor's
+IDE-integration variables, for example) reach the CLI; see
+[claude_code_interactive_mode.md → Known gaps](./claude_code_interactive_mode.md#known-gaps).
diff --git a/docs-internal/claude_code_headless_reference.md b/docs-internal/claude_code_headless_reference.md
index 8925bf11..183fd227 100644
--- a/docs-internal/claude_code_headless_reference.md
+++ b/docs-internal/claude_code_headless_reference.md
@@ -2,12 +2,14 @@
> **Source:** [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless)
> **Fetched:** 2026-05-11
-> **Why this lives in-repo:** OpenCompany spawns `claude -p` via
-> `services/cli_agent/`. The argv flags this doc describes
-> (`--output-format stream-json`, `--include-partial-messages`,
-> `--include-hook-events`, `--max-budget-usd`, `--max-turns`,
-> `--bare`) and the stream-json event schema it documents are
-> load-bearing for our session parser.
+> **Why this lives in-repo:** OpenCompany no longer spawns `claude -p`.
+> `ClaudeSessionPool` runs `claude --output-format stream-json
+> --input-format stream-json --verbose --ide ...` over stdio pipes (see
+> [claude_code_interactive_mode.md](./claude_code_interactive_mode.md)).
+> The stream-json event schema this doc documents is still the contract
+> the pool parses; the print-mode-only flags it describes
+> (`--include-partial-messages`, `--max-budget-usd`, `--max-turns`) are
+> not emitted.
---
@@ -265,27 +267,27 @@ claude -p "Continue that review" --resume "$session_id"
## What OpenCompany reads from this stream
-`services/cli_agent/session.py:_consume_stdout` parses every line of
-`--output-format stream-json` output. The event types we touch:
+The stdout reader started in `ClaudeSessionPool._spawn`
+([`nodes/agent/claude_code_agent/_pool.py`](../server/nodes/agent/claude_code_agent/_pool.py))
+parses every line of `--output-format stream-json` output and hands it to
+`_handle_stream_event`:
| Event | What we do with it |
|---|---|
-| `type: "system"` `subtype: "init"` | Log tools count + mcp_servers list. First evidence the spawn is healthy. |
-| `type: "assistant"` `content: [text]` | Log a 300-char preview as `[CC-Agent stream] assistant.text`. |
-| `type: "assistant"` `content: [tool_use]` | Log tool name + input keys as `assistant->tool_use`. |
-| `type: "tool_use"` (top-level) | Log name + input keys. |
-| `type: "tool_result"` | Log `is_error` + 300-char content preview. |
-| `type: "hook"` | Log hook event name (requires `--include-hook-events`). |
-| `type: "result"` | Final summary — drives `SessionResult` (`session_id`, `total_cost_usd`, `duration_ms`, `num_turns`, `usage`). |
-
-`--include-partial-messages` surfaces deltas to the Terminal panel via
-`broadcast_terminal_log`; we don't aggregate them into messages
-because the `result` event carries the final response anyway.
-
-`--max-budget-usd` is set from `ClaudeTaskSpec.max_budget_usd` (default
-`5.0` USD) so we cap per-task spend.
-
-`--max-turns` is set from `ClaudeTaskSpec.max_turns` (default `10`).
+| any event with `session_id` | Seeds the pooled session's UUID if it is still empty (a `--continue` spawn; otherwise the UUID is known from `--session-id` / `--resume`). |
+| every event | Appended to the turn's event buffer, which `AnthropicClaudeProvider.event_to_session_result` turns into the `SessionResult`. |
+| `type: "result"` | Ends the turn — drives `SessionResult` (`session_id`, `total_cost_usd`, `duration_ms`, `num_turns`, `usage`) and the `claude.session.usage` CloudEvent. |
+| `type: "system"` `subtype: "compact_boundary"` | Forwarded to `CompactionService.record(...)`. |
+
+The per-event log previews (`assistant.text`, tool calls, tool results)
+and Terminal-panel lines are produced only by the generic
+`AICliSession` (`services/cli_agent/session.py`), which Claude no
+longer uses.
+
+`--include-partial-messages`, `--max-budget-usd` and `--max-turns` are
+not emitted: they are print-mode only. `ClaudeTaskSpec` keeps
+`max_budget_usd` and `max_turns` for back-compat, but nothing caps
+per-task spend or turns today.
We do NOT use `--bare` — auto-discovery of hooks/skills/MCP/auto-memory
is what makes the workflow-tool bridge work. CI use cases that want
diff --git a/docs-internal/claude_code_permission_modes_reference.md b/docs-internal/claude_code_permission_modes_reference.md
index e4d83ccd..e8d6b1fe 100644
--- a/docs-internal/claude_code_permission_modes_reference.md
+++ b/docs-internal/claude_code_permission_modes_reference.md
@@ -3,7 +3,8 @@
> **Source:** [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes)
> **Fetched:** 2026-05-11
> **Why this lives in-repo:** OpenCompany's claude_code_agent defaults to
-> `--permission-mode acceptEdits` and exposes the full enum
+> `--permission-mode dontAsk` (`default_permission_mode` in
+> `server/config/ai_cli_providers.json`) and exposes the full enum
> (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`,
> `bypassPermissions`) on `ClaudeTaskSpec.permission_mode`. See
> `services/cli_agent/types.py` and
@@ -283,8 +284,8 @@ Writes to a small set of paths are never auto-approved, in every mode except `by
| Mode | Where | Notes |
|---|---|---|
-| `acceptEdits` | Default on `ClaudeTaskSpec.permission_mode` | Auto-approves file edits + safe filesystem commands inside cwd. cwd is `repo_root` for memory-bound runs (so claude can edit the actual repo) and the per-task worktree otherwise (isolated). |
+| `dontAsk` | Default (`ClaudeTaskSpec.permission_mode` and `default_permission_mode` in `ai_cli_providers.json`) | No prompts. Pre-approval comes from the `--allowedTools` list `interactive_argv` builds; anything else is denied, except read-only Bash commands (see "Allow only pre-approved tools with `dontAsk` mode" above). The other built-ins stay visible to the model. |
+| `acceptEdits` | User-selectable per task | Auto-approves file edits + safe filesystem commands inside cwd. cwd is a git worktree under the workflow workspace (`<workspace>/<node>/wt_session` for bound runs), never the repo root. Prompts for anything else, which hangs a headless run. |
| `plan` | User-selectable per task | When the user wants research without edits. |
| `bypassPermissions` | Available but not default | For sandboxed CI scenarios. Not recommended on a user's real repo. |
-| `dontAsk` | Available but not default | For locked-down CI; agent must have `permissions.allow` rules pre-configured. |
| `auto` | Available but not default | Requires Sonnet 4.6 / Opus 4.6+ and Anthropic API plan; classifier model + token cost overhead. |
diff --git a/docs-internal/claude_code_skills_reference.md b/docs-internal/claude_code_skills_reference.md
index 637acff4..38fc4d44 100644
--- a/docs-internal/claude_code_skills_reference.md
+++ b/docs-internal/claude_code_skills_reference.md
@@ -3,9 +3,10 @@
> **Source:** [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
> **Fetched:** 2026-05-11
> **Why this lives in-repo:** OpenCompany materialises connected skills
-> into `<cwd>/.claude/skills/<name>/SKILL.md` on `_pre_spawn` so claude
-> auto-discovers them — see [`cli_agent_framework.md` → Memory bridge](./cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent)
-> and [`cli_agent_canonical_patterns_rfc.md` §5 R1](./cli_agent_canonical_patterns_rfc.md).
+> into `<workspace_dir>/.claude/skills/<name>/SKILL.md` before the pool
+> spawns claude, and claude finds them through `--add-dir <workspace_dir>`
+> — see [`claude_code_interactive_mode.md` → Tools and skills](./claude_code_interactive_mode.md#tools-and-skills)
+> and [`cli_agent_canonical_patterns_rfc.md` §6 R1](./cli_agent_canonical_patterns_rfc.md).
> This is the spec we materialise against.
---
@@ -229,21 +230,29 @@ To raise the budget, set the `skillListingBudgetFraction` setting (e.g. `0.02` =
## How OpenCompany materialises skills for `claude_code_agent`
-[`services/cli_agent/session.py:_materialise_skills`](../server/services/cli_agent/session.py)
+`materialise_skills` in
+[`nodes/agent/claude_code_agent/_skills.py`](../server/nodes/agent/claude_code_agent/_skills.py)
walks `connected_skill_names` (collected by edge_walker from the
agent's `input-skill` handle) and writes each connected skill to
-`<cwd>/.claude/skills/<name>/SKILL.md`:
+`<workspace_dir>/.claude/skills/<name>/SKILL.md`, where
+`<workspace_dir>` is the workflow's workspace, passed to claude with
+`--add-dir`. `ClaudeSessionPool._spawn` calls it before a cold spawn and
+`_prepare_warm_reuse` calls it on every warm reuse with the previous
+set, so only the difference is written or removed:
- **Filesystem-origin skills:** `shutil.copytree(skill.metadata.path, dest, dirs_exist_ok=True)` — preserves `SKILL.md` + supporting `scripts/`, `references/`, `templates/`, etc.
- **DB-origin user skills:** synthesise the `SKILL.md` from `Skill.metadata` (`name`, `description`, `allowed-tools`, `metadata`) + `Skill.instructions` (the body) using `yaml.safe_dump` for the frontmatter.
-For memory-bound runs (`memory_bound=True`), cwd is `repo_root`, so
-skills land at `<repo_root>/.claude/skills/<name>/`. For non-memory
-runs the cwd is the per-task worktree.
+The cwd is a git worktree under the workspace (`<workspace>/<node>/wt_session`
+for bound runs, one per task otherwise), never the repo root, so
+skills never land in the user's repository.
Per *Live change detection* above, claude picks the skills up
-mid-session without a restart — but our spawn is fresh each task
-anyway, so we don't rely on that.
+mid-session without a restart. The pool relies on that: a warm process
+is reused across runs, and the warm-reuse diff adds or removes skill
+folders under it. (Whether the `Skill` tool itself is pre-approved is
+fixed at spawn; see
+[claude_code_interactive_mode.md → Known gaps](./claude_code_interactive_mode.md#known-gaps).)
`allowed-tools` in OpenCompany-shipped SKILL.md files uses the same
syntax as upstream (`Bash(git diff *) Read` etc.) and is honoured by