Skip to content

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

Python

codex: default effort and text verbosity follow the model catalog

justrach8bd3b81faaea
diff --git a/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.md b/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.md
new file mode 100644
index 00000000..a562afe4
--- /dev/null
+++ b/docs/adr/0226-codex-follows-the-catalog-effort-and-verbosity.md
@@ -0,0 +1,40 @@
+# 0226. Codex requests follow the model catalog's default effort and verbosity
+
+Status: accepted 2026-10-01
+
+## Context
+
+The codex model catalog gives each model a default reasoning level and a
+default text verbosity, and the route's own client sends both. graff sent
+`medium` effort to every codex model the user had not set, and no
+`text.verbosity`, so the server's `medium` applied. On a model whose catalog
+default is `low` for both, each graff turn reasoned and wrote more than the
+route's own client does.
+
+A hill-climb round on wall time against a reference harness measured the
+catalog defaults together with ADR 0227. Each change alone moved wall time
+within noise. Together they cut it on the train and the held-out split, with
+pass rate held.
+
+## Decision
+
+- `pricing.ModelInfo` has `default_verbosity`. The static codex rows carry
+ the catalog's default effort and verbosity. `models_cache` reads both for
+ the dynamic rows (`default_reasoning_level` or graff's `default_effort`,
+ and `default_verbosity`) and writes them back. A value the wire does not
+ accept is dropped, not guessed.
+- `effort_route.wireEffort`: on the codex provider, `medium` (graff's
+ default) is sent as the model's catalog default. Any other level is sent
+ as chosen.
+- The codex Responses body carries the catalog's `text.verbosity`.
+ Compaction summaries and requests with a JSON output schema do not.
+
+## Consequences
+
+On a model whose catalog default is `low`, a turn reasons and writes less
+and finishes sooner. `medium` is also the unset value, so an explicit
+`/effort medium` on such a model sends the catalog default too; the same
+function already maps `medium` this way for some other models. Choose
+`high` for deeper reasoning. Revisit if a harder suite loses pass rate at
+the catalog default, or when the catalog's defaults change: dynamic rows
+follow it, the static rows are updated by hand.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 7f53c6ee..69c5e3f7 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -252,6 +252,7 @@ record only when you need the evidence or the edge cases.
| [0223](0223-codex-cache-partition-is-the-account.md) | Codex with a ChatGPT account id partitions the prompt cache by account, not repo: the system+tools prefix carries no cwd, so turn 1 in any repo reads the prefix another repo warmed. Children keep their role lanes on the account base; other providers keep the project key (ADR 0069). |
| [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. |
## When to write one
diff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zig
index ae406260..51229aa4 100644
--- a/src/agent_request_body_responses.zig
+++ b/src/agent_request_body_responses.zig
@@ -112,7 +112,15 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too
try s.write(false);
server_compact.noteExposure(self);
try server_compact.writeContextManagement(self, s);
- if (self.output_schema) |schema_json| try writeTextFormat(s, schema_json);
+ if (self.output_schema) |schema_json| try writeTextFormat(s, schema_json) else if (!self.compaction_request and !self.server_compaction_request) {
+ if (@import("effort_route.zig").catalogVerbosity(self.provider.id, self.provider.model)) |v| {
+ try s.objectField("text");
+ try s.beginObject();
+ try s.objectField("verbosity");
+ try s.write(v);
+ try s.endObject();
+ }
+ }
// Prewarm: generate:false and no transport fields — connection setup, not inference (openai/codex).
if (self.ws_prewarm) try s.objectField("generate") else try s.objectField("stream");
// No top-level max_output_tokens: codex rejects it ("Unsupported parameter") on gpt-5.6-*.
diff --git a/src/effort_route.zig b/src/effort_route.zig
index ddaf512d..07466947 100644
--- a/src/effort_route.zig
+++ b/src/effort_route.zig
@@ -108,6 +108,31 @@ pub fn normalize(provider_id: []const u8, model: []const u8, requested: []const
return requested;
}
+/// ADR 0226: on the codex route graff's default effort (medium) and text
+/// verbosity follow the model's catalog defaults, as the route's own client
+/// does. Any other effort is sent as chosen.
+fn codexCatalog(provider_id: []const u8, model: []const u8) ?@import("pricing.zig").ModelInfo {
+ if (!std.mem.eql(u8, provider_id, "codex")) return null;
+ return @import("pricing.zig").modelInfoFor(provider_id, model);
+}
+
+pub fn catalogVerbosity(provider_id: []const u8, model: []const u8) ?[]const u8 {
+ const info = codexCatalog(provider_id, model) orelse return null;
+ return info.default_verbosity;
+}
+
+pub const effort_levels = [_][]const u8{ "minimal", "low", "medium", "high", "xhigh", "max" };
+pub const verbosity_levels = [_][]const u8{ "low", "medium", "high" };
+
+/// ADR 0226: a catalog default the wire accepts, under graff's compact key
+/// or Codex's own; anything else is dropped, not guessed.
+pub fn catalogLevel(arena: std.mem.Allocator, obj: std.json.ObjectMap, keys: []const []const u8, allowed: []const []const u8) ?[]const u8 {
+ for (keys) |key| if (@import("util.zig").strFieldObj(obj, key)) |v| {
+ for (allowed) |level| if (std.mem.eql(u8, v, level)) return arena.dupe(u8, level) catch null;
+ };
+ return null;
+}
+
pub fn allows(provider_id: []const u8, model: []const u8, tag: []const u8) bool {
for (levels(provider_id, model)) |level| if (std.mem.eql(u8, tag, level)) return true;
return false;
@@ -118,6 +143,7 @@ pub fn allows(provider_id: []const u8, model: []const u8, tag: []const u8) bool
/// `max`). Other seats still send ultra as `max` (including OpenAI).
pub fn wireEffort(provider_id: []const u8, model: []const u8, requested: []const u8) []const u8 {
if (mimoRoute(provider_id, model)) return if (std.mem.eql(u8, requested, "none")) "none" else "high";
+ if (std.mem.eql(u8, requested, "medium")) if (codexCatalog(provider_id, model)) |info| if (info.default_effort) |d| return d;
if (std.mem.eql(u8, requested, "medium") and omitsDefaultFlashEffort(model)) return "low";
if (grokFamily(model)) {
if (std.mem.eql(u8, requested, "max") or std.mem.eql(u8, requested, "ultra")) return "high";
@@ -216,3 +242,28 @@ test "MiMo exposes only Off and On while legacy positive settings remain On" {
try std.testing.expectEqualStrings("low", wireEffort("custom", "mimo-v2.6-flash", "low"));
try std.testing.expectEqualStrings("low", wireEffort("zai", "glm-5.3-flash", "medium"));
}
+
+test "codex: the default medium follows the model's catalog; explicit levels and other routes do not" {
+ try std.testing.expectEqualStrings("low", wireEffort("codex", "gpt-6.1-sol", "medium"));
+ try std.testing.expectEqualStrings("high", wireEffort("codex", "gpt-6.1-sol", "high"));
+ try std.testing.expectEqualStrings("low", wireEffort("codex", "gpt-6.1-sol", "low"));
+ try std.testing.expectEqualStrings("medium", wireEffort("codex", "gpt-6-sol", "medium"));
+ try std.testing.expectEqualStrings("medium", wireEffort("openai", "gpt-6.1-sol", "medium"));
+ try std.testing.expectEqualStrings("low", catalogVerbosity("codex", "gpt-6.1-sol").?);
+ try std.testing.expect(catalogVerbosity("openai", "gpt-6.1-sol") == null);
+}
+
+test "codex bodies carry the catalog text verbosity; a compaction summary does not" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var agent = try @import("agent_request_body_responses.zig").testAgentFor(a, "codex", .responses, "gpt-6.1-sol");
+ const body = try agent.buildBody(null, false, true, true);
+ defer std.testing.allocator.free(body);
+ try std.testing.expect(std.mem.indexOf(u8, body, "\"verbosity\":\"low\"") != null);
+ try std.testing.expect(std.mem.indexOf(u8, body, "\"effort\":\"low\"") != null);
+ agent.compaction_request = true;
+ const summary = try agent.buildBody(null, false, true, true);
+ defer std.testing.allocator.free(summary);
+ try std.testing.expect(std.mem.indexOf(u8, summary, "\"verbosity\"") == null);
+}
diff --git a/src/models_cache.zig b/src/models_cache.zig
index 24ff082c..14cc864e 100644
--- a/src/models_cache.zig
+++ b/src/models_cache.zig
@@ -144,6 +144,8 @@ fn parseCodexSnapshot(arena: Allocator, data: []const u8) ?CodexSnapshot {
.provider = "codex",
.name = arena.dupe(u8, slug) catch continue,
.context = context,
+ .default_effort = @import("effort_route.zig").catalogLevel(arena, item.object, &.{ "default_effort", "default_reasoning_level" }, &@import("effort_route.zig").effort_levels),
+ .default_verbosity = @import("effort_route.zig").catalogLevel(arena, item.object, &.{"default_verbosity"}, &@import("effort_route.zig").verbosity_levels),
}) catch continue;
}
const models = rows.toOwnedSlice(arena) catch return null;
@@ -259,7 +261,10 @@ fn writeCodexCache(io: Io, arena: Allocator, home: []const u8, version: []const
aw.writer.writeAll("{\"name\":") catch return;
var name_stringify: std.json.Stringify = .{ .writer = &aw.writer };
name_stringify.write(model.name) catch return;
- aw.writer.print(",\"context\":{d}}}", .{model.context}) catch return;
+ aw.writer.print(",\"context\":{d}", .{model.context}) catch return;
+ if (model.default_effort) |v| aw.writer.print(",\"default_effort\":\"{s}\"", .{v}) catch return;
+ if (model.default_verbosity) |v| aw.writer.print(",\"default_verbosity\":\"{s}\"", .{v}) catch return;
+ aw.writer.writeByte('}') catch return;
}
aw.writer.writeAll("]}\n") catch return;
for ([_][]const u8{ codexDirPath(arena, home), codexFlatPath(arena, home) }) |path| {
diff --git a/src/models_cache_tests.zig b/src/models_cache_tests.zig
index 5ed03bec..2cfe5fdf 100644
--- a/src/models_cache_tests.zig
+++ b/src/models_cache_tests.zig
@@ -70,6 +70,22 @@ pub fn visibleSnapshots(parse_snapshot: anytype) !void {
try std.testing.expectEqual(@as(u64, 372_000), snapshot.models[0].context);
try std.testing.expectEqualStrings("future-luna", snapshot.models[1].name);
try std.testing.expectEqual(@as(u64, 128_000), snapshot.models[1].context);
+
+ // ADR 0226: Codex's own defaults ride along (native keys and graff's
+ // compact cache keys); a level the wire does not accept is dropped.
+ const defaults = parse_snapshot(arena.allocator(),
+ \\{"models":[
+ \\ {"slug":"native","visibility":"list","default_reasoning_level":"low","default_verbosity":"low"},
+ \\ {"name":"compact","context":272000,"default_effort":"high","default_verbosity":"medium"},
+ \\ {"slug":"odd","visibility":"list","default_reasoning_level":"extreme","default_verbosity":"loud"},
+ \\ {"slug":"plain","visibility":"list"}]}
+ ).?;
+ try std.testing.expectEqualStrings("low", defaults.models[0].default_effort.?);
+ try std.testing.expectEqualStrings("low", defaults.models[0].default_verbosity.?);
+ try std.testing.expectEqualStrings("high", defaults.models[1].default_effort.?);
+ try std.testing.expectEqualStrings("medium", defaults.models[1].default_verbosity.?);
+ try std.testing.expect(defaults.models[2].default_effort == null and defaults.models[2].default_verbosity == null);
+ try std.testing.expect(defaults.models[3].default_effort == null and defaults.models[3].default_verbosity == null);
}
pub fn versionFloor(floor: []const u8, effective_version: anytype, snapshot_matches: anytype) !void {
diff --git a/src/pricing.zig b/src/pricing.zig
index 2c60e7ee..9cb8ba08 100644
--- a/src/pricing.zig
+++ b/src/pricing.zig
@@ -159,6 +159,9 @@ pub const ModelInfo = struct {
thinking_support: ThinkingSupport = .unknown,
support_efforts: []const []const u8 = &.{},
default_effort: ?[]const u8 = null,
+ /// Codex catalog `default_verbosity` (ADR 0226): the `text.verbosity` the
+ /// route's own client sends for this model.
+ default_verbosity: ?[]const u8 = null,
};
pub const ModelProtocol = enum { provider_default, kimi, anthropic };
diff --git a/src/pricing_models.zig b/src/pricing_models.zig
index 7e648c81..fb14ae55 100644
--- a/src/pricing_models.zig
+++ b/src/pricing_models.zig
@@ -57,9 +57,9 @@ pub const rows = [_]ModelInfo{
// Offline snapshot only: at startup models_cache.zig replaces the whole
// Codex slice from the account-scoped /models response (5-minute cache).
// These rows keep Codex usable when auth or discovery is unavailable.
- .{ .provider = "codex", .name = "gpt-6-astra", .context = 272_000 },
- .{ .provider = "codex", .name = "gpt-6-sol", .context = 272_000 },
- .{ .provider = "codex", .name = "gpt-6.1-sol", .context = 272_000 },
+ .{ .provider = "codex", .name = "gpt-6-astra", .context = 272_000, .default_effort = "medium", .default_verbosity = "low" },
+ .{ .provider = "codex", .name = "gpt-6-sol", .context = 272_000, .default_effort = "medium", .default_verbosity = "low" },
+ .{ .provider = "codex", .name = "gpt-6.1-sol", .context = 272_000, .default_effort = "low", .default_verbosity = "low" },
.{ .provider = "codex", .name = "gpt-5.6-sol", .context = 272_000 },
.{ .provider = "codex", .name = "gpt-5.6-terra", .context = 272_000 },
.{ .provider = "codegraff", .name = "muse-spark-1.2", .context = 262_144 },
diff --git a/src/prompt_astra.zig b/src/prompt_astra.zig
index eed5155e..0044e2ec 100644
--- a/src/prompt_astra.zig
+++ b/src/prompt_astra.zig
@@ -114,7 +114,14 @@ test "GPT6 emitted requests keep one stable guidance block and refresh on model
try testing.expect(std.mem.indexOf(u8, instructions, "# GPT-6 Sol working guidance") == null);
try testing.expect(std.mem.indexOf(u8, instructions, "# GPT-6.1 Sol working guidance") == null);
}
- try testing.expectEqualStrings(if (std.mem.eql(u8, model, "mimo-v2.6-flash")) (if (std.mem.eql(u8, provider, "codegraff")) "high" else "low") else "medium", parsed.value.object.get("reasoning").?.object.get("effort").?.string);
+ // ADR 0226: on codex the default medium is the catalog's level (low for gpt-6.1-sol).
+ const effort: []const u8 = if (std.mem.eql(u8, model, "mimo-v2.6-flash"))
+ (if (std.mem.eql(u8, provider, "codegraff")) "high" else "low")
+ else if (std.mem.eql(u8, provider, "codex") and std.mem.eql(u8, model, "gpt-6.1-sol"))
+ "low"
+ else
+ "medium";
+ try testing.expectEqualStrings(effort, parsed.value.object.get("reasoning").?.object.get("effort").?.string);
var followup: std.json.ObjectMap = .empty;
try followup.put(a, "role", .{ .string = "user" });
try followup.put(a, "content", .{ .string = "continue with the requested work" });