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.mdnew file mode 100644index 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.mdindex 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 onediff --git a/src/agent_catalog.zig b/src/agent_catalog.zigindex 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.zigindex 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.zignew file mode 100644index 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.zigindex 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 u8pub 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-connectanim.loadAnimationSetting(io, arena); // {"animation": "..."} → thinking spinner choicediff --git a/src/shell_tool.zig b/src/shell_tool.zigindex 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;