claude-code: the operator's agent, its managed configuration and the licence consumer side (hq design 36, to-be 40 WP2) #244

2026-10-03T14:13:11Z

mesh-admin commented

2026-10-03 14:13:11 +00:00

The successor of the predecessor's agent module. A tools bundle served by the node's runtime (ADR 0175, 0188), given its state directory and two files the mesh renders (ADR 0192).

What it writes

/etc/claude-code/managed-mcp.json — the console as mesh (http://127.0.0.1:<port>/mcp, the port from node-tools' mcp-endpoint, mesh-tools #34) and the servers in the module's mcp_servers setting. Exclusive, by the operator's choice: managedMcpServers in managed settings refuses any non-https URL, so it cannot carry a loopback console.
/etc/claude-code/managed-settings.json — attribution convention, allowAllClaudeAiMcps, and apiKeyHelper only while an API-key licence is held.
/etc/claude-code/CLAUDE.md — how a session here works, the node's name and role setting, conventions.
~/.claude/.credentials.json — only on a hand-over from the licence manager, access-token-only, atomic, 0600, as the operator.

Rendered whenever the runtime collects the tools; written only on change; through the operator account's passwordless sudo (true on all four, checked by nothing — stated in the README).

Tools: claude_code_status, claude_code_render, claude_code_public_key, claude_code_apply, claude_code_pending_login. The module calls nothing; the manager starts every exchange (ADR 0183's dated note).

Tests: 17 unit tests (sealing, the predecessor's lineage cases, the strip, identity, rendering). module check passes. Depends on mesh-tools #34 being merged first.

Live proof planned (to-be 40 WP2, configuration only): assign on g14, set its role and move the operator's own servers into mcp_servers for g14 first, or they stop loading.

The successor of the predecessor's agent module. A tools bundle served by the node's runtime (ADR 0175, 0188), given its state directory and two files the mesh renders (ADR 0192). **What it writes** - `/etc/claude-code/managed-mcp.json` — the console as `mesh` (`http://127.0.0.1:<port>/mcp`, the port from node-tools' `mcp-endpoint`, mesh-tools #34) and the servers in the module's `mcp_servers` setting. Exclusive, by the operator's choice: `managedMcpServers` in managed settings refuses any non-https URL, so it cannot carry a loopback console. - `/etc/claude-code/managed-settings.json` — attribution convention, `allowAllClaudeAiMcps`, and `apiKeyHelper` only while an API-key licence is held. - `/etc/claude-code/CLAUDE.md` — how a session here works, the node's name and `role` setting, conventions. - `~/.claude/.credentials.json` — only on a hand-over from the licence manager, access-token-only, atomic, 0600, as the operator. Rendered whenever the runtime collects the tools; written only on change; through the operator account's passwordless sudo (true on all four, checked by nothing — stated in the README). **Tools:** `claude_code_status`, `claude_code_render`, `claude_code_public_key`, `claude_code_apply`, `claude_code_pending_login`. The module calls nothing; the manager starts every exchange (ADR 0183's dated note). **Tests:** 17 unit tests (sealing, the predecessor's lineage cases, the strip, identity, rendering). `module check` passes. Depends on mesh-tools #34 being merged first. **Live proof planned (to-be 40 WP2, configuration only):** assign on g14, set its `role` and move the operator's own servers into `mcp_servers` for g14 first, or they stop loading.

jschoubben added 3 commits 2026-10-03 21:41:02 +00:00

claude-code: the sealed hand-over, the credentials write with the lineage rule, the identity read (hq to-be 40 WP2, in progress) 5737752744

The parts of the agent module that hold whichever way the console is registered: X25519 +
HKDF + AES-GCM from Node's own library so the bundle carries no dependency; the predecessor's
lineage rule (rotation only if newer, a re-issue adopted, a switch regardless) with its
incidents as tests; an atomic 0600 write that strips any refresh token and keeps keys it does not
know; the account read from the agent's own state file. Manifest and renderer follow.

claude-code: the manifest, the managed directory and the tools (hq design 36, to-be 40 WP2) f42b58f789

The module owns /etc/claude-code: managed-mcp.json lists the console as `mesh` over HTTP on
loopback plus the servers in its mcp_servers setting (exclusive, by the operator's choice — the
https rule of managedMcpServers refuses a loopback console); managed-settings.json carries the
attribution convention, keeps claude.ai connectors, and adds the key-helper only for an API-key
licence; CLAUDE.md says how a session here works. Rendered whenever the runtime collects the
tools, written only on change, through the operator account's sudo. Under the home, only the
credentials file, only on a hand-over. Nothing declared under a home or /etc; the console's
port comes from node-tools' mcp-endpoint (mesh-tools #34).

claude-code: launched over stdio (ADR 0193), the console's five tools in its instructions (ADR 0195) eab335b755

Every bundle is now a child speaking MCP over stdio, so stdout is the channel: the module logs on
stderr. The managed CLAUDE.md teaches mesh_search, mesh_describe, mesh_call, mesh_overview and
mesh_machine with addresses (<seat>.<verb>, <node>/<module>.<tool>) instead of flat tool names.
A hand-over is applied whatever the trailing render says; a failed render is reported beside it.
Proven over stdio as the runtime drives it: five tools listed, a key made on first use, a sealed
switch writing an access-token-only 0600 credentials file that keeps unknown keys.

jschoubben force-pushed feat/claude-code-agent from 04626be62d to eab335b755

2026-10-03 21:41:02 +00:00

Compare

jschoubben added 1 commit 2026-10-03 21:49:18 +00:00

claude-code owns /etc/claude-code and ~/.claude as declared directories 03e729d103

So the controller's ownership check refuses a second module owning either. ~/.claude is the
operator's at 0700 (it was 0755 on the workstations); of what is inside, the module owns only what it
writes, and the host keeps a directory that is not empty when the module goes (hq ADR 0182).

jschoubben added 1 commit 2026-10-04 00:23:25 +00:00

claude-code over NATS: licence events, a token by request, a login pushed to the manager, MCP servers registered per node or mesh-wide 6a7e4ebd5e

Events carry what happened and no secret; tokens travel on requests (design 32 §10). The manager's
licence.rotated/switched events make the module ask anthropic-licence-manager.current; at start it
asks once to catch up. A refresh token appearing in the credentials file is a login: it is pushed to
the manager's adopt at once, sealed to the manager's key — the one time a refresh token travels. A
switch replaces the old licence's grant whole, removes the API key and its helper, and rewrites
oauthAccount in ~/.claude.json. New tools register and unregister MCP servers on this node, or with
nodes: all / a list via an mcp.registered event every node consumes; called for one node, the
answer names the other nodes running claude-code. 26 tests.

jschoubben added 1 commit 2026-10-04 00:23:36 +00:00

claude-code: declare using the licence manager's seat when that module exists; until then the mesh refuses a seat no module declares 295cc59e1e

jschoubben added 1 commit 2026-10-04 01:49:23 +00:00

claude-code keeps its MCP servers in state, not events (novox/hq ADR 0202) 3668b02b94

One key per registration in the module's servers bucket — all.<server> or
<node>.<server> — watched by every node, so a node assigned after a
registration takes it at start, which the mcp.registered event could not do.
Also narrows apply()'s refusal by hand: the builder compiles without strict,
where the discriminated union does not narrow and the build failed.

mesh-admin merged commit 9dfd3b1105 into main

2026-10-04 09:01:31 +00:00

mesh-admin deleted branch feat/claude-code-agent

2026-10-04 09:01:32 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/mesh-catalog#244