graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! #330 embedder mode: the hard `--no-local-tools` gate.
//!
//! An embedder runs graff as the reasoning loop on a TRUSTED host and reaches
//! the sandbox only through tool calls, so the built-in tools that touch this
//! machine have to be gone rather than merely un-approved. A permission rule is
//! something a prompt-injected model can argue its way past; a tool that does
//! not exist is not. The coding tools come back in over MCP - the embedder
//! stands up a sandbox-proxy server and points graff at it - and this gate
//! never touches MCP-sourced tools, which is the whole point.
//!
//! Two enforcement layers, both required, because either alone is a promise
//! rather than a guarantee:
//! 1. the gated tools are never advertised - schema.zig drops them from the
//! root catalog (effectiveRootSpecs) and from the comptime subagent
//! catalogs, so no provider is told they exist;
//! 2. dispatch refuses - exec.zig's guard chain answers a hallucinated call
//! with a tool error naming the flag, before anything runs.
//!
//! The switch is process-global on purpose. Subagents, workflow workers,
//! retries and judges all run in-process through the same exec path, so one
//! flag covers the whole agent tree and there is no per-agent state anyone can
//! forget to inherit.
const std = @import("std");
const Allocator = std.mem.Allocator;
/// Set once at startup by `--no-local-tools` (args.zig) or
/// `GRAFF_NO_LOCAL_TOOLS=1` (session_run.zig). Never flipped mid-session.
pub var enabled: bool = false;
/// The built-in tools that reach this host: the advertised `shell` tool, the
/// three file tools, and codedb - which reads the host checkout through its
/// own index. `webfetch` is deliberately absent: it is plain host HTTP with
/// no sandbox to escape. So are the orchestration/meta tools, and everything
/// MCP-sourced (an `mcp__*` name never matches here). `bash` /
/// `bash_output` / `bash_kill` are dispatch aliases (gated_aliases): they
/// are not advertised, but layer 2 still refuses them under this gate.
pub const gated_tools = [_][]const u8{
"shell",
"read_file",
"edit_file",
"write_file",
"codedb",
"read_tool_result",
// #352: imagegen looks like a content tool but is a local write-and-spawn
// primitive — it starts `codex exec --sandbox workspace-write` or python3
// on THIS host and writes a file into the working tree. Being optional
// (tool_gates.zig) does not exempt it: an embedder that removed bash and
// write_file would otherwise still be handed a way to run a process and
// land bytes on disk.
"imagegen",
// render_html lands model-authored bytes under the user's own ~/.graff
// views directory on THIS host: not a workspace write, but still a host
// write an embedder removed bash and write_file to be rid of.
"render_html",
};
/// Pre-unification names. Still dispatched, still blocked by --no-local-tools.
pub const gated_aliases = [_][]const u8{
"bash",
"bash_output",
"bash_kill",
};
/// A name test only, independent of whether the gate is on, so the comptime
/// catalog filter and the runtime refusal can share one list.
pub fn isLocalTool(name: []const u8) bool {
for (gated_tools) |tool| {
if (std.mem.eql(u8, name, tool)) return true;
}
for (gated_aliases) |tool| {
if (std.mem.eql(u8, name, tool)) return true;
}
return false;
}
/// Layer 2's predicate: this call must be refused before anything runs.
pub fn blocks(name: []const u8) bool {
return enabled and isLocalTool(name);
}
/// --lean / GRAFF_LEAN=1 tool surface — the token-cost counterpart of the MCP
/// fold (session_start.leanMode reads the same flag/env). A one-shot
/// coding task keeps the file/shell tools plus attempt_completion; every
/// other schema is prefix re-sent on EVERY model turn. Unlike #330 this
/// is NOT a security boundary: an unadvertised tool is simply unknown.
pub var lean: bool = false;
/// The lean keep-list. File/shell tools stay on the wire: an rlm-only
/// catalog (ADR 0024 follow-up) made grok-4.6 retry scripts for 122
/// calls / 4/6. Dropping catalog `read_file` (085320) made it worse
/// (63 calls) — the model retried rlm/bash cat when print(read_file)
/// was a no-op. `load_tool_schemas` stays so MCP can unfold; it is
/// hidden only when nothing is deferred. Overflow paging
/// (`read_tool_result`) is interactive.
pub const lean_tools = [_][]const u8{
"shell",
"read_file",
"edit_file",
"write_file",
"codedb",
"subagent",
"attempt_completion",
"yield_turn",
"load_tool_schemas",
};
/// A name test only, so the catalog filter and tests share one list.
pub fn leanKeeps(name: []const u8) bool {
for (lean_tools) |tool| {
if (std.mem.eql(u8, name, tool)) return true;
}
// A folded native the turn loaded (mcp_preload, load_tool_schemas) is on
// the wire: the load note says it is callable, so lean must not drop it.
// `agent_output` was the casualty: a subagent request loaded it, the
// catalog left it out, and the model polled it without a schema.
if (@import("native_fold.zig").isLoaded(name)) return true;
// A workspace that ships skills keeps `skill` beside its catalog.
return @import("skill_docs.zig").g_workspace_skills and std.mem.eql(u8, name, "skill");
}
/// schema.zig chains this after filterRootSpecs (a tool may survive one and
/// not the other). Returns the input untouched when lean is off — no
/// allocation on the normal path, mirroring filterRootSpecs.
pub fn filterLeanSpecs(comptime Spec: type, arena: Allocator, specs: []const Spec) ![]const Spec {
if (!lean) return specs;
const buf = try arena.alloc(Spec, specs.len);
var kept: usize = 0;
for (specs) |spec| {
if (!leanKeeps(spec.name)) continue;
buf[kept] = spec;
kept += 1;
}
return buf[0..kept];
}
/// --lean's compact subagent description: same name and JSON schema, a
/// fraction of the prose. The full description is 1.9k bytes of workflow,
/// persona and tier/effort precedence detail a one-shot never exercises.
/// Sidecar-only (ADR 0023): keep the critical-path next step local. Do
/// not claim root bash/edit are approval-denied — that is true only when
/// `unattended_note` is appended (`unattended and !yolo`). `-p --yolo`
/// (evals) can act locally; the old lie forced extra child turns.
pub const lean_subagent_desc = "Spawn a sidecar for a self-contained task. Child has bash, read_file, edit_file, write_file, codedb; it does NOT share your context. Optional context/established_facts/scope/deliverable become headed sections; omit empties. Returns the final report. Keep the critical-path next step local; do not hand off the blocker and wait. Do file and command work yourself this turn; spawn only for independent work.";
/// One-shot tool prose (ADR 0046). Same names and JSON schemas; shorter
/// descriptions so flash models start and finish instead of rereading
/// essays. Do not drop to four tools (ADR 0024).
pub const lean_shell_desc = "Run /bin/sh -c in cwd. action=run returns stdout/stderr/exit. After 15s (or a shorter timeout) backgrounds. Persistent servers snapshot now — do not poll. Finite wait_ms>0 waits until exit.";
pub const lean_bash_desc = lean_shell_desc;
pub const lean_read_file_desc = "Read a UTF-8 file. Call before editing. contains=exact-key numbered lines; start_line/end_line for a window.";
pub const lean_edit_file_desc = "Replace exact text. Prefer one batched edits[] over many calls. Prefer over write_file for an existing file.";
pub const lean_codedb_desc = "Indexed nav: context <task> (local) · around <name> · callpath A B · list_dir <path> · status. Prefer over bash grep/find/ls.";
pub const lean_attempt_completion_desc = "Task is done. Put the final answer in result.";
fn leanCompactDesc(name: []const u8) ?[]const u8 {
if (std.mem.eql(u8, name, "subagent")) return lean_subagent_desc;
if (std.mem.eql(u8, name, "shell") or std.mem.eql(u8, name, "bash")) return lean_shell_desc;
if (std.mem.eql(u8, name, "read_file")) return lean_read_file_desc;
if (std.mem.eql(u8, name, "edit_file")) return lean_edit_file_desc;
if (std.mem.eql(u8, name, "codedb")) return lean_codedb_desc;
if (std.mem.eql(u8, name, "attempt_completion")) return lean_attempt_completion_desc;
return null;
}
/// schema.zig chains this after filterLeanSpecs: identical names and JSON
/// schemas, compact prose. Returns the input untouched when lean is off.
pub fn compactLeanSpecs(comptime Spec: type, arena: Allocator, specs: []const Spec) ![]const Spec {
if (!lean) return specs;
const buf = try arena.dupe(Spec, specs);
for (buf) |*spec| {
if (leanCompactDesc(spec.name)) |desc| spec.desc = desc;
}
return buf;
}
/// Refusal text. Names the flag so the model stops retrying the same call, and
/// points it at what does work in this deployment.
pub const refusal_text = "--no-local-tools is set for this process: the built-in bash, bash_output, bash_kill, read_file, edit_file, write_file, codedb and read_tool_result tools are hard-disabled and cannot be re-enabled by asking. Run commands and touch files through the sandbox tools the connected MCP server provides instead; webfetch still works.";
/// `GRAFF_NO_LOCAL_TOOLS` - affirmative-only, like GRAFF_CLOCK_SLEEP, and OR'd
/// onto the CLI flag by the caller so a stray value can never turn
/// `--no-local-tools` back off.
pub fn envEnables(value: []const u8) bool {
return std.mem.eql(u8, value, "1") or
std.ascii.eqlIgnoreCase(value, "true") or
std.ascii.eqlIgnoreCase(value, "on") or
std.ascii.eqlIgnoreCase(value, "yes");
}
/// Layer 1, comptime half: the subagent catalogs are comptime constants, so
/// their gated twin is computed once at compile time and merely selected at
/// runtime.
pub fn remoteSpecs(comptime Spec: type, comptime specs: []const Spec) []const Spec {
comptime {
var out: []const Spec = &.{};
for (specs) |spec| {
if (isLocalTool(spec.name)) continue;
out = out ++ [_]Spec{spec};
}
return out;
}
}
/// Layer 1, runtime half: the root catalog is picked at runtime (clock_sleep,
/// learning), so the gated copy is built in the caller's arena. Returns the
/// input untouched when the gate is off - no allocation on the normal path.
pub fn filterRootSpecs(comptime Spec: type, arena: Allocator, specs: []const Spec) ![]const Spec {
if (!enabled) return specs;
const buf = try arena.alloc(Spec, specs.len);
var kept: usize = 0;
for (specs) |spec| {
if (isLocalTool(spec.name)) continue;
buf[kept] = spec;
kept += 1;
}
return buf[0..kept];
}
test "#330: the gated set is exactly the host-touching built-ins; webfetch, meta and MCP names are not gated" {
const saved = enabled;
defer enabled = saved;
for (gated_tools) |tool| try std.testing.expect(isLocalTool(tool));
try std.testing.expectEqual(@as(usize, 8), gated_tools.len);
try std.testing.expect(isLocalTool("bash") and isLocalTool("bash_output") and isLocalTool("bash_kill"));
try std.testing.expect(isLocalTool("imagegen")); // #352: optional, but still a local spawn+write
try std.testing.expect(isLocalTool("render_html")); // writes the snapshot under the host's own $HOME
for ([_][]const u8{ "webfetch", "skill", "subagent", "workflow", "todo_write", "eval", "mcp__sandbox__exec", "mcp__sandbox__bash" }) |tool|
try std.testing.expect(!isLocalTool(tool));
// blocks() is the gate, not the list: nothing is refused until it is on.
enabled = false;
for (gated_tools) |tool| try std.testing.expect(!blocks(tool));
enabled = true;
for (gated_tools) |tool| try std.testing.expect(blocks(tool));
try std.testing.expect(blocks("bash") and blocks("bash_output") and blocks("bash_kill"));
try std.testing.expect(!blocks("webfetch"));
try std.testing.expect(!blocks("mcp__sandbox__bash"));
}
test "#330: GRAFF_NO_LOCAL_TOOLS is affirmative-only" {
for ([_][]const u8{ "1", "true", "TRUE", "on", "yes" }) |v| try std.testing.expect(envEnables(v));
for ([_][]const u8{ "", "0", "false", "off", "no", "2", "enabled" }) |v| try std.testing.expect(!envEnables(v));
}
test "lean: the filter keeps the one-shot tools and handoff, and allocates nothing when off" {
const Spec = struct { name: []const u8, desc: []const u8 = "" };
const specs = [_]Spec{
.{ .name = "shell" },
.{ .name = "workflow" },
.{ .name = "read_file" },
.{ .name = "todo_write" },
.{ .name = "subagent" },
.{ .name = "attempt_completion" },
.{ .name = "yield_turn" },
};
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const saved = lean;
defer lean = saved;
lean = false;
try std.testing.expectEqual(specs.len, (try filterLeanSpecs(Spec, arena, &specs)).len);
try std.testing.expectEqual(@as(usize, 0), arena_state.queryCapacity());
lean = true;
const kept = try filterLeanSpecs(Spec, arena, &specs);
try std.testing.expectEqual(@as(usize, 5), kept.len);
try std.testing.expectEqualStrings("shell", kept[0].name);
try std.testing.expectEqualStrings("read_file", kept[1].name);
try std.testing.expectEqualStrings("subagent", kept[2].name);
try std.testing.expectEqualStrings("attempt_completion", kept[3].name);
try std.testing.expectEqualStrings("yield_turn", kept[4].name);
try std.testing.expectEqual(@as(usize, 9), lean_tools.len);
try std.testing.expect(leanKeeps("read_file") and leanKeeps("edit_file") and leanKeeps("write_file"));
try std.testing.expect(!leanKeeps("read_tool_result"));
for (lean_tools) |tool| try std.testing.expect(leanKeeps(tool));
try std.testing.expect(!leanKeeps("workflow"));
try std.testing.expect(!leanKeeps("todo_write"));
try std.testing.expect(!leanKeeps("webfetch"));
// …and the compact pass shrinks one-shot prose, leaves names/schemas,
// and is a no-op when lean is off.
lean = false;
try std.testing.expectEqual(specs.len, (try compactLeanSpecs(Spec, arena, &specs)).len);
lean = true;
const compact = try compactLeanSpecs(Spec, arena, &specs);
try std.testing.expectEqual(specs.len, compact.len);
for (compact) |s| {
if (std.mem.eql(u8, s.name, "subagent")) try std.testing.expectEqualStrings(lean_subagent_desc, s.desc);
if (std.mem.eql(u8, s.name, "shell")) try std.testing.expectEqualStrings(lean_shell_desc, s.desc);
if (leanCompactDesc(s.name) == null) try std.testing.expectEqualStrings("", s.desc);
}
try std.testing.expect(lean_bash_desc.len < 200);
try std.testing.expect(lean_attempt_completion_desc.len < 80);
try std.testing.expect(std.mem.indexOf(u8, lean_subagent_desc, "sidecar") != null);
try std.testing.expect(std.mem.indexOf(u8, lean_subagent_desc, "critical-path") != null);
try std.testing.expect(std.mem.indexOf(u8, lean_subagent_desc, "approval-denied") == null); // that fact lives on unattended_note, not here
}
test "#330: filterRootSpecs drops only the gated names, and does not allocate when the gate is off" {
const Spec = struct { name: []const u8 };
const specs = [_]Spec{
.{ .name = "shell" },
.{ .name = "webfetch" },
.{ .name = "read_file" },
.{ .name = "subagent" },
.{ .name = "codedb" },
};
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const saved = enabled;
defer enabled = saved;
enabled = false;
try std.testing.expectEqual(specs.len, (try filterRootSpecs(Spec, arena, &specs)).len);
try std.testing.expectEqual(@as(usize, 0), arena_state.queryCapacity());
enabled = true;
const gated = try filterRootSpecs(Spec, arena, &specs);
try std.testing.expectEqual(@as(usize, 2), gated.len);
try std.testing.expectEqualStrings("webfetch", gated[0].name);
try std.testing.expectEqualStrings("subagent", gated[1].name);
}
test "#330: neither catalog advertises a local tool under the gate, and webfetch survives in both" {
const schema = @import("schema.zig");
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const saved = enabled;
// #352: imagegen is optional, so the ungated catalog only carries every
// gated name while it is available — turn it on for this comparison.
const imagegen = @import("imagegen.zig");
const saved_imagegen = imagegen.available;
defer {
enabled = saved;
imagegen.available = saved_imagegen;
}
imagegen.available = true;
// Root catalog (runtime-assembled, and the one MCP tools are appended to).
enabled = false;
const open = try schema.effectiveRootSpecs(arena);
var open_local: usize = 0;
for (open) |spec| {
if (isLocalTool(spec.name)) open_local += 1;
}
try std.testing.expectEqual(gated_tools.len, open_local);
enabled = true;
const gated = try schema.effectiveRootSpecs(arena);
var kept_webfetch = false;
var kept_subagent = false;
for (gated) |spec| {
try std.testing.expect(!isLocalTool(spec.name));
if (std.mem.eql(u8, spec.name, "webfetch")) kept_webfetch = true;
if (std.mem.eql(u8, spec.name, "subagent")) kept_subagent = true;
}
try std.testing.expectEqual(open.len - gated_tools.len - 1, gated.len); // rlm also drops under #330
try std.testing.expect(kept_webfetch); // pure host HTTP: no sandbox to escape
try std.testing.expect(kept_subagent); // orchestration stays; the child inherits the gate
// Subagent catalogs (comptime twins), in all three wire formats.
for ([_][]const u8{
schema.tools_anthropic_sub_remote,
schema.tools_openai_sub_remote,
schema.tools_responses_sub_remote,
}) |catalog| {
inline for (gated_tools) |tool|
try std.testing.expect(std.mem.indexOf(u8, catalog, "\"name\":\"" ++ tool ++ "\"") == null);
try std.testing.expect(std.mem.indexOf(u8, catalog, "\"name\":\"webfetch\"") != null);
}
// …and the ungated twins still carry them, so the filter is what changed.
try std.testing.expect(std.mem.indexOf(u8, schema.tools_anthropic_sub, "\"name\":\"shell\"") != null);
try std.testing.expect(std.mem.indexOf(u8, schema.tools_anthropic_sub, "\"name\":\"bash\"") == null);
}
test "#330: dispatch refuses a hallucinated bash call for the root AND for a subagent" {
const exec = @import("exec.zig");
const tools = @import("tools.zig");
const gpa = std.testing.allocator;
const saved = enabled;
defer enabled = saved;
var parsed = try std.json.parseFromSlice(std.json.Value, gpa, "{\"command\":\"echo gate-escaped\"}", .{});
defer parsed.deinit();
var client: std.http.Client = undefined;
var ctx: tools.ToolCtx = .{
.gpa = gpa,
.io = std.testing.io,
.client = &client,
.provider = undefined,
.registry = null,
.from_sub = false,
.approvals = null,
.tracer = null,
};
enabled = true;
// from_sub=true is the child path: a subagent's tool calls run through this
// very dispatch, so the process-global gate reaches them with no plumbing.
for ([_]bool{ false, true }) |from_sub| {
ctx.from_sub = from_sub;
const out = exec.execTool(ctx, .{ .id = "call_1", .name = "bash", .input = parsed.value });
defer gpa.free(out.text);
try std.testing.expect(out.is_error);
try std.testing.expect(std.mem.indexOf(u8, out.text, "--no-local-tools") != null);
try std.testing.expect(std.mem.indexOf(u8, out.text, "gate-escaped") == null); // never ran
}
}
test "lean prompt diet: no fan-out / trace / issue-filing; short local-tools note" {
const prompts = @import("prompts.zig");
const saved = lean;
defer lean = saved;
lean = true;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const out = try prompts.composeBase(arena_state.allocator(), prompts.detectCaps());
try std.testing.expect(std.mem.indexOf(u8, out, ".graff/traces") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "gh issue create") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "fan out") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "Parallelize") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "ONE response") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "not covered by /rewind") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "rlm") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "SPEC.md") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "edit that path") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "discard work") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "Fix root causes") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "Co-Authored-By") == null);
}
test "lean catalog drops overflow pager and empty load_tool_schemas" {
const schema = @import("schema.zig");
const saved = lean;
defer lean = saved;
lean = true;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const specs = try schema.effectiveRootSpecs(arena);
const json = try schema.renderRootTools(arena, .openai, specs, &.{});
try std.testing.expect(std.mem.indexOf(u8, json, "read_file") != null);
try std.testing.expect(std.mem.indexOf(u8, json, "edit_file") != null);
try std.testing.expect(std.mem.indexOf(u8, json, "write_file") != null);
try std.testing.expect(std.mem.indexOf(u8, json, "read_tool_result") == null);
try std.testing.expect(std.mem.indexOf(u8, json, "\"name\":\"load_tool_schemas\"") == null);
try std.testing.expect(std.mem.indexOf(u8, json, "\"rlm\"") != null);
try std.testing.expect(std.mem.indexOf(u8, json, "\"name\":\"read_file\"") != null);
}
test "lean keeps a folded native the turn loaded: the load note's agent_output is on the wire" {
const fold = @import("native_fold.zig");
const saved = lean;
defer lean = saved;
lean = true;
fold.clearLoadedSession();
defer fold.clearLoadedSession();
try std.testing.expect(!leanKeeps("agent_output"));
fold.markLoaded("agent_output");
try std.testing.expect(leanKeeps("agent_output"));
try std.testing.expect(!leanKeeps("workflow"));
}