Skip to content

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

Python

Sub-agents ask Jev for their own effort mid-run (ADR 0232)

justrachf565d0829df9
diff --git a/docs/adr/0232-sub-agents-at-parity-with-the-codex-route.md b/docs/adr/0232-sub-agents-at-parity-with-the-codex-route.md
index 8f3c169e..16ffdf02 100644
--- a/docs/adr/0232-sub-agents-at-parity-with-the-codex-route.md
+++ b/docs/adr/0232-sub-agents-at-parity-with-the-codex-route.md
@@ -54,6 +54,13 @@ the brief alone, at the worker default effort, so an effort set with
- A child without a spawn or persona effort pin runs at its parent's live
effort, when the child's model accepts that level. On the codex route an
unset effort already means the catalog default (ADR 0226).
+- A child can also ask Jev mid-run. While Jev serves the child's own seat,
+ its catalog carries `jev_effort` (eager on Responses), and a selection
+ lands in the child's own pending slot and applies at the child's next
+ request. It moves neither its root's effort nor the session's saved
+ effort: `jev_effort_state.apply` saves only for the root. Jev's
+ session-long circuit is shared, so one failed attempt by any agent
+ stops the rest.
- On macOS a read-only child's foreground shell runs under seatbelt
(`/usr/bin/sandbox-exec`): any command may run and read, writes inside the
project and all network access are refused, and the gate admits the
@@ -77,6 +84,7 @@ memory.
## Consequences
An unpinned child of a session at `/effort high` now reasons at high too.
+A child that asks Jev pays for that call like its root does.
A child sees the user's request, so a brief can be shorter, and a child can
also be tempted past its own task; its prompt and the context header both
say to do only its part. A `-p` run that would have kept a checklist no
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 8b269ba8..f3870985 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -258,7 +258,7 @@ record only when you need the evidence or the edge cases.
| [0229](0229-every-chatgpt-login-is-chatgpt-new.md) | The Codex client's login no longer works, so every ChatGPT login name (`chatgpt`, `codex`, `openai`, `gpt`, `oai`) and the model picker run the `chatgpt-new` sign-in, and `chatgpt-new` precedes `codex` in the provider table. The `codex` provider stays for an existing Codex CLI `auth.json`. Replaces ADR 0221's "Codex first". |
| [0230](0230-mcp-connects-in-the-background.md) | Every session but `--json` connects MCP servers in the background (interactive after consent, `--yolo`, `-p`, ACP); no request waits for a handshake, finished starts join the next request, and the root request says which server connected or did not. ACP `session/new` waits at most 250 ms; `/mcp` lists without waiting. |
| [0231](0231-no-round-trip-the-model-does-not-need.md) | No call the task did not ask for: a named small MCP server (and subagents, when asked for) loads with the first request, with the slim-shape note; `write_file` refuses to replace an unread file unless `replace: true` and reports created/replaced and JSON validity; inherited child MCP tools are never deferred; a piped bracketed paste is one prompt; unwatched (`-p`, piped) sessions get no `ask_user` and no low-effort reasoning summaries. |
-| [0232](0232-sub-agents-at-parity-with-the-codex-route.md) | Sub-agents measured (`subagents` suite and its `subagents-solo` counterfactual, `subagent_split.py`) and brought to parity: `write_file` creates a new file's directory; unwatched sessions get no `todo_write` nudges; `agent_output` takes `ids` and spawn receipts name the running children; a fresh child starts with the user's prompts and its parent's live effort (`/effort` or Jev) unless pinned; a read-only child's shell runs under macOS seatbelt instead of an allowlist; one `subagent` trace line per child; a script that computes a file writes it. |
+| [0232](0232-sub-agents-at-parity-with-the-codex-route.md) | Sub-agents measured (`subagents` suite and its `subagents-solo` counterfactual, `subagent_split.py`) and brought to parity: `write_file` creates a new file's directory; unwatched sessions get no `todo_write` nudges; `agent_output` takes `ids` and spawn receipts name the running children; a fresh child starts with the user's prompts and its parent's live effort (`/effort` or Jev) unless pinned, and can ask Jev mid-run for its own; a read-only child's shell runs under macOS seatbelt instead of an allowlist; one `subagent` trace line per child; a script that computes a file writes it. |
## When to write one
diff --git a/src/exec.zig b/src/exec.zig
index 0da9800d..7e4d320c 100644
--- a/src/exec.zig
+++ b/src/exec.zig
@@ -415,10 +415,13 @@ test "native Jev dispatch rejects other models and latches off after one failed
try std.testing.expect(older_model.is_error);
ctx.provider.model = "gpt-6-sol";
try std.testing.expect(jev.available(ctx.provider)); // ineligible attempts did not trip the circuit
+ // ADR 0232: a child asks too. Upstream fails here, so its call is the one
+ // attempt and opens the circuit for the whole session.
ctx.from_sub = true;
const worker = try execToolInner(ctx, call);
defer std.testing.allocator.free(worker.text);
- try std.testing.expect(worker.is_error);
+ try std.testing.expect(!worker.is_error);
+ try std.testing.expect(!jev.available(ctx.provider));
ctx.from_sub = false;
const first = try execToolInner(ctx, call);
defer std.testing.allocator.free(first.text);
diff --git a/src/jev_effort_state.zig b/src/jev_effort_state.zig
index 89f698e6..c3339927 100644
--- a/src/jev_effort_state.zig
+++ b/src/jev_effort_state.zig
@@ -72,6 +72,7 @@ pub fn applyToState(agent: anytype) bool {
pub fn apply(agent: anytype) void {
if (!applyToState(agent)) return;
+ if (agent.sub) return; // ADR 0232: a child's selection is its own; the saved effort is the root's
_ = @import("repl_glue.zig").saveThinkingSettings(agent.io, agent.gpa, agent.reasoning, agent.fast, agent.ultracode_mode, agent.show_thinking, agent.ai_title);
}
diff --git a/src/jev_tool.zig b/src/jev_tool.zig
index 26a4936d..6a75b181 100644
--- a/src/jev_tool.zig
+++ b/src/jev_tool.zig
@@ -20,7 +20,7 @@ pub const description = "Optionally ask Jev to choose the reasoning effort for t
pub const input_schema =
\\{"type":"object","properties":{"task":{"type":"string","description":"Short non-sensitive summary of the next task; no code, paths or secrets"}},"required":["task"],"additionalProperties":false}
;
-const spec = ToolSpec{ .name = name, .desc = description, .schema = input_schema };
+pub const spec = ToolSpec{ .name = name, .desc = description, .schema = input_schema };
const endpoint = "https://gateway.codegraff.com/v1/systemone";
const skip_text = "Jev effort selection unavailable; session effort is unchanged. No more Jev requests will be sent this session.";
const auth_skip_text = "Jev effort selection unavailable (Codegraff authorization failed); session effort is unchanged.";
@@ -244,7 +244,6 @@ fn selectedEffort(arena: Allocator, provider: Provider, raw: []const u8) !Reason
}
pub fn execute(ctx: ToolCtx, input: Value) !ToolOutput {
- if (ctx.from_sub) return invalid(ctx.gpa, "jev_effort is available only to the root agent");
if (!state.codegraff_login.load(.acquire)) return invalid(ctx.gpa, "jev_effort requires a Codegraff login (`graff login`)");
if (!scope.eligible(ctx.provider)) return invalid(ctx.gpa, "jev_effort is available only with Codex/OpenAI GPT-6 or Xiaomi MiMo v2.6 models");
if (state.down.load(.acquire)) return skipped(ctx.gpa);
diff --git a/src/subagent_run.zig b/src/subagent_run.zig
index b82f52db..803e53e3 100644
--- a/src/subagent_run.zig
+++ b/src/subagent_run.zig
@@ -391,6 +391,7 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
const task_prompt = playbook.rideBrief(ctx.io, arena, try goal_pacing.childTaskPrompt(arena, tasked, ctx.loop_deadline_ms, util.unixMs(ctx.io)));
try @import("subagent_retained.zig").restore(&agent, ctx);
@import("worker_mcp.zig").inherit(&agent); // ADR 0227
+ @import("worker_jev.zig").offer(&agent); // ADR 0232: a child asks Jev for its own effort mid-run
// ADR 0232: a fresh child starts from the user's request; a resumed one already has it.
const first = if (agent.messages.items.len == 0) try @import("subagent_fork.zig").firstMessage(arena, ctx.parent_task, task_prompt) else task_prompt;
try agent.messages.append(try textMessage(arena, "user", first));
diff --git a/src/test_hooks.zig b/src/test_hooks.zig
index 62bf9ef4..2faea162 100644
--- a/src/test_hooks.zig
+++ b/src/test_hooks.zig
@@ -337,6 +337,7 @@ test {
_ = @import("subagent_spawn_job.zig"); // ADR 0232: the spawn receipt's wait hint
_ = @import("ask_user.zig"); // ADR 0232: no todo nudges when nobody watches
_ = @import("readonly_sandbox.zig"); // ADR 0232: a read-only child computes under seatbelt
+ _ = @import("worker_jev.zig"); // ADR 0232: a child asks Jev for its own effort mid-run
_ = @import("piped_paste.zig"); // ADR 0231
_ = @import("mcp_connect_notice.zig"); // ADR 0230
_ = @import("oauth_callback.zig");
diff --git a/src/worker_jev.zig b/src/worker_jev.zig
new file mode 100644
index 00000000..7026c6ee
--- /dev/null
+++ b/src/worker_jev.zig
@@ -0,0 +1,104 @@
+//! ADR 0232: a child whose model Jev serves can ask Jev for its own effort
+//! mid-run, as its root can. A child starts at its parent's live effort; Jev
+//! can then move it for the child's next request. The selection is the
+//! child's alone: the root's effort and the session's saved effort do not
+//! change (jev_effort_state.apply).
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const schema = @import("schema.zig");
+const jev_tool = @import("jev_tool.zig");
+const Provider = @import("provider.zig").Provider;
+const Agent = @import("agent.zig").Agent;
+
+/// subagent_run calls this as it builds a child, after worker_mcp.inherit:
+/// whatever catalog the child would be served gains jev_effort while Jev is
+/// available for the child's own seat.
+pub fn offer(agent: *Agent) void {
+ if (!jev_tool.available(agent.provider)) return;
+ if (withJev(agent.arena, agent.provider.kind, agent.toolsJson())) |built| agent.worker_tools = built;
+}
+
+/// `base` (a JSON array of tool entries) plus the jev_effort entry. null when
+/// the entry is already there or `base` is not an array. On Responses the
+/// entry is eager, so hosted tool search leaves it callable (ADR 0231).
+pub fn withJev(arena: Allocator, kind: Provider.Kind, base: []const u8) ?[]const u8 {
+ if (std.mem.indexOf(u8, base, "\"" ++ jev_tool.name ++ "\"") != null) return null;
+ const head = std.mem.trimEnd(u8, base, " \t\r\n");
+ if (head.len < 2 or head[0] != '[' or head[head.len - 1] != ']') return null;
+ var aw: std.Io.Writer.Allocating = .init(arena);
+ var s: std.json.Stringify = .{ .writer = &aw.writer };
+ const written = if (kind == .responses)
+ schema.writeEagerResponsesEntry(&s, jev_tool.name, jev_tool.description, .{ .raw = jev_tool.input_schema })
+ else
+ schema.writeToolEntry(&s, kind, jev_tool.name, jev_tool.description, .{ .raw = jev_tool.input_schema });
+ written catch return null;
+ const entry = aw.writer.buffered();
+ if (std.mem.trim(u8, head[1 .. head.len - 1], " \t\r\n").len == 0) return std.fmt.allocPrint(arena, "[{s}]", .{entry}) catch null;
+ return std.fmt.allocPrint(arena, "{s},{s}]", .{ head[0 .. head.len - 1], entry }) catch null;
+}
+
+test "a child's catalog gains jev_effort once, eager on Responses (ADR 0232)" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const base = "[{\"type\":\"function\",\"name\":\"shell\"}]";
+ const out = withJev(a, .responses, base).?;
+ const parsed = try std.json.parseFromSliceLeaky(std.json.Value, a, out, .{});
+ try std.testing.expectEqual(@as(usize, 2), parsed.array.items.len);
+ try std.testing.expectEqualStrings(jev_tool.name, parsed.array.items[1].object.get("name").?.string);
+ try std.testing.expect(std.mem.indexOf(u8, out, "\"defer_loading\":false") != null);
+ try std.testing.expect(withJev(a, .responses, out) == null); // already there
+ const alone = withJev(a, .anthropic, "[]").?;
+ const one = try std.json.parseFromSliceLeaky(std.json.Value, a, alone, .{});
+ try std.testing.expectEqual(@as(usize, 1), one.array.items.len);
+ try std.testing.expect(one.array.items[0].object.get("input_schema") != null);
+ try std.testing.expect(withJev(a, .responses, "not a catalog") == null);
+}
+
+test "a child's Jev selection lands in its own pending slot, not its root's (ADR 0232)" {
+ const state = @import("jev_effort_state.zig");
+ jev_tool.configure(struct {
+ pub fn get(_: @This(), key: []const u8) ?[]const u8 {
+ return if (std.mem.eql(u8, key, "JEV_BACKEND")) "mock" else null;
+ }
+ }{});
+ defer jev_tool.configure(struct {
+ pub fn get(_: @This(), _: []const u8) ?[]const u8 {
+ return null;
+ }
+ }{});
+ _ = jev_tool.setCodegraffLoginKey(std.testing.io, "synthetic-login");
+ const p: Provider = .{ .id = "codex", .kind = .responses, .auth = .bearer, .url = "", .api_key = "", .model = "gpt-6-sol", .context = 100_000 };
+ var root_pending: state.Pending = .{};
+ var child_pending: state.Pending = .{};
+ var client: std.http.Client = undefined;
+ const child: @import("tools.zig").ToolCtx = .{ .gpa = std.testing.allocator, .io = std.testing.io, .client = &client, .provider = p, .jev_effort_pending = &child_pending, .registry = null, .from_sub = true, .approvals = null, .tracer = null };
+ const parsed = try std.json.parseFromSlice(std.json.Value, std.testing.allocator, "{\"task\":\"count lines in four log folders\"}", .{});
+ defer parsed.deinit();
+ const out = try jev_tool.execute(child, parsed.value);
+ defer std.testing.allocator.free(out.text);
+ try std.testing.expect(!out.is_error);
+ try std.testing.expect(std.mem.indexOf(u8, out.text, "reasoning effort selected") != null);
+ try std.testing.expect(child_pending.take(std.testing.io, p) != null);
+ try std.testing.expect(root_pending.take(std.testing.io, p) == null);
+
+ // Applied at the child's request boundary, to the child only.
+ const Fake = struct {
+ io: std.Io,
+ gpa: Allocator,
+ provider: Provider,
+ jev_effort_pending: state.Pending = .{},
+ reasoning: @import("main.zig").ReasoningEffort = .medium,
+ sub: bool = true,
+ fast: bool = false,
+ ultracode_mode: bool = false,
+ show_thinking: bool = false,
+ ai_title: bool = false,
+ };
+ var sub: Fake = .{ .io = std.testing.io, .gpa = std.testing.allocator, .provider = p };
+ const token = sub.jev_effort_pending.begin(std.testing.io, p).?;
+ try std.testing.expect(sub.jev_effort_pending.commit(std.testing.io, token, .high));
+ state.apply(&sub);
+ try std.testing.expectEqual(@import("main.zig").ReasoningEffort.high, sub.reasoning);
+}