Skip to content

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

Python

codex, openai: announce loaded tools in an additional_tools item

justrachec9ce85708ed
diff --git a/docs/adr/0221-chatgpt-new-sign-in.md b/docs/adr/0221-chatgpt-new-sign-in.md
index 9c127541..f0e278c6 100644
--- a/docs/adr/0221-chatgpt-new-sign-in.md
+++ b/docs/adr/0221-chatgpt-new-sign-in.md
@@ -182,6 +182,17 @@ process rather than restarting anything.
is a `tool_addition` block in a mid-conversation system message (beta
`inline-tools-2026-09-15`), which declares the tool, so its arguments
come back typed, and it needs a live check first.
+- **Codex and the OpenAI API announce loads in an `additional_tools` item.**
+ On Codex, graff marked the loaded tail `defer_loading` behind hosted tool
+ search, but the array still grew: a replay of graff's own request after a
+ load read nothing back from the cache, and the model then ran a hosted
+ search for the tools it had just loaded. With `tools` frozen and the tail
+ in a developer `additional_tools` item, the same replay kept the cache and
+ the model called the tool directly, over HTTP and on a chained WebSocket
+ delta. Hosted `tool_search` stays for tools deferred in the base catalog.
+ The tail is stripped before the hosted splices, because hosted search with
+ nothing deferred is a 400 (#746). The OpenAI API documents the same item.
+ Models without hosted search (before GPT-5.4) keep appending.
- **The first request carries every MCP server that is ready.** `-p` starts
MCP in the background and never waits out a handshake (ADR 0035). A server
restored from cache was ready before the first request, but that request
diff --git a/src/additional_tools.zig b/src/additional_tools.zig
index 580ea515..a1dfa1f9 100644
--- a/src/additional_tools.zig
+++ b/src/additional_tools.zig
@@ -4,11 +4,15 @@
//! The stable catalog (ADR 0011) appends each loaded tool to the END of the
//! `tools` array. OpenAI renders tools ahead of every message and checks cache
//! breakpoints only at message ends, so any change to `tools` makes the whole
-//! conversation miss the cache on the next request. Codex hides that tail
-//! behind hosted tool search (`defer_loading`), which the ChatGPT plan's new
-//! sign-in refuses. OpenAI's documented alternative is a developer-role
-//! `additional_tools` input item: it adds the loaded definitions where the
-//! load happened, after the prefix it would otherwise invalidate.
+//! conversation miss the cache on the next request. Codex marked that tail
+//! `defer_loading` behind hosted tool search, but the array still grew: a
+//! probe that appended the tail read nothing back, and the model then spent a
+//! search round trip loading what it had just loaded. (The ChatGPT plan's new
+//! sign-in refuses hosted search outright.) OpenAI's documented alternative is
+//! a developer-role `additional_tools` input item: it adds the loaded
+//! definitions where the load happened, after the prefix it would otherwise
+//! invalidate. On Codex the same probe kept the prefix cached, and the model
+//! called the tool directly.
//!
//! MiMo's chat wire is worse off: it renders `tools` ahead of the system
//! prompt, so one appended tool re-bills the whole prompt (a probe that
@@ -54,12 +58,19 @@ const chat_header = "Additional tools are now available. Call them exactly like
pub fn active(p: Provider) bool {
if (!mcp_schema_gate.g_stable_catalog) return false;
return switch (p.kind) {
- .responses => std.mem.eql(u8, p.id, "chatgpt-new"),
+ .responses => std.mem.eql(u8, p.id, "chatgpt-new") or openaiRoute(p),
.openai => @import("effort_route.zig").mimoRoute(p.id, p.model) or deepseekRoute(p) or claudeRoute(p),
.anthropic, .interactions => false,
};
}
+/// Codex and the OpenAI API on the models that have hosted tool search. Both
+/// take `additional_tools` items (probed on Codex; documented for the API).
+fn openaiRoute(p: Provider) bool {
+ return (std.mem.eql(u8, p.id, "codex") or std.mem.eql(u8, p.id, "openai")) and
+ @import("codex_tool_search.zig").modelSupports(p.model);
+}
+
/// The model id without a family prefix (`vendor/model`).
fn modelName(model: []const u8) []const u8 {
return if (std.mem.lastIndexOfScalar(u8, model, '/')) |slash| model[slash + 1 ..] else model;
diff --git a/src/additional_tools_tests.zig b/src/additional_tools_tests.zig
index 1b777e56..829dab39 100644
--- a/src/additional_tools_tests.zig
+++ b/src/additional_tools_tests.zig
@@ -98,8 +98,9 @@ test "ChatGPT plan: a pruned item is announced again; other routes drop the item
additional_tools.sync(&agent);
try std.testing.expectEqual(@as(usize, 1), items(agent.messages.items));
- // Switching to Codex removes the items: there the catalog tail carries the tool.
- agent.provider.id = "codex";
+ // Switching to grok removes the items: there the catalog tail carries the tool.
+ agent.provider.id = "xai";
+ agent.provider.model = "grok-4.6";
additional_tools.sync(&agent);
try std.testing.expectEqual(@as(usize, 0), items(agent.messages.items));
agent.invalidateRootTools();
@@ -264,3 +265,50 @@ test "Claude chat: a direct call's load reaches the catalog, so its string argum
try std.testing.expectEqual(@as(i64, 1), args.object.get("id").?.integer);
try std.testing.expectEqual(@as(i64, 300000), args.object.get("wait_ms").?.integer);
}
+
+test "Codex and the OpenAI API: a tool load leaves tools byte-identical and adds one additional_tools item" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const saved_fold = native_fold.enabled;
+ const saved_stable = mcp_schema_gate.g_stable_catalog;
+ defer {
+ native_fold.enabled = saved_fold;
+ mcp_schema_gate.g_stable_catalog = saved_stable;
+ native_fold.clearLoadedSession();
+ }
+ native_fold.enabled = true;
+ mcp_schema_gate.g_stable_catalog = true;
+
+ // Models without hosted tool search keep the tail in `tools`.
+ try std.testing.expect(!additional_tools.active((try testAgentFor(a, "codex", .responses, "gpt-5.3-codex")).provider));
+
+ for ([_][]const u8{ "codex", "openai" }) |id| {
+ native_fold.clearLoadedSession();
+ var agent = try testAgentFor(a, id, .responses, "gpt-6.1-sol");
+ try std.testing.expect(additional_tools.active(agent.provider));
+ agent.invalidateRootTools();
+ try agent.ensureRootTools(.responses);
+ additional_tools.sync(&agent);
+ try std.testing.expectEqual(@as(usize, 0), items(agent.messages.items));
+ const before = try agent.buildBody(agent.tools_responses, false, true, true);
+ defer std.testing.allocator.free(before);
+
+ native_fold.markLoaded("workflow");
+ agent.invalidateRootTools();
+ try agent.ensureRootTools(.responses);
+ additional_tools.sync(&agent);
+ try std.testing.expectEqual(@as(usize, 1), items(agent.messages.items));
+ const after = try agent.buildBody(agent.tools_responses, false, true, true);
+ defer std.testing.allocator.free(after);
+
+ try std.testing.expect(toolsOf(before).len > 2);
+ try std.testing.expectEqualStrings(toolsOf(before), toolsOf(after));
+ try std.testing.expect(std.mem.indexOf(u8, toolsOf(after), "\"name\":\"workflow\"") == null);
+ const at = std.mem.indexOf(u8, after, "\"type\":\"additional_tools\"") orelse return error.TestExpectedItem;
+ try std.testing.expect(at < (std.mem.indexOf(u8, after, "],\"tools\":") orelse return error.TestExpectedTools));
+ // Hosted search ships only beside a tool it can load (#746).
+ if (std.mem.indexOf(u8, toolsOf(after), "\"type\":\"tool_search\"") != null)
+ try std.testing.expect(std.mem.indexOf(u8, toolsOf(after), "\"defer_loading\":true") != null);
+ }
+}
diff --git a/src/agent_request_body_responses.zig b/src/agent_request_body_responses.zig
index c61c20ad..8400211b 100644
--- a/src/agent_request_body_responses.zig
+++ b/src/agent_request_body_responses.zig
@@ -61,7 +61,10 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too
try s.endArray();
if (tools) |t| {
const payload = blk: {
- var next = t;
+ // ADR 0221: loaded tools ride additional_tools items here, so the tail
+ // never reaches `tools`. Strip it before the hosted splices below: a
+ // hosted tool_search with nothing deferred left is a 400 (#746).
+ var next = if (additional_tools.active(self.provider)) additional_tools.stripTail(self, self.scratchAlloc(), t) else t;
if (xai_hosted.active(self.provider.id, self.provider.kind)) {
const login = self.provider.source == .login;
next = xai_hosted.splice(self.scratchAlloc(), next, login) catch next;
@@ -70,8 +73,6 @@ pub fn write(self: *Agent, s: *std.json.Stringify, tools: ?[]const u8, force_too
next = codex_tool_search.splice(self.scratchAlloc(), next) catch next;
next = codex_tool_search.spliceWebSearch(self.scratchAlloc(), next) catch next;
}
- // ADR 0221: no hosted tool search here; the loaded tail rides additional_tools items instead.
- if (additional_tools.active(self.provider)) next = additional_tools.stripTail(self, self.scratchAlloc(), next);
break :blk next;
};
const async_payload = try @import("async_tool_policy.zig").decorate(self.scratchAlloc(), self.provider, payload, self.async_tools_armed and !self.sub and !self.compaction_request and !self.server_compaction_request);