Trio Omnigent

---
name: trio-omnigent
description: Run the Cursor-backed Omnigent Trio loop from the current Claude/Codex UI session when the user explicitly says “Trio Omnigent”, “Omnigent Trio”, or invokes /trio-omnigent. Do not use for an ordinary native Trio request.
---

Omnigent agents are registered by bundle upload, not by scanning an agents directory; `omnigent` CLI has no `agent` command. The dashboard install (via `install.sh --dashboard`) renders all canonical agents to each harness's native format and registers them: for omnigent, this means uploading the rendered bundle to the broker and persisting the agent_id in a broker.json sidecar.

You are the Trio coordinator. Stay in the current Claude Code or Codex session;
never launch a separate coordinator with `omnigent run`.

Use `trioctl` to resolve the current profile, then Omnigent's
`sys_session_*` tools to launch only the two judgment roles as direct children
of this session:

- `trio-omnigent-lead`: Cursor Grok 4.6, normally `cursor-grok-4.6-medium`
- `trio-omnigent-evaluator`: Cursor Grok 4.6, normally `cursor-grok-4.6-medium`

The Grok roles own delegation. They launch ephemeral headless Cursor workers
through `trioctl`; every worker uses the profile-resolved GPT-5.6 Luna model,
normally `gpt-5.6-luna-max`. Never launch a Luna worker directly from this
coordinator.

## Preflight and one-time registration

**Omnigent version requirement**: Omnigent >= commit 780962a5 (queue-aware yolo auto-accept) is required to avoid approval cards on batched tool calls during a loop iteration.

1. Discover Omnigent's session tools if they are deferred.
2. Read `${OMNIGENT_HOME:-~/.omnigent}/agents/trio-omnigent-roles/registry.json`.
   It maps the two exact judgment-role names to persisted `agent_id` values.
   Its `_profile` must be exactly
   `cursor-grok-4.6-medium+luna-max-v2`. A missing or different marker means
   the stored agents use an obsolete role configuration: preserve the old
   registry as a backup, then register the current roles instead of reusing
   those IDs.
3. If the registry is missing or stale and this is the cloned template repository,
   register
   them by calling `sys_session_create(config_path=...)` once for each:
   - `omnigent/trio-omnigent-roles/lead`
   - `omnigent/trio-omnigent-roles/evaluator`
   Create them idle and write each returned `agent_id` and
   `bootstrap_conversation_id` to the registry JSON, keyed by the exact role
   name, and write the exact `_profile` marker above. These idle sessions are
   durable registration anchors; current Omnigent versions do not classify
   config-path sessions as closeable named sub-agents, so do not call
   `sys_session_close` on them.
4. Require both exact names in the registry. Never choose by partial name.
   If a stored agent ID is rejected, stop and tell the user to re-run setup
   from the template repository.
5. If roles remain missing outside the template repository, stop with setup
   instructions. Never fall back to native Trio or another model.
6. Confirm the registered Lead and Evaluator configs use `cursor-native`, have
   shell access, `yolo: true`, and `spawn: true`. Grok owns Luna delegation by
   running `trioctl omnigent run`;
   Builder and Scout must not be registered as persistent Omnigent agents.
7. Run `trioctl omnigent doctor`. Stop on any failed check. Then run
   `trioctl omnigent resolve lead --json`,
   `trioctl omnigent resolve evaluator --json`,
   `trioctl omnigent resolve builder --json`, and
   `trioctl omnigent resolve scout --json`. Use the returned `model` and
   `model` and `model_effort` values exactly. Pass `reasoning_effort` only when
   it is non-null; Cursor encodes effort in `model_effort` and the model ID. Never use
   `--allow-fallback` during a loop: unavailable or unentitled models must fail
   loudly.
8. `sys_list_models` may only report the current generic UI agent because the
   registered roles are not declared inline. Treat role-session creation and
   its persisted launch metadata as the authoritative model/effort preflight.
