run-agent

name	run-agent
description	Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.

Run-Agent — Execution Engine

Single entry point for agent execution. A run is model + agent (opt) + skills (opt) + prompt. Routes to the correct CLI (claude, codex, opencode) based on the model, logs everything, and writes structured index entries.

Skills source: sibling skills (../). Runtime artifacts: .orchestrate/.

Runner scripts (relative to this skill directory):

• scripts/run-agent.sh — launch a subagent run
• scripts/run-index.sh — inspect and manage runs

Run Composition

Compose runs dynamically by specifying model, skills, and prompt:

# Model + skills + prompt
scripts/run-agent.sh --model MODEL --skills SKILL1,SKILL2 -p "PROMPT"

# Model + prompt (no skills)
scripts/run-agent.sh --model MODEL -p "PROMPT"

# With labels and session grouping
scripts/run-agent.sh --model MODEL --skills SKILLS \
    --session SESSION_ID --label KEY=VALUE -p "PROMPT"

# With template variables
scripts/run-agent.sh --model MODEL \
    -v KEY1=path/to/file1 -v KEY2=path/to/file2 \
    -p "Task using {{KEY1}} and {{KEY2}}"

# Dry run — see composed prompt + CLI command without executing
scripts/run-agent.sh --model MODEL --skills SKILLS --dry-run -p "PROMPT"

Key Flags

Flag	Description
--model MODEL / -m	Model to use (auto-routes to correct CLI)
--agent NAME	Agent profile for defaults + permissions
--skills a,b,c	Skills to compose into the prompt
--strict-skills	Fail fast when any listed skill is unknown
-p "prompt"	Task prompt
-f path/to/file	Reference file appended to prompt
-v KEY=VALUE	Template variable substitution (repeatable)
--session ID	Session ID for grouping related runs
--label KEY=VALUE	Run metadata label (repeatable)
-D brief|standard|detailed	Report detail level (default: standard)
--continue-run REF	Continue a previous run's harness session
--fork	Fork the session on continuation (default where supported)
--in-place	Resume without forking (always for Codex)
--dry-run	Show composed prompt without executing
-C DIR	Working directory for subprocess

Runtime Config (.orchestrate/config.toml)

On first run in a workspace, run-agent.sh auto-creates .orchestrate/config.toml with commented examples.

Use this file to pin skills that should be auto-added on every run:

[skills]
pinned = ["orchestrate", "run-agent", "mermaid"]

Notes:

• Pinned skills are merged with agent-profile skills and CLI --skills (deduplicated by name).
• Default template is fully commented; uncomment/edit to enable.

Output Artifacts

Each run writes to .orchestrate/runs/agent-runs/<run-id>/:

• params.json — run parameters and metadata
• input.md — composed prompt
• prompt.raw.md — composed prompt before runtime-generated output/report sections
• output.jsonl — raw CLI output (stream-json or JSONL)
• stderr.log — CLI diagnostics (also streamed to terminal)
• report.md — written by the subagent (or extracted as fallback)
• files-touched.nul — NUL-delimited file paths (canonical machine format)
• files-touched.txt — newline-delimited file paths (human-readable)

Run Index

Two-row append-only index at .orchestrate/index/runs.jsonl:

• Start row (written before execution): status: "running" — provides crash visibility.
• Finalize row (written after execution): status: "completed"|"failed" with exit code, duration, token usage, git metadata.

A start row with no matching finalize row means the run crashed or is still in progress.

Structured Exit Codes

Code	Meaning
0	Success
1	Agent/model error (bad output, task failure)
2	Infrastructure error (CLI not found, harness crash)
3	Timeout
130	Interrupted (SIGINT / user cancel)
143	Terminated (SIGTERM)

Model Routing

Pattern	CLI
claude-*, opus*, sonnet*, haiku*	Claude (claude -p)
gpt-*, o1*, o3*, o4*, codex*	Codex (codex exec)
opencode-*, provider/model	OpenCode (opencode run)

Routing is automatic from the selected model.

Run Explorer CLI

scripts/run-index.sh provides index-based run inspection:

scripts/run-index.sh list                          # List recent runs
scripts/run-index.sh list --failed --json          # Failed runs as JSON
scripts/run-index.sh show @latest                  # Show last run details
scripts/run-index.sh report @latest                # Read last run's report
scripts/run-index.sh logs @latest --tools          # Tool call summary
scripts/run-index.sh files @latest                 # Files touched
scripts/run-index.sh stats                         # Aggregate statistics
scripts/run-index.sh continue @latest -p "PROMPT"  # Continue a run's session
scripts/run-index.sh retry @last-failed            # Retry a failed run
scripts/run-index.sh maintain --compact            # Archive old index entries

Run references: full ID, unique prefix (8+ chars), @latest, @last-failed, @last-completed.

Helper Scripts

Script	Purpose
run-index.sh	Run explorer CLI (list, show, report, logs, files, stats, continue, retry, maintain)
log-inspect.sh	Inspect run logs (summary, tools, errors, files, search)
extract-files-touched.sh	Extract file paths from run output
extract-harness-session-id.sh	Extract harness session/thread ID from output
extract-report-fallback.sh	Extract last assistant message as report fallback
load-model-guidance.sh	Load model guidance with override precedence