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.mdnew file mode 100644index 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.mdindex 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 onediff --git a/src/agent.zig b/src/agent.zigindex 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 catalogtodos: 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.zigindex 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: Providepub fn toolsJson(self: *const Agent) []const u8 {if (self.sub) {+ if (self.worker_tools.len != 0) return self.worker_tools; // ADR 0227if (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.zigindex 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: []constconst 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 0227try 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.zigindex 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.zignew file mode 100644index 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 = ®istry,+ };+ 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]));+}