9. Require registered-agent native launch propagation. Lead/Evaluator launch
   metadata must contain `--yolo`. Run a short
   `trioctl omnigent run scout` smoke test; it must return captured text.
   Doctor's `cursor:approval-mode` check must PASS: if the Cursor CLI's
   `~/.cursor/cli-config.json` has `approvalMode` other than
   `"unrestricted"`, `--yolo` still gets applied to the launch but
   cursor-agent surfaces interactive approval prompts anyway — Omnigent's
   auto-accept workaround retries 3 times, then gives up and surfaces a
   manual ApprovalCard. If that check FAILs, run
   `trioctl omnigent fix-approval-mode` before continuing.

Lead/Evaluator use Cursor Native with `yolo: true`. `trioctl` launches Builder
with Cursor `--force --trust` and Scout with those flags plus read-only
`--mode ask`. Changing a registered role's permission mode, harness, or model
requires re-registration because the stored `agent_id` was created from the
config as it read at registration time.

When multiple brokers are online, set `TRIO_OMNIGENT_RUNNER_ID=<runner_id>` to
select the broker runner for this loop; without it, exactly one online runner is
required. The error message lists available runners if several are online and the
variable is unset.

For offline verification, run `omnigent/smoke-test.sh`. The focused validation
command is:
`uv run pytest -q tests/tools/builtins/test_spawn.py tests/runner/test_runner_dispatch.py tests/server/integration/test_sessions_child_sessions.py -k 'reasoning_effort or session_create_spawns_child_under_caller or registered_native_agent_create_derives_launch_args_from_root_spec'`

## Mailbox

Use the requested mailbox, default `loop/`. Initialize it if absent with
`GOAL.md`, `STATE.md`, `PLAN.md`, `REPORT.md`, `VERDICT.md`, and `LOG.md`.
Preserve an existing matching mission. Refuse to repurpose an active mailbox.

## One iteration

1. Read GOAL, STATE, and the previous verdict. Enforce the iteration cap.
2. Resolve Lead with `trioctl`, then create a fresh Lead child with
   `sys_session_create(agent_id=..., model=<resolved model>, message=...)`.
   Give it the
   mailbox and iteration and require one complete Lead pass: plan, decide and
   perform its own Luna delegation through `trioctl omnigent run`,
   review/correct, verify, and write REPORT. The headless Lead prompt
   enforces a clean working tree on start and mandates per-slice commits
   (`slice(<id>): …`) before finishing — no uncommitted changes or amends to
   existing commits. Hand it **diagnosed line ranges** (from cheap grep/symbol
   search) for every product file it must touch — never "read the file" for a
   large file; first-turn full-file ingest of the 2.1 MB monolith crashed the
   provider transport twice. Use a title containing mailbox and iteration.
3. Inspect the Lead result and actual diff. Its report must identify the
   profile-resolved Luna worker and include the captured `trioctl` result.
4. Resolve Evaluator with `trioctl`, then create a fresh Evaluator child with
   its returned model and effort. Require it to independently verify, decide
   whether it needs a Luna Scout, and write VERDICT with one of SHIP, ITERATE
   (optionally `scope=design` or `scope=local:<paths>`), NEEDS_HUMAN, or
   BLOCKED on the first line. On a SHIP verdict, the Evaluator child performs
   the retirement commit as part of writing it: product changes as
   `slice(<id>): …`, then the mailbox as `loop: iteration N — SHIP`, with
   the `commit:` shas appended to VERDICT.md before the mailbox commit.
   Before spawning it, run the **commit gate**
   (active interlock) via your shell tools:
   `trio-shadow.py --mailbox <dir> --require-commits` (the script lives in
   the template repo's `metrics/`; it may be on PATH or referenced by
   absolute path from the installing repo). Exit 0 → proceed. Exit 1 lists
   code-changing slices with no `slice(<id>): ` commit — retry the Lead once
   with the missing-commit note; if the gate still fails, set `status:
   error` in STATE.md, record the breach in LOG.md, and end the loop. Then
   verify `loop/LOG.md` contains the Lead's `- iter N | lead | ...` entry
   for this iteration (the LOG.md gate) — the Evaluator cannot SHIP without
   it; if the append is missing, have the Lead add it first. After SHIP,
   queue exactly one coalesced background documentation task (change summary
   + rationale) by dispatching
   `trioctl omnigent run docs --prompt-file <path> --workspace .`.
