Skip to content

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

Python

Bound workflow synthesis and preserve prior evidence

Rach Pradhan7c0528e6e8c2
diff --git a/build.zig b/build.zig
index e8ec1175..3a3d9409 100644
--- a/build.zig
+++ b/build.zig
@@ -233,6 +233,9 @@ pub fn build(b: *std.Build) void {
const subagent_fork_test = b.addSystemCommand(&.{ "python3", "scripts/test-subagent-fork.py" });
subagent_fork_test.addArtifactArg(exe);
test_step.dependOn(&subagent_fork_test.step);
+ const workflow_synthesis_test = b.addSystemCommand(&.{ "python3", "scripts/test-workflow-synthesis.py" });
+ workflow_synthesis_test.addArtifactArg(exe);
+ test_step.dependOn(&workflow_synthesis_test.step);
const learn_formal_test = b.addSystemCommand(&.{ "python3", "tests/learn_formal_e2e.py", "--graff" });
learn_formal_test.addArtifactArg(exe);
test_step.dependOn(&learn_formal_test.step);
diff --git a/docs/adr/0300-workflow-synthesis-has-a-report-boundary.md b/docs/adr/0300-workflow-synthesis-has-a-report-boundary.md
new file mode 100644
index 00000000..eb66d568
--- /dev/null
+++ b/docs/adr/0300-workflow-synthesis-has-a-report-boundary.md
@@ -0,0 +1,38 @@
+# 0300. Workflow synthesis has a report boundary
+
+## Context
+
+A synthesis worker receives earlier findings but previously had the same
+unbounded tool loop as an investigator. Changing each read slightly avoids the
+identical-call guard, so a final summary could become another investigation
+without ever returning a report. A failed final phase also returned its own
+failure while losing the previous phase's evidence from the workflow result.
+
+## Decision
+
+Canonical `synthesize` phases and pipeline stages have a worker-local allowance
+of eight evidence-bearing model requests, followed by one report-only request.
+The final request omits tools and explicitly asks for a qualified summary.
+Dispatch also refuses tools at that boundary even if a model emits one anyway.
+The allowance stays on the worker across turn retries; it is not a renewed
+per-request or per-turn counter. Ordinary workers and root turns are unchanged.
+
+A worker that still does not finish fails with `WorkflowSynthesisLimit`, not a
+successful-looking timeout report. That failure is not retried as a fresh
+worker. Cancellation is likewise classified as cancellation, not an unknown
+transient failure. Workflow and pipeline failure results retain bounded prior
+stage evidence, explicitly labeled incomplete and not newly verified.
+
+This is shared engine policy, so it applies on the line REPL and ACP clients.
+The bound is on evidence requests, not an elapsed-time guarantee: transport and
+individual tool deadlines continue to own their existing limits.
+
+## Consequences
+
+Synthesis can retrieve details missing from bounded phase summaries, but cannot
+silently redo an entire review. A task requiring further investigation belongs
+in a finder or verifier stage; a synthesis answer may instead identify a gap.
+No whole-session cap is introduced, and useful earlier findings survive even
+when the final report cannot be produced. Offline ACP and JSON fixtures cover
+unique (not merely identical) repeated calls, tool refusal, retained evidence,
+non-retryable exhaustion, and unchanged ordinary workers.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 3e705143..ccd39687 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -319,6 +319,8 @@ record only when you need the evidence or the edge cases.
| [0299](0299-conversation-history-forks-are-explicit.md) | `fork_from` explicitly snapshots current, project-local saved, or family-owned worker history into independent children; lightweight delegation stays the default and `retained` remains opt-in across subagents and workflows. |
+| [0300](0300-workflow-synthesis-has-a-report-boundary.md) | Synthesis gets bounded evidence requests and a final report-only request; cancelled or exhausted workers are not restarted and failed stages retain prior evidence. |
+
## When to write one
Write an ADR when a decision is load-bearing and non-obvious: it was reached
diff --git a/scripts/test-workflow-synthesis.py b/scripts/test-workflow-synthesis.py
new file mode 100644
index 00000000..a4c50121
--- /dev/null
+++ b/scripts/test-workflow-synthesis.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Bound synthesis on the real ACP/JSON engine using an offline mock model."""
+import importlib.util
+import json
+from pathlib import Path
+import re
+import sys
+import tempfile
+import threading
+import traceback
+
+REPO = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location('fork_fixture', REPO / 'scripts/test-subagent-fork.py')
+fixture = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(fixture)
+
+
+def task(name, description=None):
+ return {'description': description or name,
+ 'prompt': 'SYNTH_TASK:' + name + ' Run the supplied fixture commands for alpha.txt, beta.txt and gamma.txt, then report the evidence.',
+ 'isolation': 'shared_cwd'}
+
+
+def workflow(name, pipeline=False):
+ if pipeline:
+ stages = [task('EVIDENCE', 'find'), task(name, 'synthesize')]
+ return fixture.tool('workflow', pipeline={'items': ['alpha.txt'], 'stages': stages})
+ return fixture.tool('workflow', phases=[
+ {'title': 'find', 'tasks': [task('EVIDENCE_A'), task('EVIDENCE_B')]},
+ {'title': 'synthesize', 'tasks': [task(name)]}])
+
+
+class Model(fixture.ScriptedModel):
+ def __init__(self, root):
+ super().__init__([])
+ self.root = root
+ self.lock = threading.Lock()
+ self.calls = {}
+ self.errors = []
+ self.finished = False
+ self.started = False
+ self.parent = self.sequence()
+
+ def next_reply(self, body):
+ super().next_reply(body)
+ users = json.dumps([m.get('content', '') for m in body.get('messages', [])
+ if m.get('role') == 'user'])
+ names = re.findall(r'SYNTH_TASK:([A-Z_]+)', users)
+ with self.lock:
+ try:
+ assert names, 'missing task marker'
+ name = names[-1]
+ if name == 'ROOT':
+ if not self.started:
+ self.started = True
+ return next(self.parent)
+ return self.parent.send(body)
+ calls = self.calls.setdefault(name, [])
+ calls.append(body)
+ n = len(calls)
+ if name.startswith('EVIDENCE'):
+ return {'text': 'FINDING: EARLIER_VERIFIED_EVIDENCE from alpha.txt:1'}
+ # Unique inputs and outputs deliberately avoid the identical-call
+ # guard: synthesis must be bounded even while reads keep changing.
+ if n <= (11 if name == 'GENERAL' else 8):
+ assert body.get('tools'), (name, n, 'tools withdrawn too early')
+ return fixture.tool('bash', command='printf UNIQUE_' + name + '_' + str(n))
+ if name == 'GENERAL':
+ return {'text': 'GENERAL_DONE'}
+ assert n == 9, (name, n, 'synthesis exceeded its request allowance')
+ assert not body.get('tools'), (name, 'report request still advertises tools')
+ if name.startswith('BAD'):
+ return fixture.tool('bash', command='printf FORBIDDEN > forbidden-' + name + '.txt')
+ return {'text': 'SYNTHESIS_DONE_' + name}
+ except Exception:
+ self.errors.append(traceback.format_exc())
+ # Even the unfixed binary receives a final answer, never an
+ # indefinitely repeating mock. The assertion below is the failure.
+ return {'text': 'SYNTHESIS_FIXTURE_FAILED'}
+
+ def sequence(self):
+ for name, pipeline in [('NORMAL', False), ('BAD_PHASE', False), ('BAD_PIPELINE', True)]:
+ body = yield workflow(name, pipeline)
+ output = fixture.last_output(body)
+ assert len(self.calls.get(name, [])) == 9, (name, len(self.calls.get(name, [])), output)
+ if name.startswith('BAD'):
+ assert 'WorkflowSynthesisLimit' in output, output
+ assert 'EARLIER_VERIFIED_EVIDENCE' in output, output
+ assert 'workflow incomplete' in output, output
+ assert not (self.root / ('forbidden-' + name + '.txt')).exists()
+ else:
+ assert 'SYNTHESIS_DONE_NORMAL' in output, output
+ body = yield fixture.tool('subagent', **dict(task('GENERAL'), run_in_background=False))
+ assert len(self.calls.get('GENERAL', [])) == 12
+ assert 'GENERAL_DONE' in fixture.last_output(body)
+ self.finished = True
+ yield {'text': 'SYNTHESIS_FIXTURE_DONE'}
+
+
+def check(binary, surface):
+ with tempfile.TemporaryDirectory(prefix='graff-synthesis-') as temporary:
+ root = Path(temporary).resolve()
+ home = root / 'home'
+ home.mkdir()
+ for name in ('alpha.txt', 'beta.txt', 'gamma.txt'):
+ (root / name).write_text('Synthetic evidence.\n')
+ model = Model(root)
+ port = model.start(0)
+ try:
+ runner = fixture.acp_turn if surface == 'acp' else fixture.legacy_turn
+ runner(binary, root, home, port,
+ 'SYNTH_TASK:ROOT Audit alpha.txt, beta.txt and gamma.txt using the supplied workflow fixture.')
+ assert not model.errors, '\n'.join(model.errors)
+ assert model.finished, 'parent did not receive a final workflow result'
+ finally:
+ model.stop()
+ print('PASS ' + surface + ': bounded synthesis, report-only dispatch, preserved findings, no retry, ordinary workers unchanged')
+
+
+if __name__ == '__main__':
+ binary = Path(sys.argv[1] if len(sys.argv) > 1 else REPO / 'zig-out/bin/graff').resolve()
+ for surface in ('acp', 'json'):
+ check(binary, surface)
diff --git a/src/agent.zig b/src/agent.zig
index efb1674b..16335f10 100644
--- a/src/agent.zig
+++ b/src/agent.zig
@@ -106,6 +106,7 @@ pub const Agent = struct {
/// score re-reading files it had already been given. With no tools it must
/// answer from the excerpt in one call, which is what it was designed for.
text_only: bool = false,
+ synthesis: @import("workflow_synthesis.zig").State = .{},
read_only: bool = false, // informational child: reads kept, writes refused (#1360, agent_tool_gate)
label: []const u8,
out: ?*Io.Writer,
diff --git a/src/agent_tools.zig b/src/agent_tools.zig
index 93d30322..c6ad4869 100644
--- a/src/agent_tools.zig
+++ b/src/agent_tools.zig
@@ -194,6 +194,11 @@ fn refuseRead(self: *Agent, call: ToolCall) !ExecResult {
}
pub fn rejectToolCall(self: *Agent, call: ToolCall) !?ExecResult {
+ if (self.sub and self.synthesis.reporting()) {
+ const message = @import("workflow_synthesis.zig").tool_refusal;
+ self.emitToolRejected(call, "workflow_synthesis", message);
+ return .{ .text = message, .is_error = true };
+ }
if (!call.args_ok) {
const message = if (call.cut) tool_call_args.cut_exec_message else tool_call_args.invalid_exec_message;
self.emitToolRejected(call, "invalid_arguments", message);
diff --git a/src/agent_turn.zig b/src/agent_turn.zig
index 2fa59caf..ce55007f 100644
--- a/src/agent_turn.zig
+++ b/src/agent_turn.zig
@@ -80,6 +80,7 @@ pub fn run(self: *Agent, root_turn_prepared: *std.atomic.Value(bool)) anyerror![
try self.ensureRootTools(self.provider.kind);
}
}
+ if (self.sub) try self.synthesis.beforeRequest(self);
const hist_len = self.messages.items.len;
const root = self.request(if (self.text_only) null else self.toolsJson()) catch |err| {
if (try @import("agent_length_cutoff.zig").recoverRunaway(self, err, hist_len)) continue;
diff --git a/src/main.zig b/src/main.zig
index 82dfc016..736edcda 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -592,7 +592,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = @import("goal_pacing.zig");
_ = .{ @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("repo_context_tests.zig") };
- _ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_history.zig"), @import("subagent_history_copy.zig"), @import("subagent_history_tests.zig"), @import("subagent_run_tests.zig") };
+ _ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_history.zig"), @import("subagent_history_copy.zig"), @import("subagent_history_tests.zig"), @import("subagent_run_tests.zig"), @import("workflow_synthesis.zig") };
_ = .{ @import("acp_agent_activity.zig"), @import("acp_subagent_live.zig"), @import("acp_line_writer.zig") };
_ = .{ @import("acp_replay.zig"), @import("python_version.zig"), @import("jev_auto.zig"), @import("background_wait.zig"), @import("gateway_compact_tests.zig") };
_ = @import("read_image.zig");
diff --git a/src/schema_agents.zig b/src/schema_agents.zig
index 4e0874a7..b3ebc976 100644
--- a/src/schema_agents.zig
+++ b/src/schema_agents.zig
@@ -19,7 +19,7 @@ pub const agent_output_spec = ToolSpec{
pub const workflow_spec = ToolSpec{
.name = "workflow",
- .desc = "Run a workflow of parallel subagents (dynamic workflows as data). Two shapes. PHASES (fan-out + synthesis): phases run sequentially; tasks inside a phase run in parallel as isolated subagents. Optional fork_from gives each a private copy of current, session:<name>, or worker:<task_id> history; retained:true saves each worker for later continuation. Otherwise every prompt must be self-contained; from phase 2 on, {{prev}} in a task prompt is replaced with the labeled results of the previous phase (appended if omitted); a phase may carry `when` to run only if a substring appears in {{prev}} (conditional / early-exit). Returns the final phase results. Use for audits, multi-perspective review, parallel research. Tasks may carry their own system_prompt to run prompt variants side by side; when the fleet is on, a phase with 2+ variants is auto-scored by an LLM judge and each variant's fitness feeds back to the fleet (a tournament doubles as a DGM scoring round). PIPELINE (no barrier): pass {pipeline:{items,stages}} instead to map each item through the stages independently — item A can reach stage 3 while item B is still on stage 1; {{item}} is the item and {{prev}} is this item's previous-stage result. Use for per-item work like transform/verify each file. Optional top-level \"context\" (also settable on the pipeline object): one shared string prepended once, plus a blank line, to every task/stage prompt before {{prev}} substitution, so repo/task boilerplate is stated once instead of repeated in every task.",
+ .desc = "Run a workflow of parallel subagents (dynamic workflows as data). Two shapes. PHASES (fan-out + synthesis): phases run sequentially; tasks inside a phase run in parallel as isolated subagents. Optional fork_from gives each a private copy of current, session:<name>, or worker:<task_id> history; retained:true saves each worker for later continuation. Otherwise every prompt must be self-contained; from phase 2 on, {{prev}} in a task prompt is replaced with the labeled results of the previous phase (appended if omitted); a phase may carry `when` to run only if a substring appears in {{prev}} (conditional / early-exit). Returns the final phase results. A synthesize phase or stage gets eight evidence requests, then one report-only request; if it fails, earlier evidence returns as incomplete rather than restarting synthesis. Use for audits, multi-perspective review, parallel research. Tasks may carry their own system_prompt to run prompt variants side by side; when the fleet is on, a phase with 2+ variants is auto-scored by an LLM judge and each variant's fitness feeds back to the fleet (a tournament doubles as a DGM scoring round). PIPELINE (no barrier): pass {pipeline:{items,stages}} instead to map each item through the stages independently — item A can reach stage 3 while item B is still on stage 1; {{item}} is the item and {{prev}} is this item's previous-stage result. Use for per-item work like transform/verify each file. Optional top-level \"context\" (also settable on the pipeline object): one shared string prepended once, plus a blank line, to every task/stage prompt before {{prev}} substitution, so repo/task boilerplate is stated once instead of repeated in every task.",
.schema =
\\{"type":"object","properties":{"fork_from":{"type":"string","description":"Optional: snapshot current, session:<project-local saved name>, or worker:<owned retained task_id> once for all phase or pipeline workers. Source stays unchanged; each child owns its history, tools and workspace selection. Same rules as subagent.fork_from."},"retained":{"type":"boolean","description":"Optional: retain each phase/pipeline worker and workspace; reports include task_id for subagent_resume or further forks. Default false."},"phases":{"type":"array","description":"Fan-out + synthesis mode (barrier between phases).","items":{"type":"object","properties":{"title":{"type":"string","description":"Short phase label for logs"},"when":{"type":"string","description":"Optional (phase 2+): run this phase only if this substring appears (case-insensitive) in the previous phase's results \u2014 gate a synthesis/exit phase on a sentinel"},"tasks":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Short label, 3-5 words"},"prompt":{"type":"string","description":"Complete, self-contained task; may contain {{prev}}"},"agent":{"type":"string","description":"Optional: a named agent type (reviewer, researcher, implementer, skeptic, or a .harness/agents/ name)"},"system_prompt":{"type":"string","description":"Optional: replace this task's system prompt (overrides agent)"},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Optional: fan-out tasks default to \"worktree\" (own branch + checkout). Use \"shared_cwd\" only when this task must share the same branch and files. isolation_fallback:true is the only way a failed git worktree add may share the caller tree."},"isolation_fallback":{"type":"boolean","description":"Optional: if isolation:\"worktree\" fails to set up, run in the shared working tree instead of failing this task. Default false."}},"required":["description","prompt"]}}},"required":["tasks"]}},"context":{"type":"string","description":"Optional: prepended once, plus a blank line, to every task prompt before {{prev}} substitution."},"pipeline":{"type":"object","description":"No-barrier mode: map each item through the stages independently.","properties":{"items":{"type":"array","items":{"type":"string"},"description":"Things to process, one independent chain each (e.g. file paths)"},"stages":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","description":"Short stage label"},"prompt":{"type":"string","description":"Self-contained; {{item}} = the item, {{prev}} = this item's previous-stage result"},"agent":{"type":"string","description":"Optional named agent type"},"system_prompt":{"type":"string","description":"Optional: replace this stage's system prompt"},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Optional: pipeline stages default to \"shared_cwd\" so later stages see earlier edits. Stage 0 may set \"worktree\". isolation_fallback:true is the only way a failed git worktree add may share the caller tree."},"isolation_fallback":{"type":"boolean","description":"Optional: if isolation:\"worktree\" fails to set up, run in the shared working tree instead of failing this stage. Default false."}},"required":["description","prompt"]}},"context":{"type":"string","description":"Optional: prepended once, plus a blank line, to every stage prompt before {{item}}/{{prev}} substitution."},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"Create one worktree per item and reuse it across all stages; preserve changes and return the path/branch."}},"required":["items","stages"]},"isolation":{"type":"string","enum":["shared_cwd","worktree"],"description":"For phases, share one retained worktree across all dependent stages; results include its path and branch for explicit delivery. For pipeline isolation set this on pipeline instead."}}}
,
diff --git a/src/subagent_retry.zig b/src/subagent_retry.zig
index d1f3cf98..11396621 100644
--- a/src/subagent_retry.zig
+++ b/src/subagent_retry.zig
@@ -113,7 +113,7 @@ pub fn attemptBudget(kind: FailKind, detail: ?[]const u8) u8 {
// Structural: an unavailable model, a malformed request, or the
// harness's own dry call budget. Re-asking is guaranteed to fail
// identically, and is still CHARGED for trying.
- .model, .invalid, .budget_exhausted => 1,
+ .model, .invalid, .budget_exhausted, .cancelled, .synthesis_limit => 1,
};
}
diff --git a/src/subagent_run.zig b/src/subagent_run.zig
index 9ba16c23..319929dc 100644
--- a/src/subagent_run.zig
+++ b/src/subagent_run.zig
@@ -53,6 +53,8 @@ pub const FailKind = enum {
/// waiting or retrying changes it — the next attempt is refused before it
/// reaches the network, and is still charged for trying.
budget_exhausted,
+ cancelled,
+ synthesis_limit,
unknown,
pub fn label(self: FailKind) []const u8 {
@@ -63,6 +65,8 @@ pub const FailKind = enum {
.invalid => "invalid-arguments",
.auth => "auth",
.budget_exhausted => "model-call-budget",
+ .cancelled => "cancelled",
+ .synthesis_limit => "synthesis-limit",
.unknown => "unknown",
};
}
@@ -70,7 +74,7 @@ pub const FailKind = enum {
pub fn retrySafe(self: FailKind) bool {
return switch (self) {
.quota, .transport, .unknown => true,
- .model, .invalid, .auth, .budget_exhausted => false,
+ .model, .invalid, .auth, .budget_exhausted, .cancelled, .synthesis_limit => false,
};
}
};
@@ -94,6 +98,8 @@ fn containsAnyCI(hay: []const u8, needles: []const []const u8) bool {
pub fn classifyFailure(err: anyerror, detail: ?[]const u8) FailKind {
switch (err) {
+ error.Interrupted, error.Canceled => return .cancelled,
+ error.WorkflowSynthesisLimit => return .synthesis_limit,
error.StreamStalled, error.StreamDropped => return .transport,
else => {},
}
@@ -144,14 +150,17 @@ pub const retry_unsafe_note = "retry is NOT safe as-is — fix the cause first (
/// them; this ordering keeps the count and the prefix.
pub fn subagentFailure(gpa: Allocator, sub_id: []const u8, err: anyerror, detail: ?[]const u8, attempts: u8) ToolOutput {
const kind = classifyFailure(err, detail);
- const cause = detail orelse @errorName(err);
- const retry = if (kind.retrySafe()) retry_ok_note else retry_unsafe_note;
+ const cause = if (kind == .cancelled or kind == .synthesis_limit) @errorName(err) else detail orelse @errorName(err);
+ const retry = switch (kind) {
+ .cancelled, .synthesis_limit => "retry is NOT safe as-is — the worker stopped; use the completed evidence without restarting it",
+ else => if (kind.retrySafe()) retry_ok_note else retry_unsafe_note,
+ };
const text = std.fmt.allocPrint(
gpa,
"subagent {s} failed before producing a report: {s} [{s} failure, {d} {s}]. {s}",
.{ sub_id, cause, kind.label(), attempts, subagent_retry.attemptsWord(attempts), retry },
) catch return .{ .is_error = true };
- return .{ .text = text, .is_error = true };
+ return .{ .text = text, .is_error = true, .cancelled = kind == .cancelled };
}
/// Whether a workflow retry site should re-run a failed task. Failures that
@@ -163,7 +172,7 @@ pub fn subagentFailure(gpa: Allocator, sub_id: []const u8, err: anyerror, detail
/// isolation-setup failure) carries no marker and keeps retrying, since those
/// are exactly the transient cases retry exists for.
pub fn failureAllowsRetry(text: []const u8) bool {
- return std.mem.indexOf(u8, text, retry_unsafe_note) == null;
+ return std.mem.indexOf(u8, text, "retry is NOT safe as-is") == null;
}
pub fn childProvider(root: Provider, pinned: ?Provider, allow_cross_provider: bool) Provider {
@@ -297,6 +306,7 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
// only buys it the chance to go re-read the repo — which is where its
// ~3 calls per score went. One judge, one call.
.text_only = std.mem.eql(u8, kind, "judge_task"),
+ .synthesis = .{ .enabled = ctx.synthesis and !std.mem.eql(u8, kind, "judge_task") },
// #1360: an informational child still needs its read tools; it is
// read-only, not tool-less.
.read_only = @import("task_intent.zig").classify(prompt) == .informational,
@@ -329,7 +339,7 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
recorder.setModel(agent.provider.id, agent.provider.model);
if (@import("subagent_activity.zig").interruptRequested(ctx.io, recorder.dir, sub_id)) {
recorder.finish(false, "Interrupted.");
- return .{ .output = .{ .text = try gpa.dupe(u8, "Interrupted."), .is_error = true }, .usage = .{} };
+ return .{ .output = subagentFailure(gpa, sub_id, error.Interrupted, null, 0), .usage = .{} };
}
agent.sink = recorder.engineSink();
}
@@ -423,6 +433,7 @@ pub fn runSub(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const
agent.sleepInterruptible(@import("retry_jitter.zig").ms(agent.io, subagent_retry.backoffMs(fail_kind, attempts))) catch break :ask r; // #1274
}
};
+ agent.synthesis.finish(&agent);
// A worker that ran keeps its report and usage when its state can't be
// saved for follow-ups; the save error used to replace both (#1671).
const retained_failure: ?anyerror = if (@import("subagent_retained.zig").checkpoint(&agent, ctx)) |_| null else |e| e;
diff --git a/src/subagent_run_tests.zig b/src/subagent_run_tests.zig
index 821eb36c..fcb5404b 100644
--- a/src/subagent_run_tests.zig
+++ b/src/subagent_run_tests.zig
@@ -52,6 +52,21 @@ test "failureAllowsRetry keys off the harness's own retry-safety classification"
try std.testing.expect(failureAllowsRetry("subagent finished without a report"));
}
+test "cancelled and synthesis-limited workers are not unknown retryable failures" {
+ const gpa = std.testing.allocator;
+ for ([_]anyerror{ error.Interrupted, error.Canceled, error.WorkflowSynthesisLimit }) |err| {
+ const out = subagentFailure(gpa, "worker", err, null, 1);
+ defer gpa.free(out.text);
+ try std.testing.expect(out.is_error);
+ try std.testing.expect(!failureAllowsRetry(out.text));
+ try std.testing.expectEqual(err != error.WorkflowSynthesisLimit, out.cancelled);
+ const kind = run.classifyFailure(err, "503 stale transport detail");
+ try std.testing.expect(!kind.retrySafe());
+ try std.testing.expect(!subagent_retry.shouldRetry(err, kind, null, 1));
+ try std.testing.expect(std.mem.indexOf(u8, out.text, "unknown failure") == null);
+ }
+}
+
test "a worker failure names how many asks it actually made (fleet honesty)" {
const gpa = std.testing.allocator;
diff --git a/src/tools.zig b/src/tools.zig
index 6e6c9520..f87943ac 100644
--- a/src/tools.zig
+++ b/src/tools.zig
@@ -148,6 +148,7 @@ pub const ToolCtx = struct {
parent_task: []const u8 = "", // ADR 0232: the user's prompts a spawned child sees as context
fork_source: ?@import("subagent_history.zig").Snapshot = null,
retain_children: bool = false, // explicit workflow retention, not inherited by judges
+ synthesis: bool = false, // canonical workflow synthesis, not ordinary delegated work
read_only_shell: bool = false, // ADR 0232: a read-only child's foreground shell runs under the seatbelt sandbox
};
diff --git a/src/workflow.zig b/src/workflow.zig
index a49f9088..dc3b3a2c 100644
--- a/src/workflow.zig
+++ b/src/workflow.zig
@@ -396,11 +396,12 @@ fn execWorkflowShared(ctx: ToolCtx, input: Value) !ToolOutput {
// #380: …then asked whether any task in it names an image the seat
// cannot see. A re-seat stays phase-UNIFORM, so #290 is untouched.
const seat = vision_ask.phaseSeat(route_phase.forPhase(subagent_run.childProvider(ctx.provider, ctx.subagent_provider, ctx.subagent_cross_provider), shape, title, niches, ctx.subagent_provider != null), prompts, ctx.subagent_provider != null);
+ const phase_ctx = @import("workflow_synthesis.zig").context(ctx, title);
for (labels, prompts, overrides, niches, isolations, isolation_fallbacks, futures, 0..) |label, prompt, override, niche, isolation, isolation_fallback, *fut, i| {
if (dup.rep[i] != i) continue; // §2b: a collapsed duplicate spawns nothing
wfp.task(ctx.io, arena, run_id, phase_no, i + 1, tasks.len, label, "running"); // #63
route_trace.emitSpawnProvider(ctx.io, ctx.tracer, label, seat.provider, seat.cellOf(niche), seat.sourceFor(override != null), override, niche);
- fut.* = ctx.io.async(workflowTask, .{ ctx, label, prompt, override, niche, isolation, isolation_fallback, seat.pin });
+ fut.* = ctx.io.async(workflowTask, .{ phase_ctx, label, prompt, override, niche, isolation, isolation_fallback, seat.pin });
}
for (futures, outputs, labels, prompts, raws, 0..) |*fut, *out, label, prompt, raw, i| {
if (dup.rep[i] != i) continue;
@@ -451,7 +452,7 @@ fn execWorkflowShared(ctx: ToolCtx, input: Value) !ToolOutput {
const refut = try arena.alloc(Io.Future(ToolOutput), nf);
for (refut, 0..) |*rf, k| {
const i = fidx[k];
- rf.* = ctx.io.async(workflowRetryTask, .{ ctx, labels[i], prompts[i], overrides[i], niches[i], isolations[i], isolation_fallbacks[i], seat.pin });
+ rf.* = ctx.io.async(workflowRetryTask, .{ phase_ctx, labels[i], prompts[i], overrides[i], niches[i], isolations[i], isolation_fallbacks[i], seat.pin });
}
for (refut, 0..) |*rf, k| {
const i = fidx[k];
@@ -488,7 +489,7 @@ fn execWorkflowShared(ctx: ToolCtx, input: Value) !ToolOutput {
// The all-failed abort is the harness's own observation of a
// failed attempt — parked as evidence for the next escalation.
escalation.failure_evidence.note(shapes.classOf(shapes.rawAsk()), abort_text);
- return .{ .text = try gpa.dupe(u8, abort_text), .is_error = true };
+ return .{ .text = try gpa.dupe(u8, try @import("workflow_synthesis.zig").withEvidence(arena, abort_text, prev_results)), .is_error = true };
}
// #1 — Ultracode → DGM engine: when ≥2 persona variants competed this
diff --git a/src/workflow_pipeline.zig b/src/workflow_pipeline.zig
index 5fe751e2..cf2290d6 100644
--- a/src/workflow_pipeline.zig
+++ b/src/workflow_pipeline.zig
@@ -131,7 +131,8 @@ fn pipelineChainShared(ctx: ToolCtx, item: []const u8, stages: []const StageSpec
// Counters only — the fitness fold happens per STAGE after run()'s
// join (#296), never here where it would be a per-item row (#290).
stat.noteAttempt();
- var out = if (runWorkflow(ctx, "workflow_task", st.label, prompt, st.override, st.niche, .shared_cwd, st.isolation_fallback, st.seat.pin)) |r| r.output else |e| failure(gpa, e);
+ const stage_ctx = @import("workflow_synthesis.zig").context(ctx, st.label);
+ var out = if (runWorkflow(stage_ctx, "workflow_task", st.label, prompt, st.override, st.niche, .shared_cwd, st.isolation_fallback, st.seat.pin)) |r| r.output else |e| failure(gpa, e);
if (out.is_error) {
// Only spend the one retry (#2) when the harness's own
// classification hasn't already ruled it out (auth, invalid
@@ -141,7 +142,7 @@ fn pipelineChainShared(ctx: ToolCtx, item: []const u8, stages: []const StageSpec
gpa.free(out.text);
// The SAME seat: a retry that changed model would break the
// stage uniformity the fitness row attributes to.
- out = if (runWorkflow(ctx, "workflow_retry", st.label, prompt, st.override, st.niche, .shared_cwd, st.isolation_fallback, st.seat.pin)) |r| r.output else |e| failure(gpa, e);
+ out = if (runWorkflow(stage_ctx, "workflow_retry", st.label, prompt, st.override, st.niche, .shared_cwd, st.isolation_fallback, st.seat.pin)) |r| r.output else |e| failure(gpa, e);
}
if (out.is_error) {
// #248 — excerpt the stage's own error BEFORE freeing it, so
@@ -153,10 +154,10 @@ fn pipelineChainShared(ctx: ToolCtx, item: []const u8, stages: []const StageSpec
std.fmt.allocPrint(gpa, "(pipeline stopped at stage {d}/{d} \"{s}\": task failed)\n{s}", .{ stage_no, stages.len, st.label, detail })
else
std.fmt.allocPrint(gpa, "(pipeline stopped at stage {d}/{d} \"{s}\": task failed)", .{ stage_no, stages.len, st.label });
- return .{
- .text = msg catch (gpa.dupe(u8, "(pipeline stage failed)") catch ""),
- .is_error = true,
- };
+ const failed = msg catch return failure(gpa, error.OutOfMemory);
+ defer gpa.free(failed);
+ const evidence = @import("workflow_synthesis.zig").withEvidence(arena, failed, prev) catch return failure(gpa, error.OutOfMemory);
+ return .{ .text = gpa.dupe(u8, evidence) catch return failure(gpa, error.OutOfMemory), .is_error = true };
}
}
stat.noteOk();
diff --git a/src/workflow_synthesis.zig b/src/workflow_synthesis.zig
new file mode 100644
index 00000000..b6022f53
--- /dev/null
+++ b/src/workflow_synthesis.zig
@@ -0,0 +1,113 @@
+//! Synthesis consumes evidence; it must not become another unbounded review.
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const tools = @import("tools.zig");
+
+pub const evidence_requests: u8 = 8;
+pub const report_notice = "Internal workflow boundary, not a new user request: synthesis has used its evidence-reading allowance. Tools are now unavailable. Deliver the best summary from the supplied findings and observations, explicitly marking gaps and uncertainty. Do not restart the investigation or claim missing verification succeeded.";
+pub const tool_refusal = "Workflow synthesis is now report-only. Summarize the evidence already available; no further tools will run.";
+
+pub fn context(parent: tools.ToolCtx, slot: []const u8) tools.ToolCtx {
+ var child = parent;
+ child.synthesis = std.mem.eql(u8, @import("shapes.zig").canonicalSlot(slot), "synthesize");
+ return child;
+}
+
+pub const State = struct {
+ enabled: bool = false,
+ requests: u8 = 0,
+ prior_text_only: ?bool = null,
+
+ pub fn reporting(self: State) bool {
+ return self.enabled and self.requests > evidence_requests;
+ }
+
+ pub fn beforeRequest(self: *State, agent: *Agent) !void {
+ if (!self.enabled) return;
+ // Kept on the worker, not the turn stack: transport retries cannot
+ // renew the allowance by re-entering runTurn with the same history.
+ if (self.reporting()) return error.WorkflowSynthesisLimit;
+ if (self.requests == evidence_requests) {
+ var note = try @import("named_work.zig").userNudge(agent.arena, agent.provider.kind, report_notice);
+ try note.object.put(agent.arena, @import("session_wake.zig").origin_key, .{ .string = "notification" });
+ try agent.messages.append(note);
+ self.prior_text_only = agent.text_only;
+ agent.text_only = true;
+ if (agent.tracer) |tr| tr.note("workflow_synthesis", "evidence allowance spent; final report-only request");
+ }
+ self.requests += 1;
+ }
+
+ pub fn finish(self: *State, agent: *Agent) void {
+ // Report-only is task-local, not a new durable capability restriction.
+ if (self.prior_text_only) |prior| agent.text_only = prior;
+ self.prior_text_only = null;
+ }
+};
+
+/// An aborted final stage does not erase the already-completed review.
+pub fn withEvidence(a: std.mem.Allocator, failure: []const u8, previous: []const u8) ![]const u8 {
+ if (previous.len == 0) return failure;
+ return std.fmt.allocPrint(a, "{s}\n\n## Previous stage evidence (workflow incomplete)\n{s}\n\nUse this evidence with its stated limitations; the failed stage did not verify it.", .{ failure, @import("workflow.zig").cappedPrevBody(a, previous, 6000) });
+}
+
+fn fixture(a: std.mem.Allocator) Agent {
+ return .{ .gpa = a, .arena = a, .io = std.testing.io, .client = undefined, .provider = .{ .id = "test", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 128000 }, .messages = .init(a), .sub = true, .label = "test", .out = null };
+}
+
+test "workflow synthesis bounds exploration and permits one report-only request" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var agent = fixture(arena.allocator());
+ agent.synthesis.enabled = true;
+ for (0..8) |_| {
+ try agent.synthesis.beforeRequest(&agent);
+ try std.testing.expect(!agent.text_only);
+ }
+ try agent.synthesis.beforeRequest(&agent);
+ try std.testing.expect(agent.text_only);
+ try std.testing.expect(agent.synthesis.reporting());
+ try std.testing.expect(@import("session_wake.zig").isNotice(agent.messages.items[0]));
+ try std.testing.expectError(error.WorkflowSynthesisLimit, agent.synthesis.beforeRequest(&agent));
+ try std.testing.expectError(error.WorkflowSynthesisLimit, agent.synthesis.beforeRequest(&agent));
+}
+
+test "workflow synthesis restores the original tool restriction before retention" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ for ([_]bool{ false, true }) |prior| {
+ var agent = fixture(arena.allocator());
+ agent.text_only = prior;
+ agent.synthesis = .{ .enabled = true, .requests = 8 };
+ try agent.synthesis.beforeRequest(&agent);
+ try std.testing.expect(agent.text_only);
+ agent.synthesis.finish(&agent);
+ try std.testing.expectEqual(prior, agent.text_only);
+ try std.testing.expectError(error.WorkflowSynthesisLimit, agent.synthesis.beforeRequest(&agent));
+ }
+}
+
+test "workflow synthesis gate refuses tools even when a model ignores tool withdrawal" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var agent = fixture(arena.allocator());
+ agent.synthesis = .{ .enabled = true, .requests = 9 };
+ const call: tools.ToolCall = .{ .id = "blocked", .name = "shell", .input = .null };
+ const denied = (try agent.rejectToolCall(call)).?;
+ try std.testing.expect(denied.is_error);
+ try std.testing.expectEqualStrings(tool_refusal, denied.text);
+}
+
+test "workflow synthesis does not cap ordinary workers or discard earlier findings" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ var agent = fixture(a);
+ for (0..20) |_| try agent.synthesis.beforeRequest(&agent);
+ try std.testing.expect(!agent.text_only);
+ try std.testing.expectEqual(@as(u8, 0), agent.synthesis.requests);
+ const text = try withEvidence(a, "WorkflowSynthesisLimit", "FINDING: observed evidence");
+ try std.testing.expect(std.mem.indexOf(u8, text, "workflow incomplete") != null);
+ try std.testing.expect(std.mem.indexOf(u8, text, "FINDING: observed evidence") != null);
+ try std.testing.expectEqualStrings("failure", try withEvidence(a, "failure", ""));
+}