graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Name the OS in the shell tool; let edits and small reads past the codedb guard
justrachef26a0bea5b2
diff --git a/docs/adr/0234-the-model-knows-the-os-and-the-codedb-guard-only-redirects-searches.md b/docs/adr/0234-the-model-knows-the-os-and-the-codedb-guard-only-redirects-searches.mdnew file mode 100644index 00000000..5ead749a--- /dev/null+++ b/docs/adr/0234-the-model-knows-the-os-and-the-codedb-guard-only-redirects-searches.md@@ -0,0 +1,62 @@+# 0234. The model knows the OS, and the codedb guard only redirects what codedb does better++Status: accepted 2026-10-02++## Context++Run against Claude Code on the same model and the same tasks, graff lost a+whole model call in every run of three of the coding tasks. None of those+calls did work the task asked for.++- **GNU syntax on BSD tools.** To fix one line the model wrote+ `sed -i 's/a/b/' file.py`. On macOS, BSD `sed` reads the script as the+ backup suffix and the file name as the script, fails with+ `invalid command code`, and the model tries again with `sed -i ''`. Nothing+ graff sends says which OS the commands run on. Claude Code's prompt names+ the platform, and there the model used its edit tool or BSD syntax.+- **The codedb guard refused edits.** The #626 guard blocks `grep`, `sed`,+ `cat` and the like on an indexed source file and points the model at+ codedb. It took `sed -i ''` for a read, so a correct in-place edit came back+ as an error and the model redid it with `edit_file`.+- **The guard refused small whole-file reads.** `cat utils.py; cat main.py`+ on two short files was refused too. The model then read them with+ `read_file`, which returns the same text one call later. codedb pays on+ searches and on files too big to read whole, not on a 40-line file.++## Decision++- The `shell` tool's description names the OS its commands run on: "on macOS+ (BSD tools: `sed -i ''`, no GNU-only flags)" in a macOS build, "on Linux" in+ a Linux build, and nothing elsewhere. The text is fixed per build, so the+ cached prefix does not change between turns.+- The codedb guard lets two shapes through (`codedb_guard_scope.zig`):+ - an in-place `sed` edit (`-i`, `-i ''`, `-i.bak`, `-Ei`, `--in-place`) in+ the command's first segment;+ - a plain whole-file read (`cat`, `head`, `tail`, `nl`, `wc`, `bat`) with no+ pipe, when every file it names exists and is at most 16 KiB, the size a+ tool result keeps inline before it becomes a handle.++ Searches (`grep`, `rg`, `awk`, `sed` without `-i`, or a read piped into+ one) and reads of bigger files still go to codedb. Both checks run before+ the index probe, so a command they pass also skips the `codedb outline`+ subprocess.++Three other changes were measured on the same tasks and dropped. Sending no+reasoning effort on the default level, so that the model would not think,+made it take more calls and write more, and it was slower overall. Sending+low effort instead of medium was inside the run-to-run noise. Skipping the+startup scan for orphaned listeners saves its subprocesses on every+interactive start, but the gain is below what these runs can resolve, and+that scan belongs to the server lifecycle (#199). It is not changed here.++## Consequences++An in-place `sed` edit is a shell write like any other: the write guard of+ADR 0231 and `/rewind`'s file snapshots do not see it, as they never saw a+script that writes a file. A whole read of a 16 KiB file costs the same+context as `read_file`. A Windows build says nothing about its shell, as+before.++Revisit the OS clause if traces still show GNU-only syntax failing on macOS,+and the 16 KiB read limit if models start reading many small files one `cat`+at a time where one codedb query would do.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex c6f9d084..631ecc72 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -257,6 +257,7 @@ record only when you need the evidence or the edge cases.| [0228](0228-read-only-child-calls-declared-read-only-mcp-tools.md) | An MCP tool is a read when its server declares `readOnlyHint: true` (`mcp.Tool.read_only`). A read-only (informational) child may call those and inherits only those from its root; undeclared MCP tools stay refused. || [0229](0229-every-chatgpt-login-is-chatgpt-new.md) | The Codex client's login no longer works, so every ChatGPT login name (`chatgpt`, `codex`, `openai`, `gpt`, `oai`) and the model picker run the `chatgpt-new` sign-in, and `chatgpt-new` precedes `codex` in the provider table. The `codex` provider stays for an existing Codex CLI `auth.json`. Replaces ADR 0221's "Codex first". || [0231](0231-no-round-trip-the-model-does-not-need.md) | No call the task did not ask for: a named small MCP server (and subagents, when asked for) loads with the first request, with the slim-shape note; `write_file` refuses to replace an unread file unless `replace: true` and reports created/replaced and JSON validity; inherited child MCP tools are never deferred; a piped bracketed paste is one prompt; unwatched (`-p`, piped) sessions get no `ask_user` and no low-effort reasoning summaries. |+| [0234](0234-the-model-knows-the-os-and-the-codedb-guard-only-redirects-searches.md) | The `shell` tool names the OS its commands run on (macOS: BSD tools, `sed -i ''`). The codedb guard lets an in-place `sed -i` edit and a pipe-free whole-file read of files up to 16 KiB through; searches and bigger reads still go to codedb. |## When to write onediff --git a/src/codedb_guard_scope.zig b/src/codedb_guard_scope.zignew file mode 100644index 00000000..cafde654--- /dev/null+++ b/src/codedb_guard_scope.zig@@ -0,0 +1,99 @@+//! Which shell commands the codedb guard (#626, `tools.codedbGuard`) lets+//! through even though they name an indexed source file (ADR 0234).+//!+//! The guard moves source SEARCHES, and reads of files too big to take whole,+//! onto codedb. Two shapes are neither, and blocking them only cost the model+//! a round trip: an in-place edit (`sed -i`) writes the file and reads nothing+//! back, and a whole-file read of a small file returns no more than a+//! `read_file` would.++const std = @import("std");+const Io = std.Io;++/// A whole-file read of files up to this size passes: the size a tool result+/// keeps inline before it becomes a handle.+pub const small_read_bytes: u64 = @import("tool_handle.zig").default_threshold_bytes;++/// `sed` with an in-place flag (`-i`, `-i ''`, `-i.bak`, `-Ei`, `--in-place`)+/// in its first command segment.+pub fn inPlaceEdit(tool: []const u8, cmd: []const u8) bool {+ if (!std.mem.eql(u8, tool, "sed")) return false;+ const segment = cmd[0 .. std.mem.indexOfAny(u8, cmd, ";|&\n") orelse cmd.len];+ var it = std.mem.tokenizeAny(u8, segment, " \t");+ _ = it.next(); // sed itself+ while (it.next()) |tok| {+ if (std.mem.startsWith(u8, tok, "--in-place")) return true;+ if (tok.len < 2 or tok[0] != '-' or tok[1] == '-') continue;+ // A short-flag cluster: letters only up to an optional backup suffix.+ if (std.mem.indexOfScalar(u8, tok[1..], 'i')) |i| {+ if (std.mem.indexOfNone(u8, tok[1 .. 1 + i], "Ealnrsuz") == null) return true;+ }+ }+ return false;+}++fn plainReader(tool: []const u8) bool {+ for ([_][]const u8{ "cat", "head", "tail", "nl", "wc", "bat", "batcat" }) |reader|+ if (std.mem.eql(u8, reader, tool)) return true;+ return false;+}++/// `smallRead` in the directory the command runs in: the agent's own+/// worktree when it has one, else the process cwd.+pub fn smallReadIn(io: Io, agent_cwd: ?[]const u8, tool: []const u8, cmd: []const u8) bool {+ const path = agent_cwd orelse return smallRead(io, Io.Dir.cwd(), tool, cmd);+ var dir = Io.Dir.cwd().openDir(io, path, .{}) catch return false;+ defer dir.close(io);+ return smallRead(io, dir, tool, cmd);+}++/// A plain reader (cat/head/tail/nl/wc/bat) with no pipe (`cat x | grep` is a+/// search) whose every named file is at most `small_read_bytes`. Paths+/// resolve against `cwd`, where the command runs.+pub fn smallRead(io: Io, cwd: Io.Dir, tool: []const u8, cmd: []const u8) bool {+ if (!plainReader(tool)) return false;+ if (std.mem.indexOfScalar(u8, cmd, '|') != null) return false;+ var it = std.mem.tokenizeAny(u8, cmd, " \t\n;&");+ var files: usize = 0;+ while (it.next()) |raw| {+ const tok = std.mem.trim(u8, raw, "'\"`()");+ if (tok.len == 0 or tok[0] == '-') continue;+ const st = cwd.statFile(io, tok, .{}) catch continue; // a command word, a flag value, a missing file+ if (st.kind != .file) continue;+ if (st.size > small_read_bytes) return false;+ files += 1;+ }+ return files > 0;+}++test "inPlaceEdit: in-place sed edits, not reads or scripts" {+ try std.testing.expect(inPlaceEdit("sed", "sed -i '' 's/range(n - 1)/range(n)/' fib.py && python3 test_fib.py"));+ try std.testing.expect(inPlaceEdit("sed", "sed -i 's/a/b/' x.py; python3 x.py"));+ try std.testing.expect(inPlaceEdit("sed", "sed -i.bak -e 's/a/b/' x.py"));+ try std.testing.expect(inPlaceEdit("sed", "sed -Ei 's/a/b/g' x.py"));+ try std.testing.expect(inPlaceEdit("sed", "sed --in-place=.orig 's/a/b/' x.py"));+ try std.testing.expect(!inPlaceEdit("sed", "sed -n '1,20p' x.py"));+ try std.testing.expect(!inPlaceEdit("sed", "sed -n 's/i/x/p' x.py"));+ try std.testing.expect(!inPlaceEdit("sed", "sed -e 's/i/x/' x.py"));+ try std.testing.expect(!inPlaceEdit("sed", "sed -n 1p x.py; sed -i '' 's/a/b/' y.py")); // the edit is not the guarded command+ try std.testing.expect(!inPlaceEdit("grep", "grep -i foo x.py"));+}++test "smallRead: whole small files pass; big files, pipes and searches do not" {+ var tmp = std.testing.tmpDir(.{});+ defer tmp.cleanup();+ const io = std.testing.io;+ try tmp.dir.writeFile(io, .{ .sub_path = "small.py", .data = "print(1)\n" });+ try tmp.dir.writeFile(io, .{ .sub_path = "other.py", .data = "x = 2\n" });+ const big = try std.testing.allocator.alloc(u8, small_read_bytes + 1);+ defer std.testing.allocator.free(big);+ @memset(big, 'a');+ try tmp.dir.writeFile(io, .{ .sub_path = "big.py", .data = big });++ try std.testing.expect(smallRead(io, tmp.dir, "cat", "cat small.py; cat other.py"));+ try std.testing.expect(smallRead(io, tmp.dir, "head", "head -n 40 small.py"));+ try std.testing.expect(!smallRead(io, tmp.dir, "cat", "cat small.py big.py"));+ try std.testing.expect(!smallRead(io, tmp.dir, "cat", "cat small.py | grep print"));+ try std.testing.expect(!smallRead(io, tmp.dir, "grep", "grep print small.py"));+ try std.testing.expect(!smallRead(io, tmp.dir, "cat", "cat missing.py"));+}diff --git a/src/commands_session.zig b/src/commands_session.zigindex a2487177..5c9bd8c3 100644--- a/src/commands_session.zig+++ b/src/commands_session.zig@@ -387,7 +387,7 @@ pub fn tryHandle(root: *Agent, keys: *Keys, arena: Allocator, line: []const u8,return true;}if (std.mem.eql(u8, line, "/hooks")) {- try out.print("{s}codedb guard{s} (built-in, issue #626): {s} — blocks bash grep/sed/cat/wc on indexed source files and redirects to the codedb tool; GRAFF_NO_CODEDB_GUARD=1 disables.\n", .{ style.bold, style.reset, if (main_mod.g_codedb_guard) "on" else "off" });+ try out.print("{s}codedb guard{s} (built-in, issue #626): {s} — blocks bash grep/sed/cat/wc on indexed source files (not sed -i edits or whole reads of small files) and redirects to the codedb tool; GRAFF_NO_CODEDB_GUARD=1 disables.\n", .{ style.bold, style.reset, if (main_mod.g_codedb_guard) "on" else "off" });if (main_mod.g_hooks.total() == 0) {try out.print("no lifecycle hooks. Add them to {s}:\n {s}{{\"hooks\": {{\"pre_tool\": [{{\"match\": \"shell\", \"command\": \"./guard.sh\"}}]}}}}{s}\n events: pre_tool (exit 2 blocks, stderr → model) · post_tool · turn_end; loaded at startup\n", .{ Approvals.settings_path, style.dim, style.reset });try out.flush();diff --git a/src/shell_tool.zig b/src/shell_tool.zigindex 4b4a91a9..138ae6dc 100644--- a/src/shell_tool.zig+++ b/src/shell_tool.zig@@ -21,7 +21,14 @@ const jobs = @import("jobs.zig");const exec_bash = @import("exec_bash.zig");pub const tool_name = "shell";-pub const tool_desc = "Run a shell command via /bin/sh -c in the current working directory, read a background job, or stop one. action=run (default when command is set) returns stdout/stderr/exit. A user-cancelled command reports cancelled (its whole local process group is killed; a remote process started over ssh may survive on the remote host). Foreground commands still running after 120s (lean -p: 15s, or a shorter timeout ms) move to the background and return a job id. For long-running commands set run_in_background true to skip the wait. You are notified on completion — do not poll. action=output wait_ms>0 blocks until exit (up to 10h) for a finite job; a persistent server snapshots immediately (wait_ms is ignored) and stays on /jobs. action=kill stops it. A background job that writes nothing and is read by nobody for 2 hours is stopped for inactivity; the user pins a long-lived server with /jobs keep. bash/bash_output/bash_kill still dispatch. Not a PTY: you cannot type into the process. Type in the composer to steer the turn.";+/// ADR 0234: name the OS the commands run on. Told nothing, models write GNU+/// syntax, and `sed -i 's/a/b/' f` fails on macOS's BSD sed.+const os_clause = switch (@import("builtin").os.tag) {+ .macos => " on macOS (BSD tools: `sed -i ''`, no GNU-only flags)",+ .linux => " on Linux",+ else => "",+};+pub const tool_desc = "Run a shell command via /bin/sh -c" ++ os_clause ++ " in the current working directory, read a background job, or stop one. action=run (default when command is set) returns stdout/stderr/exit. A user-cancelled command reports cancelled (its whole local process group is killed; a remote process started over ssh may survive on the remote host). Foreground commands still running after 120s (lean -p: 15s, or a shorter timeout ms) move to the background and return a job id. For long-running commands set run_in_background true to skip the wait. You are notified on completion — do not poll. action=output wait_ms>0 blocks until exit (up to 10h) for a finite job; a persistent server snapshots immediately (wait_ms is ignored) and stays on /jobs. action=kill stops it. A background job that writes nothing and is read by nobody for 2 hours is stopped for inactivity; the user pins a long-lived server with /jobs keep. bash/bash_output/bash_kill still dispatch. Not a PTY: you cannot type into the process. Type in the composer to steer the turn.";pub const tool_schema =\\{"type": "object", "properties": {"action": {"type": "string", "enum": ["run", "output", "kill"], "description": "run a command, read a job, or stop a job. Default run when command is set."}, "command": {"type": "string", "description": "Shell command to execute (action=run)"}, "timeout": {"type": "integer", "description": "Optional foreground wait in milliseconds before auto-background. A shorter value promotes earlier; a larger value cannot extend past the 120s (lean -p: 15s) bound. 0 uses the default. Ignored when run_in_background is true. A persistent server's action=output is a snapshot, not wait-until-exit."}, "run_in_background": {"type": "boolean", "description": "Start as a background job and return its id immediately instead of waiting (default false). Do not poll it."}, "id": {"type": "integer", "description": "Job id for action=output or kill"}, "wait_ms": {"type": "integer", "description": "0 = snapshot now. Finite jobs: >0 waits until exit (10h cap). Persistent servers: snapshot now; wait_ms is ignored. Do not poll."}}};@@ -208,6 +215,14 @@ test "#1270: a NUL byte in a shell command is refused with its offset, never run}}+test "ADR 0234: the shell tool names the OS its commands run on" {+ switch (@import("builtin").os.tag) {+ .macos => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c on macOS (BSD tools: `sed -i ''`, no GNU-only flags) in the current")),+ .linux => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c on Linux in the current")),+ else => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c in the current")),+ }+}+test "catalog advertises shell, not the three bash names" {const schema = @import("schema.zig");var saw_shell = false;diff --git a/src/test_hooks.zig b/src/test_hooks.zigindex 45585fbd..a92e99a9 100644--- a/src/test_hooks.zig+++ b/src/test_hooks.zig@@ -404,4 +404,5 @@ test {_ = @import("output_elide.zig"); // #1271: over-cap output keeps head and tail_ = @import("graff_dir.zig"); // #1273: .graff/.gitignore keeps run state out of git_ = @import("additional_tools.zig"); // ADR 0221: loaded tools as additional_tools items on the ChatGPT plan route+ _ = @import("codedb_guard_scope.zig"); // ADR 0234: in-place edits and small whole reads pass the codedb guard}diff --git a/src/tools.zig b/src/tools.zigindex 4cec9811..d9cca4e2 100644--- a/src/tools.zig+++ b/src/tools.zig@@ -215,7 +215,8 @@ pub fn runPostToolHooks(ctx: ToolCtx, call: ToolCall, out: ToolOutput) void {/// Built-in pre_tool guard for issue #626. Blocks a bash command that scans or/// reads a *concrete source file* (`grep`/`sed`/`cat`/… on a path ending in a-/// known code extension) and redirects the model to the codedb tool, whose+/// known code extension; not an in-place `sed -i` edit or a whole read of+/// small files, ADR 0234) and redirects the model to the codedb tool, whose/// structural queries (symbol/callers/deps/outline/context) otherwise go/// unused. Narrow on purpose: only known scan/read utilities, only a concrete/// source path (globs like `*.zig` are left alone), only when `codedb` is on@@ -244,6 +245,9 @@ pub fn codedbGuard(ctx: ToolCtx, call: ToolCall) ?ToolOutput {is_scanner = true;};if (!is_scanner) return null;+ // ADR 0234: an in-place edit and a whole read of small files cost a round trip to refuse and save nothing.+ const scope = @import("codedb_guard_scope.zig");+ if (scope.inPlaceEdit(tool, trimmed) or scope.smallReadIn(ctx.io, ctx.agent_cwd, tool, trimmed)) return null;// …aimed at a concrete source file (not a glob — codedb glob/tree cover that).const src_path = extractSourceFilePath(cmd) orelse return null;