Skip to content

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

Python

shell: name python3's version in the tool's OS note

justrach6229d0724e88
diff --git a/docs/adr/0242-the-shell-tool-names-python3s-version.md b/docs/adr/0242-the-shell-tool-names-python3s-version.md
new file mode 100644
index 00000000..522d7c23
--- /dev/null
+++ b/docs/adr/0242-the-shell-tool-names-python3s-version.md
@@ -0,0 +1,38 @@
+# 0242. The shell tool names python3's version
+
+Status: accepted 2026-10-03
+
+## Context
+
+ADR 0234 made the `shell` tool name the OS its commands run on. Models also
+assume a recent python3: in eval traces they wrote
+`datetime.fromisoformat("...Z")`, which needs 3.11, on a Mac whose `python3`
+is the system 3.9. The script failed and the model spent a whole call
+rewriting it. Another harness on the same tasks avoided this only because its
+model happened to compute in JavaScript.
+
+Running `python3 --version` at startup would tell us, but on a Mac without
+the developer tools `/usr/bin/python3` opens an install dialog, and a startup
+probe must not do that.
+
+## Decision
+
+At startup graff finds the first `python3` on `PATH` (the one a shell command
+runs) and reads its version from the resolved path: `.../Versions/3.9/...`,
+`python3.11`, `[email protected]`. macOS's `/usr/bin/python3` launcher is followed
+to the developer tools' interpreter it runs, when one is installed. Nothing
+is executed. When the version is found, the shell tool's OS clause says so:
+"python3 is 3.9, so scripts must run on 3.9". When the path names no version
+(a pyenv shim, say) or there is no python3, the description is unchanged.
+
+The version is read once per process, so the catalog bytes stay stable for
+the whole session. The root catalog and licensed workers' rendered catalogs
+carry it; the compiled-in subagent catalog does not.
+
+## Consequences
+
+The tool catalog differs between machines with different python3 versions,
+which is the point, and is invisible to the prompt cache within one machine.
+A PATH change mid-session is not seen. Revisit if traces show version errors
+in subagents, or interpreters whose path never names a version becoming
+common.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 98265dc7..89c62dfa 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -265,6 +265,7 @@ record only when you need the evidence or the edge cases.
| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. |
| [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. |
| [0238](0238-rlm-binds-keep-the-whole-mcp-result.md) | An MCP call inside an rlm script binds the whole result; `print()` shows the slim view (each item of an `each()` bind cut on its own), `project(x, field)` reads any field (`n`/`latest_author` through a comment list's fold), and `write_file` saves the whole result; inside rlm, `read_tool_result("tr_N")` with no range binds a stored result whole. |
+| [0242](0242-the-shell-tool-names-python3s-version.md) | The `shell` tool's OS clause names python3's version, read at startup from where `python3` on PATH resolves (never by running it); unknown versions leave the description unchanged. |
## When to write one
diff --git a/src/agent_catalog.zig b/src/agent_catalog.zig
index a5c816f2..2df76ba0 100644
--- a/src/agent_catalog.zig
+++ b/src/agent_catalog.zig
@@ -81,7 +81,7 @@ pub fn ensureRootTools(self: *Agent, kind: Provider.Kind) !void {
const snapshot = try registry.snapshotTools(self.arena);
break :blk if (self.sub) try surface.filterWorkerMcp(self.arena, snapshot) else snapshot;
} else &.{};
- dest.* = try schema.renderRootTools(self.arena, kind, specs, connected);
+ dest.* = try @import("shell_tool.zig").withPython(self.arena, try schema.renderRootTools(self.arena, kind, specs, connected)); // ADR 0242
}
test "invalidate without ensure leaves toolsJson empty; rebuild is a JSON array" {
diff --git a/src/main.zig b/src/main.zig
index 7a65d043..9dc86467 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -594,7 +594,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = @import("acp_agents.zig");
_ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_run_tests.zig") };
_ = .{ @import("acp_agent_activity.zig"), @import("acp_subagent_live.zig"), @import("acp_line_writer.zig") };
- _ = @import("acp_replay.zig");
+ _ = .{ @import("acp_replay.zig"), @import("python_version.zig") };
_ = @import("read_image.zig");
_ = .{ @import("pr_local_checks.zig"), @import("mcp_names.zig"), @import("workspace_history.zig"), @import("file_worktree.zig"), @import("mcp_turn_context.zig"), @import("review_deadline.zig"), @import("issue_cmd.zig"), @import("shell_tool.zig"), @import("acp_ask.zig"), @import("side_steer.zig"), @import("task_workspace_tests.zig"), @import("workspace_prepare_tests.zig"), @import("worktree_reap.zig") };
}
diff --git a/src/python_version.zig b/src/python_version.zig
new file mode 100644
index 00000000..4f32aa54
--- /dev/null
+++ b/src/python_version.zig
@@ -0,0 +1,106 @@
+//! ADR 0242: python3's version on this machine, for the shell tool's OS note.
+//! Read from where `python3` on PATH resolves, never by running it: on a Mac
+//! without the developer tools, /usr/bin/python3 opens an install dialog.
+//! Detected once at startup, so the tool catalog stays byte-stable all session.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const Io = std.Io;
+
+var version_buf: [8]u8 = undefined;
+/// "3.9", or empty when unknown. Written once by `detect`, before the first request.
+pub var version: []const u8 = "";
+
+/// The developer-tools interpreters macOS's /usr/bin/python3 launches.
+const macos_dev_pythons = [_][]const u8{
+ "/Library/Developer/CommandLineTools/usr/bin/python3",
+ "/Applications/Xcode.app/Contents/Developer/usr/bin/python3",
+};
+
+/// Find the first `python3` on `path_env`, the one a shell command runs, and
+/// read its version off the resolved path. `version` stays empty when no
+/// python3 is on PATH or its path names no version (a pyenv shim, say).
+pub fn detect(io: Io, path_env: ?[]const u8) void {
+ version = "";
+ if (builtin.os.tag == .windows) return;
+ var dirs = std.mem.tokenizeScalar(u8, path_env orelse return, ':');
+ while (dirs.next()) |dir| {
+ var cand_buf: [std.fs.max_path_bytes]u8 = undefined;
+ const cand = std.fmt.bufPrint(&cand_buf, "{s}/python3", .{dir}) catch continue;
+ var real_buf: [std.fs.max_path_bytes]u8 = undefined;
+ const real = resolve(io, cand, &real_buf) orelse continue;
+ if (fromPath(real)) |v| return remember(v);
+ if (builtin.os.tag == .macos and std.mem.eql(u8, real, "/usr/bin/python3")) {
+ for (macos_dev_pythons) |dev| {
+ const r = resolve(io, dev, &real_buf) orelse continue;
+ if (fromPath(r)) |v| return remember(v);
+ }
+ }
+ return;
+ }
+}
+
+fn resolve(io: Io, path: []const u8, buf: *[std.fs.max_path_bytes]u8) ?[]const u8 {
+ const n = Io.Dir.cwd().realPathFile(io, path, buf) catch return null;
+ return buf[0..n];
+}
+
+fn remember(v: []const u8) void {
+ @memcpy(version_buf[0..v.len], v);
+ version = version_buf[0..v.len];
+}
+
+/// "3.N" from an interpreter's resolved path: `.../Versions/3.9/bin/python3.9`,
+/// `/usr/bin/python3.11`, `.../[email protected]/...`. Null when it names none.
+pub fn fromPath(path: []const u8) ?[]const u8 {
+ for ([_][]const u8{ "python3.", "Versions/3.", "python@3." }) |pre| {
+ var from: usize = 0;
+ while (std.mem.indexOfPos(u8, path, from, pre)) |at| : (from = at + 1) {
+ const digits = at + pre.len;
+ var end = digits;
+ while (end < path.len and std.ascii.isDigit(path[end])) end += 1;
+ if (end > digits and end - digits <= 3) return path[digits - 2 .. end];
+ }
+ }
+ return null;
+}
+
+test "ADR 0242: fromPath reads the version a resolved interpreter path names" {
+ const cases = [_]struct { []const u8, ?[]const u8 }{
+ .{ "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin/python3.9", "3.9" },
+ .{ "/opt/homebrew/Cellar/[email protected]/3.12.4/Frameworks/Python.framework/Versions/3.12/bin/python3.12", "3.12" },
+ .{ "/usr/bin/python3.11", "3.11" },
+ .{ "/usr/bin/python3", null },
+ .{ "/home/u/.pyenv/shims/python3", null },
+ };
+ for (cases) |c| {
+ const got = fromPath(c[0]);
+ if (c[1]) |want| try std.testing.expectEqualStrings(want, got orelse return error.NoVersion) else try std.testing.expect(got == null);
+ }
+}
+
+test "ADR 0242: detect follows the first python3 on PATH and never a later one" {
+ if (builtin.os.tag == .windows) return error.SkipZigTest;
+ const io = std.testing.io;
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ try tmp.dir.createDirPath(io, "real");
+ try tmp.dir.createDirPath(io, "a");
+ try tmp.dir.createDirPath(io, "b");
+ try tmp.dir.writeFile(io, .{ .sub_path = "real/python3.10", .data = "" });
+ try tmp.dir.symLink(io, "../real/python3.10", "b/python3", .{});
+ var root_buf: [std.fs.max_path_bytes]u8 = undefined;
+ const root = root_buf[0..try tmp.dir.realPath(io, &root_buf)];
+ var path_buf: [3 * std.fs.max_path_bytes]u8 = undefined;
+ defer version = "";
+
+ detect(io, try std.fmt.bufPrint(&path_buf, "{s}/a:{s}/b", .{ root, root }));
+ try std.testing.expectEqualStrings("3.10", version);
+
+ try tmp.dir.writeFile(io, .{ .sub_path = "a/python3", .data = "" }); // a shim: names no version
+ detect(io, try std.fmt.bufPrint(&path_buf, "{s}/a:{s}/b", .{ root, root }));
+ try std.testing.expectEqualStrings("", version);
+
+ detect(io, null);
+ try std.testing.expectEqualStrings("", version);
+}
diff --git a/src/session_settings.zig b/src/session_settings.zig
index 5b169d8f..14d4610d 100644
--- a/src/session_settings.zig
+++ b/src/session_settings.zig
@@ -276,6 +276,7 @@ fn codegraffLoginKey(io: Io, arena: Allocator, environ_map: anytype) ?[]const u8
pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out: *Io.Writer, flags: args.Flags, use_color: bool, json_mode: bool, cwd_display: []const u8) !ThemeSetup {
try applyEnvKnobs(arena, environ_map);
+ @import("python_version.zig").detect(io, environ_map.get("PATH")); // ADR 0242: before any catalog renders
_ = jev_tool.setCodegraffLoginKey(io, codegraffLoginKey(io, arena, environ_map));
skills.loadSkillSettings(io, arena); // per-skill opt-outs, also gates the auto-connect
anim.loadAnimationSetting(io, arena); // {"animation": "..."} → thinking spinner choice
diff --git a/src/shell_tool.zig b/src/shell_tool.zig
index 04991dfd..eca7a42c 100644
--- a/src/shell_tool.zig
+++ b/src/shell_tool.zig
@@ -28,11 +28,25 @@ const os_clause = switch (@import("builtin").os.tag) {
.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 (interactive sessions and lean -p: 15s) 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.";
+const desc_head = "Run a shell command via /bin/sh -c";
+pub const tool_desc = desc_head ++ 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 (interactive sessions and lean -p: 15s) 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": "Unattended runs only: foreground wait in milliseconds before auto-background. A shorter value promotes earlier, not below 5000; a larger value cannot extend past the 120s (lean -p: 15s) bound. Interactive sessions always wait 15s. 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."}}}
;
+/// ADR 0242: a rendered catalog whose shell description names python3's
+/// version, read once at startup (python_version.zig). Unchanged when unknown.
+pub fn withPython(arena: std.mem.Allocator, catalog: []const u8) ![]const u8 {
+ const v = @import("python_version.zig").version;
+ if (v.len == 0) return catalog;
+ const clause = switch (@import("builtin").os.tag) {
+ .macos => try std.fmt.allocPrint(arena, " on macOS (BSD tools: `sed -i ''`, no GNU-only flags; python3 is {s}, so scripts must run on {s})", .{ v, v }),
+ .linux => try std.fmt.allocPrint(arena, " on Linux (python3 is {s}, so scripts must run on {s})", .{ v, v }),
+ else => try std.fmt.allocPrint(arena, " (python3 is {s}, so scripts must run on {s})", .{ v, v }),
+ };
+ return std.mem.replaceOwned(u8, arena, catalog, desc_head ++ os_clause, try std.mem.concat(arena, u8, &.{ desc_head, clause }));
+}
+
pub const Action = enum { run, output, kill };
pub fn isFamily(name: []const u8) bool {
@@ -223,6 +237,23 @@ test "ADR 0234: the shell tool names the OS its commands run on" {
}
}
+test "ADR 0242: a known python3 version rides the shell tool's OS clause" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const pv = @import("python_version.zig");
+ const saved = pv.version;
+ defer pv.version = saved;
+ const catalog = "[{\"name\":\"shell\",\"description\":\"" ++ tool_desc ++ "\"}]";
+ pv.version = "";
+ try std.testing.expectEqualStrings(catalog, try withPython(a, catalog));
+ pv.version = "3.9";
+ const out = try withPython(a, catalog);
+ try std.testing.expect(std.mem.indexOf(u8, out, "python3 is 3.9, so scripts must run on 3.9") != null);
+ try std.testing.expect(std.mem.indexOf(u8, out, ") in the current working directory") != null or @import("builtin").os.tag != .macos);
+ try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, out, "python3 is 3.9"));
+}
+
test "catalog advertises shell, not the three bash names" {
const schema = @import("schema.zig");
var saw_shell = false;