Jamon's agent orchestrator docs and CLI. Note -- this is designed for my code base and workflow and the harnesses/agents I have access to. Adapt to your own needs.

a-AGENT_ORCHESTRATOR.md

Agent Orchestrator Protocol

Summary: Orchestrator protocol for driving multi-agent task execution. One coordinating agent (the orchestrator, often Codex) slices a task into parallel-safe units and dispatches worker agents (often Claude) via the Tools/agent_review CLI wrapper. Covers work slicing, context hygiene, temp report files, parallelism, avoiding conflicting edits, polling/tailing results, and output validation. Use when the user asks an agent to act as orchestrator/coordinator/dispatcher rather than do the work directly.

Key Files: Tools/agent_review, AGENT_WORKFLOW.md, AGENT_REVIEW.md, CODING_CONVENTIONS.md

Status: IMPLEMENTED

When To Orchestrate

Adopt the orchestrator role when:

• User request: User or agent explicitly asks for an orchestrator, coordinator, or dispatcher role.
• Wide mechanical work: A change touches many independent files (rename sweep, per-file refactor, per-file doc update) where workers can run in parallel.
• Mixed read/write fan-out: Several read-only investigations plus a few isolated edits can proceed concurrently.
• Context pressure: The full task would blow the primary agent's context; slicing keeps each worker's context small and the orchestrator's clean.

Do not orchestrate trivial single-file work — the dispatch overhead is not worth it. Do the work directly per AGENT_WORKFLOW.md.

Roles

• Orchestrator: owns the plan, the work slices, the dispatch, and the validation. Often Codex (or whichever agent the user is driving). Never holds large file dumps in its own context — it reads worker report files, not raw worker transcripts.
• Worker: a fresh CLI agent spawned per slice via Tools/agent_review. Often Claude (claude-opus-4-8). Each worker gets a tight brief, does one slice, and writes a concise result to a temp file.

The orchestrator and a worker should not be the same model family running the same slice — keep workers fresh-context so they don't inherit the orchestrator's assumptions (same rationale as AGENT_REVIEW.md § Context Isolation).

Protecting Orchestrator Context

The orchestrator's context is the scarce resource. Protect it:

• Never paste worker transcripts or large diffs into the orchestrator's own reasoning. Have workers write to temp report files and read only the summary.
• Give each worker a self-contained brief: this doc, the task source, the exact files/slice it owns, and the expected output contract. Do not pass the orchestrator's full investigation trail.
• Keep the worker's deliverable small — a short structured report, not a re-dump of everything it read.
• When fanning out reads, ask each worker to return only a verdict + 2–5 bullets, not full file contents (same pattern as AGENT_WORKFLOW.md Step 1 worksheet fan-out).

Slicing Work

Slice so workers never collide:

