graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
mcp: a read-only child calls the tools its server declares read-only
justrach2eac762a7137
diff --git a/docs/adr/0228-read-only-child-calls-declared-read-only-mcp-tools.md b/docs/adr/0228-read-only-child-calls-declared-read-only-mcp-tools.mdnew file mode 100644index 00000000..d5aa24b6--- /dev/null+++ b/docs/adr/0228-read-only-child-calls-declared-read-only-mcp-tools.md@@ -0,0 +1,37 @@+# 0228. A read-only child calls the MCP tools their server declares read-only++Status: accepted 2026-10-01++## Context++ADR 0227 gives a child the MCP tools its root loaded. A child whose task is+informational runs read-only (#1360), and its gate allowed an MCP call only+for a companion read tool: graff read no MCP tool annotations. A root that+loaded a server's list tools and asked two children to fetch data spawned+children that were classified informational, saw the tools in their catalog,+and had every call refused. They reported the fetch blocked, and the root+gave up instead of writing its result.++The MCP spec lets a server annotate each tool; `readOnlyHint: true` says the+tool does not modify its environment, and absent means it may. Hosted+servers mark their list and get tools this way.++## Decision++- `mcp_pages.appendTools` reads `annotations.readOnlyHint` into+ `mcp.Tool.read_only`; `Registry.declaresReadOnly` answers it by name.+- A read-only child's gate allows an MCP call that is a companion read or a+ tool its server declares read-only. Anything else stays refused.+- A read-only child inherits only the loaded tools its gate lets it call+ (`worker_mcp.withLoaded`), so its catalog never lists a tool it cannot+ use. A child that is not read-only inherits every loaded tool, as before.+- The Linear-shaped eval fixture declares its two list tools read-only, as+ the hosted server it imitates does.++## Consequences++An informational child can fetch through a read tool its root loaded. The+hint is the server's word: a server that marks a writing tool read-only can+write from a read-only child, the same trust the root already extends by+calling it. Plan mode still refuses every MCP call but companion reads;+letting declared reads through there is a separate decision.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 11755d97..e36a8dc2 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -254,6 +254,7 @@ record only when you need the evidence or the edge cases.| [0225](0225-mcp-load-result-states-the-slim-rule.md) | Every MCP load/search/select result says how large list results are slimmed (identity fields; comment lists become `{n, latest_author}`), so a fresh project does not code against dropped fields. A direct call's slimmed result keeps the full payload as a `read_tool_result` handle; rlm binds stay plain slim JSON. || [0226](0226-codex-follows-the-catalog-effort-and-verbosity.md) | On the codex provider, graff's default `medium` effort is sent as the model catalog's default level, and the Responses body carries the catalog's `text.verbosity` (not on compaction or output-schema requests). Any other effort is sent as chosen. || [0227](0227-children-inherit-the-roots-loaded-mcp-tools.md) | A spawned child's catalog gains the MCP tools its root loaded, with full schemas (`worker_mcp.inherit` into `Agent.worker_tools`, served first by `toolsJson`). Unloaded tools stay out; children still have no load tool. |+| [0228](0228-read-only-child-calls-declared-read-only-mcp-tools.md) | An MCP tool is a read when its server declares `readOnlyHint: true` (`mcp.Tool.read_only`). A read-only (informational) child may call those and inherits only those from its root; undeclared MCP tools stay refused. |## When to write onediff --git a/scripts/linear_fixture_mcp.py b/scripts/linear_fixture_mcp.pyindex b2e5e77b..f9e0d33b 100755--- a/scripts/linear_fixture_mcp.py+++ b/scripts/linear_fixture_mcp.py@@ -87,6 +87,7 @@ TOOLS = ["name": "list_issues","description": "List issues in the fixture workspace. Returns fat issue objects (many unused fields).","inputSchema": {"type": "object", "properties": {}},+ "annotations": {"readOnlyHint": True},},{"name": "list_comments",@@ -96,6 +97,7 @@ TOOLS = ["properties": {"id": {"type": "string", "description": "Issue id, e.g. ISS-1"}},"required": ["id"],},+ "annotations": {"readOnlyHint": True},},]diff --git a/src/agent_tool_gate.zig b/src/agent_tool_gate.zigindex 414270cb..f919a99b 100644--- a/src/agent_tool_gate.zig+++ b/src/agent_tool_gate.zig@@ -150,11 +150,14 @@ fn gateHarnessPolicyWrite(self: *Agent, call: ToolCall) !?ExecResult {/// An informational child keeps its read, search and read-only shell tools/// (#1360); withholding the whole catalog left audits with nothing to inspect.-/// Writes are refused the way plan mode refuses them at the root.-fn readOnlyChildAllows(call: ToolCall) bool {+/// Writes are refused the way plan mode refuses them at the root. An MCP tool+/// is a read when it is a companion read or its server declares it read-only+/// (ADR 0228).+fn readOnlyChildAllows(registry: ?*mcp.Registry, call: ToolCall) bool {for ([_][]const u8{ "write_file", "edit_file", "imagegen", "peer_message", "learn_candidate" }) |name|if (std.mem.eql(u8, call.name, name)) return false;- if (mcp.Registry.isMcp(call.name)) return companionReadOnly(call.name, call.input);+ if (mcp.Registry.isMcp(call.name)) return companionReadOnly(call.name, call.input) or+ (if (registry) |reg| reg.declaresReadOnly(call.name) else false);if (!shell_tool.runsCommand(call.name)) return true;const args = json_args.object(call.input) orelse return true;const cmd_val = args.get("command") orelse return true; // action=output / kill@@ -173,12 +176,23 @@ test "a read-only child keeps reads and read-only shell, not writes (#1360)" {return .{ .id = "c", .name = name, .input = v };}}.f;- try std.testing.expect(readOnlyChildAllows(call(a, "read_file", "{\"path\":\"src/main.zig\"}")));- try std.testing.expect(readOnlyChildAllows(call(a, "bash", "{\"command\":\"ls src\"}")));- try std.testing.expect(readOnlyChildAllows(call(a, "bash", "{\"action\":\"output\",\"id\":3}")));- try std.testing.expect(!readOnlyChildAllows(call(a, "write_file", "{\"path\":\"a\",\"content\":\"b\"}")));- try std.testing.expect(!readOnlyChildAllows(call(a, "edit_file", "{}")));- try std.testing.expect(!readOnlyChildAllows(call(a, "bash", "{\"command\":\"rm -rf build\"}")));+ try std.testing.expect(readOnlyChildAllows(null, call(a, "read_file", "{\"path\":\"src/main.zig\"}")));+ try std.testing.expect(readOnlyChildAllows(null, call(a, "bash", "{\"command\":\"ls src\"}")));+ try std.testing.expect(readOnlyChildAllows(null, call(a, "bash", "{\"action\":\"output\",\"id\":3}")));+ try std.testing.expect(!readOnlyChildAllows(null, call(a, "write_file", "{\"path\":\"a\",\"content\":\"b\"}")));+ try std.testing.expect(!readOnlyChildAllows(null, call(a, "edit_file", "{}")));+ try std.testing.expect(!readOnlyChildAllows(null, call(a, "bash", "{\"command\":\"rm -rf build\"}")));+ // ADR 0228: an MCP tool is a read when its server declares it read-only.+ var registry = mcp.Registry.empty(std.testing.allocator, std.testing.io);+ defer registry.deinit();+ var listed = [_]mcp.Tool{+ .{ .server_index = 0, .original_name = "list", .qualified_name = "mcp__linear__list", .description = "", .input_schema = .null, .read_only = true },+ .{ .server_index = 0, .original_name = "save", .qualified_name = "mcp__linear__save", .description = "", .input_schema = .null },+ };+ registry.tools = &listed;+ try std.testing.expect(readOnlyChildAllows(®istry, call(a, "mcp__linear__list", "{}")));+ try std.testing.expect(!readOnlyChildAllows(®istry, call(a, "mcp__linear__save", "{}")));+ try std.testing.expect(!readOnlyChildAllows(null, call(a, "mcp__linear__list", "{}")));}pub fn gateTool(self: *Agent, call: ToolCall) !?ExecResult {@@ -197,7 +211,7 @@ pub fn gateTool(self: *Agent, call: ToolCall) !?ExecResult {};};}- if (self.read_only and !readOnlyChildAllows(call)) return .{+ if (self.read_only and !readOnlyChildAllows(self.registry, call)) return .{.text = try self.arena.dupe(u8, "this subagent is read-only (an informational task) — read, search and run read-only commands, and report the change instead of making it"),.is_error = true,};diff --git a/src/mcp.zig b/src/mcp.zigindex b81b49d8..a20dbfa8 100644--- a/src/mcp.zig+++ b/src/mcp.zig@@ -47,6 +47,7 @@ pub const Tool = struct {qualified_name: []const u8, // "mcp__<server>__<tool>" shown to the modeldescription: []const u8,input_schema: Value, // arena-owned parsed JSON Schema+ read_only: bool = false, // the server's `readOnlyHint` (ADR 0228)pub fn serverName(tool: Tool) []const u8 {return tool.server_name orelse @import("mcp_names.zig").serverOf(tool.qualified_name);}@@ -265,6 +266,14 @@ pub const Registry = struct {};return n;}+ /// Whether the server declared this qualified tool read-only (ADR 0228).+ pub fn declaresReadOnly(reg: *Registry, qualified: []const u8) bool {+ reg.mutex.lockUncancelable(reg.io);+ defer reg.mutex.unlock(reg.io);+ for (reg.tools) |t| if (std.mem.eql(u8, t.qualified_name, qualified)) return t.read_only;+ return false;+ }+pub fn snapshotTools(reg: *Registry, allocator: Allocator) ![]Tool {reg.mutex.lockUncancelable(reg.io);defer reg.mutex.unlock(reg.io);diff --git a/src/mcp_pages.zig b/src/mcp_pages.zigindex 8e29cbd5..8ce16c31 100644--- a/src/mcp_pages.zig+++ b/src/mcp_pages.zig@@ -87,10 +87,36 @@ pub fn appendTools(a: Allocator, tools: *std.ArrayList(Tool), server_index: usiz.description = try a.dupe(u8, desc),.input_schema = schema,.ui_resource_uri = if (@import("mcp_apps.zig").resourceUri(t)) |uri| try a.dupe(u8, uri) else null,+ .read_only = declaresReadOnly(t),});}}+/// MCP tool annotations: `readOnlyHint: true` says the tool does not modify+/// its environment. Absent or false means it may (the spec's default).+pub fn declaresReadOnly(t: Value) bool {+ if (t != .object) return false;+ const annotations = t.object.get("annotations") orelse return false;+ if (annotations != .object) return false;+ const hint = annotations.object.get("readOnlyHint") orelse return false;+ return hint == .bool and hint.bool;+}++test "a tool is read-only only when its annotations say readOnlyHint: true (ADR 0228)" {+ const a = std.testing.allocator;+ for ([_]struct { json: []const u8, want: bool }{+ .{ .json = "{\"name\":\"list\",\"annotations\":{\"readOnlyHint\":true}}", .want = true },+ .{ .json = "{\"name\":\"save\",\"annotations\":{\"readOnlyHint\":false}}", .want = false },+ .{ .json = "{\"name\":\"save\",\"annotations\":{\"destructiveHint\":false}}", .want = false },+ .{ .json = "{\"name\":\"plain\"}", .want = false },+ .{ .json = "{\"name\":\"odd\",\"annotations\":{\"readOnlyHint\":\"true\"}}", .want = false },+ }) |case| {+ const parsed = try std.json.parseFromSlice(Value, a, case.json, .{});+ defer parsed.deinit();+ try std.testing.expectEqual(case.want, declaresReadOnly(parsed.value));+ }+}+/// Ask a 2026-07-28 stdio server for `notifications/tools/list_changed`./// Fire and forget: the acknowledgement and later notifications are read/// (and observed) by the next request's wait, and the id never matches adiff --git a/src/worker_mcp.zig b/src/worker_mcp.zigindex 2fae3021..7e625942 100644--- a/src/worker_mcp.zig+++ b/src/worker_mcp.zig@@ -22,19 +22,22 @@ pub fn inherit(agent: *Agent) void {const registry = agent.registry orelse return;const base = agent.toolsJson();const tools = registry.snapshotTools(agent.arena) catch return;- const built = withLoaded(agent.arena, agent.provider.kind, base, tools);+ const built = withLoaded(agent.arena, agent.provider.kind, base, tools, agent.read_only);if (built.ptr != base.ptr) agent.worker_tools = built;}/// `base` (a JSON array of tool entries) plus an entry for each loaded MCP-/// tool in `tools`. `base` itself when nothing is loaded.-pub fn withLoaded(arena: Allocator, kind: Provider.Kind, base: []const u8, tools: []const mcp.Tool) []const u8 {+/// tool in `tools`; for a read-only child, only the tools their server+/// declares read-only, the ones its gate lets it call (ADR 0228). `base`+/// itself when nothing qualifies.+pub fn withLoaded(arena: Allocator, kind: Provider.Kind, base: []const u8, tools: []const mcp.Tool, read_only: bool) []const u8 {var aw: std.Io.Writer.Allocating = .init(arena);var s: std.json.Stringify = .{ .writer = &aw.writer };var n: usize = 0;s.beginArray() catch return base;for (tools) |t| {if (mcp_schema_gate.omitMcp(t.qualified_name) or !mcp_schema_gate.isLoaded(t.qualified_name)) continue;+ if (read_only and !t.read_only) continue;schema.writeToolEntry(&s, kind, t.qualified_name, t.description, .{ .value = t.input_schema }) catch return base;n += 1;}@@ -58,14 +61,14 @@ test "a child's catalog gains the MCP tools the root loaded, and only those" {mcp_schema_gate.g_policy = .{ .enabled = true, .budget = 0, .eager = &.{} };const all = try @import("mcp_schema_gate_tests.zig").fixture(a, "wiki", 2, 200);const base = "[{\"type\":\"function\",\"name\":\"shell\"}]";- try std.testing.expectEqualStrings(base, withLoaded(a, .responses, base, all)); // nothing loaded yet+ try std.testing.expectEqualStrings(base, withLoaded(a, .responses, base, all, false)); // nothing loaded yetmcp_schema_gate.autoLoad(a, all, all[1].qualified_name); // what a root's direct call does- const out = withLoaded(a, .responses, base, all);+ const out = withLoaded(a, .responses, base, all, false);const parsed = try std.json.parseFromSliceLeaky(std.json.Value, a, out, .{});try std.testing.expectEqual(@as(usize, 2), parsed.array.items.len);try std.testing.expect(std.mem.indexOf(u8, out, all[1].qualified_name) != null);try std.testing.expect(std.mem.indexOf(u8, out, all[0].qualified_name) == null);- const alone = withLoaded(a, .responses, "[]", all);+ const alone = withLoaded(a, .responses, "[]", all, false);try std.testing.expectEqual(@as(usize, 1), (try std.json.parseFromSliceLeaky(std.json.Value, a, alone, .{})).array.items.len);}@@ -106,3 +109,23 @@ test "a spawned child's catalog carries the tools its root loaded" {try std.testing.expect(std.mem.indexOf(u8, got, all[0].qualified_name) == null);try std.testing.expect(std.mem.startsWith(u8, got, static[0 .. static.len - 1]));}++test "a read-only child inherits only the loaded tools declared read-only (ADR 0228)" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ mcp_schema_gate.reset();+ defer mcp_schema_gate.reset();+ const saved_policy = mcp_schema_gate.g_policy;+ defer mcp_schema_gate.g_policy = saved_policy;+ mcp_schema_gate.g_policy = .{ .enabled = true, .budget = 0, .eager = &.{} };+ const all = try @import("mcp_schema_gate_tests.zig").fixture(a, "wiki", 2, 200);+ all[0].read_only = true;+ mcp_schema_gate.autoLoad(a, all, all[0].qualified_name);+ mcp_schema_gate.autoLoad(a, all, all[1].qualified_name);+ const base = "[{\"type\":\"function\",\"name\":\"shell\"}]";+ const reader = withLoaded(a, .responses, base, all, true);+ try std.testing.expect(std.mem.indexOf(u8, reader, all[0].qualified_name) != null);+ try std.testing.expect(std.mem.indexOf(u8, reader, all[1].qualified_name) == null);+ try std.testing.expect(std.mem.indexOf(u8, withLoaded(a, .responses, base, all, false), all[1].qualified_name) != null);+}