Skip to content

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

Python

mcp: a slimmed result keeps the full payload behind a handle

justrachf75e08271a4d
diff --git a/docs/adr/0225-mcp-load-result-states-the-slim-rule.md b/docs/adr/0225-mcp-load-result-states-the-slim-rule.md
index f1ed600b..ebd816c3 100644
--- a/docs/adr/0225-mcp-load-result-states-the-slim-rule.md
+++ b/docs/adr/0225-mcp-load-result-states-the-slim-rule.md
@@ -15,14 +15,23 @@ A hill-climb round against a reference harness measured stating the rule on
the load result: cost per task fell on the train and the held-out split, wall
time fell, and pass rate held.
+The slim was also lossy: a caller that needed a dropped field (a body, a
+state, a label) could not get it back.
+
## Decision
-`mcp_shapes.annotate` appends the slim rule to every `load_tool_schemas`,
-`mcp_search_tools` and `mcp_select_tool` result, whether or not shapes are
-stored. It never rides the catalog prefix (ADR 0011).
+- `mcp_shapes.annotate` appends the slim rule to every `load_tool_schemas`,
+ `mcp_search_tools` and `mcp_select_tool` result, whether or not shapes are
+ stored. It never rides the catalog prefix (ADR 0011).
+- A direct call's slimmed result keeps the full payload as a tool-result
+ handle (`tool_handle.keep`, the #440 store and run budget) and names it, so
+ `read_tool_result` reads any dropped field (`mcp_shapes.takeSlimKept`).
+- A host call from inside an rlm script (`ToolCtx.rlm_host`) binds the plain
+ slim JSON, because `each`, `project` and `write_file` parse it. The rule says
+ so: for a dropped field, call the tool directly.
## Consequences
-Each MCP load result carries one more sentence. The slim itself is unchanged:
-a caller that needs a dropped field still cannot get it, which is a separate
-decision about ADR 0029.
+Each MCP load result carries one more sentence, and each slimmed direct result
+one more line plus a handle file under `.graff/tool-results/`. When the run's
+handle budget is spent, the slim falls back to the plain cut.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index c44bf839..dc433af8 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -247,7 +247,7 @@ record only when you need the evidence or the edge cases.
| [0218](0218-background-jobs-survive-a-crash.md) | A finite root job started in the background writes its output to `.graff/job-output/<id>/` with an exit receipt from its own shell, so it outlives a crashed graff. Loading the session re-attaches this session's unreported jobs under their old ids, reports what ended while graff was down, and sweeps other sessions' stale captures. Foreground commands, servers, subagent jobs and Windows keep pipes. |
| [0219](0219-claude-5-5-era-request-contract.md) | Claude Opus 5.5, Sonnet 5.5 and Fable 5.1 are never forced to a tool, get `drop_block` thinking binding (with its beta header), take `/effort` as `output_config.effort` (left off at graff's default), and get 64K/128K `max_tokens`. Claude errors take the same retry-without ladder as other providers; a refusal ends the turn outside history. Default model `claude-opus-5-5`, ladder opus-5-5 → sonnet-5-5. |
| [0220](0220-claude-prompt-cache-forks-and-pricing.md) | On the Anthropic API, compaction's note and summary fork the conversation while its cache is warm. They use the same tools, system prompt and history, with the instruction appended, so they read the history instead of rewriting it. Otherwise the old shape runs without breakpoints. A turn-opening request keeps the TTL of the last gap inside a turn. 1-hour writes bill at 2x. 5.5-era models get graff's effort as shown; titles and recaps run at low. A second breakpoint marks where the previous request wrote. |
-| [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. Never on the catalog prefix. |
+| [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. |
## When to write one
diff --git a/src/exec.zig b/src/exec.zig
index 82db1d54..a1d22f8b 100644
--- a/src/exec.zig
+++ b/src/exec.zig
@@ -189,7 +189,8 @@ fn execToolInner(ctx: ToolCtx, call: ToolCall) !ToolOutput {
if (!r.is_error) {
const shapes = @import("mcp_shapes.zig");
shapes.remember(ctx, call.name, r.text);
- return .{ .text = shapes.takeSlim(gpa, r.text), .is_error = false };
+ const keep_in: ?@import("tool_handle.zig").Target = if (ctx.rlm_host) null else .{ .io = io, .dir = .cwd() };
+ return .{ .text = shapes.takeSlimKept(gpa, keep_in, r.text), .is_error = false };
}
return .{ .text = r.text, .is_error = r.is_error };
}
diff --git a/src/mcp_shapes.zig b/src/mcp_shapes.zig
index 968ad9af..5dd59355 100644
--- a/src/mcp_shapes.zig
+++ b/src/mcp_shapes.zig
@@ -8,6 +8,7 @@ const Value = std.json.Value;
const Allocator = std.mem.Allocator;
const tools = @import("tools.zig");
+const tool_handle = @import("tool_handle.zig");
const ToolCtx = tools.ToolCtx;
pub const file_name = "mcp-shapes.json";
@@ -316,6 +317,22 @@ pub fn takeSlim(gpa: Allocator, text: []u8) []u8 {
return cut;
}
+/// ADR 0225: `takeSlim`, lossless. With `keep_in` the full payload is kept as
+/// a tool-result handle that the slim result names, so a dropped field is one
+/// read_tool_result away. Null (an rlm bind, which each/project/write_file
+/// parse as JSON) or a failed write returns the plain cut.
+pub fn takeSlimKept(gpa: Allocator, keep_in: ?tool_handle.Target, text: []u8) []u8 {
+ const cut = slim(gpa, text) orelse return text;
+ defer gpa.free(text);
+ const target = keep_in orelse return cut;
+ var arena_state = std.heap.ArenaAllocator.init(gpa);
+ defer arena_state.deinit();
+ const path = tool_handle.keep(arena_state.allocator(), target, text) orelse return cut;
+ const out = std.fmt.allocPrint(gpa, "{s}\n[slimmed from {d} bytes; the full result is handle {s} (read_tool_result reads any dropped field)]", .{ cut, text.len, tool_handle.idOf(path) }) catch return cut;
+ gpa.free(cut);
+ return out;
+}
+
fn arrayItems(v: Value) ?[]const Value {
if (v == .array) return v.array.items;
if (v != .object) return null;
@@ -450,7 +467,7 @@ pub fn annotate(gpa: Allocator, arena: Allocator, io: Io, cwd: ?[]const u8, text
/// where the model first meets the tools. Unsaid, the model wrote code for
/// the full rows, failed on the first missing field, and spent calls finding
/// the real shape.
-pub const slim_rule = "\nLarge list results from these tools come back slimmed, in rlm binds too: rows keep only id/identifier/title/name, and a comment list becomes {\"n\": count, \"latest_author\": name}. Code against those fields.";
+pub const slim_rule = "\nLarge list results from these tools come back slimmed: rows keep only id/identifier/title/name, and a comment list becomes {\"n\": count, \"latest_author\": name}. Code against those fields. A direct call's result names a handle holding the full result; rlm binds stay slimmed.";
pub fn lookup(io: Io, name: []const u8) ?[]const u8 {
store.mu.lockUncancelable(io);
@@ -530,33 +547,6 @@ test "remember merges keys; annotate splices shapes; prefix text is untouched" {
try std.testing.expect(std.mem.indexOf(u8, @import("rlm.zig").tool_desc, "muscle:") == null);
}
-test "slim drops description/body; comments fold to n and latest_author" {
- const gpa = std.testing.allocator;
- try std.testing.expect(slim(gpa, "[{\"id\":1}]") == null);
- const pad: [400]u8 = @splat('x');
- const pad_s: []const u8 = &pad;
- const issues = try std.fmt.allocPrint(gpa, "[{{\"id\":\"ISS-1\",\"identifier\":\"ENG-101\",\"title\":\"Login\",\"description\":\"{s}\",\"body\":\"KEEP-OUT\"}},{{\"id\":\"ISS-2\",\"identifier\":\"ENG-102\",\"title\":\"Tax\",\"description\":\"{s}\"}}]", .{ pad_s, pad_s });
- defer gpa.free(issues);
- const cut = slim(gpa, issues) orelse return error.ExpectedSlim;
- defer gpa.free(cut);
- try std.testing.expect(std.mem.indexOf(u8, cut, "ISS-1") != null);
- try std.testing.expect(std.mem.indexOf(u8, cut, "ENG-101") != null);
- try std.testing.expect(std.mem.indexOf(u8, cut, "Login") != null);
- try std.testing.expect(std.mem.indexOf(u8, cut, "description") == null);
- try std.testing.expect(std.mem.indexOf(u8, cut, "KEEP-OUT") == null);
- try std.testing.expect(std.mem.indexOf(u8, cut, pad_s) == null);
-
- const comments = try std.fmt.allocPrint(gpa, "[{{\"body\":\"old {s}\",\"author\":{{\"name\":\"ada\"}},\"createdAt\":\"2026-08-11T01:00:00Z\"}},{{\"body\":\"new {s}\",\"author\":{{\"name\":\"bev\"}},\"createdAt\":\"2026-08-12T02:00:00Z\"}}]", .{ pad_s, pad_s });
- defer gpa.free(comments);
- const folded = slim(gpa, comments) orelse return error.ExpectedCommentSlim;
- defer gpa.free(folded);
- try std.testing.expect(std.mem.indexOf(u8, folded, "\"n\":2") != null);
- try std.testing.expect(std.mem.indexOf(u8, folded, "bev") != null);
- try std.testing.expect(std.mem.indexOf(u8, folded, "ada") == null);
- try std.testing.expect(std.mem.indexOf(u8, folded, "old ") == null);
- try std.testing.expect(std.mem.indexOf(u8, folded, pad_s) == null);
-}
-
test "annotate writes a muscle playbook once two MCP shapes are stored" {
const gpa = std.testing.allocator;
const io = std.testing.io;
diff --git a/src/mcp_shapes_tests.zig b/src/mcp_shapes_tests.zig
index 41612b54..3428dafe 100644
--- a/src/mcp_shapes_tests.zig
+++ b/src/mcp_shapes_tests.zig
@@ -20,3 +20,59 @@ test "annotate states the slim rule on every load result, stored shapes or not"
try std.testing.expect(std.mem.indexOf(u8, annotated, "return_shapes") == null); // nothing stored yet
try std.testing.expect(std.mem.indexOf(u8, @import("mcp_schema_gate.zig").tool_desc, "come back slimmed") == null); // never the prefix
}
+
+test "slim drops description/body; comments fold to n and latest_author" {
+ const gpa = std.testing.allocator;
+ try std.testing.expect(shapes.slim(gpa, "[{\"id\":1}]") == null);
+ const pad: [400]u8 = @splat('x');
+ const pad_s: []const u8 = &pad;
+ const issues = try std.fmt.allocPrint(gpa, "[{{\"id\":\"ISS-1\",\"identifier\":\"ENG-101\",\"title\":\"Login\",\"description\":\"{s}\",\"body\":\"KEEP-OUT\"}},{{\"id\":\"ISS-2\",\"identifier\":\"ENG-102\",\"title\":\"Tax\",\"description\":\"{s}\"}}]", .{ pad_s, pad_s });
+ defer gpa.free(issues);
+ const cut = shapes.slim(gpa, issues) orelse return error.ExpectedSlim;
+ defer gpa.free(cut);
+ try std.testing.expect(std.mem.indexOf(u8, cut, "ISS-1") != null);
+ try std.testing.expect(std.mem.indexOf(u8, cut, "ENG-101") != null);
+ try std.testing.expect(std.mem.indexOf(u8, cut, "Login") != null);
+ try std.testing.expect(std.mem.indexOf(u8, cut, "description") == null);
+ try std.testing.expect(std.mem.indexOf(u8, cut, "KEEP-OUT") == null);
+ try std.testing.expect(std.mem.indexOf(u8, cut, pad_s) == null);
+
+ const comments = try std.fmt.allocPrint(gpa, "[{{\"body\":\"old {s}\",\"author\":{{\"name\":\"ada\"}},\"createdAt\":\"2026-08-11T01:00:00Z\"}},{{\"body\":\"new {s}\",\"author\":{{\"name\":\"bev\"}},\"createdAt\":\"2026-08-12T02:00:00Z\"}}]", .{ pad_s, pad_s });
+ defer gpa.free(comments);
+ const folded = shapes.slim(gpa, comments) orelse return error.ExpectedCommentSlim;
+ defer gpa.free(folded);
+ try std.testing.expect(std.mem.indexOf(u8, folded, "\"n\":2") != null);
+ try std.testing.expect(std.mem.indexOf(u8, folded, "bev") != null);
+ try std.testing.expect(std.mem.indexOf(u8, folded, "ada") == null);
+ try std.testing.expect(std.mem.indexOf(u8, folded, "old ") == null);
+ try std.testing.expect(std.mem.indexOf(u8, folded, pad_s) == null);
+}
+
+test "a direct call's slim result names a handle holding the full payload; an rlm bind stays plain JSON" {
+ const gpa = std.testing.allocator;
+ const io = std.testing.io;
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ const pad: [900]u8 = @splat('x');
+ const fat = try std.fmt.allocPrint(gpa, "[{{\"id\":\"ISS-1\",\"title\":\"Login\",\"description\":\"{s}\",\"state\":\"open\"}}]", .{@as([]const u8, &pad)});
+ const fat_len = fat.len;
+ const kept = shapes.takeSlimKept(gpa, .{ .io = io, .dir = tmp.dir }, fat);
+ defer gpa.free(kept);
+ try std.testing.expect(std.mem.indexOf(u8, kept, "ISS-1") != null);
+ try std.testing.expect(std.mem.indexOf(u8, kept, "\"state\"") == null); // dropped from the slim view...
+ const at = std.mem.indexOf(u8, kept, "handle tr_") orelse return error.MissingHandle;
+ const id_end = std.mem.indexOfScalarPos(u8, kept, at + 7, ' ') orelse return error.MissingHandle;
+ const rel = try std.fmt.allocPrint(gpa, ".graff/tool-results/{s}.txt", .{kept[at + 7 .. id_end]});
+ defer gpa.free(rel);
+ const whole = try tmp.dir.readFileAlloc(io, rel, gpa, .limited(1 << 20));
+ defer gpa.free(whole);
+ try std.testing.expectEqual(fat_len, whole.len); // ...but kept whole behind the handle
+ try std.testing.expect(std.mem.indexOf(u8, whole, "\"state\":\"open\"") != null);
+
+ const bind_src = try std.fmt.allocPrint(gpa, "[{{\"id\":\"ISS-2\",\"title\":\"T\",\"description\":\"{s}\"}}]", .{@as([]const u8, &pad)});
+ const bind = shapes.takeSlimKept(gpa, null, bind_src);
+ defer gpa.free(bind);
+ const parsed = try std.json.parseFromSlice(std.json.Value, gpa, bind, .{}); // rlm parses binds as JSON
+ defer parsed.deinit();
+ try std.testing.expect(std.mem.indexOf(u8, bind, "handle") == null);
+}
diff --git a/src/rlm.zig b/src/rlm.zig
index 102cbfaa..7fdb5988 100644
--- a/src/rlm.zig
+++ b/src/rlm.zig
@@ -252,7 +252,9 @@ fn runHostRaw(ctx: ToolCtx, call: spec_ptc.Call) ToolOutput {
// A denial is an error result, so the script stops here.
const host_call: tools.ToolCall = .{ .id = if (ctx.host_gate) |gate| gate.call_id else "rlm", .name = ready.name, .input = parsed.value };
if (ctx.host_gate) |gate| if (gate.check(gate.context, host_call)) |denied| return denied;
- return exec_mod.execTool(ctx, host_call);
+ var host_ctx = ctx;
+ host_ctx.rlm_host = true;
+ return exec_mod.execTool(host_ctx, host_call);
}
fn runSleep(ctx: ToolCtx, args_json: []const u8) ToolOutput {
diff --git a/src/tool_handle.zig b/src/tool_handle.zig
index cd97b2ab..2ec0f1a7 100644
--- a/src/tool_handle.zig
+++ b/src/tool_handle.zig
@@ -175,6 +175,16 @@ pub fn withFirstNote(arena: Allocator, r: Result, shown: *bool) ![]const u8 {
return std.fmt.allocPrint(arena, "{s}{s}", .{ r.text, first_note });
}
+/// ADR 0225: keep a payload whole as a handle (null when the run budget is
+/// spent or the write fails) — the lossless half of MCP result slimming.
+pub fn keep(arena: Allocator, target: Target, text: []const u8) ?[]const u8 {
+ return persist(arena, target, text);
+}
+
+pub fn idOf(path: []const u8) []const u8 {
+ return handleId(path);
+}
+
fn handleId(path: []const u8) []const u8 {
const base = std.fs.path.basename(path);
return if (std.mem.endsWith(u8, base, ".txt")) base[0 .. base.len - 4] else base;
diff --git a/src/tools.zig b/src/tools.zig
index adc580b8..4cec9811 100644
--- a/src/tools.zig
+++ b/src/tools.zig
@@ -125,6 +125,7 @@ pub const ToolCtx = struct {
registry: ?*mcp.Registry,
mcp_context: ?@import("mcp_turn_context.zig").Snapshot = null,
from_sub: bool,
+ rlm_host: bool = false, // ADR 0225: a host call from inside an rlm script (its MCP result stays plain slim JSON)
has_eval: bool = false, // the root's --eval loop: escalation's strongest verifier
approvals: ?*Approvals,
plan_read_owner: ?*const anyopaque = null,