GUIDE / FIELD NOTES
A work order goes out. Evidence comes back.
From first delegation to local Dispatch and share cards: the flow, what happens, and the data boundaries.
0.4 / COOPERATION ARCHITECTURE
Hand over. Bring back. Move forward.
The 0.4 series connects whole responsibilities, worker self-check, main-agent help and same-session continuation. The main agent keeps the goal and acceptance judgment. Codex owns native execution; the optional ACP runner adds sessions, receipts, delivery collection and finite batches.
- MAIN AGENT
Keep the goal. Shape the work.
Take an engineering goal, honor the chosen channel, and hand over a whole responsibility with boundaries and completion criteria.
Goal · Work order · Permissions - WORKER
Check, repair, and deliver.
Keep investigation, implementation, self-check and ordinary repairs together. Bring back progress and a precise question when a key judgment is missing.
Investigate → Implement → Check → Repair - MAIN AGENT
Read the evidence. Move forward.
Inspect artifacts, coverage and conflicts; check concrete doubts. Integrate supported work for delivery, or supply the judgment needed to continue.
Artifacts · Check evidence · Final delivery
Return decisions, added constraints or specific rework to the original session; keep useful execution with its worker.
The main agent makes judgments using plugin instructions; the CLI performs authorized mechanical steps. Runtime completion, worker reports and engineering acceptance are different evidence. Dispatch is an optional projection of ACP receipts.
01 / GETTING STARTED
The plugin routes work. Everything else is optional.
Start by installing Worker Routing so your main agent receives guidance for delegation, whole responsibilities, assistance, continuation and acceptance. Native Codex workers can provide the execution channel; add ACP and the private-context hook when needed.
- Ask Codex’s built-in plugin-creator to register plugins/worker-routing into your personal marketplace, keeping your current model and provider.
- Then open a new main session to confirm it loaded: registration is not activation.
- It only changes future routing: no request is taken over, no model or paid route chosen for you. The ACP route and main-session context integration are separate optional additions.
02 / DELEGATION & ACCEPTANCE
Hand over a whole responsibility, not a command.
Delegate a responsibility that can finish on its own: investigation, change and self-check for one worker. A work order names the outcome, boundaries and what to return; small or nearly finished tasks can stay with the main agent.
Fix the CSV import failure caused by blank rows.
Scope: one function plus one focused check.
Add a check that reproduces the bug, run it, and return the diff and result.
Do not touch the public API or unrelated files.
Stop and report if the fix would cross that boundary.- Continue the same session for corrections. After two explicit reworks leave the same gap without progress, decide how to recover before repeating the order.
- Workers check and repair ordinary in-scope defects before delivery, stop when stated conditions are supported, and return precise questions for material decision gaps.
- The main agent accepts actual artifacts and evidence by risk. For batches, inspect coverage, key conclusions and conflicts, then expand concrete doubts. A worker saying done is still a candidate declaration.
- Say “solo” or “do not delegate” to keep the work in the main session; the main agent should also avoid re-implementing work already delegated.
03 / OPTIONAL ACP ROUTE
An external route is optional.
Start with one default worker, without comparing models or writing capability profiles. Honor the existing channel choice first: native workers use host tools; a registered ACP route can be the everyday default with its own separate session.
- Route config, worker home, workspace allowlist and provider/account choices stay outside Git, under your control.
- Set routing.default in the existing ACP config and omit --route on ordinary runs. Change channels in that one place; routing.fallbacks may stay empty and backups require prior authorization.
- Automatic backups handle only unavailable entries or missing required environment credentials before launch. After startup, recover the original execution first. Changing the default preserves existing sessions; disabling a channel blocks further continuation.
- Every run / continue requires explicit --permissions read|full; omission is rejected before dispatch and no mode is inherited. This only selects ACP permission responses, not an OS sandbox.
- A late completed result cannot overwrite timeout or cancellation; output and cleanup stay separate. A route starting or a model listed still does not prove real inference succeeds.
- Complex outcomes can opt into bounded delivery collection; known independent responsibilities can use the finite batch below. For recovery, establish the original session, receipt and cleanup state before continuing existing work.
The main agent chooses the work. The CLI handles the mechanics.
One order spec authored by the main agent connects preparation, finite execution and incremental collection. One default worker is enough to start; batch only responsibilities already known to be independent.
prepareAssemble ordersGenerate orders and a manifest mechanically; launch no worker.batchAdmit and executeCheck authorizations and resources, execute this finite batch, and persist each settled result.collectRead what has landedRead the settled index without waiting for the rest; retain outstanding responsibilities.
The ACP runner retains sessions, receipts and bounded delivery clues. Worker reports, observed runtime state and main-agent acceptance remain distinct. Serialize a shared HOME when its concurrency safety is unknown.
For a first run, hand over a small, complete task: edit one function, add a check, then review the actual diff and result.
04 / LOCAL DISPATCH
Receipts leave a trail.
Dispatch displays local ACP receipts and review notes you add on purpose. Business data is read-only; theme, language and timezone can be saved. It schedules nothing and adds no second job database. Native Codex activity has no data source here: every metric is ACP-only.
node integrations/acpx/src/cli.mjs dashboard --config /absolute/private/config.json
node integrations/acpx/src/cli.mjs stats --config /absolute/private/config.json --since 7d- The command runs in the foreground and prints a private loopback URL (ephemeral port by default); open that URL yourself and keep the process running. Before your first ACP task the panel opens empty, which is expected.
- Accounting: runtime completion is not acceptance; observed tokens are known workload, not quota saved and not billing evidence; missing data stays unknown.
- Projects come from the working directory: Git repositories group linked worktrees, with a folder filter. These are not saved Codex project names; no chat text infers identity.
- Usage coverage states how many tasks have attributable data; ordinary completion needs no annotation or to-do.
05 / SHARE CARDS & PRIVACY
A little card that stays yours.
Share cards preview 1600×900 landscape and 1080×1350 portrait, as SVG or PNG. Theme, language and layout are independent: four themes × two languages × two layouts × SVG/PNG give 32 combinations, named with theme, language, format and date.
- Share cards open from the “Share card” button in the dashboard header.
- Numerals offer Soft / Book / Mono, ornaments Thread / Bloom / None; decorations stay in local SVG.
- The slogan starts from four bilingual presets and is editable; an optional shared-by credit is separate. Both are text you enter, escaped as plain text, never inferred from records.
- The statistics portion accepts only aggregate totals, period, timezone and coverage. Work orders, outputs, private route names, paths and internal IDs are never filled in automatically, and nothing auto-uploads.
Drafts live only in browser memory and reset on refresh, separate from persistent display preferences: only theme, language and timezone are saved.
06 / CONTEXT & BOUNDARIES
An input boundary, not a filesystem sandbox.
The optional main-session integration uses a native SessionStart hook to load your private instructions before the first root request, into the root only; new workers do not inherit the main conversation. Main context must arrive before that first request for new work to keep the root/child boundary.
- The hook applies to the root only and must be reviewed and trusted by you; the installer does not rewrite AGENTS, auto-approve hooks or change model/provider config.
- Host-shared engineering rules may still reach workers — “shared rules” is not limiting file access to one directory; route config alone provides no isolation.
- File permissions come from the host sandbox; this does not stop a process with file tools reading other local files.
After setup, use a new session to confirm the main agent received the instructions, then check worker input with a small work order containing no private material. The installation reference covers verification and recovery.