Skip to content

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.md
new file mode 100644
index 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.md
index 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 one
diff --git a/src/codedb_guard_scope.zig b/src/codedb_guard_scope.zig
new file mode 100644
index 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.zig
index 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.zig
index 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.zig
index 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.zig
index 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;