Skip to content

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

Python

feat(acp): preview negotiated child session activity

Rach Pradhane75e8eeaae84
diff --git a/docs/acp-compatibility.md b/docs/acp-compatibility.md
index 69eaa995..48337880 100644
--- a/docs/acp-compatibility.md
+++ b/docs/acp-compatibility.md
@@ -31,6 +31,7 @@ optional feature or draft extension is enabled.
| Content | Text, resource links and supported embedded text resources are accepted. Image and audio prompt capabilities are currently advertised as false. | `src/acp_protocol.zig` |
| Client filesystem and terminals | These are optional negotiated ACP facilities, not a requirement that local harness tools be replaced by client tools. The local tool implementation does not imply support for every client-side method. | Capability negotiation and the upstream v1 schema |
| Usage | Connection usage is a namespaced extension. It preserves unknown totals and is not a standard ACP v1 billing contract. | `scripts/test-acp-usage.py`, ADR 0182 |
+| Subagents | The proposed child-session update stream is an opt-in live preview: client `subagents` capability plus `GRAFF_ACP_DRAFT_SUBAGENTS=1`. Foreground children stream separately; detached workers use `graff/agents`. Child history is not yet replayed on `session/load`. | `src/acp_subagent_live.zig`, ADR 0194 |
| Transport | ACP uses JSON-RPC over stdio. HTTP/2 checks exercise the model request transport behind ACP; they do not redefine ACP as an HTTP/2 protocol. | `scripts/test-acp-http2.py`, `scripts/test-acp-http2-retry.py` |
## Client acceptance checklist
diff --git a/docs/adr/0194-acp-child-sessions-are-an-opt-in-preview.md b/docs/adr/0194-acp-child-sessions-are-an-opt-in-preview.md
new file mode 100644
index 00000000..327efcbb
--- /dev/null
+++ b/docs/adr/0194-acp-child-sessions-are-an-opt-in-preview.md
@@ -0,0 +1,28 @@
+# 0194. Live ACP child sessions are an opt-in draft preview
+
+Status: accepted 2026-09-24
+
+## Context
+
+ACP's proposed child-session extension is still under review. Graff already
+records worker activity for process-local inspection, but those snapshots are
+bounded and disappear with the parent process. They cannot satisfy the draft's
+ordered `session/load` replay and orphan recovery requirements.
+
+## Decision
+
+Keep stable ACP behavior as the default. A client that advertises
+`clientCapabilities.subagents` can receive live `subagent_update` and child
+session updates only when Graff is also launched with
+`GRAFF_ACP_DRAFT_SUBAGENTS=1`. Announce only foreground children that complete
+within the active parent prompt; detached workers remain available through
+`graff/agents`. Preserve the parent tool call for clients and early failures,
+with a namespaced tool name and parent call ID for exact UI correlation.
+
+## Consequences
+
+The preview streams child thoughts, messages and tools as they happen, with a
+terminal state before the parent prompt returns. It does not yet replay child
+streams on `session/load`, so it is not full conformance with the draft. Remove
+the environment gate only after durable ordered replay and orphan recovery are
+implemented and tested against the accepted protocol shape.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index e3a5db5e..64add5d8 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -219,6 +219,7 @@ record only when you need the evidence or the edge cases.
| [0191](0191-acp-effort-is-session-configuration.md) | ACP thought-level options follow the active model and share `/effort` state; changes received during a turn apply after that turn. |
| [0192](0192-mimo-thinking-is-a-binary-setting.md) | MiMo exposes Off/On, preserves legacy positive settings as On, and uses the documented thinking control on each wire. |
| [0193](0193-jev-selects-effort-only.md) | Optional Jev selects only supported session effort at the next request boundary; arbitrary judgments are not exposed. |
+| [0194](0194-acp-child-sessions-are-an-opt-in-preview.md) | Draft ACP child sessions stream live only with explicit opt-in; durable replay is required before default enablement. |
| [0195](0195-embedded-browser-replaces-kuri.md) | Desktop browser uses embedded Chromium, web preview uses the paired extension, and CLI fetch uses built-in HTTP without a sidecar. |
## When to write one
diff --git a/src/acp.zig b/src/acp.zig
index 90931f69..a620b912 100644
--- a/src/acp.zig
+++ b/src/acp.zig
@@ -196,7 +196,6 @@ fn nudgeAcp() void {
pub fn runAcpCommand(gpa: Allocator, io: Io, environ_map: anytype, root: *agent_mod.Agent, keys: *provider_mod.Keys, client: *std.http.Client, in: *Io.Reader, out: *Io.Writer, arena: Allocator, flags: args.Flags) !bool {
if (!(flags.positionals.items.len > 0 and std.mem.eql(u8, flags.positionals.items[0], "acp"))) return false;
- _ = environ_map;
_ = client;
main_mod.unattended = true;
// GUI is an interactive root (ADR 0154): park long shells and resume on exit.
@@ -236,6 +235,7 @@ pub fn runAcpCommand(gpa: Allocator, io: Io, environ_map: anytype, root: *agent_
.meter = liveMeter,
.extra = liveModels,
.cwd = if (std.fs.path.isAbsolute(main_mod.g_cwd_display)) main_mod.g_cwd_display else "",
+ .draft_subagents_enabled = std.mem.eql(u8, environ_map.get("GRAFF_ACP_DRAFT_SUBAGENTS") orelse "", "1"),
};
@import("acp_session_load.zig").configure(&d, &live);
while (true) {
diff --git a/src/acp_engine.zig b/src/acp_engine.zig
index 8a0ba669..dbe2f4e5 100644
--- a/src/acp_engine.zig
+++ b/src/acp_engine.zig
@@ -72,8 +72,22 @@ pub const Dispatch = struct {
error_message: ?*const fn (ctx: *anyopaque, err: anyerror) []const u8 = null,
/// Isolated checkout after session start (`g_cwd_display`). Empty omits the field.
cwd: []const u8 = "",
+ /// ACP v1 draft subagent updates are opt-in at initialize.
+ subagents: bool = false,
+ /// The current implementation streams live child activity; historical
+ /// child replay is not yet available, so CLI leaves this off by default.
+ draft_subagents_enabled: bool = false,
};
+fn supportsSubagents(params: ?std.json.Value) bool {
+ const root = params orelse return false;
+ if (root != .object) return false;
+ const caps = root.object.get("clientCapabilities") orelse return false;
+ if (caps != .object) return false;
+ const subagents = caps.object.get("subagents") orelse return false;
+ return subagents == .object;
+}
+
pub fn configOptions(d: *Dispatch, arena: Allocator) ![]const ConfigOption {
const config = d.config orelse return &.{};
const option = try config(d.ctx, arena) orelse return &.{};
@@ -229,7 +243,10 @@ pub fn handlePreAuthLine(arena: Allocator, w: *Io.Writer, line: []const u8) !voi
pub fn handleLine(d: *Dispatch, arena: Allocator, w: *Io.Writer, line: []const u8) !void {
const req = parseRequest(arena, line) orelse return;
- if (std.mem.eql(u8, req.method, "initialize")) return respondInitialize(w, req, d.load_session != null);
+ if (std.mem.eql(u8, req.method, "initialize")) {
+ d.subagents = supportsSubagents(req.params);
+ return respondInitialize(w, req, d.load_session != null);
+ }
if (std.mem.eql(u8, req.method, "authenticate"))
return respondError(w, req, err_method_not_found, "terminal auth is out of band: re-spawn graff login");
if (std.mem.eql(u8, req.method, "session/new")) {
@@ -319,6 +336,22 @@ test "in-process handleLine speaks the same initialize / new / prompt envelopes"
try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"stopReason\":\"end_turn\"") != null);
}
+test "subagent draft updates require explicit client capability" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buf: [8192]u8 = undefined;
+ var out: Io.Writer = .fixed(&buf);
+ var dispatch: Dispatch = .{ .turn = echoTurn, .ctx = undefined };
+ try handleLine(&dispatch, arena.allocator(), &out, "{\"id\":1,\"method\":\"initialize\",\"params\":{\"clientCapabilities\":{}}}");
+ try std.testing.expect(!dispatch.subagents);
+ out = .fixed(&buf);
+ try handleLine(&dispatch, arena.allocator(), &out, "{\"id\":2,\"method\":\"initialize\",\"params\":{\"clientCapabilities\":{\"subagents\":{}}}}");
+ try std.testing.expect(dispatch.subagents);
+ out = .fixed(&buf);
+ try handleLine(&dispatch, arena.allocator(), &out, "{\"id\":3,\"method\":\"initialize\",\"params\":{\"clientCapabilities\":{\"subagents\":null}}}");
+ try std.testing.expect(!dispatch.subagents);
+}
+
test "session/new reports an isolated checkout when Dispatch.cwd is set" {
var state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer state.deinit();
diff --git a/src/acp_live_turn.zig b/src/acp_live_turn.zig
index c22c117c..636f625d 100644
--- a/src/acp_live_turn.zig
+++ b/src/acp_live_turn.zig
@@ -70,7 +70,11 @@ pub const LiveTurn = struct {
self.saw_text = false;
var sink: stream.EventSink = undefined;
sink.init(self.root.gpa, self.out, &self.session_id, &self.saw_text);
+ const subagents = self.dispatch != null and self.dispatch.?.subagents and self.dispatch.?.draft_subagents_enabled;
defer sink.deinit();
+ var child_state: @import("acp_subagent_live.zig").State = .{ .out = self.out, .parent = self.session_id };
+ if (subagents) @import("acp_subagent_live.zig").install(self.root.io, &child_state);
+ defer if (subagents) @import("acp_subagent_live.zig").uninstall(self.root.io);
self.root.out = &sink.writer;
main_mod.g_out = &sink.writer;
defer {
diff --git a/src/acp_stream.zig b/src/acp_stream.zig
index 2dacbc59..9b70330a 100644
--- a/src/acp_stream.zig
+++ b/src/acp_stream.zig
@@ -74,6 +74,7 @@ pub fn writeToolCall(w: *Io.Writer, session_id: []const u8, id: []const u8, name
.kind = kindFor(name),
.status = "in_progress",
.rawInput = input,
+ ._meta = .{ .@"graff/toolName" = name },
},
});
}
diff --git a/src/acp_subagent_live.zig b/src/acp_subagent_live.zig
new file mode 100644
index 00000000..1f0d0080
--- /dev/null
+++ b/src/acp_subagent_live.zig
@@ -0,0 +1,131 @@
+//! ACP v1 draft subagent stream. A child is exposed only while its parent
+//! prompt is active and only after the client negotiated `subagents`.
+const std = @import("std");
+const Io = std.Io;
+const main = @import("main.zig");
+const sink = @import("engine_sink.zig");
+const stream = @import("acp_stream.zig");
+const proto = @import("acp_protocol.zig");
+const util = @import("util.zig");
+
+pub const State = struct {
+ out: *Io.Writer,
+ parent: []const u8,
+};
+
+var active: ?*State = null;
+
+pub fn eligible(kind: []const u8, depth: u8, detached: bool) bool {
+ return depth == 0 and !detached and std.mem.eql(u8, kind, "subagent");
+}
+
+pub fn install(io: Io, state: *State) void {
+ main.g_gui_mu.lockUncancelable(io);
+ defer main.g_gui_mu.unlock(io);
+ active = state;
+}
+
+pub fn uninstall(io: Io) void {
+ main.g_gui_mu.lockUncancelable(io);
+ defer main.g_gui_mu.unlock(io);
+ active = null;
+}
+
+pub fn announce(io: Io, id: []const u8, name: []const u8, task: []const u8, parent_call_id: []const u8) bool {
+ main.g_gui_mu.lockUncancelable(io);
+ defer main.g_gui_mu.unlock(io);
+ const state = active orelse return false;
+ proto.writeNotification(state.out, "session/update", .{ .sessionId = state.parent, .update = .{
+ .sessionUpdate = "subagent_update",
+ .subagentSessionId = id,
+ .name = util.utf8Prefix(name, 256),
+ .task = util.utf8Prefix(task, 2048),
+ ._meta = .{ .@"graff/parentToolCallId" = parent_call_id },
+ } }) catch return false;
+ state.out.flush() catch {};
+ return true;
+}
+
+pub fn finish(io: Io, id: []const u8, outcome: []const u8, parent_call_id: []const u8) void {
+ main.g_gui_mu.lockUncancelable(io);
+ defer main.g_gui_mu.unlock(io);
+ const state = active orelse return;
+ proto.writeNotification(state.out, "session/update", .{ .sessionId = state.parent, .update = .{
+ .sessionUpdate = "subagent_update",
+ .subagentSessionId = id,
+ .state = outcome,
+ ._meta = .{ .@"graff/parentToolCallId" = parent_call_id },
+ } }) catch return;
+ state.out.flush() catch {};
+}
+
+/// Fan out the child's semantic events to its own ACP session, retaining the
+/// existing recorder sink for graff/agents inspection and terminal frontends.
+pub const ChildSink = struct {
+ id: []const u8,
+ io: Io,
+ recorder: ?sink.EngineSink = null,
+
+ pub fn engineSink(self: *ChildSink) sink.EngineSink {
+ return .{ .ctx = self, .vt = &vtable };
+ }
+
+ const vtable: sink.VTable = .{ .emit = emit, .durable = false };
+
+ fn emit(ctx: *anyopaque, stamped: sink.Stamped) void {
+ const self: *ChildSink = @ptrCast(@alignCast(ctx));
+ if (self.recorder) |record| record.vt.emit(record.ctx, stamped);
+ main.g_gui_mu.lockUncancelable(self.io);
+ defer main.g_gui_mu.unlock(self.io);
+ const state = active orelse return;
+ const w = state.out;
+ switch (stamped.event) {
+ .reasoning_delta => |v| stream.writeThought(w, self.id, v.text) catch return,
+ .text_delta => |v| stream.writeMessage(w, self.id, v.text) catch return,
+ .tool_call_announced => |v| {
+ if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
+ stream.writeToolCall(w, self.id, v.id, v.name, v.input) catch return;
+ },
+ .tool_result => |v| {
+ if (v.ask_user or std.mem.eql(u8, v.name, "attempt_completion")) return;
+ stream.writeToolDone(w, self.id, v.id, v.is_error or v.cancelled, v.text) catch return;
+ },
+ .tool_rejected => |v| stream.writeToolDone(w, self.id, v.id, true, v.message) catch return,
+ else => return,
+ }
+ w.flush() catch {};
+ }
+};
+
+test "negotiated child stream announces before activity and terminates on parent" {
+ var buffer: [8192]u8 = undefined;
+ var out: Io.Writer = .fixed(&buffer);
+ const io = std.testing.io;
+ var state: State = .{ .out = &out, .parent = "parent" };
+ install(io, &state);
+ defer uninstall(io);
+ try std.testing.expect(announce(io, "child", "Scout", "Inspect the code", "spawn-1"));
+ var child: ChildSink = .{ .id = "child", .io = io };
+ const emit_sink = child.engineSink();
+ emit_sink.emit(io, .{ .reasoning_delta = .{ .text = "I will inspect it" } });
+ emit_sink.emit(io, .{ .tool_call_announced = .{ .id = "read-1", .name = "read_file", .input = .null } });
+ emit_sink.emit(io, .{ .tool_result = .{ .id = "read-1", .name = "read_file", .text = "contents", .is_error = false } });
+ emit_sink.emit(io, .{ .text_delta = .{ .text = "Found the cause" } });
+ finish(io, "child", "completed", "spawn-1");
+ const wire = out.buffered();
+ const announced = std.mem.indexOf(u8, wire, "\"subagentSessionId\":\"child\"") orelse return error.MissingAnnouncement;
+ const thought = std.mem.indexOf(u8, wire, "agent_thought_chunk") orelse return error.MissingThought;
+ const call = std.mem.indexOf(u8, wire, "\"toolCallId\":\"read-1\"") orelse return error.MissingTool;
+ const answer = std.mem.indexOf(u8, wire, "Found the cause") orelse return error.MissingAnswer;
+ const terminal = std.mem.indexOf(u8, wire, "\"state\":\"completed\"") orelse return error.MissingTerminal;
+ try std.testing.expect(announced < thought and thought < call and call < answer and answer < terminal);
+ try std.testing.expect(std.mem.indexOf(u8, wire, "\"sessionId\":\"child\"") != null);
+ try std.testing.expect(std.mem.indexOf(u8, wire, "\"graff/parentToolCallId\":\"spawn-1\"") != null);
+}
+
+test "draft child sessions exclude detached and nested workers" {
+ try std.testing.expect(eligible("subagent", 0, false));
+ try std.testing.expect(!eligible("subagent", 0, true));
+ try std.testing.expect(!eligible("subagent", 1, false));
+ try std.testing.expect(!eligible("workflow_task", 0, false));
+}
diff --git a/src/exec.zig b/src/exec.zig
index 7d81040d..6105a630 100644
--- a/src/exec.zig
+++ b/src/exec.zig
@@ -352,7 +352,11 @@ fn execToolInner(ctx: ToolCtx, call: ToolCall) !ToolOutput {
// #352: codex-gated. execImagegen answers a call that was never advertised
// (an unavailable session) with the same honest error it gives the model.
if (std.mem.eql(u8, call.name, imagegen.tool_name)) return imagegen.execImagegen(ctx, input);
- if (std.mem.eql(u8, call.name, "subagent")) return execSubagent(ctx, input);
+ if (std.mem.eql(u8, call.name, "subagent")) {
+ var child_ctx = ctx;
+ child_ctx.parent_tool_call_id = call.id;
+ return execSubagent(child_ctx, input);
+ }
if (std.mem.eql(u8, call.name, "workflow")) return execWorkflow(ctx, input);
if (std.mem.eql(u8, call.name, @import("rlm.zig").tool_name)) return @import("rlm.zig").exec(ctx, input);
if (local_tools.isLocal(call.name)) return local_tools.exec(gpa, io, call.name, input);
diff --git a/src/main.zig b/src/main.zig
index 5532ad57..59ec1a60 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -593,7 +593,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("presence_accord.zig"), @import("peer_idle.zig"), @import("acp_idle.zig"), @import("presence_chan.zig"), @import("presence_record.zig"), @import("daddy.zig"), @import("peer_inbox_content_test.zig"), @import("peer_inbox_failure_test.zig"), @import("peer_inbox_storage_test.zig"), @import("peer_inbox_sequence_test.zig"), @import("peer_inbox_snapshot_test.zig") };
_ = @import("acp_agents.zig");
_ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_run_tests.zig") };
- _ = @import("acp_agent_activity.zig");
+ _ = .{ @import("acp_agent_activity.zig"), @import("acp_subagent_live.zig") };
_ = @import("acp_replay.zig");
_ = @import("read_image.zig");
_ = .{ @import("pr_local_checks.zig"), @import("mcp_names.zig"), @import("workspace_history.zig"), @import("file_worktree.zig"), @import("mcp_turn_context.zig"), @import("review_deadline.zig"), @import("issue_cmd.zig"), @import("shell_tool.zig"), @import("acp_ask.zig"), @import("side_steer.zig"), @import("task_workspace_tests.zig"), @import("workspace_prepare_tests.zig"), @import("worktree_reap.zig") };
diff --git a/src/subagent_run.zig b/src/subagent_run.zig
index 0a0d7d2d..8de25fe8 100644
--- a/src/subagent_run.zig
+++ b/src/subagent_run.zig
@@ -356,6 +356,17 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
agent.agent_cwd = ctx.agent_cwd;
}
+ // ACP v1's draft child-session scope is one foreground prompt. Detached
+ // workers keep the existing graff/agents inspection path: they may finish
+ // after session/prompt has returned, which v1 child sessions forbid.
+ const acp_children = @import("acp_subagent_live.zig");
+ const announce_child = acp_children.eligible(kind, ctx.depth, ctx.subagent_feedback != null);
+ const announced = announce_child and acp_children.announce(ctx.io, sub_id, label, prompt, ctx.parent_tool_call_id);
+ var child_stream: acp_children.ChildSink = .{ .id = sub_id, .io = ctx.io, .recorder = agent.sink };
+ if (announced) agent.sink = child_stream.engineSink();
+ var child_state: []const u8 = "failed";
+ defer if (announced) acp_children.finish(ctx.io, sub_id, child_state, ctx.parent_tool_call_id);
+
const wf_task = std.mem.eql(u8, kind, "workflow_task");
if (wf_task) guiEmit(ctx.io, .{ .type = "tool_call", .name = "subagent", .input = .{ .description = label }, .id = sub_id });
const tasked = try @import("subagent_brief.zig").prepare(arena, ctx.io, kind, prompt, ctx.agent_cwd, main_mod.g_hooks.pre_tool);
@@ -382,6 +393,8 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
try @import("subagent_retained.zig").checkpoint(&agent, ctx);
const run_ms: i64 = @intCast(@max(0, sub_start.untilNow(ctx.io, .awake).toMilliseconds()));
const run_ok = if (report) |r| r.len > 0 else |_| false;
+ const interrupted = if (activity) |*recorder| @import("subagent_activity.zig").interruptRequested(ctx.io, recorder.dir, sub_id) else false;
+ child_state = if (interrupted) "cancelled" else if (report) |_| (if (run_ok) "completed" else "failed") else |err| (if (err == error.Interrupted or err == error.Canceled) "cancelled" else "failed");
if (activity) |*recorder| recorder.finish(run_ok, if (report) |r| r else |_| (agent.last_api_error orelse "Sub-agent failed"));
if (wf_task) {
// The sa- id (shared with agent_usage) pairs parallel workflow rows;
diff --git a/src/tools.zig b/src/tools.zig
index b4f297a7..cd85ce7b 100644
--- a/src/tools.zig
+++ b/src/tools.zig
@@ -102,6 +102,7 @@ pub const ToolCtx = struct {
io: Io,
client: *std.http.Client,
provider: Provider,
+ parent_tool_call_id: []const u8 = "",
jev_effort_pending: ?*@import("jev_effort_state.zig").Pending = null,
subagent_provider: ?Provider = null,
subagent_cross_provider: bool = false,