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 Pradhan95a88eafd2a8
diff --git a/docs/acp-compatibility.md b/docs/acp-compatibility.mdindex 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 checklistdiff --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.mdnew file mode 100644index 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.mdindex 9d6bdf1f..e571465b 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. || [0194](0194-native-learning-formal-baseline.md) | Optional native learning admits and promotes only with a fresh pinned formal baseline check bound to the evaluated binary; remote submission waits for a compatible signed receipt. || [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. || [0198](0198-project-choice-survives-session-isolation.md) | New chats inherit the chosen project while ACP reports each worker checkout; generated worktrees are rooted at the main checkout. |diff --git a/src/acp.zig b/src/acp.zigindex 471b2eb7..e24e7390 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.zigindex 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) !voipub 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.zigindex 0dfc2dad..8356ce45 100644--- a/src/acp_live_turn.zig+++ b/src/acp_live_turn.zig@@ -72,7 +72,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.zigindex 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.zignew file mode 100644index 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.zigindex 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.zigindex 6eda7186..eda9c176 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.zigindex 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: []constagent.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: []consttry @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.zigindex 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,