istosandClaude Fable 5
9fed08d174
BOARD_AGENT_MODEL picks one model for every headless launch;
BOARD_AGENT_MODEL_WORK / _ACT_PR / _REVIEW beat it per intent (review
covers PR reviews and relevance checks). Empty — the default — means
the variable never reaches the adapter and the vendor's own resolution
applies, exactly today's behaviour; a stray AGENT_MODEL in the board's
own environment is stripped rather than inherited silently.
Core carries the name as an opaque string: config resolves intent →
model, _launch passes it as AGENT_MODEL, and each adapter renders it
natively — claude appends --model, opencode sets the generated
config's model key ("provider/model-id", per its docs). The resolved
model (or its absence) is recorded on the agent record, so the
Sessions and Focus views state what a run actually rode instead of
leaving it to whoever's machine the board happens to run on.
Stub-binary tests pin the byte-identical-when-unset guarantee, the
per-intent resolution, the launch-env seam and the record.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.2 KiB
Agent adapters
An adapter makes the task manager work with a particular coding agent.
Core never speaks any vendor's language — it launches jobs and ingests
normalized events; adapters translate at the edge. Two ship as reference
implementations: claude/ (the default) and opencode/. Select with
BOARD_AGENT_ADAPTER in local/.env; a directory of the same name under
local/adapters/ overrides the core one.
The contract
An adapter is a directory with two executables:
run — execute one headless job to completion
- env in:
AGENT_PROMPT(the full prompt),AGENT_MODE(the launch intent, below),AGENT_COMMANDS(the project's allowed command prefixes, below),AGENT_MODEL(optional, below),AGENT_CWD, and theBOARD_*passthrough (BOARD_AGENT_ID,BOARD_TASK,BOARD_PORT) which your event bridge must forward with every event. - stdout is captured by the board as the job log. The prompts instruct the
agent to end with marker lines (
NOT READY:,RELEVANCE REVIEW:,PR REVIEW:,ADDRESSED:) — the board parses them from this output, so the agent's final text must reach stdout. - exit 0 = completed; anything else = failed.
Launch intents (AGENT_MODE)
Core signals intent; every adapter maps it to its vendor's permission mechanism. Headless runs have no human at a permission prompt, so anything not auto-approved is denied — grant each intent exactly the side effects its prompt demands, and never a blanket allow-everything (the worktree is isolated, the shell is not):
work— implement, test, commit in an isolated worktree. May edit files, run local git bookkeeping (git add/commit/status/diff) and the project'sAGENT_COMMANDS. No push.act-pr— the work stance, plusgit push(the PR must update) and reading the PR's reviews and line comments (gh pr view,gh pr diff,gh api).review— read-only on the working tree: no edit tools, no commits. May read a PR (gh pr view,gh pr diff, read-only git) and post the verdict (gh pr review,gh pr comment).
The project's allowed commands (AGENT_COMMANDS)
The git/gh grants above are universal; which test/check commands a
project's agents run is project knowledge. It arrives as comma-separated
plain command prefixes — BOARD_AGENT_COMMANDS in local/.env, e.g.
python3 -m unittest,npm test — never in any vendor's rule syntax. Each
adapter renders them natively; both shipped rule languages are
prefix-pattern based, so the translation is mechanical:
- claude →
Bash(git commit:*)-style allow-rules in the generated settings JSON (claude/hook_settings.py) - opencode →
"permission": {"bash": {"*": "deny", "git commit *": "allow"}}in a generated config, wildcard rules, last match wins (opencode/permission_config.py)
The model (AGENT_MODEL) — optional
Absent = the vendor's own default: launch without any model argument and
let your CLI resolve it however it normally would. When set, it is an
opaque vendor-native model name — a claude alias, an opencode
provider/model-id — that core never validates or interprets; pass it
through untranslated (claude → --model "$AGENT_MODEL", opencode → the
generated config's model key). Never send your vendor an empty value:
the board only sets the variable when a model is actually configured
(BOARD_AGENT_MODEL and its per-intent overrides in local/.env).
wire — wire live-session visibility into the host project
Called by install.py with the project root as argv[1] (plus --dry-run).
Idempotently make the project's own interactive sessions report events —
however your platform allows (Claude Code: hooks in .claude/settings.json;
opencode: a plugin shim in .opencode/plugin/ subscribing to its event
bus). Print a report; exit 0 on ok/fixed. If the platform has no way to
observe sessions, be a no-op with an honest message: the board still runs
headless jobs via run, you just lose the live play-by-play.
Events — the normalized schema (v1)
POST to http://127.0.0.1:$BOARD_PORT/api/events:
{"v": 1, "session": str, "kind": str, "summary": str,
"file"?: str, "cmd"?: str, "detail"?: str, "ok"?: bool,
"running"?: bool, "agent"?: $BOARD_AGENT_ID, "task"?: $BOARD_TASK}
kinds: session end idle edit read search command test check git plan subagent web other. running: true marks an in-flight action (shown as
the live line, not appended to the timeline); follow it with the completed
event. kind: idle = finished responding; kind: end = session over.
Classification happens in YOUR emitter — core never sees vendor payloads.
Writing one
Read the two shipped adapters side by side — they are small and map the same three intents onto very different vendor mechanisms. The essentials:
run: launch your agent headlessly with permissions generated fromAGENT_MODE+AGENT_COMMANDS; make sure the final output lands on stdout and the exit code passes through.wire: install your platform's observer (hook, plugin) into the project so sessions POST the normalized schema with theBOARD_*env forwarded.- Events beat perfection: start with
session/endplus a genericcommandper tool call, refine kinds later —opencode/plugin.jsstarts exactly that coarse on purpose.