bench/manager/core/adapters/README.md

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 the BOARD_* 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.
• The workflow brief the prompts point agents at is AGENTS.md at the repo root (CLAUDE.md beside it is only a compatibility pointer). Vendors that read AGENTS.md from the working directory's tree natively — opencode does, as does current Claude Code — pick it up in every worktree with no adapter work; run never needs to inject it.

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's AGENT_COMMANDS. No push.
• act-pr — the work stance, plus git push (the PR must update), reading the PR's reviews and line comments (gh pr view, gh pr diff, gh api), and git fetch/git merge so a conflicted PR can be resolved by merging main into the branch. Resolution is additive only — the branch is public — so git rebase and the force-push spellings must be denied, not merely unlisted (a plain git push allow would otherwise cover them).
• 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 from AGENT_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 the BOARD_* env forwarded.
• Events beat perfection: start with session/end plus a generic command per tool call, refine kinds later — opencode/plugin.js starts exactly that coarse on purpose.