graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
0039. Agent-authored local tools are project scripts, not skills
Status: accepted 2026-08-27
Context
#555 asked for exo's install_agent_tool loop: the agent writes a tool at
runtime, the harness validates it, and later sessions see it as a first-class
tool. Graff already has skills (instruction playbooks) and MCP (out-of-process
servers). A third thing that is "just a skill with a shebang" would blur both.
schema.zig is at the 600-line cap and feeds the 64-cell
spec/kernels/tool_catalog.json cube. Putting every installed name into
effectiveRootSpecs would force an SDK regen on every project script.
Decision
- A local tool lives at
.graff/tools/<name>/withmanifest.jsonplus a script. Runners arepython3,bun, orsh. install_agent_toolvalidates the manifest, dry-runsargv --dry-run(exit 0 required), then registerslocal__<name>. Live calls pass the JSON args as argv[2] —process_runner.runCappedhas no stdin.- Skills stay instructions. MCP stays consent-gated servers. This is the executable, project-local half.
- Catalog extras are concatenated in
agent_catalog.ensureRootTools, not added toschema.effectiveRootSpecs.--no-local-tools/--leanhide them. Subagents do not see them. Plan mode refuses install and live calls.
Consequences
- A script that ignores
--dry-runfails install. A script that reads stdin for args will see nothing. - Do not grow
schema.meta_namesor the SDK cube for these names. - Revisit if a project needs MCP-shaped stdin JSON or a fourth runner.