graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
claude-agent: run rlm llm_query on a throwaway claude process
justrachabaec3241149
diff --git a/docs/adr/0309-claude-agent-runs-the-users-claude.md b/docs/adr/0309-claude-agent-runs-the-users-claude.mdindex 037f00ff..1893c249 100644--- a/docs/adr/0309-claude-agent-runs-the-users-claude.md+++ b/docs/adr/0309-claude-agent-runs-the-users-claude.md@@ -72,7 +72,9 @@ approvals, sinks, ACP, usage and compaction run unchanged:- graff's system prompt replaces Claude Code's by default;`GRAFF_CLAUDE_AGENT_PROMPT=claude` keeps Claude Code's and appends graff's.- Usage is Claude Code's per-response counts; billing is the flat-rate plan.-- `rlm`'s nested `llm_query` reports that it is unavailable (no endpoint).+- `rlm`'s nested `llm_query` runs on a throwaway child too, tools off at low+ effort, with a short system prompt in place of Claude Code's. It never+ takes the chat's held session, so that child and its cache carry on.## Measurementsdiff --git a/scripts/test-claude-agent.py b/scripts/test-claude-agent.pyindex 2cd3ba5d..fe0ef671 100755--- a/scripts/test-claude-agent.py+++ b/scripts/test-claude-agent.py@@ -12,6 +12,10 @@ loop has run it, then answers. Asserts:`_meta["claudecode/toolUseId"]`, and the file graff wrote exists- the second step reuses the same `claude` process (one spawn per run)- Claude Code's own login is never read: the fake sees no graff credential++A second run has the model call `rlm` with `llm_query`: the sub-query runs on+its own tools-off `claude` process and its answer reaches the held call,+while the chat's process carries on (no restart, one process each)."""import json, os, shutil, subprocess, sys, tempfilefrom pathlib import Path@@ -32,19 +36,38 @@ def mcp(rid, msg):out({"type": "control_request", "request_id": rid, "request": {"subtype": "mcp_message", "server_name": "graff", "message": msg}})return read()init = read()+usage = {"input_tokens": 10, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 1}+def ready(): out({"type": "control_response", "response": {"subtype": "success", "request_id": init["request_id"], "response": {"claude_code_version": "2.1.304", "models": []}}})+def answer(msg_id, parts):+ ev({"type": "message_start", "message": {"id": msg_id, "type": "message", "role": "assistant", "model": "claude-test", "content": [], "usage": usage}})+ ev({"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}})+ for p in parts: ev({"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": p}})+ ev({"type": "content_block_stop", "index": 0})+ ev({"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": None}, "usage": {"output_tokens": 3}})+ ev({"type": "message_stop"})+ out({"type": "result", "subtype": "success", "is_error": False, "result": "".join(parts)})+if "sdkMcpServers" not in init["request"]:+ # A tools-off side call (llm_query): answer once, then wait to be stopped.+ note("mode", "side"); ready(); read()+ answer("msg_side", ["SUB-", "ANSWER-42"])+ while True: read()+note("mode", "main")# As claude does: connect the SDK server before answering initialize.mcp("m1", {"method": "initialize", "params": {"protocolVersion": "2025-11-25"}, "jsonrpc": "2.0", "id": 0})mcp("m2", {"method": "tools/list", "jsonrpc": "2.0", "id": 1})-out({"type": "control_response", "response": {"subtype": "success", "request_id": init["request_id"], "response": {"claude_code_version": "2.1.304", "models": []}}})+ready()user = read()-usage = {"input_tokens": 10, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 1}+if os.environ.get("FAKE_SCENARIO") == "llm_query":+ name, args = "rlm", {"code": 'a = llm_query("what is six times seven")\nprint(a)'}+else:+ name, args = "write_file", {"path": "out.txt", "content": "from claude agent\n"}ev({"type": "message_start", "message": {"id": "msg_1", "type": "message", "role": "assistant", "model": "claude-test", "content": [], "usage": usage}})-ev({"type": "content_block_start", "index": 0, "content_block": {"type": "tool_use", "id": "toolu_1", "name": "mcp__graff__write_file", "input": {}}})-ev({"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": json.dumps({"path": "out.txt", "content": "from claude agent\n"})}})+ev({"type": "content_block_start", "index": 0, "content_block": {"type": "tool_use", "id": "toolu_1", "name": "mcp__graff__" + name, "input": {}}})+ev({"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": json.dumps(args)}})ev({"type": "content_block_stop", "index": 0})ev({"type": "message_delta", "delta": {"stop_reason": "tool_use", "stop_sequence": None}, "usage": {"output_tokens": 20}})ev({"type": "message_stop"})-reply = mcp("m3", {"method": "tools/call", "params": {"name": "write_file", "arguments": {"path": "out.txt", "content": "from claude agent\n"}, "_meta": {"claudecode/toolUseId": "toolu_1"}}, "jsonrpc": "2.0", "id": 2})+reply = mcp("m3", {"method": "tools/call", "params": {"name": name, "arguments": args, "_meta": {"claudecode/toolUseId": "toolu_1"}}, "jsonrpc": "2.0", "id": 2})ev({"type": "message_start", "message": {"id": "msg_2", "type": "message", "role": "assistant", "model": "claude-test", "content": [], "usage": usage}})ev({"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}})ev({"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "FAKE-DONE"}})@@ -106,9 +129,38 @@ def main():assert call['id'] == 2 and not call['result'].get('isError'), callassert 'out.txt' in call['result']['content'][0]['text'], callprint('PASS claude-agent: graff tools as the SDK server, a held call answered with graff\'s result, one process', flush=True)+ llm_query_case(binary, temp, env)finally:shutil.rmtree(temp, ignore_errors=True)+def llm_query_case(binary, temp, base_env):+ """rlm's llm_query on Claude Agent: a throwaway tools-off process answers+ it, and the chat's own process is neither restarted nor shared."""+ log = temp / 'llm_query.log'+ work = temp / 'proj-llm-query'+ work.mkdir()+ env = dict(base_env, FAKE_CLAUDE_LOG=str(log), FAKE_SCENARIO='llm_query')+ run = subprocess.run([binary, '--model', 'claude-agent/sonnet', '--yolo', '-p', 'ask the sub-model'], cwd=work, env=env,+ capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=120)+ assert run.returncode == 0, run.stderr[-2000:]+ assert 'FAKE-DONE' in run.stdout, (run.stdout[-500:], run.stderr[-1500:])+ rows = [json.loads(l) for l in log.read_text().splitlines() if l.strip()]+ inputs = [r['obj'] for r in rows if r['kind'] == 'in']+ replies = {i['response']['request_id']: i['response'] for i in inputs if i.get('type') == 'control_response'}+ call = replies['m3']['response']['mcp_response']+ text = call['result']['content'][0]['text']+ assert not call['result'].get('isError') and 'SUB-ANSWER-42' in text, call+ modes = [r['obj'] for r in rows if r['kind'] == 'mode']+ assert sorted(modes) == ['main', 'side'], f'expected the chat process and one side process, got {modes}'+ side_argv = [r['obj'] for r in rows if r['kind'] == 'argv' and '--allowedTools' not in r['obj']]+ assert len(side_argv) == 1 and side_argv[0][side_argv[0].index('--model') + 1] == 'sonnet', side_argv+ side_init = [i['request'] for i in inputs if i.get('type') == 'control_request' and 'sdkMcpServers' not in i['request']]+ assert len(side_init) == 1 and side_init[0]['systemPrompt'], side_init+ users = [i for i in inputs if i.get('type') == 'user']+ assert any('what is six times seven' in json.dumps(u['message']['content']) for u in users), users+ print('PASS claude-agent: llm_query runs on its own tools-off process; the chat\'s process carries on', flush=True)++if __name__ == '__main__':main()diff --git a/src/claude_agent.zig b/src/claude_agent.zigindex dbb41ded..50d81f50 100644--- a/src/claude_agent.zig+++ b/src/claude_agent.zig@@ -25,11 +25,12 @@ const wire = @import("claude_agent_wire.zig");const history = @import("claude_agent_history.zig");const session = @import("claude_agent_session.zig");const Session = session.Session;+const Tracer = @import("trace.zig").Tracer;pub const provider_id = "claude-agent";/// Claude Code retries and backs off on its own; silence this long means the/// child is stuck, not thinking (thinking summaries stream as deltas).-const turn_budget_ms: u64 = 300_000;+pub const turn_budget_ms: u64 = 300_000;const init_budget_ms: u64 = 60_000;const init_id = "graff_init";@@ -148,10 +149,26 @@ fn staleBecause(a: std.mem.Allocator, s: *const Session, props_fp: u64, rewrites}fn start(self: *Agent, a: std.mem.Allocator, spawn: wire.Spawn, mode: wire.PromptMode, system: []const u8, tools: ?Value, props_fp: u64, poll: bool) !*Session {+ const owner: Owner = .{ .gpa = self.gpa, .io = self.io, .cwd = self.agent_cwd, .tracer = self.tracer, .note = if (sideCall(self)) "started (side call)" else "started" };+ return open(owner, a, spawn, mode, system, tools, props_fp, poll);+}++/// Who a new `claude` process is for: an Agent's step, or a query made+/// without one (claude_agent_query.zig).+pub const Owner = struct {+ gpa: std.mem.Allocator,+ io: Io,+ cwd: ?[]const u8,+ tracer: ?*Tracer,+ note: []const u8,+};++/// Start `claude` and wait for its `initialize` answer.+pub fn open(owner: Owner, a: std.mem.Allocator, spawn: wire.Spawn, mode: wire.PromptMode, system: []const u8, tools: ?Value, props_fp: u64, poll: bool) !*Session {const argv = try wire.argv(a, spawn);- const s = try Session.start(self.gpa, self.io, argv, @import("mcp_lazy.zig").parent_env, self.agent_cwd, props_fp);+ const s = try Session.start(owner.gpa, owner.io, argv, @import("mcp_lazy.zig").parent_env, owner.cwd, props_fp);errdefer s.stop();- if (self.tracer) |tr| tr.note("claude-agent", if (sideCall(self)) "started (side call)" else "started");+ if (owner.tracer) |tr| tr.note("claude-agent", owner.note);try s.send(try wire.initRequest(a, init_id, mode, system, spawn.has_tools));while (true) {const line = try s.readLine(poll, init_budget_ms);@@ -191,7 +208,7 @@ fn refreshTools(s: *Session, a: std.mem.Allocator, tools: ?Value, poll: bool) !vtry control(s, a, "graff_tools_on", "{\"subtype\":\"mcp_set_servers\",\"servers\":{\"" ++ wire.server_name ++ "\":{\"type\":\"sdk\",\"name\":\"" ++ wire.server_name ++ "\"}}}", tools, poll);}-fn startProblem(e: anyerror) []const u8 {+pub fn startProblem(e: anyerror) []const u8 {return switch (e) {error.FileNotFound => "Claude Code isn't installed. Install it (https://code.claude.com/docs/en/setup), sign in with `claude auth login`, then try again.",error.ClaudeAgentTooOld => "Claude Code is too old for Claude Agent; version " ++ wire.min_version ++ " or later is required. Run `claude update`.",@@ -233,7 +250,7 @@ fn pendingIndex(s: *Session, tool_use_id: []const u8) ?usize {/// Answer a control request from Claude Code. A `tools/call` graff already/// has a result for is answered at once; any other is held for graff's loop.-fn service(s: *Session, a: std.mem.Allocator, c: wire.Control, tools: ?Value) !void {+pub fn service(s: *Session, a: std.mem.Allocator, c: wire.Control, tools: ?Value) !void {if (std.mem.eql(u8, c.subtype, "mcp_message")) {const msg = c.request.get("message") orelse return s.send(try wire.controlErr(a, c.request_id, "missing message"));if (msg != .object) return s.send(try wire.controlErr(a, c.request_id, "bad message"));@@ -337,7 +354,7 @@ fn turn(self: *Agent, a: std.mem.Allocator, s: *Session, tools: ?Value, poll: boreturn .{ .sse = try full.toOwnedSlice() };}-fn problem(a: std.mem.Allocator, text: []const u8) ![]const u8 {+pub fn problem(a: std.mem.Allocator, text: []const u8) ![]const u8 {if (std.mem.indexOf(u8, text, "Not logged in") != null or std.mem.indexOf(u8, text, "/login") != null)return "Claude Code is not logged in. Run `claude auth login` in a terminal, then try again.";return std.fmt.allocPrint(a, "Claude Code stopped: {s}", .{text});diff --git a/src/claude_agent_query.zig b/src/claude_agent_query.zignew file mode 100644index 00000000..7c93bbf4--- /dev/null+++ b/src/claude_agent_query.zig@@ -0,0 +1,127 @@+//! Claude Agent one-shot query (ADR 0309): a tools-off completion made+//! without an Agent, such as rlm's `llm_query`. Claude Agent has no HTTP+//! endpoint, so the Messages body runs on a throwaway `claude` process, the+//! way titles and recaps do. The chat's held session (keyed by its Agent in+//! claude_agent_session.zig) is never taken, so its process and prompt cache+//! carry on untouched.++const std = @import("std");+const Io = std.Io;+const Value = std.json.Value;+const Allocator = std.mem.Allocator;+const Provider = @import("provider.zig").Provider;+const Tracer = @import("trace.zig").Tracer;+const agent = @import("claude_agent.zig");+const wire = @import("claude_agent_wire.zig");+const history = @import("claude_agent_history.zig");++/// Without a system prompt Claude Code would run its own coding-agent prompt.+const default_system = "Answer the request directly. You have no tools.";++/// gpa-owned: a Messages response (`{"content":[{"type":"text",...}]}`), or+/// a problem the caller shows as is.+pub const Reply = union(enum) {+ message: []u8,+ problem: []u8,++ pub fn deinit(self: Reply, gpa: Allocator) void {+ switch (self) {+ inline else => |bytes| gpa.free(bytes),+ }+ }+};++pub const Options = struct {+ cwd: ?[]const u8 = null,+ effort: ?[]const u8 = null,+ tracer: ?*Tracer = null,+};++/// Run one Messages request body (`system`, `messages`; any `tools` ignored)+/// on a new `claude` process and stop it afterwards.+pub fn post(gpa: Allocator, io: Io, provider: Provider, body: []const u8, opts: Options) !Reply {+ var arena: std.heap.ArenaAllocator = .init(gpa);+ defer arena.deinit();+ const a = arena.allocator();+ const req = try std.json.parseFromSliceLeaky(Value, a, body, .{ .allocate = .alloc_always });+ if (req != .object) return error.ClaudeAgentBadRequest;+ const messages = req.object.get("messages") orelse return error.ClaudeAgentBadRequest;+ if (messages != .array) return error.ClaudeAgentBadRequest;+ const given = try history.textOf(a, req.object.get("system"));+ const system = if (given.len > 0) given else default_system;+ const exe = if (provider.api_key.len > 0) provider.api_key else "claude";+ const spawn: wire.Spawn = .{ .exe = exe, .model = wire.modelArg(provider.model), .effort = opts.effort, .has_tools = false };+ const owner: agent.Owner = .{ .gpa = gpa, .io = io, .cwd = opts.cwd, .tracer = opts.tracer, .note = "started (llm_query)" };+ const s = agent.open(owner, a, spawn, .graff, system, null, 0, false) catch |e| switch (e) {+ error.Interrupted => return e,+ else => return .{ .problem = try gpa.dupe(u8, agent.startProblem(e)) },+ };+ defer s.stop();+ try s.send(try wire.userLine(a, try history.freshContent(a, messages.array.items)));++ var text: std.ArrayList(u8) = .empty;+ while (true) {+ switch (try wire.classify(a, try s.readLine(false, agent.turn_budget_ms))) {+ .event => |ev| {+ const kind = wire.strField(ev.object, "type") orelse "";+ // Keep only the last response's text, as the chat path does.+ if (std.mem.eql(u8, kind, "message_start")) text.clearRetainingCapacity();+ if (deltaText(ev)) |t| try text.appendSlice(a, t);+ },+ .control => |c| try agent.service(s, a, c, null),+ .result => |r| {+ if (r.is_error) return .{ .problem = try gpa.dupe(u8, try agent.problem(a, r.text)) };+ return .{ .message = try messageJson(gpa, if (text.items.len > 0) text.items else r.text) };+ },+ .cancel, .response, .ignore => {},+ }+ }+}++/// The text of a `content_block_delta` carrying a `text_delta`.+fn deltaText(ev: Value) ?[]const u8 {+ if (ev != .object) return null;+ if (!std.mem.eql(u8, wire.strField(ev.object, "type") orelse "", "content_block_delta")) return null;+ const d = ev.object.get("delta") orelse return null;+ if (d != .object or !std.mem.eql(u8, wire.strField(d.object, "type") orelse "", "text_delta")) return null;+ return wire.strField(d.object, "text");+}++/// A minimal Messages response carrying `text`, for title.assistantText.+fn messageJson(gpa: Allocator, text: []const u8) ![]u8 {+ var aw: Io.Writer.Allocating = .init(gpa);+ errdefer aw.deinit();+ var s: std.json.Stringify = .{ .writer = &aw.writer };+ try s.beginObject();+ try s.objectField("type");+ try s.write("message");+ try s.objectField("role");+ try s.write("assistant");+ try s.objectField("content");+ try s.beginArray();+ try s.beginObject();+ try s.objectField("type");+ try s.write("text");+ try s.objectField("text");+ try s.write(text);+ try s.endObject();+ try s.endArray();+ try s.endObject();+ return aw.toOwnedSlice();+}++test "claude agent query reads streamed text deltas and wraps them as a Messages reply" {+ const gpa = std.testing.allocator;+ var arena: std.heap.ArenaAllocator = .init(gpa);+ defer arena.deinit();+ const a = arena.allocator();+ const line = "{\"type\":\"stream_event\",\"parent_tool_use_id\":null,\"event\":{\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"4\\\"2\"}}}";+ const ev = (try wire.classify(a, line)).event;+ try std.testing.expectEqualStrings("4\"2", deltaText(ev).?);+ const thinking = try std.json.parseFromSliceLeaky(Value, a, "{\"type\":\"content_block_delta\",\"delta\":{\"type\":\"thinking_delta\",\"thinking\":\"hm\"}}", .{});+ try std.testing.expect(deltaText(thinking) == null);+ const json = try messageJson(gpa, "4\"2");+ defer gpa.free(json);+ const parsed = try std.json.parseFromSliceLeaky(Value, a, json, .{});+ try std.testing.expectEqualStrings("4\"2", @import("title.zig").assistantText(.anthropic, parsed.object));+}diff --git a/src/main.zig b/src/main.zigindex 4fe9b1dd..ac5e99f3 100644--- a/src/main.zig+++ b/src/main.zig@@ -582,7 +582,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_session_load.zig"), @import("acp_session_fork.zig"), @import("session_fork.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("mcp_lazy.zig"), @import("mcp_share.zig"), @import("acp_room.zig"), @import("mcp_catalog.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.zig") };_ = @import("task_outcome.zig"); // goal-outcome telemetry events_ = @import("learn_delete.zig"); // #303: its tests were dead until listed here- _ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig") };+ _ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig"), @import("claude_agent_query.zig") };_ = @import("goal_pacing_autonomous_test.zig");_ = .{ @import("goal_state.zig"), @import("goal_state_tests.zig") };_ = @import("goal_persist_tests.zig");diff --git a/src/rlm_query.zig b/src/rlm_query.zigindex 623d9387..64b390e8 100644--- a/src/rlm_query.zig+++ b/src/rlm_query.zig@@ -5,6 +5,8 @@//! `rlm_query`. Here the host function is that sub-call: one bounded//! completion, no tools, so spec_ptc can launch it the moment the prompt//! literal closes — overlapping generation of the rest of the script.+//! On Claude Agent (ADR 0309) the call goes to a throwaway `claude` process+//! instead of an HTTP endpoint (claude_agent_query.zig).const std = @import("std");const Io = std.Io;@@ -40,14 +42,14 @@ pub fn run(ctx: ToolCtx, args_json: []const u8) ToolOutput {};}defer if (permit) |*p| p.release();- // Claude Agent has no HTTP endpoint: every model call goes through the- // session's `claude` child (ADR 0309), which a nested query cannot share.- if (std.mem.eql(u8, ctx.provider.id, "claude-agent"))- return .{ .text = ctx.gpa.dupe(u8, "rlm: llm_query is not available on Claude Agent; work with the data directly") catch &.{}, .is_error = true };const body = buildBody(ctx.gpa, ctx.provider, prompt) catch {return .{ .text = ctx.gpa.dupe(u8, "rlm: llm_query could not build request") catch &.{}, .is_error = true };};defer ctx.gpa.free(body);+ // Claude Agent has no HTTP endpoint (ADR 0309). The query runs on its own+ // throwaway `claude` process, like a title; the chat's held session is+ // keyed by its Agent and never taken here.+ if (std.mem.eql(u8, ctx.provider.id, "claude-agent")) return viaClaudeAgent(ctx, body);const raw = http.postWatched(ctx.gpa, ctx.io, ctx.client, ctx.provider, body, null) catch |err| {return .{.text = std.fmt.allocPrint(ctx.gpa, "rlm: llm_query failed: {s}", .{@errorName(err)}) catch &.{},@@ -58,6 +60,25 @@ pub fn run(ctx: ToolCtx, args_json: []const u8) ToolOutput {return extract(ctx.gpa, ctx.provider.kind, raw);}+fn viaClaudeAgent(ctx: ToolCtx, body: []const u8) ToolOutput {+ const reply = @import("claude_agent_query.zig").post(ctx.gpa, ctx.io, ctx.provider, body, .{+ .cwd = ctx.agent_cwd,+ .effort = "low",+ .tracer = ctx.tracer,+ }) catch |err| return .{+ .text = std.fmt.allocPrint(ctx.gpa, "rlm: llm_query failed: {s}", .{@errorName(err)}) catch &.{},+ .is_error = true,+ };+ defer reply.deinit(ctx.gpa);+ return switch (reply) {+ .message => |raw| extract(ctx.gpa, .anthropic, raw),+ .problem => |text| .{+ .text = std.fmt.allocPrint(ctx.gpa, "rlm: llm_query failed: {s}", .{text}) catch &.{},+ .is_error = true,+ },+ };+}+pub fn buildBody(gpa: Allocator, provider: Provider, prompt: []const u8) ![]u8 {var aw: Io.Writer.Allocating = .init(gpa);errdefer aw.deinit();