5. Inspect the Evaluator result. Any delegated Scout evidence must come from
   its own `trioctl omnigent run scout` invocation.
6. Track every `conversation_id` returned by `sys_session_create` in this
   loop — every Lead and Evaluator child (steps 2 and 4) and any worker
   session created directly from this coordinator — in a running list kept
   for the life of the loop.
7. Update STATE and LOG. After the verdict, set `loop/STATE.md` bookkeeping:
   `status: <verdict>`, `verdict: <outcome>`, `eval: <one-line compressed
   evidence>` (key metrics + evidence dir path, e.g.
   `loop/evidence/iter<N>/`; schema: MAILBOX-SCHEMA.md), and `last_run:
   <date>`. Two materially identical ITERATE verdicts become
   BLOCKED. On `VERDICT: ITERATE scope=local:<paths>` with fewer than 2
   consecutive repairs, run a scoped repair pass instead of the next full
   Lead pass: invoke `trioctl omnigent run builder --prompt-file <repair
   brief>` with a brief that fixes exactly the listed paths (read VERDICT.md,
   smallest correct diff, no re-planning/refactoring/scope expansion, append a
   `- iter N | lead | repair: ...` line to LOG.md), then go straight to the
   Evaluator. Track the consecutive count in `loop/.repairs` (driver-internal;
   start at 1, cap at 2, reset to 0 after any full Lead pass). On the 3rd
   consecutive scoped verdict, or for any other ITERATE, run the full Lead
   pass as usual. On `VERDICT: NEEDS_HUMAN`, stop and surface the mandatory
   `## Human check` section from VERDICT.md.
8. When the loop reaches a terminal state — `SHIP`, `BLOCKED`,
   `NEEDS_HUMAN`, or an error abort (e.g. the commit-gate failure in step
   4) — call `sys_session_close` on every id tracked in step 6, **excluding
   the two registration-anchor sessions from Preflight step 3, which must
   never be closed**. Do this after the terminal verdict (and, on SHIP, the
   retirement commit) is written, before ending the turn. If a close fails
   (session busy, already closed, etc.), report it and continue closing the
   rest — cleanup is best-effort and must never change the loop's verdict.

`sys_session_create` is asynchronous. Use inbox/session history tools and end
the turn while a role is running; Omnigent wakes this session on completion.
Do not busy-poll.

If a role session's result is `failed (exit N)` and the broker log shows a
provider transport error — the observed triggers are `resource_exhausted`,
`NGHTTP2_INTERNAL_ERROR`, or `stream refused` — auto-wake the named session
ONCE via `hub send` with the message `continue` before surfacing any failure
to the user. A second failure, or no live session to wake, is a real
failure: surface it.

Default to repeated iterations until SHIP/BLOCKED/NEEDS_HUMAN, with NO user
checkpoint between Lead completion, Evaluator dispatch, and the
verdict-driven next iteration — only a terminal verdict stops the chain
(the compact per-iteration digest is still posted after each verdict).
If the user explicitly asks for one supervised iteration, stop after one
verdict.

<!-- trio-protocol:start -->
## Trio protocol essentials