• One edit agent per touched file set. Each writing worker owns a disjoint set of files. Two workers must never edit the same file — overlapping edits silently clobber each other.
• Group files that must change together (a class plus its test, a doc plus its Key Files: source) into one slice so a single worker keeps them consistent.
• Read-only investigations can overlap freely — they touch nothing.
• Keep each slice small enough that one worker finishes it in a single focused pass with a small context.
• If two slices have a dependency (B needs A's output), run them in sequence, not parallel; pass A's report file path to B.
• Name off-limits files in every brief. Human-owned or do-not-touch files (e.g. DataMigration.gd) must be called out explicitly in the worker prompt, even for slices that legitimately touch nearby code. Workers will otherwise "fix" them or stall debating whether they may — state up front which files to read-but-not-edit and which to leave entirely alone.

Worker Brief Contract

Every worker prompt should include the same core contract. Missing pieces create avoidable stalls, scope creep, or unusable reports.

• Role and mode: read-only, edit, validation, review, or wrap
• Exact slice: task number/name, files or file families owned, and what success means
• Allowed files: the files or directories the worker may edit
• Forbidden files: human-owned, unrelated, or explicitly out-of-scope files
• Context inputs: docs, worksheets, report files, or scratch diffs the worker must read
• Output path: a predictable /tmp/gso_<slice>.md report file
• Report shape: files changed, commands run, pass/fail, blockers, and follow-up recommendations
• Validation expectation: tests/lints to run, or an explicit reason they are not required
• Stop condition: stop and report instead of guessing when a blocker appears

Template:

<SLICE NAME> ONLY. You are a <mode> worker in this repo.
Read <docs/reports>. Edit only <allowed files>. Do not edit <forbidden files>.
Do <exact task>. Run <validation>.
Write /tmp/gso_<slice>.md with: files changed, behavior, commands/results, blockers.
Stdout one line only with status and report path. Do not commit.

The worker's stdout should be disposable. The report file is the interface.

Parallelism

• Run read-only workers in parallel. Investigations, audits, and validations have no write conflicts — dispatch them concurrently and collect their report files.
• Run writing workers in parallel only when their file sets are disjoint (see slicing). When in doubt, serialize the writers.
• Background long-running workers and poll their result files rather than blocking on each one (see Polling).
• Cap concurrency to what the machine and metered-model budget allow; free pools (Copilot, Cursor included pool) are cheaper to fan out wide.

Temp Report Files

Workers communicate results through files, not stdout-into-orchestrator-context.

• Each worker writes to a predictable path, e.g. /tmp/claude_step0.md, /tmp/claude_step1.md, … one file per slice.
• Use a consistent prefix (claude_) and a slice index or slug so the orchestrator can tail/poll deterministically.
• For large inputs handed to a worker (a big diff, a file list), write the input to a gitignored scratch path inside the repo and tell the worker to read that path — keeps both the worker and the orchestrator under context limits.
• Report files are scratch; do not commit them.

CLI worker dispatch (via Tools/agent_review)

Workers are spawned through the same wrapper used for cross-review, so one tool covers all CLI agent families. The wrapper owns per-CLI transport quirks (read-only enforcement, < /dev/null stdin redirect, effort-flag mapping, default models); when a CLI's API changes, fix Tools/agent_review and this doc stays the same.

Tools/agent_review <agent> <model|default> <effort|default> "<prompt>"

• <agent> — copilot | codex | claude | cursor
• <model> — a model id for that agent, or default
• <effort> — low | medium | high | none | default
• <prompt> — the worker brief; pass - to read it from stdin

The repo is the current git toplevel; override with REPO=/path. List models with Tools/agent_review <agent> --list-models.

Agents, their default model, and when to reach for each:

(SIDENOTE: this heuristic is for "Jamon" -- if this is being run under some other user, this MAY NOT BE TRUE and you must check with the user regarding their specific account circumstances and refine this section first)

• copilot → gpt-5.4 — prefer first for free read-only fan-out: Copilot tokens are free. auto and claude-sonnet-4.5 reject --effort (the wrapper retries without it automatically).
• codex → gpt-5.5 — OpenAI frontier (metered). Use when you specifically want gpt-5.5.
• claude → claude-opus-4-8 — Anthropic frontier (metered). Default worker model. Use the id claude-opus-4-8, not claude-opus-4-8-thinking-high.
• cursor → composer-2.5 — Cursor's own model from the included pool (effectively free on Pro). Cursor bakes reasoning effort into the model id, so <effort> is a no-op for Cursor. Headless cursor-agent -p needs --force --trust (the wrapper passes both) or it hangs and exits empty; --mode plan still blocks edits.

Choosing model / effort

If the user specified an agent / model / effort, that takes precedence. Otherwise:

• Default to Opus 4.8 at low effort for routine slices unless the user says otherwise. Escalate effort only for genuinely hard or cross-system slices.
• Prefer free pools (copilot, cursor included) for wide read-only fan-out; reserve metered frontier (codex, claude) for slices that need it.
• Do not use "fast mode" anywhere — it burns tokens quickly.

Preflight: confirm worker availability

Before fanning out to a CLI agent, confirm it is actually usable — a misconfigured login wastes a whole dispatch round.

• Claude login check: verify the claude CLI is authenticated before dispatching Claude workers (e.g. a trivial Tools/agent_review claude default low "reply OK" smoke test). A logged-out CLI returns empty/garbage, which reads as a silent worker failure.
• Smoke-test any agent family you have not used this session before relying on it for a batch.
• Smoke tests are necessary but not sufficient. Direct claude -p may answer a tiny prompt and still empty-exit on a larger write-worker brief, especially when the brief is passed through stdin or shell substitution. If a direct Claude worker exits with no stdout, no report file, and no progress log, stop retrying broad prompts; switch to a smaller brief, Tools/agent_review for read-only work, or another agent family.

Resuming agent sessions

Prefer resuming a live/recent agent session for follow-up critique or course correction instead of starting a fresh context every time. It is easier on credits and often benefits from provider-side KV cache when resumed quickly.

• Claude: use claude --continue for the most recent conversation in the current directory, or claude --resume <session-id> when you have a specific session. For planned long-running workers, consider --session-id <uuid> or a memorable --name so the session is easy to resume.
• Cursor: use cursor-agent --continue, cursor-agent --resume <chatId>, or cursor-agent create-chat / cursor-agent ls to manage reusable planning/review chats.
• Use resume for targeted follow-ups: "review this plan again with these constraints", "tighten the patch to only these files", "continue from your prior report and address finding M1".
• Do not resume a broad worker after major repo state changes unless you explicitly tell it what changed (new commits, files edited by others, tests now passing/failing).

Dispatch pattern

# Read-only investigation worker writing to a temp report file
Tools/agent_review claude default low \
  "Read Docs/Workflow/AGENT_ORCHESTRATOR.md. Investigate <slice>. \
   Write a concise report (verdict + 3-5 bullets, file:line refs) to /tmp/gso_step0.md. \
   Do not dump file contents into your reply." < /dev/null

# Fan out several read-only workers in parallel, each to its own report file
for i in 0 1 2; do
  Tools/agent_review copilot default low \
    "Read Docs/Workflow/AGENT_ORCHESTRATOR.md. Handle slice $i (see /tmp/gso_slice_$i.md). \
     Write findings to /tmp/gso_step$i.md." < /dev/null &
done
wait

Polling and tailing results

• After dispatching background workers, poll their report files for existence/completion rather than holding the worker process in the orchestrator's context.
• tail -f or re-read a report file once the worker exits; read only the summary section the worker was told to produce.
• If a report file is missing or empty after the worker exits, treat it as a failed slice — re-dispatch with a tighter brief or escalate effort.

Progress signal contract

Progress files are useful but only reliable when the prompt makes them an explicit contract. For long edit workers, require a heartbeat file separate from the final report:

• Worker creates /tmp/<slice>_progress.log as its first action.
• Worker appends one line before and after each phase: start, inventory, edit, lint, tests, report.
• Each line should include a timestamp, a short phase label, and at most one concrete fact, e.g. 2026-06-27T07:30 edit Career.gd/Me.gd done.
• The final report is still /tmp/<slice>_impl.md; stdout is disposable.
• The orchestrator polls ps, the heartbeat mtime, and the final report. Avoid reading the raw transcript unless the worker exits without a report or the report contradicts the diff.
• If the process is alive but the heartbeat file was never created after a reasonable startup window, assume the prompt was not followed or the CLI failed before tool use. Resume or restart with a much smaller first task: "create the heartbeat file, then do inventory only."

This is good enough for most work, but not perfect. It is a liveness signal, not proof of quality; the orchestrator still owns diff review and validation.

Patience while polling

Workers go quiet for legitimate reasons. Do not mistake silence for failure:

• Claude workers often run quietly for several minutes while tests execute or while they iterate internally. This is normal — prefer generous timeouts and polling over interrupting early.
• Poll ps and the report file on an interval rather than blocking; allow the worker the wall-clock a real test run or multi-step edit needs before considering intervention.
• Distinguish "silent but active" from "silent and idle." A worker with a live child process (test runner, compiler) or a report file that is still growing is working — leave it alone. A worker with no child process and no report file written after enough time is a stalled idle wrapper — only then interrupt.
• When in doubt, wait one more poll cycle. Interrupting a worker mid-test-run wastes the whole slice.

Permission modes and worker stalls

Hard-won dispatch hints:

• Plan mode blocks writes — including tests and /tmp reports. claude --permission-mode plan can refuse to run tests or write report files. Use plan mode only for pure read-only review. When plan mode blocks a /tmp write, expect the output to land in ~/.claude/plans instead — check there if a report file is missing.
• Validation-only workers: forbid edits in the prompt, not via plan mode. Dispatch them with bypassPermissions (or the appropriate non-plan mode) and explicitly state "do not edit any files" in the brief — plan mode would otherwise prevent the tests the validation depends on.
• Long-running edit workers can stall silently after partial edits. Tell every edit worker to write a progress/report file early and update it as it goes, so a stall is detectable. Poll with ps plus the report file rather than blocking. Be ready to interrupt a stalled worker and hand its partial git diff to a smaller follow-up worker to finish the slice.
• Forbid stash/checkout in write-worker prompts. Direct CLI workers may reach for git stash to run a baseline comparison, which is risky in an orchestrated dirty tree. Tell workers to report suspected baselines instead of stashing, and have the orchestrator run any baseline check in a separate clean worktree or after committing the slice.
• Use --flag=value for direct Claude tool filters. With claude -p, --disallowedTools Edit,Write "prompt" can consume the prompt as more tool names. Prefer --disallowedTools=Edit,Write "prompt" when bypassing the wrapper for direct read/write workers.
• Use Cursor for planning/review when it is the better fit. Cursor Composer 2.5 has been useful as a read-only scout/reviewer through Tools/agent_review. Treat its plans as drafts: the orchestrator should critique assumptions, add architecture guidance, and feed sharper follow-up prompts back into the same resumed Cursor session when possible.
• Do not over-interpret transient credit/auth failures. Any agent family can hit credits, auth, CLI, or network issues. Record the operational failure and switch routes, but do not treat a credit outage as evidence that the model is bad for the task.

Timeout and interruption policy

Do not interrupt just because a worker is quiet. Use process state:

• Active child process: wait. A test runner, compiler, linter, or Godot process means the worker is still doing useful work.
• Report file growing: wait. The worker is communicating through the expected channel.
• Wrapper only, no child process, no report: poll a few times, then interrupt and preserve the partial diff.
• After interruption: do not resume the same broad prompt. Dispatch a smaller follow-up worker with the current git diff, the last known report, and one clear finishing task.
• After a worker edits files: do not launch another writer over the same file set until the first worker is done or interrupted.

Prefer patience for test-heavy slices. Prefer interruption for idle wrappers that have no child process and no report file after several poll cycles.

Validating worker output

Worker output is advisory until validated. The orchestrator owns correctness:

• Re-read each report file and check it against the slice contract — did the worker do what it was asked, in the right files only?
• For edit slices, inspect the actual git diff for the worker's file set, not just its self-report. Confirm no out-of-slice files were touched.
• Run the project gates the change requires: python3 Tools/gdlint.py <changed .gd> for code, python3 Tools/lint_docs.py for any .md in ./Docs or AGENTS.md.
• Cross-check overlapping claims between parallel read-only workers; divergence flags a slice that needs a second pass.
• Reject and re-dispatch any slice whose output is incomplete, out-of-scope, or fails a gate. Do not merge unvalidated worker output.

LSP and lint caveats

Large GDScript type migrations can confuse the Godot LSP and therefore Tools/gdlint.py.

• If gdlint reports impossible type errors after a broad type migration, compare against real Godot test runs before assuming the code is broken.
• Restart the headless Godot LSP when practical before final gdlint. Stale daemon state can make the final gate noisy.
• Do not hand-wave lint failures silently. Record whether they are real, stale-LSP artifacts, or pre-existing warnings, and include the exact command/result in the wrap report.
• New class_name scripts and .uid files must be staged together before the final gate/commit, or tools may fail to resolve them.

Wrap and Commit

Use a two-phase wrap for substantial orchestrated work.

1. Prepare wrap report: ask a worker to summarize changed files, commands, test results, lint status, docs/worksheet/changelog/TODOS updates, risks, and proposed commit message
2. Orchestrator review: personally read the report, inspect git status, inspect key diffs, and decide whether the commit is allowed
3. Commit: only then let a worker stage and commit, or commit directly

Wrap-worker contract:

• Do not include Co-Authored-By
• Do not use --no-verify unless explicitly approved by the orchestrator after reviewing the gate failure
• Stage all intended files, including new .uid files
• Never stage unrelated user changes by accident; list the staged files in the report
• Include validation caveats in the commit body when a gate is noisy or skipped

If a hook blocks on a suspected stale tool state, prefer fixing/restarting the tool and rerunning the gate. If the orchestrator decides to commit anyway, the final report must say exactly why.

Related Docs

• AGENT_WORKFLOW.md — single-task workflow; orchestration sits on top of it for wide/parallel work
• AGENT_REVIEW.md — cross-review protocol; shares the Tools/agent_review wrapper and context-isolation rationale
• AGENT_LOOP.md — night-shift cadence; an orchestrator can drive a loop's wide tasks
• CODING_CONVENTIONS.md — quality bar workers must meet
• DOCS_AUTHORING_GUIDE.md — rules for any doc slice a worker edits

z-agent_cli

#!/usr/bin/env bash
#
# agent_cli — one front door for cross-agent work: read-only review/research
# OR write-capable edit/refactor.
#
# Generalizes agent_review (read-only only) by adding an optional trailing
# `mode` arg. `review` (default) keeps every agent read-only — identical to
# agent_review. `edit` flips each CLI into its write-capable mode so a worker
# can apply targeted refactors/edits. Existing 4-arg review calls work
# unchanged; append `edit` to allow writes.
#
# Wraps the four CLI agents (copilot, codex, claude, cursor) behind a single
# signature so one doc describes one tool, not four. This script owns the
# per-CLI transport quirks (read-only vs write mode, stdin redirect, effort
# flag mapping, default models). When a CLI's API changes, fix it HERE.
#
# Usage:
#   Tools/agent_cli <agent> <model|default> <effort|default> "<prompt>" [mode]
#
#   <agent>   copilot | codex | claude | cursor
#   <model>   a model id for that agent, or `default` (see DEFAULT_MODEL_* below)
#   <effort>  low | medium | high | none | default   (mapped per agent)
#   <prompt>  the prompt; pass `-` to read it from stdin
#   [mode]    review (default, read-only) | edit (write-capable)
#
# Examples:
#   Tools/agent_cli copilot default high "Review the uncommitted diff."
#   Tools/agent_cli codex gpt-5.5 high "Review Scripts/TreeRegion.gd for perf."
#   Tools/agent_cli claude default low "Refactor Scripts/Foo.gd: extract helper." edit
#   git diff main...HEAD | Tools/agent_cli claude default high -
#
# review mode runs READ-ONLY (no edits); edit mode allows writes within the
# repo. The repo is the current git toplevel (override with REPO=/path).
# List models with: Tools/agent_cli <agent> --list-models

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=/dev/null
source "$SCRIPT_DIR/colors.sh"

REPO="${REPO:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"

# Per-agent default models (the frontier the project prefers for that CLI).
DEFAULT_MODEL_copilot="gpt-5.4"          # Copilot tops out here; no gpt-5.5. Free tokens.
DEFAULT_MODEL_codex="gpt-5.5"            # OpenAI frontier; metered.
DEFAULT_MODEL_claude="claude-opus-4-8"   # Anthropic frontier; metered.
DEFAULT_MODEL_cursor="composer-2.5"      # Cursor's own model; included pool, distinct family.

DEFAULT_EFFORT="low"   # cheapest that fits; escalate per AGENT_REVIEW.md rubric

usage() {
  cat <<'EOF'
Usage: Tools/agent_cli <agent> <model|default> <effort|default> "<prompt>" [mode]

  agent    copilot | codex | claude | cursor
  model    a model id, or `default`
  effort   low | medium | high | none | default
  prompt   the prompt; `-` reads from stdin
  mode     review (default, read-only) | edit (write-capable)

review mode runs read-only; edit mode allows writes within the repo.
List models: Tools/agent_cli <agent> --list-models
EOF
}

die() { echo -e "${RED}agent_cli: $*${NC}" >&2; exit 1; }
note() { echo -e "${DKGRAY}» $*${NC}" >&2; }

[ $# -ge 1 ] || { usage >&2; exit 1; }
AGENT="$1"; shift

# --list-models shortcut
if [ "${1:-}" = "--list-models" ] || [ "${1:-}" = "models" ]; then
  case "$AGENT" in
    cursor) exec cursor-agent --list-models ;;
    codex)  exec codex --help ;;  # codex enumerates via -m; no list subcommand
    copilot) die "copilot has no headless model list; run \`copilot\` then /model. Known good: gpt-5.4, claude-sonnet-4.6, auto" ;;
    claude) die "claude model ids: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5-20251001" ;;
    *) die "unknown agent '$AGENT'" ;;
  esac
