graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
claude-agent: refresh tools in place; addressed mail wakes a finished task
justrach87565622277b
diff --git a/docs/adr/0311-tool-refresh-and-addressed-wakes.md b/docs/adr/0311-tool-refresh-and-addressed-wakes.mdnew file mode 100644index 00000000..603779ba--- /dev/null+++ b/docs/adr/0311-tool-refresh-and-addressed-wakes.md@@ -0,0 +1,61 @@+# 0311. Claude Agent refreshes tools in place; a finished task still hears addressed mail++Status: accepted 2026-11-02++## Context++Two defects came out of one test: a finished worker owns a task, and three+follow-ups for it arrive as peer mail while five unrelated room lines arrive+around them.++**Claude Agent dropped the call that loaded a tool.** When graff's tool list+changed (usually `load_tool_schemas`, loading `peer_message`), the next step+removed graff's SDK MCP server from Claude Code and added it back+(`mcp_set_servers {}` then `{graff}`), so Claude Code would re-read+`tools/list`. The `load_tool_schemas` call was still held at that moment.+Removing the server failed it with "Connection closed", and the model often+ended its turn on that error. In other turns the model went on to call the+tool and got "No such tool available". Against real Claude Code 2.1.304, a+held call failed on every reset. With `notifications/tools/list_changed`+sent instead, Claude Code re-read the list and the model called the new tool+in the same turn.++**Whether a follow-up woke the worker depended on how its last turn ended.**+Commit a53242d4 (#1137) made a final answer settle the task: room mail+stays parked for the next human prompt, and only mail addressed to the+session starts a turn. `attempt_completion` kept an older, stricter latch+that blocked addressed mail too. A model that ends its turns with+`attempt_completion` never heard a follow-up sent straight to it; a model+that ends with a plain answer did.++## Decision++- The claude-agent transport refreshes a changed tool list by sending+ Claude Code an MCP `notifications/tools/list_changed` for graff's server (a+ client-to-CLI `mcp_message`), then serving the `tools/list` it sends back+ before anything else. The server stays connected, so held calls stay open.+ graff's MCP `initialize` result declares `tools.listChanged`. If Claude Code+ does not re-read the list within 15 seconds, graff starts a fresh session,+ which reads the list at start.+- The results sent after a refresh carry one line telling the model that+ graff's tools are named `mcp__graff__<name>`. `load_tool_schemas` prints+ schemas under graff's own names, and the model's first call to a tool it+ had just loaded used that bare name, which Claude Code rejects ("No such+ tool available"); the turn went on, but that call was wasted.+- A turn started by a peer wake ("peer_message action=inbox") preloads+ `peer_message` with its first request, as a request naming subagents+ preloads `subagent` (ADR 0231). Without it the woken turn's first call was+ to the unloaded tool; on Claude Agent, Claude Code refuses that call itself,+ so graff never answered it, and the transcript mismatch forced a fresh+ session.+- `attempt_completion` settles the task exactly as a final answer does:+ room mail stays parked and readable until the next human prompt, and mail+ addressed to this session (a DM, or the user's own `/tell`) can start a+ turn. `yield_turn` keeps its strict latch: it waits on the person.++## Consequences++Loading a tool on Claude Agent no longer costs the turn or a fresh process.+A peer can hand a finished worker a follow-up by addressing it, whatever the+model ended with; unaddressed room chatter still never wakes it. Revisit the+second rule if addressed mail is used to spam finished workers.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 8ac45994..0716838e 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -334,6 +334,7 @@ record only when you need the evidence or the edge cases.| [0307](0307-resumed-sessions-keep-their-compaction-state-count.md) | A session saves the provider's count of its compaction state, scoped to provider, model, size and digest; loading reapplies it before rebasing the meter, so a restart neither inflates the meter nor forces a compaction. || [0309](0309-claude-agent-runs-the-users-claude.md) | Claude Agent runs the user's own `claude` over the SDK control protocol: graff's tools as an in-process MCP server with held calls, graff's history as the source of truth, never reading Claude Code's login. || [0310](0310-auth-failures-name-the-rejected-credential.md) | A terminal auth rejection names the seat that failed: sign-in text keeps "sign in again"; key and promoted-key texts say "API key was rejected" and never the signed-out phrases. Key seats carry `{"kind":"api_key_rejected","provider":…}` (v1 `-32603` data, v2 `_meta["graff/recovery"]`); `reauth_required` is unchanged. |+| [0311](0311-tool-refresh-and-addressed-wakes.md) | Claude Agent refreshes a changed tool list with MCP `tools/list_changed` (served before anything else; fresh session if not re-read in 15 s) instead of removing and re-adding its server, which failed held calls. `attempt_completion` settles a task like a final answer: room mail waits for the next human prompt, addressed mail can still start a turn; `yield_turn` stays strict. A peer wake preloads `peer_message`. || [0302](0302-sse-idle-watchdogs-follow-body-byte-progress.md) | SSE idle watchdogs observe partial body-byte progress, while separate unfinished-event time and size bounds preserve recovery. |diff --git a/src/claude_agent.zig b/src/claude_agent.zigindex 50d81f50..aef10a22 100644--- a/src/claude_agent.zig+++ b/src/claude_agent.zig@@ -101,12 +101,23 @@ pub fn post(self: *Agent, body: []const u8) ![]u8 {s.stop();held = null;} else if (self.tracer) |tr| tr.note("claude-agent", "reused");+ var relisted = false;if (held) |s| if (s.tools_fp != tools_fp) {- refreshTools(s, a, tools, poll) catch |e| {- s.stop();- return e;- };- if (self.tracer) |tr| tr.note("claude-agent", "tool list refreshed");+ if (refreshTools(s, a, tools, poll)) {+ relisted = true;+ if (self.tracer) |tr| tr.note("claude-agent", "tool list refreshed");+ } else |e| switch (e) {+ error.Interrupted => {+ s.stop();+ return e;+ },+ else => {+ // A fresh session reads the new list at start.+ s.stop();+ held = null;+ if (self.tracer) |tr| tr.note("claude-agent", "restart: tool list was not re-read");+ },+ }};var restarts: u8 = 0;@@ -117,7 +128,7 @@ pub fn post(self: *Agent, body: []const u8) ![]u8 {};held = s;s.tools_fp = tools_fp;- if (try sendDelta(self, a, s, items)) break s;+ if (try sendDelta(self, a, s, items, if (relisted) relisted_note else "")) break s;// The new messages are not something this session can take: replay// everything into a fresh one, once.s.stop();@@ -200,12 +211,28 @@ fn control(s: *Session, a: std.mem.Allocator, id: []const u8, request_json: []co}}-/// graff's tool list changed: remove and re-add its server, which makes-/// Claude Code initialize it again and re-read tools/list. The session and-/// its history stay; only the prompt cache past the tools is rewritten.+/// How long Claude Code gets to re-read the tool list after being told.+const relist_budget_ms: u64 = 15_000;++/// graff's tool list changed (load_tool_schemas, an MCP server joining).+/// Tell Claude Code with MCP's tools/list_changed and serve the tools/list it+/// sends back before answering anything, so the next model request already+/// has the new tools. The server stays connected, so a call graff is still+/// holding (usually the load_tool_schemas that changed the list) stays open.+/// Removing and re-adding the server instead failed that call with+/// "Connection closed", and the model often ended its turn there.fn refreshTools(s: *Session, a: std.mem.Allocator, tools: ?Value, poll: bool) !void {- try control(s, a, "graff_tools_off", "{\"subtype\":\"mcp_set_servers\",\"servers\":{}}", tools, poll);- try control(s, a, "graff_tools_on", "{\"subtype\":\"mcp_set_servers\",\"servers\":{\"" ++ wire.server_name ++ "\":{\"type\":\"sdk\",\"name\":\"" ++ wire.server_name ++ "\"}}}", tools, poll);+ const listed = s.tools_listed;+ try control(s, a, "graff_tools_changed", wire.tools_changed_request, tools, poll);+ const deadline = nowMs(s.io) + @as(i64, relist_budget_ms);+ while (s.tools_listed == listed) {+ const left = deadline - nowMs(s.io);+ if (left <= 0) return error.ClaudeAgentToolsNotRelisted;+ switch (try wire.classify(a, try s.readLine(poll, @intCast(left)))) {+ .control => |c| try service(s, a, c, tools),+ else => {},+ }+ }}pub fn startProblem(e: anyerror) []const u8 {@@ -217,9 +244,16 @@ pub fn startProblem(e: anyerror) []const u8 {};}+/// Told with the results that follow a tool-list refresh. load_tool_schemas+/// prints schemas under graff's own names, and without this the model's+/// first call to a tool it just loaded used that bare name, which Claude+/// Code rejects ("No such tool available").+const relisted_note = "Your tool list was just updated. Call the newly loaded tools by their names in your tool list: graff's tools are named " ++ wire.tool_prefix ++ "<name>.";+/// Send what Claude Code has not seen. False when the session cannot take-/// it and a fresh one must start from a checkpoint.-fn sendDelta(self: *Agent, a: std.mem.Allocator, s: *Session, items: []const Value) !bool {+/// it and a fresh one must start from a checkpoint. `note` rides with the+/// last result.+fn sendDelta(self: *Agent, a: std.mem.Allocator, s: *Session, items: []const Value, note: []const u8) !bool {_ = self;if (s.seen == 0) {try s.send(try wire.userLine(a, try history.freshContent(a, items)));@@ -232,8 +266,9 @@ fn sendDelta(self: *Agent, a: std.mem.Allocator, s: *Session, items: []const Valtry s.send(try wire.userLine(a, d.user.?));return true;}+ const last_extra = if (note.len == 0) d.extra_text else if (d.extra_text.len == 0) note else try std.mem.concat(a, u8, &.{ d.extra_text, "\n\n", note });for (d.results, 0..) |r, i| {- const result = try wire.toolResult(a, r.block, if (i + 1 == d.results.len) d.extra_text else "");+ const result = try wire.toolResult(a, r.block, if (i + 1 == d.results.len) last_extra else "");if (pendingIndex(s, r.id)) |pi| {const p = s.pending.items[pi];try s.send(try wire.mcpReply(a, p.request_id, p.rpc_id, result));@@ -268,10 +303,10 @@ pub fn service(s: *Session, a: std.mem.Allocator, c: wire.Control, tools: ?Value}const result: []const u8 = if (std.mem.eql(u8, method, "initialize"))try wire.initializeResult(a, if (params) |p| wire.strField(p, "protocolVersion") orelse "2025-06-18" else "2025-06-18")- else if (std.mem.eql(u8, method, "tools/list"))- try wire.toolsList(a, tools)- else- "{}";+ else if (std.mem.eql(u8, method, "tools/list")) blk: {+ s.tools_listed +%= 1;+ break :blk try wire.toolsList(a, tools);+ } else "{}";return s.send(try wire.mcpReply(a, c.request_id, rpc_id, result));}if (std.mem.eql(u8, c.subtype, "can_use_tool")) {diff --git a/src/claude_agent_session.zig b/src/claude_agent_session.zigindex 825a78a2..5adc902f 100644--- a/src/claude_agent_session.zig+++ b/src/claude_agent_session.zig@@ -38,6 +38,8 @@ pub const Session = struct {props_fp: u64,/// The tool list Claude Code last read from graff's server.tools_fp: u64 = 0,+ /// How many times Claude Code has read graff's tools/list.+ tools_listed: u32 = 0,/// graff messages Claude Code already holds, and a hash of them.seen: usize = 0,seen_fp: u64 = 0,diff --git a/src/claude_agent_tests.zig b/src/claude_agent_tests.zigindex 65a23d05..414820f9 100644--- a/src/claude_agent_tests.zig+++ b/src/claude_agent_tests.zig@@ -84,6 +84,23 @@ test "claude-agent classify: stream events, held tool calls, results; subagent etry std.testing.expect(resp.response.ok);}+test "claude-agent MCP: a new tool list is announced with list_changed, never a server reset (ADR 0311)" {+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena.deinit();+ const a = arena.allocator();+ const init = try parse(a, try wire.initializeResult(a, "2025-06-18"));+ const caps = init.object.get("capabilities").?.object.get("tools").?.object;+ try std.testing.expect(caps.get("listChanged").?.bool);+ const req = try parse(a, wire.tools_changed_request);+ try std.testing.expectEqualStrings("mcp_message", req.object.get("subtype").?.string);+ try std.testing.expectEqualStrings(wire.server_name, req.object.get("server_name").?.string);+ const msg = req.object.get("message").?.object;+ try std.testing.expectEqualStrings("notifications/tools/list_changed", msg.get("method").?.string);+ try std.testing.expect(msg.get("id") == null); // a notification: Claude Code answers with a tools/list+ const src = @embedFile("claude_agent.zig");+ try std.testing.expect(std.mem.indexOf(u8, src, "\\\"servers\\\":{}") == null);+}+test "claude-agent MCP: tools/list renames input_schema; a tool_result becomes MCP content" {var arena = std.heap.ArenaAllocator.init(std.testing.allocator);defer arena.deinit();diff --git a/src/claude_agent_wire.zig b/src/claude_agent_wire.zigindex 50b10cb9..f74d9bc2 100644--- a/src/claude_agent_wire.zig+++ b/src/claude_agent_wire.zig@@ -219,8 +219,12 @@ pub fn mcpReply(a: Allocator, request_id: []const u8, rpc_id: ?[]const u8, resulreturn controlOk(a, request_id, inner);}+/// Control request telling Claude Code that graff's server has a new tool+/// list (MCP `notifications/tools/list_changed`, client to CLI).+pub const tools_changed_request = "{\"subtype\":\"mcp_message\",\"server_name\":\"" ++ server_name ++ "\",\"message\":{\"jsonrpc\":\"2.0\",\"method\":\"notifications/tools/list_changed\"}}";+pub fn initializeResult(a: Allocator, protocol_version: []const u8) ![]u8 {- return std.fmt.allocPrint(a, "{{\"protocolVersion\":{f},\"capabilities\":{{\"tools\":{{}}}},\"serverInfo\":{{\"name\":\"" ++ server_name ++ "\",\"version\":\"1\"}}}}", .{std.json.fmt(protocol_version, .{})});+ return std.fmt.allocPrint(a, "{{\"protocolVersion\":{f},\"capabilities\":{{\"tools\":{{\"listChanged\":true}}}},\"serverInfo\":{{\"name\":\"" ++ server_name ++ "\",\"version\":\"1\"}}}}", .{std.json.fmt(protocol_version, .{})});}/// graff's Anthropic tool list (`[{name, description, input_schema}]`) as andiff --git a/src/daddy.zig b/src/daddy.zigindex eb7befe6..591d851e 100644--- a/src/daddy.zig+++ b/src/daddy.zig@@ -212,7 +212,7 @@ test "parkedDirectives sees a [daddy] body and takeIdleText fires after completi@import("peer_idle.zig").resetForTest();}@import("peer_idle.zig").noteCompletion();- try std.testing.expect(@import("peer_idle.zig").idleWakeSuppressed());+ try std.testing.expect(@import("peer_idle.zig").isSettled());try std.testing.expect(!parkedDirectives());_ = peer_inbox.parkHeard(&.{.{ .from_session = "s-dad", .text = "[daddy] switch to the tests" }}, &.{});try std.testing.expect(parkedDirectives());diff --git a/src/mcp_preload.zig b/src/mcp_preload.zigindex 82ff3501..78e6f7af 100644--- a/src/mcp_preload.zig+++ b/src/mcp_preload.zig@@ -46,9 +46,13 @@ pub fn namedServers(self: *Agent) bool {/// Folded natives a message asks for outright. A request to split work across/// subagents spawns them and waits on what they return, so both load with the-/// request instead of one load call each.+/// request instead of one load call each. A peer wake says "peer_message+/// action=inbox": the turn it starts reads the inbox first, and on Claude+/// Agent a call to the unloaded tool is refused by Claude Code itself+/// ("No such tool available"), which also costs a fresh session (ADR 0311).const named_natives = [_]struct { words: []const []const u8, tools: []const []const u8 }{.{ .words = &.{ "subagent", "subagents", "sub-agent", "sub-agents" }, .tools = &.{ "subagent", "agent_output" } },+ .{ .words = &.{"peer_message"}, .tools = &.{"peer_message"} },};fn namedNatives(arena: std.mem.Allocator, text: []const u8, loaded: *std.ArrayList(u8)) void {@@ -124,6 +128,22 @@ test "asking for subagents loads subagent and agent_output with the request (ADR}}+test "a peer wake loads peer_message with the turn it starts (ADR 0311)" {+ const fold = @import("native_fold.zig");+ fold.clearLoadedSession();+ defer fold.clearLoadedSession();+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ var loaded: std.ArrayList(u8) = .empty;+ namedNatives(arena_state.allocator(), "Message the peer when you are done.", &loaded);+ try std.testing.expectEqual(@as(usize, 0), loaded.items.len);+ namedNatives(arena_state.allocator(), "[peer] 1 unread from lead \u{2014} parked; peer_message action=inbox when relevant", &loaded);+ if (fold.enabled) {+ try std.testing.expectEqualStrings("peer_message", loaded.items);+ try std.testing.expect(fold.isLoaded("peer_message"));+ }+}+test "a server is named only as a whole word, in any case" {try std.testing.expect(names("This workspace has a Linear-shaped MCP server named linear (stdio).", "linear"));try std.testing.expect(names("check LINEAR for open bugs", "linear"));diff --git a/src/peer_idle.zig b/src/peer_idle.zigindex 05eca26c..17f971c9 100644--- a/src/peer_idle.zig+++ b/src/peer_idle.zig@@ -42,22 +42,31 @@ pub fn isBusy() bool {return turn_busy.load(.acquire);}-/// Accepted `attempt_completion` ends the task. Parked mail stays readable-/// but must not start another assistant/tool cycle (#1137).+/// Accepted `attempt_completion` ends the task the same way a final answer+/// does (ADR 0311): room mail stays parked for the next human prompt, and+/// only mail addressed to this session can start a turn. Which of the two a+/// model happens to end with must not decide whether a peer's follow-up is+/// heard.pub fn noteCompletion() void {- suppress_idle_wake = true;+ settled = true;}/// A root turn ended with an ordinary final answer (#1137). The human task-/// is done just as after `attempt_completion`, but more softly: mail posted-/// to the folder's room is ambient coordination and no longer starts a turn-/// on its own. It stays parked and readable, and the next human prompt sees-/// it. Mail addressed to this session (a DM, or the user's own `/tell`) is an-/// explicit request and still wakes, so peers can still hand work over.+/// is done: mail posted to the folder's room is ambient coordination and no+/// longer starts a turn on its own. It stays parked and readable, and the+/// next human prompt sees it. Mail addressed to this session (a DM, or the+/// user's own `/tell`) is an explicit request and still wakes, so peers can+/// still hand work over.pub fn noteFinalAnswer() void {settled = true;}+/// The last task ended (final answer or attempt_completion) and no human+/// prompt has come since.+pub fn isSettled() bool {+ return settled;+}+/// Whether the parked mail at or after `from` may start a turn by itself.fn mayStartTurn(from: usize) bool {if (settled) return peer_inbox.anyAddressedNeedsTurnFrom(from);@@ -182,7 +191,7 @@ test "#1001 idle wake fires once per new unread batch" {try std.testing.expect(takeIdleWake(io, &buf) == null);}-test "#1137 idle wake is silent after attempt_completion until a human prompt" {+test "ADR 0311: after attempt_completion only mail addressed to this session wakes" {peer_inbox.resetForTest();resetForTest();defer {@@ -190,6 +199,10 @@ test "#1137 idle wake is silent after attempt_completion until a human prompt" {resetForTest();}var buf: [256]u8 = undefined;+ noteCompletion();+ try std.testing.expect(isSettled() and !idleWakeSuppressed());+ _ = peer_inbox.parkHeard(&.{.{ .from_pid = 2, .from_start = 1, .from_session = "s-peer", .text = "room chatter" }}, &.{});+ try std.testing.expect(takeIdleWake(std.testing.io, &buf) == null);const msg: presence_chan.Message = .{.from_pid = 2,.from_start = 1,@@ -198,10 +211,7 @@ test "#1137 idle wake is silent after attempt_completion until a human prompt" {.to = "s-me",};_ = peer_inbox.parkHeard(&.{msg}, &.{});- noteCompletion();- try std.testing.expect(takeIdleWake(std.testing.io, &buf) == null);- noteHumanPrompt();- const wake = takeIdleWake(std.testing.io, &buf) orelse return error.ExpectedWakeAfterHuman;+ const wake = takeIdleWake(std.testing.io, &buf) orelse return error.ExpectedAddressedWake;try std.testing.expect(std.mem.indexOf(u8, wake, "[peer]") != null);}diff --git a/src/peer_wake_loop.zig b/src/peer_wake_loop.zigindex 082a9bba..b5bcb9a4 100644--- a/src/peer_wake_loop.zig+++ b/src/peer_wake_loop.zig@@ -175,7 +175,7 @@ test "#1137 peer arrival after attempt_completion does not auto-run" {}_ = peer_inbox.parkHeard(&.{.{ .from_pid = 2, .from_start = 1, .from_session = "s-peer", .text = "hold gui" }}, &.{});peer_idle.noteCompletion();- try std.testing.expect(peer_idle.idleWakeSuppressed());+ try std.testing.expect(peer_idle.isSettled());try std.testing.expect(!shouldInjectAuthoritative(false, 1));var buf: [256]u8 = undefined;try std.testing.expect(peer_idle.takeIdleWake(std.testing.io, &buf) == null);