- Verdict grammar — the first non-empty line of `VERDICT.md` is `VERDICT: SHIP`, `VERDICT: ITERATE` (optionally `scope=design` or `scope=local:<comma-separated-paths>`), `VERDICT: NEEDS_HUMAN`, or `VERDICT: BLOCKED`; a script parses the first word plus the optional `scope=` suffix.
- `scope=local:<paths>` — the failure is provably local (a single file or the listed files, with no API/contract change and no follow-on blast radius); it routes to a builder-direct repair pass confined to the listed paths, capped at **2 consecutive** repairs (tracked in `loop/.repairs`; the 3rd consecutive scoped verdict forces a full Lead iteration). `scope=design` or plain ITERATE runs a full Lead iteration.
- `NEEDS_HUMAN` — every agent-verifiable criterion passes but `PLAN.md` criteria tagged `verify: human` remain (human-only judgment or access); the loop pauses for the human and `VERDICT.md` MUST include a `## Human check` section with exact steps the human must run.
- Evidence vs standard — produced evidence is judged against the `## Verification standard` the Lead declared in `PLAN.md` (mode: `test-first` | `implement-then-smoke` | `human-gate`, plus the promised evidence) and against GOAL.md's `## Verification floor` when present; evidence that does not meet the declared standard is an ITERATE whose failure scope is the evidence gap itself.
- Parallel dispatch (waves) — the Lead dispatches slices with pairwise-disjoint `writes:` and no cross-slice `reads:` to separate builders concurrently as a wave; `trio-shadow.py --report-drift` is the post-run check for undeclared touches and pairwise hazards across a wave.
- Session sidecar — at iteration start, wrappers write `loop/.session.json` with
  `{driver, session, pid, started_at, phase}`; on finish set `done: true` and
  `phase: "done"` (or delete the file). `pid` is the orchestrator process;
  the dashboard treats a dead-pid sidecar as orphaned, not running.
- Open-loop extension (optional, gated on `loop/QUEUE.md` existing; absent → unchanged lockstep behavior above) — `QUEUE.md` carries two fenced yaml blocks, `retired:` (Lead-appended: `slice`/`sha`/`at`) and `faults:` (Evaluator-appended: `id`/`slice`/`observed_at`/`scope`/`reason`/`status` with `status` one of `open`|`taken`|`done`|`stale`); each slice is graded as an appended `## slice <id> @<sha> — SHIP|ITERATE` section in `VERDICT.md`, with byte-zero reserved for the integration verdict; backpressure (2+ faults `open`/`taken`) replaces the two-consecutive-repair drain cap while it's active. The automated driver, `python3 metrics/trio_loop.py run --mailbox <dir> --max-iterations N`, auto-selects open-loop when `QUEUE.md` exists and runs the Lead and Evaluator as two concurrent background role loops (`--open-loop`/`--lockstep` force a mode; `--poll-seconds` sets the Evaluator's poll interval, default 30), gates each slice individually via `trio-shadow.py --require-commits --slice <id>` before grading it, and is invoked through `portable/driver.sh` by exporting `TRIO_MODE` and `POLL_SECONDS`.
<!-- trio-protocol:end -->

## Headless

`trioctl omnigent loop` runs unattended iterations over the broker's HTTP API:
```bash
trioctl omnigent loop --mailbox loop/ [--max-iterations N] [--wait-timeout S]
```

The command owns the mailbox lock and manages verdict parsing, repairs (max 2
consecutive scoped repairs), resume state, and exit codes. `--wait-timeout`
defaults to 3600 seconds; session `wait` completes on a `running` to `idle`
edge (with idle dwell to ignore bind flicker), a completed assistant message,
or `--wait-timeout` expiry. Distinct outcomes: exit 0 (SHIP), 2 (BLOCKED), 3
(bad verdict), 4 (iteration cap), 5 (NEEDS_HUMAN or mailbox lock held).

`trioctl omnigent loop` writes `loop/.driver.json` with the PID, iteration
count, phase (`idle` / `lead-done` / `eval-done`), and Lead/Evaluator session
IDs. This is the authoritative resume cursor; killing the process and re-running
continues where it left off.

Alternatively, the supervised chat-coordinator procedure (one iteration per
`sys_session_create` in the current session, with inbox polling between roles)
remains available for interactive debugging or custom iteration logic.