fi

[ $# -ge 3 ] || { usage >&2; die "need <model> <effort> <prompt>"; }
MODEL="$1"; EFFORT="$2"; PROMPT="$3"; MODE="${4:-review}"

[ "$MODEL" = "default" ] && { v="DEFAULT_MODEL_$AGENT"; MODEL="${!v:-}"; [ -n "$MODEL" ] || die "unknown agent '$AGENT'"; }
[ "$EFFORT" = "default" ] && EFFORT="$DEFAULT_EFFORT"
[ "$PROMPT" = "-" ] && PROMPT="$(cat)"
[ -n "$PROMPT" ] || die "empty prompt"

case "$MODE" in
  review|edit) ;;
  *) die "unknown mode '$MODE' (expected review | edit)" ;;
esac

case "$AGENT" in
  copilot)
    command -v copilot >/dev/null 2>&1 || die "copilot CLI not found"
    # review: --plan = read-only/planning (no edits). edit: drop --plan so
    # the agent can write. --allow-all-tools suppresses permission prompts on
    # tools (required non-interactive). Some models (auto, *-4.5) reject
    # --effort, so retry without it on error.
    eff=()
    [ "$EFFORT" != "none" ] && eff=(--effort "$EFFORT")
    plan=(--plan)
    [ "$MODE" = "edit" ] && plan=()
    note "copilot --model $MODEL ${eff[*]:-} ${plan[*]:-} ($MODE)"
    out="$(copilot -p "$PROMPT" --model "$MODEL" ${eff[@]+"${eff[@]}"} ${plan[@]+"${plan[@]}"} --allow-all-tools --no-color -C "$REPO" </dev/null 2>&1)" || true
    if grep -q "does not support reasoning effort" <<<"$out"; then
      note "model rejects --effort; retrying without it"
      out="$(copilot -p "$PROMPT" --model "$MODEL" ${plan[@]+"${plan[@]}"} --allow-all-tools --no-color -C "$REPO" </dev/null 2>&1)" || true
    fi
    printf '%s\n' "$out"
    ;;

  codex)
    command -v codex >/dev/null 2>&1 || die "codex CLI not found"
    sandbox="read-only"
    [ "$MODE" = "edit" ] && sandbox="workspace-write"
    note "codex exec -m $MODEL reasoning.effort=$EFFORT -s $sandbox ($MODE)"
    codex exec -m "$MODEL" -c reasoning.effort="$EFFORT" -s "$sandbox" -C "$REPO" "$PROMPT" </dev/null
    ;;

  claude)
    command -v claude >/dev/null 2>&1 || die "claude CLI not found"
    # review: plan mode + Edit/Write disallowed = read-only. edit: acceptEdits
    # so the agent applies changes without prompting.
    if [ "$MODE" = "edit" ]; then
      note "claude -p --model $MODEL --effort $EFFORT --permission-mode acceptEdits (edit)"
      ( cd "$REPO" && printf '%s' "$PROMPT" | claude -p \
          --model "$MODEL" --effort "$EFFORT" \
          --permission-mode acceptEdits )
    else
      note "claude -p --model $MODEL --effort $EFFORT --permission-mode plan (review)"
      ( cd "$REPO" && printf '%s' "$PROMPT" | claude -p \
          --model "$MODEL" --effort "$EFFORT" \
          --permission-mode plan --disallowedTools Edit Write )
    fi
    ;;

  cursor)
    command -v cursor-agent >/dev/null 2>&1 || die "cursor-agent CLI not found"
    # Cursor bakes effort into model ids (e.g. gpt-5.5-high); EFFORT is
    # informational only. review: --mode plan blocks edits. edit: cursor's
    # write/agent mode is the default, so we OMIT --mode (its only --mode
    # choices are plan|ask; there is no `agent` value). Headless -p cannot
    # show tool-permission prompts, so --force --trust are required or it
    # hangs and exits empty. stream-json reliably emits the final result text
    # (text format drops it for agentic runs), so we stream the final result.
    cmode=(--mode plan); cprompt="Review-only: do not edit any files. $PROMPT"
    [ "$MODE" = "edit" ] && { cmode=(); cprompt="$PROMPT"; }
    note "cursor-agent -p --output-format stream-json ${cmode[*]:-} --force --trust --model $MODEL ($MODE; effort '$EFFORT' n/a)"
    cursor-agent -p --output-format stream-json ${cmode[@]+"${cmode[@]}"} --force --trust \
      --workspace "$REPO" --model "$MODEL" \
      "$cprompt" \
      | python3 -c '
import sys, json
out = ""
for line in sys.stdin:
    line = line.strip()
    if not line: continue
    try: obj = json.loads(line)
    except Exception: continue
    if obj.get("type") == "result" and obj.get("result"): out = obj["result"]
print(out if out else "(cursor returned no result text)")'
    ;;

  *)
    die "unknown agent '$AGENT' (expected copilot | codex | claude | cursor)"
    ;;
esac