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 comment list names its issue (ADR 0257)

justrach636e0ec76e8e
diff --git a/docs/adr/0257-a-slimmed-comment-list-names-its-issue.md b/docs/adr/0257-a-slimmed-comment-list-names-its-issue.md
new file mode 100644
index 00000000..ced9a8ec
--- /dev/null
+++ b/docs/adr/0257-a-slimmed-comment-list-names-its-issue.md
@@ -0,0 +1,31 @@
+# 0257. A slimmed comment list names its issue
+
+Status: accepted 2026-10-06
+
+## Context
+
+Large MCP list results are slimmed before the model sees them (ADR 0029,
+ADR 0225): a comment list becomes `{"n": count, "latest_author": name}` and
+the full result goes to a handle. The fold dropped every field of the rows,
+including the issue they belong to.
+
+When a model fetched several issues' comments in one response, each result
+came back paired with its call, but nothing in the result itself said which
+issue it described. Handles are numbered as results complete, so in a batch
+they do not follow the order of the calls. Sub-agents on the eval tasks that
+fan out over issues reported the right counts against the wrong issues: the
+counts followed the handle numbers, not the calls.
+
+## Decision
+
+When every comment row carries the same parent id (`issueId`, `issue_id`, or
+a nested `issue.identifier` / `issue.id`), the fold keeps it first:
+`{"issue": "ISS-4", "n": 4, "latest_author": "jay"}`. Rows that disagree, or
+any row without the field, fold as before. The load note that states the slim
+rule says so.
+
+## Consequences
+
+A result names its own issue, so pairing no longer depends on call order or
+handle numbers. The fold grows by one short field when the rows carry it.
+Handles stay numbered by completion; nothing should read order into them.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 936c1dbf..cbbbc340 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -282,6 +282,7 @@ record only when you need the evidence or the edge cases.
| [0254](0254-imported-conversations-use-the-configured-route.md) | Imported Claude history uses the configured graff provider and credentials; source models are metadata, and foreign tool results remain historical receipts. |
| [0255](0255-codegraff-claude-uses-native-messages.md) | Claude aliases on codegraff use the native Messages endpoint; `isClaudeApi` is the one predicate for the real Claude wire. |
| [0256](0256-gemini-takes-fewer-requests-per-task.md) | Gemini models get a working note (chained shell steps, no read-backs, no pasted files, check computed answers) and may batch `attempt_completion` with a final check or write; the completion is recorded only if every batched call succeeded. |
+| [0257](0257-a-slimmed-comment-list-names-its-issue.md) | A slimmed MCP comment list keeps the issue id its rows share (`{issue, n, latest_author}`), so parallel results name what they describe. |
## When to write one
diff --git a/src/mcp_shapes.zig b/src/mcp_shapes.zig
index 40b48687..410329ef 100644
--- a/src/mcp_shapes.zig
+++ b/src/mcp_shapes.zig
@@ -438,36 +438,52 @@ fn latestIndex(items: []const Value) usize {
}
fn slimComments(alloc: Allocator, items: []const Value) ?[]u8 {
- const name = authorName(items[latestIndex(items)]);
var aw: Io.Writer.Allocating = .init(alloc);
- var s: std.json.Stringify = .{ .writer = &aw.writer };
- s.beginObject() catch {
- aw.deinit();
- return null;
- };
- s.objectField("n") catch {
- aw.deinit();
- return null;
- };
- s.write(items.len) catch {
- aw.deinit();
- return null;
- };
- s.objectField("latest_author") catch {
- aw.deinit();
- return null;
- };
- s.write(name orelse "") catch {
- aw.deinit();
- return null;
- };
- s.endObject() catch {
+ writeCommentFold(&aw.writer, items) catch {
aw.deinit();
return null;
};
return aw.toOwnedSlice() catch null;
}
+/// `{issue?, n, latest_author}`. `issue` is the parent every row names: the
+/// fold otherwise loses which issue a list belongs to, and a model pairing
+/// parallel results by position credited counts to the wrong issue.
+fn writeCommentFold(w: *Io.Writer, items: []const Value) !void {
+ var s: std.json.Stringify = .{ .writer = w };
+ try s.beginObject();
+ if (sharedParent(items)) |parent| {
+ try s.objectField("issue");
+ try s.write(parent);
+ }
+ try s.objectField("n");
+ try s.write(items.len);
+ try s.objectField("latest_author");
+ try s.write(authorName(items[latestIndex(items)]) orelse "");
+ try s.endObject();
+}
+
+/// The one parent id every row carries (`issueId`, `issue_id`, or a nested
+/// `issue.identifier` / `issue.id`), or null when rows disagree or omit it.
+fn sharedParent(items: []const Value) ?[]const u8 {
+ for ([_][2][]const u8{ .{ "issueId", "" }, .{ "issue_id", "" }, .{ "issue", "identifier" }, .{ "issue", "id" } }) |path| {
+ var shared: ?[]const u8 = null;
+ for (items) |item| {
+ const v = parentField(item, path[0], path[1]) orelse break;
+ if (shared) |prev| if (!std.mem.eql(u8, prev, v)) break;
+ shared = v;
+ } else if (shared) |v| return v;
+ }
+ return null;
+}
+
+fn parentField(item: Value, key: []const u8, sub: []const u8) ?[]const u8 {
+ if (item != .object) return null;
+ var v = item.object.get(key) orelse return null;
+ if (sub.len > 0) v = if (v == .object) (v.object.get(sub) orelse return null) else return null;
+ return if (v == .string) v.string else null;
+}
+
fn authorName(item: Value) ?[]const u8 {
if (item != .object) return null;
const author = item.object.get("author") orelse return null;
@@ -547,7 +563,7 @@ pub fn annotate(gpa: Allocator, arena: Allocator, io: Io, cwd: ?[]const u8, text
/// the full rows, failed on the first missing field, and spent calls finding
/// the real shape. ADR 0238: rlm binds keep every field; only print() slims.
/// ADR 0240: computing over the results happens in the same script.
-pub const slim_rule = "\nLarge list results from these tools are shown slimmed: rows keep only id/identifier/title/name, and a comment list becomes {\"n\": count, \"latest_author\": name}. A direct call's result names a handle holding the full result. In rlm a bind keeps every field: print() shows the slim view, project(x, field) reads any field, and write_file(\"f.json\", x) saves the whole result for a script. To compute over results in the same call, save them and run the computation inside the script: issues = tool(); write_file(\"issues.json\", issues); r = bash(\"python3 - <<'EOF'\\n...\\nEOF\"); print(r).";
+pub const slim_rule = "\nLarge list results from these tools are shown slimmed: rows keep only id/identifier/title/name, and a comment list becomes {\"issue\": its issue when the comments name one, \"n\": count, \"latest_author\": name}. A direct call's result names a handle holding the full result. In rlm a bind keeps every field: print() shows the slim view, project(x, field) reads any field, and write_file(\"f.json\", x) saves the whole result for a script. To compute over results in the same call, save them and run the computation inside the script: issues = tool(); write_file(\"issues.json\", issues); r = bash(\"python3 - <<'EOF'\\n...\\nEOF\"); print(r).";
pub fn lookup(io: Io, name: []const u8) ?[]const u8 {
store.mu.lockUncancelable(io);
diff --git a/src/mcp_shapes_tests.zig b/src/mcp_shapes_tests.zig
index 96acdcac..cb436146 100644
--- a/src/mcp_shapes_tests.zig
+++ b/src/mcp_shapes_tests.zig
@@ -202,3 +202,28 @@ test "the slim rule says to compute inside the same script (ADR 0240)" {
try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "run the computation inside the script") != null);
try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "write_file(\"issues.json\", issues)") != null);
}
+
+test "a comment fold names the issue every row shares, and only then" {
+ const gpa = std.testing.allocator;
+ const pad: [400]u8 = @splat('x');
+ const pad_s: []const u8 = &pad;
+ const shared = try std.fmt.allocPrint(gpa, "[{{\"issueId\":\"ISS-4\",\"body\":\"{s}\",\"author\":{{\"name\":\"gus\"}},\"createdAt\":\"2026-08-11\"}},{{\"issueId\":\"ISS-4\",\"body\":\"{s}\",\"author\":{{\"name\":\"jay\"}},\"createdAt\":\"2026-08-12\"}}]", .{ pad_s, pad_s });
+ defer gpa.free(shared);
+ const folded = shapes.slim(gpa, shared) orelse return error.ExpectedCommentSlim;
+ defer gpa.free(folded);
+ try std.testing.expectEqualStrings("{\"issue\":\"ISS-4\",\"n\":2,\"latest_author\":\"jay\"}", folded);
+
+ const nested = try std.fmt.allocPrint(gpa, "[{{\"issue\":{{\"id\":\"u1\",\"identifier\":\"ENG-7\"}},\"body\":\"{s}\",\"author\":\"ada\"}},{{\"issue\":{{\"id\":\"u1\",\"identifier\":\"ENG-7\"}},\"body\":\"{s}\",\"author\":\"bev\"}}]", .{ pad_s, pad_s });
+ defer gpa.free(nested);
+ const nested_fold = shapes.slim(gpa, nested) orelse return error.ExpectedCommentSlim;
+ defer gpa.free(nested_fold);
+ try std.testing.expect(std.mem.startsWith(u8, nested_fold, "{\"issue\":\"ENG-7\","));
+
+ // Rows that disagree, or a row without the key, name no issue.
+ const mixed = try std.fmt.allocPrint(gpa, "[{{\"issueId\":\"ISS-1\",\"body\":\"{s}\",\"author\":\"ada\"}},{{\"issueId\":\"ISS-2\",\"body\":\"{s}\",\"author\":\"bev\"}},{{\"body\":\"{s}\",\"author\":\"cam\"}}]", .{ pad_s, pad_s, pad_s });
+ defer gpa.free(mixed);
+ const mixed_fold = shapes.slim(gpa, mixed) orelse return error.ExpectedCommentSlim;
+ defer gpa.free(mixed_fold);
+ try std.testing.expect(std.mem.indexOf(u8, mixed_fold, "issue") == null);
+ try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "\"issue\"") != null);
+}