Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

subagent: a child inherits the MCP tools its root loaded

justrach5fcf6a2ca9d6
diff --git a/docs/adr/0227-children-inherit-the-roots-loaded-mcp-tools.md b/docs/adr/0227-children-inherit-the-roots-loaded-mcp-tools.md
new file mode 100644
index 00000000..460e23bb
--- /dev/null
+++ b/docs/adr/0227-children-inherit-the-roots-loaded-mcp-tools.md
@@ -0,0 +1,40 @@
+# 0227. Children inherit the MCP tools their root loaded
+
+Status: accepted 2026-10-01
+
+## Context
+
+A child is served a fixed, comptime-baked catalog (`schema.subToolsJson`)
+with no MCP tools and no load tool. A root that loaded a server's tools and
+delegated work on them spawned children that could not call them. Each child
+reported the tools missing, and the root either did the work itself or
+re-spawned children that spoke the server's JSON-RPC by hand through a
+shell. On a task that splits MCP calls across two children, that was the
+largest wall-time gap against a reference harness.
+
+A child's provider slots (`tools_anthropic`, `tools_responses`, ...) default
+to the static catalogs, so `agent_catalog.ensureRootTools` returns before it
+builds anything for a child. A per-child catalog cannot hang off an empty
+slot.
+
+## Decision
+
+- `worker_mcp.inherit` runs once as `subagent_run` builds a child, a resumed
+ worker included. Whatever catalog the child would be served gains an entry,
+ with its full schema, for each MCP tool the root has loaded
+ (`mcp_schema_gate.isLoaded`). The result lives in `Agent.worker_tools`,
+ which `toolsJson` serves first.
+- Tools the root has not loaded stay out, and a child still has no load tool.
+- A child's request keeps every tool it lists: the `additional_tools`
+ announcement path (ADR 0221) is root-only.
+
+## Consequences
+
+A child can call what its root loaded, so split MCP work runs in parallel
+instead of serially in the root. Each child request carries those schemas;
+a child's catalog is fixed for its run, so its prompt cache holds. A
+write-capable tool the root loaded reaches its children too, under the same
+approvals. The licensed worker catalog in `ensureRootTools` hits the same
+default slots and still never builds for a child; turning it on needs its
+own change, because that render also drops the folded natives a child
+cannot load.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 69c5e3f7..11755d97 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -253,6 +253,7 @@ record only when you need the evidence or the edge cases.
| [0224](0224-six-rare-natives-join-the-fold.md) | `render_html`, `agent_message`, `install_agent_tool`, `read_tool_result`, `subagent_resume` and `schedule_task` join `native_fold.folded`: listed by `load_tool_schemas`, auto-loaded on a confident call, no longer paid on every request. |
| [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. |
## When to write one
diff --git a/src/agent.zig b/src/agent.zig
index 0a947dcb..2316ed89 100644
--- a/src/agent.zig
+++ b/src/agent.zig
@@ -183,6 +183,7 @@ pub const Agent = struct {
tools_openai: []const u8 = schema.tools_openai_sub,
tools_responses: []const u8 = schema.tools_responses_sub,
tools_interactions: []const u8 = @import("schema_interactions.zig").tools_interactions_sub,
+ worker_tools: []const u8 = "", // ADR 0227: a spawned child's catalog plus the MCP tools its root loaded (worker_mcp.inherit); empty = the static child catalog
todos: std.ArrayList(TodoItem) = .empty,
eval_cmd: ?[]const u8 = null, // --eval: shell command that scores the current output (eval-driven loop)
eval_target: u8 = 90, // --until: stop when the score reaches this (0-100)
@@ -289,9 +290,7 @@ pub const Agent = struct {
pub fn toolsJson(self: *const Agent) []const u8 {
return @import("agent_catalog.zig").toolsJson(self);
}
- pub fn ensureRootTools(self: *Agent, kind: Provider.Kind) !void {
- return @import("agent_catalog.zig").ensureRootTools(self, kind);
- }
+ pub const ensureRootTools = @import("agent_catalog.zig").ensureRootTools;
pub const invalidateRootTools = @import("agent_catalog.zig").invalidateRootTools;
pub noinline fn ensureModelCatalog(self: *Agent, keys: provider_mod.Keys) void {
if (self.model_catalog) |*catalog|
diff --git a/src/agent_catalog.zig b/src/agent_catalog.zig
index ef34b4bf..455a192e 100644
--- a/src/agent_catalog.zig
+++ b/src/agent_catalog.zig
@@ -28,6 +28,7 @@ fn withExtras(arena: Allocator, base: []const schema.ToolSpec, provider: Provide
pub fn toolsJson(self: *const Agent) []const u8 {
if (self.sub) {
+ if (self.worker_tools.len != 0) return self.worker_tools; // ADR 0227
if (main_mod.g_codedbpro_licensed) return slot(self);
return schema.subToolsJson(self.provider.kind, no_local_tools.enabled);
}
diff --git a/src/subagent_run.zig b/src/subagent_run.zig
index 506d4ba0..4921a8cc 100644
--- a/src/subagent_run.zig
+++ b/src/subagent_run.zig
@@ -390,6 +390,7 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
const tasked = try @import("subagent_brief.zig").prepare(arena, ctx.io, kind, prompt, ctx.agent_cwd, main_mod.g_hooks.pre_tool);
const task_prompt = playbook.rideBrief(ctx.io, arena, try goal_pacing.childTaskPrompt(arena, tasked, ctx.loop_deadline_ms, util.unixMs(ctx.io)));
try @import("subagent_retained.zig").restore(&agent, ctx);
+ @import("worker_mcp.zig").inherit(&agent); // ADR 0227
try agent.messages.append(try textMessage(arena, "user", task_prompt));
defer agent.tools_used.deinit(gpa);
// Retry transient failures against the same child history.
diff --git a/src/test_hooks.zig b/src/test_hooks.zig
index 3b48b6a8..c852dae1 100644
--- a/src/test_hooks.zig
+++ b/src/test_hooks.zig
@@ -330,6 +330,7 @@ test {
_ = retry_hint;
_ = agent_compact_summary_test;
_ = side_question_tests;
+ _ = @import("worker_mcp.zig"); // ADR 0227
_ = @import("cache_key_tests.zig"); // ADR 0223: moved off http_headers.zig (600-line cap)
_ = @import("mcp_shapes_tests.zig"); // ADR 0225: moved off mcp_shapes.zig (600-line cap)
_ = json_controls;
diff --git a/src/worker_mcp.zig b/src/worker_mcp.zig
new file mode 100644
index 00000000..2fae3021
--- /dev/null
+++ b/src/worker_mcp.zig
@@ -0,0 +1,108 @@
+//! ADR 0227: a child's catalog carries the MCP tools its root loaded.
+//!
+//! A worker is served a fixed, comptime-baked catalog. A root that loaded an
+//! MCP server's tools and delegated work on them got children that could not
+//! call them: each child reported the tools missing, and the root re-spawned
+//! children to speak the server's JSON-RPC by hand. Loading is the root's
+//! decision to use a server, so its children inherit what it loaded, with full
+//! schemas and no meta tool. Unloaded tools stay out.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const mcp = @import("mcp.zig");
+const mcp_schema_gate = @import("mcp_schema_gate.zig");
+const schema = @import("schema.zig");
+const Provider = @import("provider.zig").Provider;
+const Agent = @import("agent.zig").Agent;
+
+/// subagent_run calls this once as it builds a child: whatever catalog the
+/// child would be served gains the MCP tools the root loaded. A resumed worker
+/// is rebuilt through the same path, so it also picks up later loads.
+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);
+ 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 {
+ 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;
+ schema.writeToolEntry(&s, kind, t.qualified_name, t.description, .{ .value = t.input_schema }) catch return base;
+ n += 1;
+ }
+ s.endArray() catch return base;
+ if (n == 0) return base;
+ const extra = aw.writer.buffered();
+ const head = std.mem.trimEnd(u8, base, " \t\r\n");
+ if (head.len < 2 or head[head.len - 1] != ']') return base;
+ if (std.mem.trim(u8, head[1 .. head.len - 1], " \t\r\n").len == 0) return extra;
+ return std.fmt.allocPrint(arena, "{s},{s}]", .{ head[0 .. head.len - 1], extra[1 .. extra.len - 1] }) catch base;
+}
+
+test "a child's catalog gains the MCP tools the root loaded, and only those" {
+ 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);
+ const base = "[{\"type\":\"function\",\"name\":\"shell\"}]";
+ try std.testing.expectEqualStrings(base, withLoaded(a, .responses, base, all)); // 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 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);
+ try std.testing.expectEqual(@as(usize, 1), (try std.json.parseFromSliceLeaky(std.json.Value, a, alone, .{})).array.items.len);
+}
+
+test "a spawned child's catalog carries the tools its root loaded" {
+ // A child starts with the static catalogs in its provider slots, so a build
+ // that waited for an empty slot never ran: the live child saw no loaded tool.
+ 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 = &.{} };
+ var registry = mcp.Registry.empty(std.testing.allocator, std.testing.io);
+ defer registry.deinit();
+ const all = try @import("mcp_schema_gate_tests.zig").fixture(a, "wiki", 2, 200);
+ registry.tools = all;
+ var child: Agent = .{
+ .gpa = std.testing.allocator,
+ .arena = a,
+ .io = std.testing.io,
+ .client = undefined,
+ .provider = .{ .id = "codex", .kind = .responses, .auth = .bearer, .url = "", .api_key = "", .model = "gpt-6.1-sol", .context = 272_000 },
+ .messages = undefined,
+ .sub = true,
+ .label = "child",
+ .out = null,
+ .registry = &registry,
+ };
+ const static = child.toolsJson();
+ inherit(&child); // nothing loaded: the static catalog, untouched
+ try std.testing.expectEqualStrings(static, child.toolsJson());
+ mcp_schema_gate.autoLoad(a, all, all[1].qualified_name);
+ inherit(&child);
+ const got = child.toolsJson();
+ try std.testing.expect(std.mem.indexOf(u8, got, all[1].qualified_name) != null);
+ 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]));
+}