Skip to content

Self-improving AI Employees for everyone

fix(cli_agent): plug pooled-claude tool-surface leak + tighten allowlist

trohitg42e2eb742f28
diff --git a/CLAUDE.md b/CLAUDE.md
index 47c68f25..6d95d819 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3499,10 +3499,15 @@ When `simpleMemory` is connected to `claude_code_agent`, memory continuity is ha
**Stale-model coercion.** `ClaudeCodeAgentParams.model` is a `Literal` of supported model IDs + aliases — strict validation would reject legacy saved values like `"claude-sonnet-4.6"` (dot-spelled), `"claude-3-5-sonnet-20241022"` (date-suffixed), `""`. A `field_validator("model", "fallback_model", mode="before")` coerces unknown values to the default (`"claude-sonnet-4-6"` for `model`, `None` for `fallback_model`) so old workflows keep loading; the UI dropdown still constrains new edits.
+**Strict tool allowlist — no claude built-ins, gated by `--permission-mode dontAsk`.** The spawn argv emits `--permission-mode dontAsk` (documented as *"only pre-approved tools, no prompts"* per [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes)) so `--allowedTools` is actually enforced. The previous default `bypassPermissions` *"skips the permission layer entirely"* — same doc — which turned the allowlist into documentation-only and let claude's built-in `Read` / `Edit` / `Bash` / `Glob` / `Grep` / `Write` / `Skill` / `WebSearch` / `WebFetch` fire regardless of wiring. The new `--allowedTools` list contains exactly: (a) one `mcp__machinaos__<node_type>` per node wired through the agent's `input-tools` handle, (b) the five MachinaOs MCP infrastructure tools (`getWorkspaceFiles`, `listSkills`, `getSkill`, `getCredential`, `broadcastLog`). Every filesystem / shell / web operation flows through wired MCP tools (`fileRead` / `fileModify` / `fsSearch` / `shell` / `browser` / `perplexitySearch`) — explicit wiring, no built-in escape hatches. Defaults live in [`server/config/ai_cli_providers.json`](./server/config/ai_cli_providers.json) (`default_allowed_tools: ""`, `default_permission_mode: "dontAsk"`); per-task override via `ClaudeTaskSpec.allowed_tools` is honored verbatim (no auto-merge).
+
+**Warm-subprocess tool-surface rebind — no respawn cost.** Claude bakes the MCP bearer token into argv (`--mcp-config`) at spawn time and can't rotate without respawning. The pool stashes the spawn-time token on `PooledClaudeSession.batch_token` so subsequent batches can rebind the same persistent `BatchContext` in place. On warm reuse, `ClaudeSessionPool.acquire` calls [`rebind_batch(existing.batch_token, connected_tools=new_ctx.connected_tools, ...)`](./server/services/cli_agent/mcp_server.py) — diffs old vs new tool lists, calls `unexpose_workflow_tools(removed)` to decrement FastMCP refcounts (so a disconnected `duckduckgoSearch` falls off the tool list when its refcount hits zero), `expose_workflow_tools(added)` for newly-wired ones, then unregisters the redundant new token. `_terminate_locked` calls `unregister_batch(session.batch_token)` so refcounts drain on pool eviction / `clear` / `shutdown_all` (closes the long-standing leak where every pooled run permanently incremented every wired tool's refcount). The per-handler scope check in `workflow_tools._build_handler` reads `ctx.connected_tools` at call time, so even if claude's frozen `--allowedTools` argv still references a now-disconnected tool, the handler returns `{"error": "...not connected to this batch", "status": 403}` — double-lock against tool leakage across warm-reuse turns.
+
**Logs to grep on a live run:**
- `[Claude Code memory] memory_node=<id> -> --continue (claude auto-finds latest session under cwd)`
- `[ClaudeSessionPool] spawned new session memory_node=<id> pid=<N>` (cold spawn) or `warm reuse memory_node=<id> pid=<N> uuid=<UUID>` (intra-process turn)
- `[CC-Agent _persist_memory] saved memory_node=<id> last_session_id=<UUID> appended_turns=1 ... content_length=<N>`
+- On tool-surface change between batches: `[CC-Agent MCP rebind_batch] node=<id> wf=<id> token=<8hex>... +<added> -<removed> kept=<n> (now <total> tools)` — confirms the in-place rebind ran instead of a respawn.
- On crash recovery: `[ClaudeSessionPool] dropping dead session memory_node=<id> ... — will respawn` followed by spawn with `--resume <UUID>` argv.
## Memory Compaction, Token Tracking, and Cost Calculation
diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsx
index 5c820e0a..b2f941a3 100644
--- a/client/src/contexts/WebSocketContext.tsx
+++ b/client/src/contexts/WebSocketContext.tsx
@@ -249,7 +249,6 @@ export interface WhatsAppMessage {
export interface NodeParameters {
parameters: Record<string, any>;
version: number;
- timestamp?: number;
}
// Per-session compaction/token usage stats (pushed by backend broadcasts)
@@ -923,18 +922,40 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
}
break;
- // Node parameters broadcasts (from other clients)
- case 'node_parameters_updated':
- if (node_id) {
- const nextParams = {
- parameters: message.parameters,
- version: message.version,
- timestamp: message.timestamp,
+ // CloudEvents v1.0 envelope from `broadcaster.broadcast_node_parameters_updated`.
+ // Wire shape (RFC §6.4 — same convention as `agent_progress` above):
+ // { type: "node_parameters_updated",
+ // data: { specversion, id, time, source, type,
+ // subject: <node_id>, workflow_id?,
+ // data: { node_id, parameters, version, source } } }
+ // Snake-case keys preserved across the Python → JSON → TS wire so
+ // the FE reads them by their Python field names directly. The
+ // pre-CloudEvent handler read `message.parameters` / `message.node_id`
+ // from the top level — both `undefined` post-cutover — so every
+ // broadcast was silently dropped and the simpleMemory panel only
+ // refreshed after a full page reload. Three emission sites today:
+ // user param-save (source="user"), Claude Code memory bridge
+ // (source="cli"), Temporal AgentWorkflow per-turn persist
+ // (source="agent").
+ case 'node_parameters_updated': {
+ const envelope = data as WorkflowEvent<{
+ node_id?: string;
+ parameters?: Record<string, any>;
+ version?: number;
+ source?: string;
+ }> | undefined;
+ const inner = envelope?.data;
+ const target_node_id = inner?.node_id || envelope?.subject;
+ if (target_node_id && inner?.parameters !== undefined) {
+ const next_params: NodeParameters = {
+ parameters: inner.parameters,
+ version: inner.version ?? 1,
};
- setNodeParameters(prev => ({ ...prev, [node_id]: nextParams }));
- queryClient.setQueryData(nodeParamsQueryKey(node_id), nextParams);
+ setNodeParameters(prev => ({ ...prev, [target_node_id]: next_params }));
+ queryClient.setQueryData(nodeParamsQueryKey(target_node_id), next_params);
}
break;
+ }
case 'node_parameters_deleted':
if (node_id) {
@@ -1931,7 +1952,6 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
const params: NodeParameters = {
parameters: response.parameters,
version: response.version || 0,
- timestamp: response.timestamp
};
// Update local cache
setNodeParameters(prev => ({ ...prev, [nodeId]: params }));
@@ -1955,7 +1975,6 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
result[nodeId] = {
parameters: data.parameters || {},
version: data.version || 0,
- timestamp: response.timestamp
};
}
// Update local cache with all parameters
diff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.md
index a06e1268..62fcf7bd 100644
--- a/docs-internal/claude_code_interactive_mode.md
+++ b/docs-internal/claude_code_interactive_mode.md
@@ -71,8 +71,8 @@ claude
[--mcp-config <json> --strict-mcp-config]
--model <name>
[--resume <UUID> | --continue]
- [--allowedTools <csv>]
- --permission-mode bypassPermissions
+ --allowedTools <csv>
+ --permission-mode dontAsk
[--append-system-prompt <text>]
[--effort low|medium|high]
[--add-dir <path>]...
@@ -89,10 +89,21 @@ Notable absences (intentional):
| `--session-id <UUID>` | Rejected by claude in non-headless mode. We discover the UUID from the first event that carries `session_id`. |
| `--include-partial-messages`, `--include-hook-events`, `--max-turns`, `--max-budget-usd`, `--fallback-model` | All `-p`-only. `ClaudeTaskSpec` keeps the fields for back-compat; they're silently dropped here. External cost / turn caps are a Phase 2 follow-up. |
-`--permission-mode bypassPermissions` is required for non-interactive
-automation — there's no human at the keyboard to approve the per-tool
-prompts `acceptEdits` would surface. Documented at
+`--permission-mode dontAsk` is the documented mode for *"only
+pre-approved tools, no prompts"* per
[`code.claude.com/docs/en/permission-modes`](https://code.claude.com/docs/en/permission-modes).
+It gates `--allowedTools` strictly — anything not in the allowlist
+returns a permission denial without surfacing a TUI prompt
+(non-interactive automation has no human at the keyboard to click
+"Allow"). The earlier `bypassPermissions` default *"skips the
+permission layer entirely"* (same doc, §"Skip all checks"), which
+turned `--allowedTools` / `--disallowedTools` into documentation-only
+fields and let claude's built-in `Read` / `Edit` / `Bash` /
+`Glob` / `Grep` / `Write` / `Skill` / `WebSearch` / `WebFetch` fire
+regardless of wiring. `acceptEdits` was the prior config default but
+would prompt for any non-Edit tool — hanging the headless agent.
+`dontAsk` is the only mode that combines no-prompts with a strict
+allowlist gate.
## Session pool — warm-process reuse
@@ -173,13 +184,50 @@ ferried UUID).
`claude` handles its own MCP authentication. We embed the bearer in
`--mcp-config` at spawn time; the spawned claude uses it for the
-lifetime of its process. The pool stashes the token on
-`PooledClaudeSession.bearer_token` at spawn time so warm-reuse callers
-(`AICliService.run_batch`'s pool path) can re-register the batch
-context against the SAME token claude already has in its argv. The pool
-itself never issues / unregisters — that's `run_batch`'s job, with the
-twist that for pooled sessions the token persists across batches and
-orphans on pool eviction (bounded by `max_size`, acceptable for Phase 1).
+lifetime of its process — the JSON blob (token included) is frozen
+into argv and can never be rotated without respawning. The pool
+stashes the spawn-time token on
+[`PooledClaudeSession.batch_token`](../server/services/cli_agent/session_pool.py)
+so subsequent batches can find and update its bound `BatchContext`.
+
+Token lifecycle, three phases:
+
+1. **Cold spawn.** `AICliService.run_batch` issues a fresh token T,
+ calls `register_batch(T, ctx)` (which adds T to `_active_tokens`
+ and bumps FastMCP refcounts for each `ctx.connected_tools` entry
+ via `expose_workflow_tools`), then passes T to `pool.acquire`. The
+ pool spawns claude with T baked into `--mcp-config` argv and
+ records `session.batch_token = T`.
+2. **Warm reuse with a changed surface.** A subsequent batch issues
+ a NEW token T_new and registers `ctx_new` against it. Pool
+ `acquire` detects warm reuse and calls
+ [`rebind_batch`](../server/services/cli_agent/mcp_server.py)
+ on T (the persistent token claude bakes into MCP requests),
+ transplanting `ctx_new`'s `connected_tools` /
+ `connected_skill_names` / `allowed_credentials` /
+ `workspace_dir` onto T's `BatchContext` in place. The diff is
+ applied to FastMCP — `unexpose_workflow_tools` decrements
+ refcounts for tools dropped between batches (so a disconnected
+ `duckduckgoSearch` falls off the FastMCP tool list when its
+ refcount hits zero), `expose_workflow_tools` increments for
+ added tools. T_new is then immediately unregistered (it would
+ sit orphaned otherwise — claude's argv never references it).
+3. **Termination.** `_terminate_locked` calls `unregister_batch(T)`
+ so the dying subprocess's FastMCP refcounts drain cleanly on
+ pool eviction / `pool.clear` / `shutdown_all`. Closes the
+ long-standing leak where every pooled run permanently incremented
+ the refcount of every wired tool.
+
+The per-handler scope check in
+[`workflow_tools._build_handler`](../server/services/cli_agent/workflow_tools.py)
+reads `ctx.connected_tools` at call time — so even if claude's
+frozen `--allowedTools` argv still lists a tool that's since been
+disconnected, the handler returns
+`{"error": "...not connected to this batch", "status": 403}`.
+Combined with `--permission-mode dontAsk` (strict allowlist gate on
+the claude side) this gives a double-lock: the tool surface visible
+to claude is what the batch wired, no more no less, even across
+warm-reuse turns.
## CloudEvents broadcasts
@@ -204,16 +252,36 @@ store that renders the panel.
## Tools and skills
-**Tools (MCP) — unchanged from the `-p` era.** Spawn argv carries
-`--mcp-config <json>` (HTTP transport, bearer header) + `--strict-mcp-config`
-so the spawned claude only loads MachinaOs's FastMCP server. The
-`mcpServers.machinaos` block sets `alwaysLoad: true` to opt out of MCP
-tool-search deferral so all `mcp__machinaos__*` tools enter context at
-session start. `--allowedTools` lists the explicit allowlist:
-five built-ins (`Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch`),
-every `mcp__machinaos__<connected_tool>` passed by the caller, plus the
-five core MCP tools (`getWorkspaceFiles`, `listSkills`, `getSkill`,
-`getCredential`, `broadcastLog`).
+**Tools (MCP) — strict allowlist, no claude built-ins.** Spawn argv
+carries `--mcp-config <json>` (HTTP transport, bearer header) +
+`--strict-mcp-config` so the spawned claude only loads MachinaOs's
+FastMCP server. The `mcpServers.machinaos` block sets `alwaysLoad:
+true` to opt out of MCP tool-search deferral so all
+`mcp__machinaos__*` tools enter context at session start.
+`--allowedTools` is the explicit allowlist, and it does NOT include
+claude's built-in escape hatches (`Read`, `Edit`, `Bash`, `Glob`,
+`Grep`, `Write`, `Skill`, `WebSearch`, `WebFetch`) — every workflow
+already wires the equivalents (`fileRead`, `fileModify`, `fsSearch`,
+`shell`, `browser`, `perplexitySearch`, …) as MCP tools, and the
+built-ins were the leakage path that let the agent invoke
+capabilities the workflow didn't explicitly grant. The default
+allowlist is:
+
+- `mcp__machinaos__<node_type>` per node connected to the agent's
+ `input-tools` handle (LLM sees their typed Pydantic schemas via
+ FastMCP's `tools/list` reflection on the plugin `Params`).
+- The five MachinaOs MCP infrastructure tools — `getWorkspaceFiles`,
+ `listSkills`, `getSkill`, `getCredential`, `broadcastLog` — which
+ are how the agent reads its workspace, discovers connected skills,
+ fetches scoped credentials, and surfaces intermediate progress to
+ the FE.
+
+Callers wanting specific claude built-ins back in opt in per-task via
+`ClaudeTaskSpec.allowed_tools` (the field is honored verbatim — no
+auto-merge with workflow tools). Default value: empty string.
+Combined with `--permission-mode dontAsk`, the strict allowlist is
+actually enforced (see "argv shape" above for why `bypassPermissions`
+was the wrong default).
**Skills — known gap on the pool path.** `AICliSession._materialise_skills`
writes connected skills under `<cwd>/.claude/skills/` for the one-shot
@@ -222,6 +290,27 @@ discover skills via MCP `listSkills` / `getSkill` tools at runtime
instead. Fine for now, but pool-side skill materialisation is an open
follow-up.
+**Workspace dir — routed via `--add-dir`.**
+[`AICliService.run_batch`](../server/services/cli_agent/service.py)
+splices the per-workflow workspace
+(`data/workspaces/<workflow_id>/`, injected into `ctx.raw` by
+`workflow.py:_get_workspace_dir`) into each task's `add_dir` list
+right after `task_list` is built — `interactive_argv` already emits
+`--add-dir <path>` per entry. Runs BEFORE the pool/non-pool branch
+split so both warm-subprocess and one-shot paths get it. Without
+this, the workspace is invisible to claude: memory-bound runs spawn
+with `cwd=repo_root` (stable for `--continue`'s `project_key`
+resolution) and non-memory runs with `cwd=worktree`, neither of which
+sees files dropped by upstream nodes (`fileDownloader`,
+`documentParser`, code executors, etc.). Mirrors the ai_agent
+pattern ([`services/ai.py:1899`](../server/services/ai.py) —
+`config['workspace_dir'] = context.get('workspace_dir', '')`) but
+uses claude's native `--add-dir` instead of MCP-tool-config injection
+because claude has its own filesystem tools (`Read`, `Edit`, `Glob`,
+`Grep`, `Write`, `Bash`) rather than MCP-injected ones. Verified
+end-to-end: a marker file dropped into a workspace is reachable via
+claude's `Read` tool inside a pooled turn.
+
## `/usage` and `/compact` semantics
- **`/usage`** — TUI-only plain text per Anthropic. Not parseable. We
diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.md
index 9df9e02e..a427241f 100644
--- a/docs-internal/cli_agent_framework.md
+++ b/docs-internal/cli_agent_framework.md
@@ -166,9 +166,9 @@ class ClaudeTaskSpec(BaseAICliTaskSpec):
resume_session_id: Optional[str] = None
max_turns: Optional[int] = None
max_budget_usd: Optional[float] = None
- allowed_tools: Optional[str] = None
+ allowed_tools: Optional[str] = None # default: "" — see "Strict allowlist"
permission_mode: Literal["default", "acceptEdits", "plan", "auto",
- "dontAsk", "bypassPermissions"] = "acceptEdits"
+ "dontAsk", "bypassPermissions"] = "dontAsk"
# Optional documented CLI flags
effort: Optional[Literal["low", "medium", "high", "xhigh", "max"]] = None
fallback_model: Optional[str] = None
@@ -247,7 +247,7 @@ Lockfile path: `~/.claude/ide/<pid>.lock` (Claude) or `<tmpdir>/gemini/ide/gemin
}
```
-Bearer-token middleware (`mcp_server.py:_BearerAuthMiddleware`) validates each request against an in-memory per-batch `BatchContext` registry. Tokens registered at `AICliService.run_batch()` entry; unregistered in `finally` so 401s flip immediately when a batch settles.
+Bearer-token middleware (`mcp_server.py:_BearerAuthMiddleware`) validates each request against an in-memory per-batch `BatchContext` registry. **Non-pool path**: tokens registered at `AICliService.run_batch()` entry, unregistered in `finally` so 401s flip immediately when a batch settles. **Pool path** (`use_pool=True`, see [Claude Code Interactive Mode](./claude_code_interactive_mode.md#mcp-bearer-token-lifecycle) for the full lifecycle): claude bakes the bearer into argv (`--mcp-config`) at spawn time and can't rotate without respawning, so the pool stashes the spawn-time token on `PooledClaudeSession.batch_token` and rebinds the `BatchContext` in place on warm reuse via `rebind_batch(token, connected_tools=..., ...)` — closes the "disconnected tool still works" leak by (a) diffing `connected_tools` and decrementing FastMCP refcounts for tools dropped between batches, and (b) updating the per-handler scope check's data so `workflow_tools._build_handler` returns 403 for stale tools. `_terminate_locked` calls `unregister_batch(session.batch_token)` so refcounts drain on pool eviction / `clear` / `shutdown_all`.
Tools exposed (mirror MachinaOs capabilities; deferred ones marked):
@@ -410,8 +410,26 @@ ClaudeCodeAgentNode.execute_op
├─ appends user/assistant turns to params["memory_content"]
│ via append_to_memory_markdown + trim_markdown_window
├─ database.save_node_parameters(memory_node_id, params)
- └─ broadcaster.broadcast({"type": "node_parameters_updated",
- "node_id": memory_node_id, ...})
+ └─ broadcaster.broadcast_node_parameters_updated(
+ memory_node_id,
+ parameters=params,
+ source_hint="cli",
+ )
+ # Emits a CloudEvents v1.0 envelope (RFC §6.4):
+ # { type: "node_parameters_updated",
+ # data: { specversion, id, time,
+ # source: "machinaos://services/parameters",
+ # type: "com.machinaos.node.parameters.updated",
+ # subject: <memory_node_id>,
+ # workflow_id?,
+ # data: { node_id, parameters, version, source } } }
+ # The FE handler in `client/src/contexts/WebSocketContext.tsx`
+ # casts ``data`` to ``WorkflowEvent<{node_id, parameters,
+ # version, source}>`` and routes the inner payload to
+ # ``setNodeParameters`` + ``queryClient.setQueryData``,
+ # so the simpleMemory parameter panel auto-refreshes
+ # live (no page reload needed). Snake-case wire keys
+ # preserved (``node_id``, not ``nodeId``).
```
### Parallel-batch guard
diff --git a/server/config/ai_cli_providers.json b/server/config/ai_cli_providers.json
index 969385a6..7763f8b9 100644
--- a/server/config/ai_cli_providers.json
+++ b/server/config/ai_cli_providers.json
@@ -9,8 +9,8 @@
"default_model": "claude-sonnet-4-6",
"default_max_turns": 10,
"default_max_budget_usd": 5.0,
- "default_allowed_tools": "Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch",
- "default_permission_mode": "acceptEdits",
+ "default_allowed_tools": "",
+ "default_permission_mode": "dontAsk",
"supports": [
"max_budget",
"max_turns",
diff --git a/server/services/cli_agent/mcp_server.py b/server/services/cli_agent/mcp_server.py
index 85d43b0e..704f3f60 100644
--- a/server/services/cli_agent/mcp_server.py
+++ b/server/services/cli_agent/mcp_server.py
@@ -118,6 +118,75 @@ def lookup_batch(token: str) -> Optional[BatchContext]:
return _active_tokens.get(token)
+def rebind_batch(
+ token: str,
+ *,
+ connected_tools: Optional[List[Dict[str, Any]]] = None,
+ connected_skill_names: Optional[Set[str]] = None,
+ allowed_credentials: Optional[Set[str]] = None,
+ workspace_dir: Optional[Path] = None,
+) -> Optional[BatchContext]:
+ """In-place rebind of an existing batch's surface.
+
+ Used by :class:`ClaudeSessionPool` on warm-subprocess reuse:
+ claude bakes the bearer token into its argv at spawn time (via
+ ``--mcp-config``), so a warm subprocess keeps hitting the SAME
+ token across batches. If the operator disconnects a tool between
+ batches, the bearer-token's :class:`BatchContext` must be updated
+ in place — otherwise the per-handler scope check in
+ ``workflow_tools._build_handler`` still sees the stale
+ ``connected_tools`` and lets disconnected tools fire.
+
+ For ``connected_tools``: refcount diff is applied to FastMCP — any
+ node_type that's in the OLD list but not the new gets one
+ :func:`unexpose_workflow_tools` decrement (may remove the tool
+ from FastMCP when its refcount hits zero); any node_type that's
+ new gets one :func:`expose_workflow_tools` increment. Tools that
+ survive in both lists are left alone but their ``parameters`` /
+ ``label`` fields are refreshed via the in-place list assignment.
+
+ Returns the rebound context, or ``None`` if the token is unknown.
+ """
+ ctx = _active_tokens.get(token)
+ if ctx is None:
+ return None
+ if connected_tools is not None:
+ from services.cli_agent.workflow_tools import (
+ expose_workflow_tools,
+ unexpose_workflow_tools,
+ )
+ old_by_type = {
+ t.get("node_type"): t for t in ctx.connected_tools
+ if t.get("node_type")
+ }
+ new_by_type = {
+ t.get("node_type"): t for t in connected_tools
+ if t.get("node_type")
+ }
+ added = [v for k, v in new_by_type.items() if k not in old_by_type]
+ removed = [v for k, v in old_by_type.items() if k not in new_by_type]
+ if removed:
+ unexpose_workflow_tools(removed)
+ if added:
+ expose_workflow_tools(added)
+ ctx.connected_tools = list(connected_tools)
+ logger.info(
+ "[CC-Agent MCP rebind_batch] node=%s wf=%s token=%s... "
+ "+%d -%d kept=%d (now %d tools)",
+ ctx.node_id, ctx.workflow_id, token[:8],
+ len(added), len(removed),
+ len(old_by_type.keys() & new_by_type.keys()),
+ len(ctx.connected_tools),
+ )
+ if connected_skill_names is not None:
+ ctx.connected_skill_names = set(connected_skill_names)
+ if allowed_credentials is not None:
+ ctx.allowed_credentials = set(allowed_credentials)
+ if workspace_dir is not None:
+ ctx.workspace_dir = Path(workspace_dir).resolve()
+ return ctx
+
+
def active_batch_count() -> int:
return len(_active_tokens)
diff --git a/server/services/cli_agent/providers/anthropic_claude.py b/server/services/cli_agent/providers/anthropic_claude.py
index c8c668d9..2e3755ef 100644
--- a/server/services/cli_agent/providers/anthropic_claude.py
+++ b/server/services/cli_agent/providers/anthropic_claude.py
@@ -220,34 +220,40 @@ class AnthropicClaudeProvider:
elif task.continue_session:
argv += ["--continue"]
- # Allowed tools — built-in defaults plus every workflow tool we
- # exposed via the per-batch FastMCP bridge. Same shape as the
- # prior headless argv. With ``--permission-mode bypassPermissions``
- # (below) the allowlist becomes documentation-of-intent rather
- # than an active gate, but we keep it explicit so the surface is
- # auditable. Default fallback:
- # - Read,Edit,Bash,Glob,Grep,Write — filesystem + shell escape hatches
- # - Skill — invoke materialised `.claude/skills/<name>/SKILL.md`
- # - WebSearch,WebFetch — escape hatches when no MCP tool matches
- # `ToolSearch` is intentionally NOT here: it's permission-free per
- # https://code.claude.com/docs/en/tools-reference#built-in-tools.
- allowed = task.allowed_tools or defaults.get(
+ # Allowed tools — STRICTLY scoped to what the operator wired
+ # through ``input-tools`` plus MachinaOs's own MCP infrastructure
+ # tools. Claude's built-in escape hatches (Read, Edit, Bash,
+ # Glob, Grep, Write, Skill, WebSearch, WebFetch) are intentionally
+ # NOT in the default allowlist: 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, and
+ # connected skills are surfaced via MachinaOs's own
+ # ``listSkills`` / ``getSkill`` MCP tools (no materialisation
+ # under ``.claude/skills/`` on the pool path, so the built-in
+ # ``Skill`` tool has nothing to load anyway).
+ #
+ # 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",
- "Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch",
- ),
+ self._defaults.get("default_allowed_tools", ""),
)
allowed_list: List[str] = (
- [t.strip() for t in allowed.split(",") if t.strip()]
- if allowed else []
+ [t.strip() for t in allowed_extra.split(",") if t.strip()]
+ if allowed_extra else []
)
if connected_tool_names:
allowed_list += [
f"mcp__machinaos__{name}" for name in connected_tool_names
]
- # Always permit MachinaOs's built-in MCP tools so the agent can
- # discover skills + read workspace files without prompting.
+ # MachinaOs'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__machinaos__getWorkspaceFiles",
"mcp__machinaos__listSkills",
@@ -258,18 +264,22 @@ class AnthropicClaudeProvider:
if allowed_list:
argv += ["--allowedTools", ",".join(allowed_list)]
- # Permission mode — ``bypassPermissions`` for non-interactive
- # automation. ``acceptEdits`` (the prior default) auto-permits
- # Edit-class tools but prompts for everything else, which would
- # hang the PTY since no human is present to approve.
- # ``bypassPermissions`` is one of the documented permission
- # modes (https://code.claude.com/docs/en/permission-modes) —
- # behaviourally equivalent to ``--dangerously-skip-permissions``
- # but uses the documented mode enum. Per-task override still
- # honoured if the user explicitly wants ``acceptEdits``.
+ # Permission mode — ``dontAsk`` is the documented mode for
+ # "only pre-approved tools, no prompts"
+ # (https://code.claude.com/docs/en/permission-modes), which is
+ # what we want for non-interactive automation with a STRICT
+ # tool allowlist. 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 correct middle: no prompts AND strict
+ # allowlist gating. Per-task override still honoured.
perm = task.permission_mode or defaults.get(
"default_permission_mode",
- self._defaults.get("default_permission_mode", "bypassPermissions"),
+ self._defaults.get("default_permission_mode", "dontAsk"),
)
if perm:
argv += ["--permission-mode", perm]
diff --git a/server/services/cli_agent/service.py b/server/services/cli_agent/service.py
index 9b69ca80..83963e8f 100644
--- a/server/services/cli_agent/service.py
+++ b/server/services/cli_agent/service.py
@@ -92,6 +92,37 @@ class AICliService:
"""
provider = create_cli_provider(provider_name)
task_list: List[BaseAICliTaskSpec] = list(tasks)
+
+ # Pass the per-workflow workspace dir
+ # (``data/workspaces/<workflow_id>/`` — injected into ctx by
+ # ``workflow.py:_get_workspace_dir``) to the spawned claude via
+ # ``--add-dir`` so claude's built-in filesystem tools (``Read``,
+ # ``Edit``, ``Glob``, ``Grep``, ``Write``, ``Bash``) can access
+ # files produced by upstream nodes (``fileDownloader``,
+ # ``documentParser``, ``code`` executors, etc.). Without this
+ # the workspace is invisible to claude: memory-bound runs spawn
+ # with ``cwd=repo_root`` and non-memory runs with
+ # ``cwd=worktree``, neither of which sees the workflow's
+ # workspace files.
+ #
+ # Mirrors the ai_agent pattern (``services/ai.py:1899`` —
+ # ``config['workspace_dir'] = context.get('workspace_dir', '')``),
+ # but uses claude's native ``--add-dir`` mechanism instead of
+ # tool-config injection because claude has its own filesystem
+ # tools rather than MCP-injected ones.
+ workspace_str = str(Path(workspace_dir).resolve())
+ for t in task_list:
+ existing_add_dir = list(getattr(t, "add_dir", []) or [])
+ if workspace_str not in existing_add_dir:
+ existing_add_dir.append(workspace_str)
+ # ``ClaudeTaskSpec.add_dir`` is ``List[str]`` per
+ # ``types.py``; ``model_copy(update=...)`` is the
+ # Pydantic-clean way to splice it without mutating.
+ if hasattr(t, "model_copy"):
+ task_list[task_list.index(t)] = t.model_copy(
+ update={"add_dir": existing_add_dir},
+ )
+
tool_names = [t.get("node_type") for t in (connected_tools or [])]
memory_node = (
connected_memory.get("node_id") if connected_memory else None
@@ -241,11 +272,21 @@ class AICliService:
finally:
async with self._lock:
self._active_sessions.pop(key, None)
- # When ``use_pool`` is True, the bearer token persists with
- # the warm PTY across batches — unregistering here would
- # break the next batch's MCP auth. The CLI owns its token;
- # we accept that the registration leaks until app shutdown
- # (bounded by max pool size).
+ # When ``use_pool`` is True, the bearer token for THIS batch
+ # is consumed by ``ClaudeSessionPool.acquire`` directly:
+ # - Cold spawn: pool stores ``token`` on
+ # ``PooledClaudeSession.batch_token`` so it survives
+ # across subsequent batches; ``_terminate_locked``
+ # unregisters it when the subprocess dies (drains
+ # FastMCP tool refcounts cleanly on eviction / pool
+ # shutdown).
+ # - Warm reuse: pool rebinds the surviving warm
+ # subprocess's persistent BatchContext to this batch's
+ # surface in place and unregisters ``token`` (which
+ # was redundant the moment we picked the warm path).
+ # Either way the pool owns the token's fate, so we must
+ # NOT unregister here for the pool path — doing so on
+ # cold spawn would 401 every subsequent warm-reuse turn.
if not use_pool:
unregister_batch(token)
diff --git a/server/services/cli_agent/session_pool.py b/server/services/cli_agent/session_pool.py
index 55685947..bc6c3eb9 100644
--- a/server/services/cli_agent/session_pool.py
+++ b/server/services/cli_agent/session_pool.py
@@ -121,6 +121,16 @@ class PooledClaudeSession:
# memory_node_id (after a crash / reap) emit ``--resume <UUID>`` so
# the same on-disk JSONL keeps growing across process restarts.
current_session_uuid: str = ""
+ # Bearer token baked into claude's argv (via ``--mcp-config``) at
+ # spawn time. The token persists for the subprocess's lifetime —
+ # claude reads it from the frozen argv on every MCP request, so we
+ # can never rotate it without respawning. Stored here so the pool
+ # can (a) rebind the matching :class:`BatchContext` in place when
+ # the tool / skill / credential surface changes between batches
+ # without paying a cold-spawn, and (b) call ``unregister_batch``
+ # in ``_terminate_locked`` to drain the FastMCP tool refcounts
+ # when the subprocess dies.
+ batch_token: str = ""
last_used_at: float = field(default_factory=time.monotonic)
# Per-session lock; held throughout a turn. The reaper consults
# ``lock.locked()`` to skip in-flight sessions.
@@ -234,6 +244,39 @@ class ClaudeSessionPool:
if existing is not None:
existing.last_used_at = time.monotonic()
+ # Rebind the persistent :class:`BatchContext` bound to
+ # the warm subprocess's argv-baked bearer token to the
+ # surface the current batch declares. Without this the
+ # per-handler scope check in
+ # ``workflow_tools._build_handler`` still sees the
+ # stale ``connected_tools`` from the spawn batch and
+ # lets disconnected tools fire (and FastMCP refcounts
+ # leak by 1 per batch indefinitely).
+ #
+ # Service.py just issued ``mcp_bearer_token`` (T_new)
+ # for this batch and called ``register_batch`` on it.
+ # We transplant T_new's BatchContext values onto
+ # T_warm (the argv-baked one), then drop T_new — it
+ # would otherwise sit orphaned in ``_active_tokens``
+ # until app shutdown.
+ if (
+ existing.batch_token
+ and mcp_bearer_token
+ and mcp_bearer_token != existing.batch_token
+ ):
+ from services.cli_agent.mcp_server import (
+ lookup_batch, rebind_batch, unregister_batch,
+ )
+ new_ctx = lookup_batch(mcp_bearer_token)
+ if new_ctx is not None:
+ rebind_batch(
+ existing.batch_token,
+ connected_tools=new_ctx.connected_tools,
+ connected_skill_names=new_ctx.connected_skill_names,
+ allowed_credentials=new_ctx.allowed_credentials,
+ workspace_dir=new_ctx.workspace_dir,
+ )
+ unregister_batch(mcp_bearer_token)
logger.info(
"[ClaudeSessionPool] warm reuse memory_node=%s pid=%s uuid=%s",
memory_node_id, existing.process.pid,
@@ -260,6 +303,12 @@ class ClaudeSessionPool:
mcp_bearer_token=mcp_bearer_token,
connected_tool_names=connected_tool_names,
)
+ # Track the spawn-time bearer token so subsequent batches can
+ # rebind the persistent BatchContext in place (warm-reuse
+ # path above) and ``_terminate_locked`` can drain FastMCP
+ # tool refcounts on death.
+ if mcp_bearer_token:
+ session.batch_token = mcp_bearer_token
if crashed_uuid:
# The new subprocess is resuming the prior session; pre-seed
# the UUID so the first turn's emitted CloudEvents carry
@@ -682,6 +731,22 @@ class ClaudeSessionPool:
return
session_uuid = session.current_session_uuid
+ # Drop the spawn-time BatchContext: decrement FastMCP tool
+ # refcounts (so disconnected tools eventually fall off the
+ # registry) and remove the token from ``_active_tokens`` (so a
+ # subsequent MCP request with a stale token gets a clean 401
+ # instead of resolving to leaked state). Best-effort — a failure
+ # here must not block subprocess teardown.
+ if session.batch_token:
+ try:
+ from services.cli_agent.mcp_server import unregister_batch
+ unregister_batch(session.batch_token)
+ except Exception as exc: # pragma: no cover — defensive
+ logger.debug(
+ "[ClaudeSessionPool] unregister_batch on terminate "
+ "memory_node=%s exc=%s", memory_node_id, exc,
+ )
+
# 1. Close stdin so claude can exit gracefully.
process = session.process
if process.returncode is None and process.stdin is not None:
diff --git a/server/services/cli_agent/types.py b/server/services/cli_agent/types.py
index 32deceae..67cacee6 100644
--- a/server/services/cli_agent/types.py
+++ b/server/services/cli_agent/types.py
@@ -96,10 +96,13 @@ class ClaudeTaskSpec(BaseAICliTaskSpec):
)
allowed_tools: Optional[str] = Field(
default=None,
- description="Comma-separated tool list. Defaults to "
- "Read,Edit,Bash,Glob,Grep,Write.",
+ description="Comma-separated tool list. Default is empty — "
+ "claude built-ins (Read/Edit/Bash/Glob/Grep/Write/"
+ "Skill/WebSearch/WebFetch) are intentionally NOT in "
+ "the allowlist; the agent only gets connected MCP "
+ "tools + MachinaOs's own MCP infrastructure tools.",
)
- permission_mode: Literal["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"] = "acceptEdits"
+ permission_mode: Literal["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"] = "dontAsk"
# ---- optional documented CLI flags (cli-reference) ----
effort: Optional[Literal["low", "medium", "high", "xhigh", "max"]] = Field(
diff --git a/server/tests/services/cli_agent/test_providers.py b/server/tests/services/cli_agent/test_providers.py
index f7a8fd59..01442e49 100644
--- a/server/tests/services/cli_agent/test_providers.py
+++ b/server/tests/services/cli_agent/test_providers.py
@@ -104,11 +104,47 @@ class TestClaudeArgv:
assert "--allowedTools" in argv
assert "--permission-mode" in argv
# Default permission mode is read from ``config/ai_cli_providers.json``
- # (currently ``acceptEdits``). Callers wanting ``bypassPermissions``
- # set it explicitly on ``task.permission_mode`` or via the per-call
- # ``defaults`` arg.
+ # (currently ``dontAsk`` — "only pre-approved tools, no prompts",
+ # which gates ``--allowedTools`` strictly so claude's built-in
+ # Read/Edit/Bash/etc. can NOT fire unless explicitly listed).
+ # Callers wanting ``acceptEdits`` / ``bypassPermissions`` set it
+ # on ``task.permission_mode`` or via the per-call ``defaults`` arg.
perm_idx = argv.index("--permission-mode")
- assert argv[perm_idx + 1] == "acceptEdits"
+ assert argv[perm_idx + 1] == "dontAsk"
+
+ def test_no_claude_builtins_in_default_allowlist(self, claude_provider):
+ """Claude's built-in escape-hatch tools (Read, Edit, Bash, Glob,
+ Grep, Write, Skill, WebSearch, WebFetch) are intentionally NOT
+ in the default ``--allowedTools`` list. Combined with
+ ``--permission-mode dontAsk`` (which gates strictly on the
+ allowlist) this means the agent can ONLY invoke MCP tools that
+ were explicitly wired through ``input-tools`` plus MachinaOs's
+ own MCP infrastructure tools — never the built-ins.
+
+ Disconnected workflow tools are also blocked by the per-handler
+ scope check in ``workflow_tools._build_handler`` reading the
+ rebound ``BatchContext.connected_tools``.
+ """
+ task = ClaudeTaskSpec(prompt="x")
+ argv = claude_provider.interactive_argv(task, defaults={})
+ allowed_idx = argv.index("--allowedTools")
+ allowlist = argv[allowed_idx + 1]
+ entries = [e.strip() for e in allowlist.split(",")]
+ builtins = {
+ "Read", "Edit", "Bash", "Glob", "Grep", "Write",
+ "Skill", "WebSearch", "WebFetch",
+ }
+ for entry in entries:
+ assert entry not in builtins, (
+ f"claude built-in {entry!r} leaked into default allowlist"
+ )
+ # MachinaOs MCP infrastructure must still be present so the
+ # agent can read the workspace + invoke connected skills.
+ assert "mcp__machinaos__getWorkspaceFiles" in entries
+ assert "mcp__machinaos__listSkills" in entries
+ assert "mcp__machinaos__getSkill" in entries
+ assert "mcp__machinaos__getCredential" in entries
+ assert "mcp__machinaos__broadcastLog" in entries
def test_no_session_id_flag_in_interactive(self, claude_provider):
"""Claude assigns its own session UUID in interactive mode; we