Skip to content

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.md
new file mode 100644
index 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.md
index 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.zig
index 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 Val
try 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.zig
index 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.zig
index 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 e
try 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.zig
index 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, resul
return 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 an
diff --git a/src/daddy.zig b/src/daddy.zig
index 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.zig
index 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.zig
index 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.zig
index 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);