graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Fewer requests per task for one model family (ADR 0256)
justrache850e83e25e7
diff --git a/docs/adr/0256-gemini-takes-fewer-requests-per-task.md b/docs/adr/0256-gemini-takes-fewer-requests-per-task.mdnew file mode 100644index 00000000..82227594--- /dev/null+++ b/docs/adr/0256-gemini-takes-fewer-requests-per-task.md@@ -0,0 +1,65 @@+# 0256. Gemini takes fewer requests per task++Status: accepted 2026-10-06++## Context++On the hosted route every Gemini request carries graff's system prompt and+tool catalog again, and each one takes several seconds. A task's wall time and+cost therefore follow its request count far more than its output.++Traces of the core and MCP eval suites showed requests the work did not need:+reading back a file the model had just written or a script had produced, a+separate request for a step that could have chained onto the previous command,+and a last request whose only call was `attempt_completion`. Final answers+also pasted whole files the task had already written to disk.++The harness already accepted `attempt_completion` in the same response as a+read or a check: it ran the check first and withdrew the completion if the+check failed (ADR 0024). The model was never told, and a write in the same+response refused the completion outright. Telling the model through the tool+description alone changed nothing; it batched only when the system prompt+asked it to.++## Decision++For `gemini-` model ids, on any provider:++- The system prompt ends with a short working note: run dependent shell steps+ as one command (writing exact text with `printf`, since `echo -n` under a+ POSIX `sh` prints the flag), treat a write's own result as its evidence, name files+ instead of pasting them into the final answer, call `attempt_completion` in+ the same response as the final check or write, and check a computed answer+ against every condition the task states before writing it.+- `attempt_completion`'s description says the same. A batched `edit_file` or+ `write_file` is held to the rule a check already followed: the batch runs+ first (serially and in the order sent, because it writes) and the+ completion is recorded only if every call succeeded. `rlm`, `subagent` and+ mutating MCP calls still refuse a batched completion.+- Switching between this family and another model rebuilds the root catalog,+ so the description follows the model.++Other models are unchanged. Sub-agents get the note; their catalogs are fixed+at build time and keep the old description.++## Consequences++In interleaved eval rounds on the hosted route the core and MCP suites took+about a third fewer requests and a third less wall time per task, and cost+about a quarter less, with pass rates unchanged; the held-out swe, scatter+and sub-agent suites moved the same way.++A completion batched with a write is recorded without a separate look at the+result. That is what the work note already asked for after a successful+write, and a failed write still withdraws the completion.++Fewer requests also meant fewer second looks. On a count whose naive pattern+also matches a longer token with the same prefix, the model's first command+was wrong in every arm; without the note it looked at the data again and+corrected it, with the first note it wrote the wrong count at once and nearly+always missed. Two lines of that note went: one said to inspect data only+after a step failed, and one treated a command's printed output, not only a+write, as its own evidence. The last line, check a computed answer against+the task's conditions and print what matched, recovered most of those runs for+about one request each. Revisit the note if misses of that kind return, and+the description if another model family shows the same request pattern.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 56e8ceab..936c1dbf 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -281,6 +281,7 @@ record only when you need the evidence or the edge cases.| [0253](0253-an-interactive-session-signs-in-to-chatgpt-again.md) | When a ChatGPT request is rejected and the refresh cannot replace the token, an interactive root session opens the browser sign-in, waits up to three minutes and retries once; `-p`, piped, `--json`, ACP and sub-agents never do. One unfinished sign-in ends it for the process. || [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. |## When to write onediff --git a/src/agent_catalog.zig b/src/agent_catalog.zigindex cb221147..9f7ad7cd 100644--- a/src/agent_catalog.zig+++ b/src/agent_catalog.zig@@ -90,7 +90,8 @@ pub fn ensureRootTools(self: *Agent, kind: Provider.Kind) !void {const snapshot = try registry.snapshotTools(self.arena);break :blk if (self.sub) try surface.filterWorkerMcp(self.arena, snapshot) else snapshot;} else &.{};- dest.* = try @import("shell_tool.zig").withPython(self.arena, try schema.renderRootTools(self.arena, kind, specs, connected)); // ADR 0242+ const rendered = try @import("shell_tool.zig").withPython(self.arena, try schema.renderRootTools(self.arena, kind, specs, connected)); // ADR 0242+ dest.* = try @import("gemini_turns.zig").withCompletionBatch(self.arena, rendered, self.provider.model); // ADR 0256}test "invalidate without ensure leaves toolsJson empty; rebuild is a JSON array" {diff --git a/src/agent_eval_control.zig b/src/agent_eval_control.zigindex 242b7e0c..1daeb64a 100644--- a/src/agent_eval_control.zig+++ b/src/agent_eval_control.zig@@ -47,9 +47,16 @@ pub fn toolInvalidatesEval(call: ToolCall) bool {/// may fail. bash/read/codedb are verify/read — they run first, then/// completion is accepted only if none failed (ADR 0024 turn tax vs grok).pub fn batchBlocksCompletion(calls: []const ToolCall) bool {+ return batchBlocksCompletionFor(calls, false);+}++/// `writes_complete` (ADR 0256): edit_file and write_file are held to the+/// verify rule instead — they run first and completion follows only if they+/// succeeded. rlm, subagent and mutating MCP calls still refuse.+pub fn batchBlocksCompletionFor(calls: []const ToolCall, writes_complete: bool) bool {for (calls) |call| {- if (std.mem.eql(u8, call.name, "edit_file") or- std.mem.eql(u8, call.name, "write_file") or+ if ((!writes_complete and (std.mem.eql(u8, call.name, "edit_file") or+ std.mem.eql(u8, call.name, "write_file"))) orstd.mem.eql(u8, call.name, "rlm") orstd.mem.eql(u8, call.name, "subagent")) return true;if (std.mem.startsWith(u8, call.name, "mcp__") and !companionReadOnly(call.name, call.input)) return true;@@ -68,8 +75,12 @@ pub fn completionIndex(calls: []const ToolCall) ?usize {/// and no workspace mutation. runTools executes those tools first, then/// accepts completion only if none failed.pub fn shouldDeferCompletion(calls: []const ToolCall) bool {+ return shouldDeferCompletionFor(calls, false);+}++pub fn shouldDeferCompletionFor(calls: []const ToolCall, writes_complete: bool) bool {if (completionIndex(calls) == null) return false;- if (batchBlocksCompletion(calls)) return false;+ if (batchBlocksCompletionFor(calls, writes_complete)) return false;for (calls) |call| {if (!isMetaName(call.name)) return true;}diff --git a/src/agent_tools.zig b/src/agent_tools.zigindex 3b097bf1..e093c80a 100644--- a/src/agent_tools.zig+++ b/src/agent_tools.zig@@ -74,8 +74,10 @@ pub fn runTools(self: *Agent, calls: []const ToolCall) ![]ExecResult {const results = try self.arena.alloc(ExecResult, calls.len);if (try @import("turn_handoff.zig").rejectMixedBatch(self, calls, results)) return results;const eval_index = eval_control.evalCallIndex(calls);- const blocks_completion = eval_control.batchBlocksCompletion(calls);- const defer_completion = eval_control.shouldDeferCompletion(calls);+ // ADR 0256: only a batch that completes needs the model family.+ const writes_complete = eval_control.completionIndex(calls) != null and @import("gemini_turns.zig").family(self.provider.model);+ const blocks_completion = eval_control.batchBlocksCompletionFor(calls, writes_complete);+ const defer_completion = eval_control.shouldDeferCompletionFor(calls, writes_complete);// Collect the indices of external (non-meta) calls for parallel exec.var ext_idx: std.ArrayList(usize) = .empty;diff --git a/src/gemini_turns.zig b/src/gemini_turns.zignew file mode 100644index 00000000..b38ab2f8--- /dev/null+++ b/src/gemini_turns.zig@@ -0,0 +1,71 @@+//! ADR 0256: Gemini models finish a task in fewer model requests.+//!+//! On the hosted route each Gemini request carries the system prompt and the+//! tool catalog again, so a task's cost and wall time follow its request+//! count. Traces showed requests the work did not need: reading back a file+//! the model had just written, a separate request for a command that could+//! have chained onto the previous one, and a last request whose only call was+//! attempt_completion.+//!+//! For these models only:+//! - A working note asks for chained shell steps, no read-backs, and a final+//! answer that names files instead of pasting them.+//! - attempt_completion may share a response with the last write or edit, as+//! it already could with a final check. The harness runs the other calls+//! first (a batch with a write runs serially, in the order sent) and records+//! the completion only if every one of them succeeded, so the claim still+//! follows evidence. The tool description says so.++const std = @import("std");++/// A Gemini model id, bare or behind a `vendor/` prefix.+pub fn family(model: []const u8) bool {+ const bare = model[if (std.mem.lastIndexOfScalar(u8, model, '/')) |i| i + 1 else 0..];+ return std.ascii.startsWithIgnoreCase(bare, "gemini-");+}++/// Appended to the system prompt by prompt_guidance.append.+pub const note =+ \\+ \\# Working guidance+ \\Each model request takes seconds, so finish in as few responses as the work allows:+ \\- Run dependent shell steps as one command (`a && b`), cleanup of temporary files included; to write exact text from the shell use `printf`, not `echo -n`.+ \\- A write's own result is its evidence: do not read back or list a file you just wrote.+ \\- The final answer names the files and the key result; never paste a file's contents into it.+ \\- Call attempt_completion in the same response as your final check or write: the harness runs those first and records the completion only if they succeed.+ \\- Before you write a computed answer, check it against every condition the task states (exact tokens, exclusions, formats): print what matched, not only a count.+;++/// Added to attempt_completion's description on these models.+pub const completion_batch = " You may call it in the same response as your final check (a test run or other command): the harness runs that check first and records the completion only if it succeeds; if it fails you get its result instead. The same holds for a final write_file or edit_file when nothing after it needs checking: the completion is recorded only if the write succeeds.";++/// A rendered root catalog with attempt_completion's description extended+/// for this model (the shell_tool.withPython pattern). Other models, and a+/// catalog without the full description (lean), come back unchanged.+pub fn withCompletionBatch(arena: std.mem.Allocator, catalog: []const u8, model: []const u8) ![]const u8 {+ if (!family(model)) return catalog;+ const desc = @import("schema.zig").attempt_completion_desc;+ if (std.mem.indexOf(u8, catalog, desc) == null) return catalog;+ return std.mem.replaceOwned(u8, arena, catalog, desc, desc ++ completion_batch);+}++test "family matches Gemini ids with or without a vendor prefix, and nothing else" {+ for ([_][]const u8{ "gemini-3.8-flash", "gemini-3.7-flash", "google/gemini-3.1-pro-preview", "Gemini-3.8-Flash" }) |m|+ try std.testing.expect(family(m));+ for ([_][]const u8{ "gemma-3", "gpt-6-sol", "deepseek-v4-flash", "mimo-v2.6-flash", "my-gemini-proxy", "" }) |m|+ try std.testing.expect(!family(m));+}++test "only Gemini catalogs advertise a batched completion" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ const desc = @import("schema.zig").attempt_completion_desc;+ const catalog = try std.mem.concat(a, u8, &.{ "[{\"name\":\"attempt_completion\",\"description\":\"", desc, "\"}]" });+ const extended = try withCompletionBatch(a, catalog, "gemini-3.8-flash");+ try std.testing.expect(std.mem.indexOf(u8, extended, completion_batch) != null);+ try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, extended, desc));+ try std.testing.expect(std.json.validate(a, extended) catch false);+ try std.testing.expectEqualStrings(catalog, try withCompletionBatch(a, catalog, "gpt-6.1-sol"));+ try std.testing.expectEqualStrings("[]", try withCompletionBatch(a, "[]", "gemini-3.8-flash"));+}diff --git a/src/gemini_turns_tests.zig b/src/gemini_turns_tests.zignew file mode 100644index 00000000..734b937b--- /dev/null+++ b/src/gemini_turns_tests.zig@@ -0,0 +1,125 @@+//! ADR 0256 regressions: the Gemini working note, the batched-completion+//! description, and the write rule follow the model, including across a+//! same-wire model switch.+const std = @import("std");+const Agent = @import("agent.zig").Agent;+const Provider = @import("provider.zig").Provider;+const ToolCall = @import("tools.zig").ToolCall;+const providers = @import("providers.zig");+const gemini = @import("gemini_turns.zig");+const eval_control = @import("agent_eval_control.zig");++fn call(arena: std.mem.Allocator, name: []const u8) !ToolCall {+ return .{ .id = name, .name = name, .input = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{}", .{}) };+}++test "a write may share a response with attempt_completion only where writes complete" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ const done = try call(a, "attempt_completion");+ for ([_][]const u8{ "edit_file", "write_file" }) |name| {+ const write = try call(a, name);+ for ([_][2]ToolCall{ .{ write, done }, .{ done, write } }) |batch| {+ try std.testing.expect(eval_control.batchBlocksCompletionFor(&batch, false));+ try std.testing.expect(!eval_control.shouldDeferCompletionFor(&batch, false));+ try std.testing.expect(!eval_control.batchBlocksCompletionFor(&batch, true));+ try std.testing.expect(eval_control.shouldDeferCompletionFor(&batch, true));+ }+ const check = try call(a, "shell");+ const with_check = [_]ToolCall{ write, check, done };+ try std.testing.expect(eval_control.shouldDeferCompletionFor(&with_check, true));+ }+ // Calls that change more than a named file still refuse a batched completion.+ for ([_][]const u8{ "rlm", "subagent", "mcp__codedbpro__edit" }) |name| {+ const mutation = [_]ToolCall{ try call(a, "write_file"), try call(a, name), done };+ try std.testing.expect(eval_control.batchBlocksCompletionFor(&mutation, true));+ try std.testing.expect(!eval_control.shouldDeferCompletionFor(&mutation, true));+ }+ // The defaults are the old rule.+ const old = [_]ToolCall{ try call(a, "edit_file"), done };+ try std.testing.expect(eval_control.batchBlocksCompletion(&old));+ try std.testing.expect(!eval_control.shouldDeferCompletion(&old));+}++fn promptAgent(arena: std.mem.Allocator, id: []const u8, kind: Provider.Kind, model: []const u8) Agent {+ return .{+ .gpa = std.testing.allocator,+ .arena = arena,+ .io = std.testing.io,+ .client = undefined,+ .provider = .{ .id = id, .kind = kind, .auth = .bearer, .url = "", .api_key = "", .model = model, .context = 1_000_000 },+ .messages = std.json.Array.init(arena),+ .sub = false,+ .label = "",+ .out = null,+ .sys_normal = "BASE",+ };+}++test "the working note rides only on Gemini models, on any route" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ const compose = @import("agent_request_body_responses.zig").schemaAwarePrompt;+ const routes = [_]struct { id: []const u8, kind: Provider.Kind, model: []const u8 }{+ .{ .id = "codegraff", .kind = .openai, .model = "gemini-3.8-flash" },+ .{ .id = "google", .kind = .interactions, .model = "gemini-3.7-flash" },+ };+ for (routes) |r| {+ var agent = promptAgent(a, r.id, r.kind, r.model);+ const prompt = try compose(&agent);+ try std.testing.expect(std.mem.startsWith(u8, prompt, "BASE\n"));+ try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, prompt, "# Working guidance"));+ agent.sub = true; // children carry it too: they pay the same per request+ try std.testing.expect(std.mem.indexOf(u8, try compose(&agent), "# Working guidance") != null);+ }+ for ([_][]const u8{ "gpt-5.6", "deepseek-v4-flash", "mimo-v2.6-flash", "gemma-3" }) |model| {+ var agent = promptAgent(a, "codegraff", .openai, model);+ try std.testing.expect(std.mem.indexOf(u8, try compose(&agent), "# Working guidance") == null);+ }+}++test "attempt_completion's description follows a same-wire model switch" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const a = arena_state.allocator();+ const deepseek: Provider = .{ .id = "codegraff", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "deepseek-v4-flash", .context = 1_000_000 };+ var flash = deepseek;+ flash.model = "gemini-3.8-flash";++ var root: Agent = undefined;+ root.provider = deepseek;+ root.io = std.testing.io;+ root.jev_effort_pending = .{};+ root.subagent_provider = null;+ root.subagent_provider_explicit = true;+ root.arena = a;+ root.registry = null;+ root.messages = std.json.Array.init(a);+ root.sub = false;+ root.strict = false;+ root.sys_normal = "";+ root.sys_strict = "";+ root.tools_anthropic = "";+ root.tools_openai = "";+ root.tools_responses = "";+ root.tools_interactions = "";+ root.keep_context = true;+ root.last_context_tokens = 0;+ root.context_local_tokens = 0;+ root.last_cache_read = 0;+ root.cap_new = false;+ root.sox_json_object = false;+ root.effort_rejected = false;+ root.ws_off = false;+ root.ws_transport_failures = 0;++ try root.ensureRootTools(.openai);+ try std.testing.expect(std.mem.indexOf(u8, root.tools_openai, gemini.completion_batch) == null);+ _ = try providers.applyProviderInner(&root, a, flash, false);+ try std.testing.expect(std.mem.indexOf(u8, root.tools_openai, gemini.completion_batch) != null);+ try std.testing.expect(std.json.validate(a, root.tools_openai) catch false);+ _ = try providers.applyProviderInner(&root, a, deepseek, false);+ try std.testing.expect(std.mem.indexOf(u8, root.tools_openai, gemini.completion_batch) == null);+}diff --git a/src/main.zig b/src/main.zigindex 97f4f58b..dabb2147 100644--- a/src/main.zig+++ b/src/main.zig@@ -559,7 +559,7 @@ const agentJobsReap = subagent.agentJobsReap; // #276 P0-3: background subagentsconst workflow = @import("workflow_test.zig"); // the engine's tests live here (workflow.zig hit the 600-line cap)const exec = @import("exec.zig");test { // ── Unit tests (`zig build test`): pull in tests from imported modules (mcp.zig)- _ = .{ @import("beta_feed.zig"), @import("jev_tool.zig"), @import("jev_model_scope.zig"), @import("jev_provider_switch_tests.zig"), @import("jev_effort_state.zig") };+ _ = .{ @import("beta_feed.zig"), @import("jev_tool.zig"), @import("jev_model_scope.zig"), @import("jev_provider_switch_tests.zig"), @import("jev_effort_state.zig"), @import("gemini_turns.zig"), @import("gemini_turns_tests.zig") };_ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("usage_trace.zig"), @import("providers_confirmation_tests.zig"), @import("repl_model_confirmation_tests.zig"), @import("repl_model_pick_tests.zig"), @import("engine_sink_citation_tests.zig"), @import("cite_markup_stream_tests.zig"), @import("oneshot_citation_tests.zig"), @import("acp_permission.zig"), @import("acp_usage.zig") };_ = .{ @import("mcp_server_tests.zig"), @import("main_test.zig"), @import("artifact_claim_command.zig"), @import("cli_path_hint.zig"), @import("run_budget.zig") };_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };diff --git a/src/prompt_astra.zig b/src/prompt_astra.zigindex 1ce881dc..66fefb7c 100644--- a/src/prompt_astra.zig+++ b/src/prompt_astra.zig@@ -85,7 +85,7 @@ test "Astra guidance follows model switches, child limits and output schemas" {try std.testing.expect(std.mem.indexOf(u8, child, "A JSON output schema is enforced") != null);agent.output_schema = null;agent.sub = false;- for ([_][]const u8{ "gpt-5.5", "gemini-3.7-flash", "gpt-6-astraish" }) |model| { // gpt-5.6 has its own note (prompt_guidance.zig)+ for ([_][]const u8{ "gpt-5.5", "gpt-6-astraish" }) |model| { // gpt-5.6 and Gemini have their own notes (prompt_guidance.zig)agent.provider.model = model;try std.testing.expectEqualStrings("BASE", try compose(&agent));}diff --git a/src/prompt_guidance.zig b/src/prompt_guidance.zigindex 9cb9e2e7..e2be0fcf 100644--- a/src/prompt_guidance.zig+++ b/src/prompt_guidance.zig@@ -43,6 +43,8 @@ pub fn isGpt56(model: []const u8) bool {/// Compose `base` plus the note for the agent's current model, if it has one.pub fn append(self: *Agent, base: []const u8) ![]const u8 {if (isGpt56(self.provider.model)) return std.mem.concat(self.scratchAlloc(), u8, &.{ base, "\n", gpt56 });+ const gemini = @import("gemini_turns.zig"); // ADR 0256+ if (gemini.family(self.provider.model)) return std.mem.concat(self.scratchAlloc(), u8, &.{ base, "\n", gemini.note });return @import("prompt_astra.zig").append(self, base);}diff --git a/src/providers.zig b/src/providers.zigindex d9524aa4..dc105db8 100644--- a/src/providers.zig+++ b/src/providers.zig@@ -73,6 +73,9 @@ pub fn applyProviderInner(root: *Agent, arena: Allocator, p: Provider, persist:note = "history cleared — /keepcontext on to carry it across formats";}}+ // ADR 0256: attempt_completion's description follows the model family.+ const gemini = @import("gemini_turns.zig");+ if (gemini.family(root.provider.model) != gemini.family(p.model)) root.invalidateRootTools();@import("jev_tool.zig").updateProvider(root, p);if (root.reasoning == .none and !@import("effort_route.zig").mimoRoute(p.id, p.model)) {root.reasoning = .medium;diff --git a/src/schema.zig b/src/schema.zigindex 2abafcb7..486d7fbb 100644--- a/src/schema.zig+++ b/src/schema.zig@@ -51,6 +51,9 @@ const empty_schema =\\{"type": "object", "properties": {}};+/// attempt_completion's description; gemini_turns.withCompletionBatch extends it per model (ADR 0256).+pub const attempt_completion_desc = "Signal that the task is complete. Put your final answer to the user in the result field. In strict mode use this for completed tasks; use yield_turn instead to stop for missing user input without claiming completion. Completing also closes the standing /goal; if its checklist still has open items you will be asked once to finish or confirm.";+pub const base_specs = [_]ToolSpec{.{ .name = shell_tool.tool_name, .desc = shell_tool.tool_desc, .schema = shell_tool.tool_schema },.{@@ -131,7 +134,7 @@ const meta_specs = [_]ToolSpec{},.{.name = "attempt_completion",- .desc = "Signal that the task is complete. Put your final answer to the user in the result field. In strict mode use this for completed tasks; use yield_turn instead to stop for missing user input without claiming completion. Completing also closes the standing /goal; if its checklist still has open items you will be asked once to finish or confirm.",+ .desc = attempt_completion_desc,.schema =\\{"type": "object", "properties": {"result": {"type": "string", "description": "Final answer to present to the user"}}, "required": ["result"]},