Skip to content

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

Python

Task worktrees honor .agents/prepare and .agents/linked (ADR 0283)

justrache1443bcc79e2
diff --git a/build.zig b/build.zig
index 48105ed5..c55644de 100644
--- a/build.zig
+++ b/build.zig
@@ -206,6 +206,9 @@ pub fn build(b: *std.Build) void {
const workspace_lifecycle_test = b.addSystemCommand(&.{ "python3", "scripts/test-workspace-lifecycle.py" });
workspace_lifecycle_test.addArtifactArg(exe);
test_step.dependOn(&workspace_lifecycle_test.step);
+ const agents_prepare_test = b.addSystemCommand(&.{ "python3", "scripts/test-agents-prepare.py" });
+ agents_prepare_test.addArtifactArg(exe);
+ test_step.dependOn(&agents_prepare_test.step);
const acp_workspace_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-workspace.py" });
acp_workspace_test.addArtifactArg(exe);
test_step.dependOn(&acp_workspace_test.step);
diff --git a/docs/adr/0283-agents-prepare-and-linked.md b/docs/adr/0283-agents-prepare-and-linked.md
new file mode 100644
index 00000000..bc0e9018
--- /dev/null
+++ b/docs/adr/0283-agents-prepare-and-linked.md
@@ -0,0 +1,40 @@
+# 0283. New task worktrees honor `.agents/prepare` and `.agents/linked`
+
+Status: accepted 2026-10-14
+
+## Context
+
+ADR 0153 gave task worktrees a setup step: copy gitignored include files from
+the main checkout and run `scripts.setup` from `.graff/workspace.toml`. That
+format is graff's own, so a repository prepared for agents in general (whose
+setup lives in the shared `.agents/` directory, next to `.agents/skills`) got
+no setup in a graff worktree. Copies also go stale: a `.env` edited in the main
+checkout after the worktree was made is not the one the worktree reads.
+
+## Decision
+
+When graff mints a task worktree (`graff worktree create`, auto-isolation, an
+ACP `-w` workspace):
+
+- `.agents/linked` lists repository-relative literal paths, one per line (`#`
+ comments, a leading `/` allowed). Each entry that is gitignored in the main
+ checkout, exists there, and is absent in the new checkout becomes a symlink
+ to the main checkout's copy. Tracked paths, `..`, globs and missing paths are
+ skipped, and nothing is moved or deleted. Linking runs before the ADR 0153
+ copy, so a linked path is a symlink, not a copy. Windows links nothing
+ (symlinks need privileges); the `.env*` copy still applies there.
+- `.agents/prepare`, committed in the checkout, runs from the checkout root as
+ the setup script when `.graff/workspace.toml` names no `scripts.setup`. It
+ is executed directly when executable, else through `sh`, with the same
+ environment, deadline and report as `scripts.setup`.
+
+`graff worktree create` reports the linked count beside the copied count.
+
+## Consequences
+
+A repository set up once for agents works in graff worktrees with no
+graff-specific file, and shared local files stay current in every worktree.
+`.graff/workspace.toml` keeps precedence, so existing setups are unchanged.
+A prepare script should stay fast and safe to repeat: it runs for every new
+worktree. Revisit if worktrees need per-checkout copies of a linked file
+(today that means leaving it out of `.agents/linked`).
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 2f96607c..ea733fb6 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -293,6 +293,7 @@ record only when you need the evidence or the edge cases.
| [0280](0280-mcp-servers-report-state-and-reconnect.md) | Every configured MCP server has one status row (`graff mcp status --json`, `/mcp`); `graff mcp reconnect` / `/mcp reconnect` run a real handshake and refresh its catalog; `graff mcp enable|disable` live in `~/.codegraff/mcp-state.json`; the catalog cache keys on cwd + env, and server `env` overlays graff's own. |
| [0281](0281-anthropic-console-sign-in-reads-the-sdk-profile.md) | Anthropic Console sign-in: graff reads the `user_oauth` profile Anthropic's CLI writes (`ant auth login`), in the SDK's precedence (API key wins), sends it as Bearer, and refreshes through `ant auth print-credentials`; `graff login anthropic` runs `ant auth login`. No claude.ai subscription login. |
| [0282](0282-claude-system-breakpoint-closes-before-the-repo-context.md) | On Claude, the system prompt is two text blocks with the same bytes: the cache breakpoint closes the static instructions, before the project instructions and layout, so every repo shares the tools + instructions prefix. |
+| [0283](0283-agents-prepare-and-linked.md) | New task worktrees symlink the gitignored paths `.agents/linked` lists from the main checkout and run `.agents/prepare` when `.graff/workspace.toml` names no setup script. |
## When to write one
diff --git a/scripts/test-agents-prepare.py b/scripts/test-agents-prepare.py
new file mode 100644
index 00000000..1f35aaeb
--- /dev/null
+++ b/scripts/test-agents-prepare.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Offline: a new task worktree honors the tool-neutral .agents/prepare and .agents/linked.
+
+Every mutation stays in a temporary repo. Windows links nothing (symlinks need
+privileges there) and runs prepare through the same POSIX shell as other setup
+scripts, so the script is skipped on Windows.
+"""
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+
+if os.name == "nt":
+ print("skip: .agents/linked symlinks are POSIX-only")
+ sys.exit(0)
+
+binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else "zig-out/bin/graff").resolve())
+
+
+def git(root, *args):
+ return subprocess.check_output(["git", "-C", str(root), *args], text=True, stderr=subprocess.STDOUT).strip()
+
+
+def make_repo(root, toml_setup=None):
+ root.mkdir()
+ git(root, "init", "-q", "-b", "main")
+ git(root, "config", "user.name", "Test")
+ git(root, "config", "user.email", "[email protected]")
+ (root / "app.txt").write_text("app\n")
+ (root / "tracked.cfg").write_text("tracked\n")
+ (root / ".gitignore").write_text(".env\nsecrets/\n.graff/\nprepared\n")
+ agents = root / ".agents"
+ agents.mkdir()
+ prepare = agents / "prepare"
+ prepare.write_text("#!/bin/sh\nset -eu\npwd > prepared\n")
+ prepare.chmod(0o755)
+ (agents / "linked").write_text("# shared, never committed\n/.env\nsecrets/\ntracked.cfg\n../escape\n*.key\nmissing.txt\n")
+ if toml_setup:
+ (root / ".graff").mkdir()
+ (root / ".graff/workspace.toml").write_text(f'[scripts]\nsetup = "{toml_setup}"\n')
+ git(root, "add", ".")
+ git(root, "commit", "-qm", "initial")
+ # Gitignored, so they exist only in the main checkout.
+ (root / ".env").write_text("TOKEN=one\n")
+ (root / "secrets").mkdir()
+ (root / "secrets/key").write_text("k\n")
+
+
+def create(root, name):
+ r = subprocess.run([binary, "worktree", "create", name], cwd=root, text=True, capture_output=True, timeout=60)
+ assert r.returncode == 0, (r.returncode, r.stdout, r.stderr)
+ for line in r.stdout.splitlines():
+ line = line.strip()
+ if line.startswith("/") and Path(line).is_dir():
+ return Path(line), r.stdout
+ # Fall back to the newest worktree git knows about.
+ paths = [l.split(" ", 1)[1] for l in git(root, "worktree", "list", "--porcelain").splitlines() if l.startswith("worktree ")]
+ return Path(paths[-1]), r.stdout
+
+
+with tempfile.TemporaryDirectory(prefix="graff-agents-prepare-") as temporary:
+ root = Path(temporary).resolve() / "repo"
+ make_repo(root)
+ wt, out = create(root, "t1")
+ assert wt != root and wt.is_dir(), out
+
+ # prepare ran from the new checkout's root.
+ assert (wt / "prepared").read_text().strip() == str(wt.resolve()), out
+
+ # Gitignored entries became symlinks to the main checkout's copy.
+ for rel in (".env", "secrets"):
+ p = wt / rel
+ assert p.is_symlink(), (rel, out)
+ assert Path(os.readlink(p)).resolve() == (root / rel).resolve(), (rel, os.readlink(p))
+ assert "linked 2 shared file(s)" in out, out
+
+ # Edited once in the main checkout, current in the worktree.
+ (root / ".env").write_text("TOKEN=two\n")
+ assert (wt / ".env").read_text() == "TOKEN=two\n"
+
+ # Tracked, escaping, glob and missing entries are never linked.
+ assert not (wt / "tracked.cfg").is_symlink()
+ assert (wt / "tracked.cfg").read_text() == "tracked\n"
+ assert not (Path(temporary) / "escape").exists()
+ assert not (wt / "missing.txt").exists()
+
+ # A setup script in .graff/workspace.toml still wins over .agents/prepare.
+ root2 = Path(temporary).resolve() / "repo2"
+ make_repo(root2, toml_setup="printf toml > from-toml")
+ wt2, out2 = create(root2, "t2")
+ assert (wt2 / "from-toml").read_text() == "toml", out2
+ assert not (wt2 / "prepared").exists(), out2
+
+print("ok: .agents/prepare runs in a new worktree; .agents/linked links gitignored paths only")
diff --git a/src/agents_prepare.zig b/src/agents_prepare.zig
new file mode 100644
index 00000000..ae7b0af3
--- /dev/null
+++ b/src/agents_prepare.zig
@@ -0,0 +1,93 @@
+//! The tool-neutral project setup convention in `.agents/` (the directory
+//! graff already reads skills from): what a fresh worktree needs before an
+//! agent works in it.
+//!
+//! - `.agents/prepare`: an executable script run from the new checkout's root
+//! once it exists. It should be fast and safe to repeat (install
+//! dependencies, point tools at a shared cache). `.graff/workspace.toml`'s
+//! `setup` still wins when it names one.
+//! - `.agents/linked`: one repository-relative path per line (`#` comments and
+//! blank lines ignored, a leading `/` allowed). Each listed path must be
+//! gitignored; the new checkout gets a symlink to the main checkout's copy,
+//! so a `.env` edited once is current in every worktree.
+//!
+//! Linking only ever adds a symlink where nothing exists: a path the main
+//! checkout lacks, or one the new checkout already has, is left alone, and
+//! nothing is moved or deleted.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const process_runner = @import("process_runner.zig");
+
+/// Shell command that runs the checkout's prepare script, or null when it has none.
+pub fn setupCommand(arena: Allocator, io: Io, checkout: []const u8) ?[]const u8 {
+ const abs = std.fs.path.join(arena, &.{ checkout, ".agents/prepare" }) catch return null;
+ const st = Io.Dir.cwd().statFile(io, abs, .{}) catch return null;
+ if (st.kind != .file) return null;
+ return "if [ -x .agents/prepare ]; then ./.agents/prepare; else sh ./.agents/prepare; fi";
+}
+
+/// The linked list's text: the checkout's committed copy, else the main checkout's.
+fn linkedText(arena: Allocator, io: Io, checkout: []const u8, root: []const u8) ?[]const u8 {
+ for ([_][]const u8{ checkout, root }) |base| {
+ const path = std.fs.path.join(arena, &.{ base, ".agents/linked" }) catch return null;
+ if (Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(64 * 1024))) |t| return t else |_| {}
+ }
+ return null;
+}
+
+/// One entry as a safe repository-relative path, or null to skip it.
+pub fn entryPath(line: []const u8) ?[]const u8 {
+ var p = std.mem.trim(u8, line, " \t\r");
+ if (p.len == 0 or p[0] == '#') return null;
+ while (p.len > 0 and p[0] == '/') p = p[1..];
+ while (p.len > 0 and p[p.len - 1] == '/') p = p[0 .. p.len - 1];
+ if (p.len == 0) return null;
+ var it = std.mem.splitScalar(u8, p, '/');
+ while (it.next()) |part| {
+ if (part.len == 0 or std.mem.eql(u8, part, "..") or std.mem.eql(u8, part, ".")) return null;
+ if (std.mem.indexOfAny(u8, part, "*?[\\") != null) return null; // literal paths, never globs
+ }
+ return p;
+}
+
+fn ignoredInRoot(gpa: Allocator, io: Io, root: []const u8, rel: []const u8) bool {
+ const r = process_runner.runCapped(gpa, io, &.{ "git", "-C", root, "check-ignore", "-q", "--", rel }, 256, 256, 15_000) catch return false;
+ defer {
+ gpa.free(r.stdout);
+ gpa.free(r.stderr);
+ }
+ return process_runner.ranOk(r);
+}
+
+/// Symlink each listed gitignored path from the main checkout into a new
+/// checkout. Returns how many links were made. Windows needs privileges for
+/// symlinks, so it links nothing there (the `.env*` copy still applies).
+pub fn linkShared(gpa: Allocator, io: Io, arena: Allocator, root: []const u8, checkout: []const u8) usize {
+ if (builtin.os.tag == .windows) return 0;
+ if (std.mem.eql(u8, root, checkout)) return 0;
+ const text = linkedText(arena, io, checkout, root) orelse return 0;
+ var n: usize = 0;
+ var lines = std.mem.splitScalar(u8, text, '\n');
+ while (lines.next()) |line| {
+ const rel = entryPath(line) orelse continue;
+ const shared = std.fs.path.join(arena, &.{ root, rel }) catch continue;
+ const local = std.fs.path.join(arena, &.{ checkout, rel }) catch continue;
+ _ = Io.Dir.cwd().statFile(io, shared, .{}) catch continue; // the main checkout lacks it
+ if (Io.Dir.cwd().statFile(io, local, .{ .follow_symlinks = false })) |_| continue else |_| {}
+ if (!ignoredInRoot(gpa, io, root, rel)) continue; // tracked files are never redirected
+ if (std.fs.path.dirname(local)) |parent| Io.Dir.cwd().createDirPath(io, parent) catch continue;
+ Io.Dir.cwd().symLink(io, shared, local, .{}) catch continue;
+ n += 1;
+ }
+ return n;
+}
+
+test "entryPath keeps literal repo-relative paths and drops the rest" {
+ try std.testing.expectEqualStrings(".env", entryPath("/.env").?);
+ try std.testing.expectEqualStrings("config/local", entryPath(" config/local/ \r").?);
+ for ([_][]const u8{ "", " ", "# shared secrets", "/", "../outside", "a/../b", "./x", "*.env", "certs/**", "a//b" }) |bad|
+ try std.testing.expect(entryPath(bad) == null);
+}
diff --git a/src/main.zig b/src/main.zig
index ab47b7b2..598db769 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -565,7 +565,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };
_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig") }; // per-model guidance (Astra, GPT-5.6); ChatGPT plan sign-in (ADR 0253)
_ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig") };
- _ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };
+ _ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };
_ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig") };
_ = @import("repo_map.zig");
_ = @import("agent_overflow_tests.zig"); // #414: and, through it, agent_overflow.zig's table tests
diff --git a/src/task_workspace.zig b/src/task_workspace.zig
index bbcc061a..bb587b0e 100644
--- a/src/task_workspace.zig
+++ b/src/task_workspace.zig
@@ -48,6 +48,7 @@ pub const Workspace = struct {
branch: []const u8,
base: []const u8 = "",
copied: usize = 0,
+ linked: usize = 0,
setup_ran: bool = false,
setup_ok: bool = true,
};
@@ -255,6 +256,7 @@ pub fn create(gpa: Allocator, io: Io, arena: Allocator, opts: CreateOpts) (Creat
.branch = named.branch,
.base = readHead(gpa, io, arena, path),
.copied = prep.copied,
+ .linked = prep.linked,
.setup_ran = prep.setup_ran,
.setup_ok = prep.setup_ok,
};
diff --git a/src/workspace_prepare.zig b/src/workspace_prepare.zig
index c9437de9..c23ae09a 100644
--- a/src/workspace_prepare.zig
+++ b/src/workspace_prepare.zig
@@ -1,5 +1,6 @@
-//! After minting a task worktree: copy selected gitignored files and run
-//! project scripts from `.graff/workspace.toml`.
+//! After minting a task worktree: link and copy selected gitignored files and
+//! run project scripts from `.graff/workspace.toml`, or the tool-neutral
+//! `.agents/prepare` + `.agents/linked` (agents_prepare.zig).
const std = @import("std");
const Io = std.Io;
@@ -28,6 +29,7 @@ pub const Scripts = struct {
pub const Report = struct {
copied: usize = 0,
+ linked: usize = 0,
setup_ran: bool = false,
setup_ok: bool = true,
};
@@ -68,11 +70,14 @@ pub fn loadScripts(arena: Allocator, io: Io, root: []const u8) Scripts {
pub fn afterCreate(gpa: Allocator, io: Io, arena: Allocator, cwd: []const u8, dest: []const u8, name: []const u8) Report {
const root = mainCheckout(gpa, io, arena, cwd);
var report: Report = .{};
+ const agents = @import("agents_prepare.zig");
+ // Link before copying, so a linked path becomes a symlink, not a stale copy.
+ report.linked = agents.linkShared(gpa, io, arena, root, dest);
report.copied = copyIgnored(gpa, io, arena, root, dest);
const scripts = loadScripts(arena, io, root);
- if (scripts.setup.len == 0) return report;
+ const setup = if (scripts.setup.len > 0) scripts.setup else agents.setupCommand(arena, io, dest) orelse return report;
report.setup_ran = true;
- report.setup_ok = runScript(gpa, io, arena, scripts.setup, dest, root, name, setup_ms);
+ report.setup_ok = runScript(gpa, io, arena, setup, dest, root, name, setup_ms);
return report;
}
diff --git a/src/worktree_cmd.zig b/src/worktree_cmd.zig
index 938a5be2..3596fb8c 100644
--- a/src/worktree_cmd.zig
+++ b/src/worktree_cmd.zig
@@ -244,6 +244,7 @@ fn runTo(gpa: Allocator, io: Io, arena: Allocator, args: []const []const u8, out
return;
};
try out.print("✓ workspace {s}\n path {s}\n branch {s}\n", .{ wt.name, wt.path, wt.branch });
+ if (wt.linked > 0) try out.print(" linked {d} shared file(s) from the main checkout\n", .{wt.linked});
if (wt.copied > 0) try out.print(" copied {d} gitignored file(s)\n", .{wt.copied});
if (wt.setup_ran) try out.print(" setup {s}\n", .{if (wt.setup_ok) "ok" else "failed (workspace kept)"});
return;