Skip to content

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.md
new file mode 100644
index 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.md
index 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 one
diff --git a/scripts/linear_fixture_mcp.py b/scripts/linear_fixture_mcp.py
index 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.zig
index 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(&registry, call(a, "mcp__linear__list", "{}")));
+ try std.testing.expect(!readOnlyChildAllows(&registry, 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.zig
index 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 model
description: []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.zig
index 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 a
diff --git a/src/worker_mcp.zig b/src/worker_mcp.zig
index 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 yet
mcp_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);
+}