graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.266 (2026-08-19)
This cut is the peer / plugin / workspace stack on top of 0.0.265. Other harness trees are read where they already live. The system-prompt prefix stays byte-stable so prompt cache can hit.
Peer talk is a working set (ADR 0004)
History no longer carries a second copy of the room.
peer_message action=list— who is livepeer_message action=inbox— read and clear the process-local ringpeer_message/action=send— room or DM send- Inbound bodies park in the ring. The model sees one wake line:
[peer] 2 unread from session-aaa — peer_message action=inbox - Named pings are DMs to the agent that is doing the work, not a broadcast
- The human still sees full
session_noticelines - Compact drops spent injects and never treats them as the human
Standing goal stays in the prefix (ADR 0005)
--goal//goalis one[standing goal: …]line on the system prompt- The long todo-coaching essay injects on first sight and on change only — not every N turns
/loopchecklist refresh is unchanged (still 8 quiet turns)- Bundled
jspaceskill is on-demand (skill name=jspace). It is not resident in every prompt
Mid-session workspace switch (ADR 0006)
A skill cannot move read_file / edit_file / bash — they bind to
process cwd. cd in one bash call dies with the shell. graff -w only
enters a tree at startup.
- Folded
workspacetool:action=list(default) oraction=use path= /workspaceand/wsfor the human- Bundled
workspaceskill is the playbook only — loading it does not chdir - Root session only; subagents keep their assigned tree
- Exact path / folder / branch beat substring matches
- Presence rebinds to the new folder's room; project instructions stay the
ones from session start until
/clearor restart
Plugins and foreign MCP, in place (ADR 0007)
Same model as Claude, grok-build, OpenCode, and Codex: do not copy other harness trees, do not walk hashed cache trees.
What counts as a plugin. A directory with .codex-plugin/plugin.json
(first), .claude-plugin/plugin.json, .cursor-plugin/plugin.json,
.grok-plugin/plugin.json, plugin.json, .mcp.json / mcp.json,
skills/, agents/, Claude commands/*.md, or a root SKILL.md.
Where we look. ~/.cursor/plugins/, ~/.claude/plugins/,
~/.grok/plugins/, ~/.codex/plugins/, ~/.codegraff/plugins/, and the
matching project trees. Parent dirs are listed two levels deep so Cursor
local/<name>/ still shows. Cap 32.
Cache is never walked. cache/ and marketplaces/ are skipped.
- Claude / Cursor cache installs come from
installed_plugins.jsoninstallPath(user/unscoped always;local/projectcwd-gated) - Codex does not write that file. Enabled ids in
~/.codex/config.toml([plugins."name@marketplace"]) resolve toplugins/cache/<marketplace>/<name>/<version>(preferlocal, else the last sorted version). Disabled keys stay invisible - A cache-only tree with no registry / config row stays invisible
Skills stay on-demand. Plugin skills/, Claude commands/*.md, and a
plugin-root SKILL.md join the skill catalog. The named skill tool
loads one body. Project .harness/skills still wins.
MCP is consent-gated. Plugin and foreign MCP fill missing names
only. graff's ~/.codegraff/mcp.json and .mcp.json still win.
/mcp trust / --yolo unchanged. ${CLAUDE_PLUGIN_ROOT} and
${CLAUDE_PROJECT_DIR} expand in MCP strings.
Load stays cheap.
- One readdir per visited folder (not a stat per marker)
- Skill catalog reads an 8 KB frontmatter prefix, not the whole SKILL.md
- MCP merge only opens plugin trees that already have MCP
- Production caches the first walk;
/pluginsprintsN plugin(s) in Xms GRAFF_NO_PLUGINS=1disables the scan- Hooks and plugin
bin/PATH are not applied
Prompt-cache max
Codex's rule: the old prompt must be an exact prefix of the new one. We
already send a sticky prompt_cache_key. The skill catalog now cooperates:
- Pinned once at session start into the system-prompt prefix
- Sorted by name so a rebuild cannot shuffle the first cache hash
- No file paths (Codex prints
file: ~/.codex/plugins/cache/.../SKILL.md; those move and bust the prefix) - Bodies stay on disk until
skill name= - A mid-session skill is loadable via the tool without rewriting the prefix
GPT-5.6 explicit stable-prefix boundary (ADR 0009)
OpenAI Platform GPT-5.6 requests now mark the stable instructions/tool prefix with an explicit 30-minute cache boundary. Root conversations retain the useful implicit latest-message checkpoint; one-shot children avoid writing their unique task suffix. Codex and xAI stay on their supported keyed automatic-cache paths, and OpenAI/Codex child work is spread across four stable role lanes instead of one high-traffic key.
Cache creation tokens are also tracked separately from cache reads and ordinary input. Cost reports apply the documented 1.25× write rate for GPT-5.6 and Anthropic ephemeral caches rather than hiding writes inside ordinary input.
Install PATH
install.sh appends ~/bin (or HARNESS_DIR) to ~/.zshrc, and to
~/.bashrc / fish config when that is the login shell or the file already
exists. HARNESS_NO_PATH=1 skips.
Long-horizon evals (ADR 0008)
evals/long_horizon/ generates seeded multi-file workspaces and grades
them with external deterministic checks. Model judges may tiebreak, never
decide correctness. --showcase --seed 469 prints the generated repo
without a provider call.
Also: plugin out-of-band evals (evals/plugins_oob/), and a TUI fix so
C0 controls cannot leak through the frame painter (already on main, now
on this release line).
Executable behavior contracts
Path confinement, transport selection, score filing, and terminal mode cleanup now have executable state-machine references with matching Lean proofs. This makes lifecycle and fleet behavior checkable as transitions rather than a set of unrelated snapshots.
Suite
Unit suite floor is 1444. Tier 1 reach / lines / fmt stay the gate.
python3 evals/plugins_oob/run.py --self-test
python3 scripts/eval-tier2.py --only plugin-command-as-skill
python3 scripts/eval-tier2.py --only plugin-skill-on-demand
python3 scripts/eval-tier2.py --only plugin-off-keeps-personal-skills
python3 scripts/eval-tier2.py --only workspace-list-use