---
name: scode-harness-shellout
description: >-
  Use when asked to start, spawn, run, or delegate work to a named-model agent (e.g. "astra agent", "opus agent", "neon agent", "sol high agent", "sonnet subagent"), use another provider or harness, or use an agent/model the current harness cannot launch natively. The user need not name this skill. Prefer supported native delegation when the launch mechanism is open; honor an external mechanism selected by the user or caller. Also loaded by other skills for foreign-harness launches, including to pick which CLI runs a model. Supplies the CLI choice and verified launch, monitoring, resume, and kill mechanics for `codex exec`, `claude -p`, `muse exec`, `agy -p` (Antigravity), `opencode run`, and `omp -p`; loading alone activates no session-wide behavior.
title: scode-harness-shellout
canonical_url: https://skilld.dev/gh/scode/dotfiles/scode-harness-shellout
last_updated: 2026-11-20T11:10:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [AGENTS.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/AGENTS.md), [agents/openai.yaml](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/agents/openai.yaml), [CLAUDE.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/CLAUDE.md), [harness/agy.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/agy.md), [harness/claude.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/claude.md), [harness/codex.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/codex.md), [harness/muse.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/muse.md), [harness/omp.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/omp.md), [harness/opencode.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/harness/opencode.md), [SPEC.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-harness-shellout/SPEC.md).
>
> If the user asked to install this Skill, run `npx skilld install scode/dotfiles/scode-harness-shellout`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/scode-harness-shellout`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/scode/dotfiles/scode-harness-shellout) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/scode-harness-shellout`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/scode-harness-shellout --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/scode-harness-shellout --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# scode-harness-shellout

Loading this skill writes no state, launches nothing by itself, and establishes no session-wide mode or rule for later
spawns. Use it for the current delegation request, whether the user asked directly or another skill needs the mechanics.
Everything below is conditional on inputs the caller supplies, and the caller keeps every decision: which model, which
harness (unless it supplies `external`, which hands the CLI choice to this skill), whether to resume, how to judge the
result, and what to do with the tree afterwards.

## Recognizing a delegation request

Load this skill for requests such as "start an astra agent to review this", "have an opus agent investigate", "start a
neon agent", "run a sonnet subagent", or "use a model your native agents don't support". Naming this skill in
parentheses is unnecessary. A question about a model, or a model name appearing in task content, is not itself an
instruction to launch an agent.

Honor the requested model and effort, and preserve any launch mechanism and constraints the user or caller has already
selected. For a direct request that leaves the mechanism open, first check whether the current harness's native
delegation tool supports the requested model, effort, and any required resume behavior. If it does, use that tool;
loading this skill does not require a shell-out. Otherwise pick the external mechanism as described in Choosing the
external mechanism below. A selected external mechanism stays external even when native delegation is available. Read
the matching harness file before launching. Lack of native support is a reason to check the shell-out path, not to
silently substitute a native model or claim the requested agent cannot be run. If the external path is unavailable too,
report that limitation.

## Choosing the external mechanism

This applies when the caller supplies `external`, or when a direct request leaves the mechanism open and native
delegation cannot serve it. A caller that supplies a concrete mechanism has already chosen, and this section does not
apply to it. The rule picks the CLI and nothing else: the model and effort stay what the caller or user asked for, and
no rule here substitutes a different model.

The candidates, in order:

1. A harness the user names for this launch ("run it through opencode", "run it through antigravity"), or a harness or
   provider preference the user has stated in their standing instructions ("use opencode for GLM"), including one the
   caller passes on as a launch preference.
2. The family's own harness: `codex exec` for GPT, `claude -p` for Claude, `muse exec` for Muse, and `agy -p`
   (Antigravity) for Gemini (including bare Gemini line names such as `neon`, `argon`, `hydrogen`, and `flash`).
3. `omp -p`, for any model. It is the default for everything outside those four families (GLM, grok, mercury, and the
   rest), and the next candidate for a GPT, Claude, Muse, or Gemini model whose own harness is not installed.
4. `opencode run`, when one of its providers serves the model.

A CLI with no harness file here is never a candidate, even a vendor's own CLI for its own models (a grok CLI, say).

Take the first candidate that is installed and can serve the model. A harness the user named for this launch is not
replaced: if it cannot serve the model, report that instead of falling through. A standing preference that cannot serve
the model falls through to the next candidate. The checks:

- The CLI is on `PATH`. Every candidate needs this.
- `omp -p`: the launch itself is the check. omp resolves the model before any model call, and an id it cannot resolve
  exits 1 with `Model "..." not found` at no cost; treat that exit as "cannot serve" and move on. The omp harness file
  says which provider to use and how to spell the id.
- `opencode run`: `opencode providers list` shows a credential for the provider in the model id. Check instead of
  probing: a probe with a reachable model starts a paid run, and a launch with no model hangs.
- `codex exec`, `claude -p`, `muse exec`, and `agy -p`: they serve their own family's models, and `PATH` is the only
  check. When `agy -p` is requested for a non-Gemini model, check `agy models` (an unsupported model also exits 1 before
  any model call).

Each harness file says how to spell the model id for its CLI. When no candidate can serve the model, report it to the
caller as unreachable from here, naming what each candidate lacked, and say whether that holds for the model's whole
family (no installed candidate could serve any of its models), so the caller can stop offering the family rather than
retrying model by model.

## What the caller supplies

The caller supplies these inputs before an external launch, applying the request rules above when the mechanism is still
open.

- The launch mechanism: one of `codex exec`, `claude -p`, `muse exec`, `agy -p`, `opencode run`, or `omp -p`; or
  `external`, which leaves the CLI to Choosing the external mechanism above; or `native`, the caller's own sub agent
  mechanism, to which the shell-out procedures below do not apply.
- The model id and reasoning effort, both set explicitly on every launch.
- Optionally, a launch preference: the user's own words naming a harness or provider for this model, which the caller
  read from the user's configuration and passes on verbatim. It is a standing preference under Choosing the external
  mechanism, so it falls through when it cannot serve the model.
- A run id, a string unique to this delegation that the caller generated, used to name every file this skill creates.
- The prompt, as a file the caller writes before the launch, the way Launch hygiene below describes.
- The working directory or tree the delegate runs in.
- An expected duration and a hard deadline.
- Whether the run will be resumed later (a writer that stops and continues), so that the session or thread id is
  arranged at launch.
- Where the deliverable goes: a named artifact file the prompt tells the delegate to write, because every harness
  captures only the final message and a deliverable emitted mid-run is stranded in the transcript.

## Read the harness file, then launch

The harness files are the only place launch commands live. That is deliberate: a launch built from memory of a previous
session, or improvised from a harness's `--help`, skips the observed-behavior notes that exist because each one cost
someone a hung or silently wrong run. Read the file for the mechanism in full the first time in a session that you are
about to launch through it, then launch.

| mechanism      | read                                                       |
| -------------- | ---------------------------------------------------------- |
| `codex exec`   | `harness/codex.md`                                         |
| `claude -p`    | `harness/claude.md`                                        |
| `muse exec`    | `harness/muse.md`                                          |
| `agy -p`       | `harness/agy.md`                                           |
| `opencode run` | `harness/opencode.md`                                      |
| `omp -p`       | `harness/omp.md`                                           |
| `native`       | nothing; no shell-out mechanics apply to native delegation |

"`harness/`" means the `harness` directory under the directory this `SKILL.md` was loaded from, whatever path that is in
the current harness. Each file carries the launch template, the writer launch and resume commands, where the final
message lands, the effort words the provider rejects or silently ignores, and what a dead or hung run looks like. Where
a harness's process layout has been observed, the file also says which process to target so a kill takes the delegate's
children with it; the others have not been verified and say nothing.

## Launch hygiene

These rules were each learned from a real incident and apply to every shelled-out harness, whatever its flags:

- Every file you create for a delegate — prompt files, result and `-o` files, event logs, stderr logs, resume prompts —
  goes in scratch space private to this session (a fresh `mktemp -d`, or your harness's per-session scratch directory)
  and carries the run id the caller supplies in its name. Never a fixed name under `/tmp`: other orchestrators may be
  running delegates on the same machine at the same time, and this skill's `SPEC.md` requires that nothing it writes can
  collide with or be mistaken for theirs.
- Build the prompt in its own earlier command — write it to a scratch file — and pass it to the launch as a file
  argument or `"$(cat <file>)"`. Keep heredocs out of the command that launches the delegate: at least one agent harness
  omits its own stdin redirect from the wrapper exactly when the command text contains a heredoc, handing the child a
  pipe that never closes.
- Always end the launch with an explicit `< /dev/null`. Some harnesses read stdin to EOF before starting work and block
  forever on a pipe that never closes; the hang is intermittent and looks like a slow run. The redirect holds even when
  the wrapper drops its own, and it is harmless on harnesses that never read stdin.
- Set the model and the reasoning effort explicitly on every launch, matching the model and effort the caller supplies.
  Never rely on the user's configured default, and check the harness file for effort words the provider rejects or
  silently ignores.
- A zero exit status is necessary but not sufficient. Every harness exits 0 when the turn completes, including turns
  whose final message declines the task, reports a tool or permission failure it could not work around, asks a question
  nobody will answer, or gives status instead of the work. The caller judges the captured result against the task's
  explicit acceptance criteria. A result far shorter than the task warrants is the cheapest tell — a reason to look, not
  grounds to reject on its own. When a whole fan-out fails the same way, treat it as one broken execution path rather
  than N model failures: stop the batch and fix the path instead of judging each delegate separately.
- Long tasks can exceed your shell tool's default timeout. Run them in the background and monitor them per the section
  below; use a foreground timeout only when it is shorter than the monitoring interval.
- Permission bypass flags (`--yolo`, `--auto`, `--dangerously-skip-permissions`, `--approval-mode yolo`) disable
  approval and trust checks for the delegate, and sandboxing where the harness has one. Use them only where you would
  accept the same for the orchestrating session.

## Monitoring long-running delegates

The stdin hang above was found only after an orchestrator waited hours on a shelled-out code review that was never going
to finish. The lesson generalizes beyond that one bug: a background delegate has no guaranteed liveness or
forward-progress signal before it exits, and "no news yet" is not evidence of progress.

Prefer the parent harness's managed background execution with automatic completion delivery when it supports it. The
parent owns that delivery, regardless of which CLI the child runs; a detached process, a JSON event stream, or a status
file does not itself wake the parent model. Use the current tool contract rather than assuming all harnesses or versions
notify. Prefer monitoring without model turns. A small-context watcher agent is reasonable when it can notify the caller
directly and is expected to cost less than repeated caller wakeups; account for its launch overhead, model price, and
polling usage. Give it only the monitoring context it needs. The caller must not have to poll the watcher to receive its
alerts.

Without automatic delivery, use bounded waits on the returned job/session handle, choosing the longest wait compatible
with tool limits, required responsiveness, the next monitoring check, and the hard deadline. Batch checks of running
jobs instead of making one model turn per job. Avoid short sleep/status loops and repeatedly reading unchanged logs:
each empty model turn can reprocess a large conversation prefix as cached input. Keep routine observations compact (exit
state, log growth, and new diagnostics); inspect more only when investigation warrants it. A wait returning "still
running" is not a deadline and must not terminate the child. These choices reduce needless wakeups; they do not relax
the monitoring obligations below or any more frequent resource checks the caller requires.

- Never wait open-endedly on a shelled-out delegate, and never make a foreground call whose timeout exceeds the
  monitoring interval — a blocked foreground wait bypasses monitoring entirely. Run long delegates in the background and
  record what you need to check on and kill them later: job handle or pid, log path, output path, start time, expected
  duration, and a hard deadline. Include still-running delegates in any handoff or pre-compaction note.
- Wake up and check every running delegate at least every 30 minutes — sooner when the expected duration is shorter —
  using whatever timer, scheduled wake-up, or bounded-wait mechanism your harness offers. Failing all else, cap each
  blocking wait at 30 minutes and re-check between waits. In a fan-out, check every member at each wake-up: the batch is
  only done when its slowest member is, and one hung member silently holds the whole batch.
- Check known hang signatures first; they are cheap and decisive. Each harness file names its own, which may depend on
  the output mode (codex's differs with and without `--json`, for example); when one matches, kill and relaunch with the
  corrected invocation, since more waiting cannot help.
- Otherwise weigh the evidence by what the tool shows. Harnesses that stream a transcript or event log while working
  give you something to compare against the last check's baseline; record the new observation for the next one. New
  output proves activity, not necessarily useful progress; a log that has not grown across a full interval is a reason
  to inspect the run, not by itself grounds to kill it — long reasoning stretches can be quiet. Harnesses that print
  only the final message tell you nothing while silent; each harness file says which mode it is in and how to get a
  stream when a long run needs one.
- Use the estimate and the deadline for different decisions. Crossing the expected duration triggers investigation, not
  a kill. Crossing the hard deadline means the run is over budget regardless of apparent liveness: kill it, capture the
  log, and report the result to the caller as inconclusive.
- A hang or launch failure is an execution-path failure, not a substantive model failure: report it to the caller as
  such, with the signature seen, rather than as a failure of the model. The caller owns cleanup of whatever the run left
  in the tree and decides whether to relaunch; when it does, fix the path first, and make sure the kill took down the
  delegate's children too.
- Kill by pid, walking descendants first (see the harness files for which process to target). Never `pkill -f codex` or
  the like: the pattern matches unrelated sessions of the same harness and the shell that launched the run.

## Resuming a stopped delegate

A delegate that stops mid-task and is later continued with more input is resumed in the same session rather than
relaunched. Resume works on every harness (verified with a planted codeword that each harness answered on the resumed
turn: 2026-08-30 for codex, claude, muse, and opencode, 2026-10-19 for omp 18.12.3, and 2026-11-18 for agy 1.5.12).
Resuming preserves context and can reuse cached input, but cache hits still count toward usage; resume for work or
guidance, not for status polling. Whether a run stops, what it must produce before stopping, and what the continuation
says are the caller's protocol; this skill supplies the mechanics common to every harness:

- Record the harness's session or thread id at launch; each harness file says where it comes from (a `--session-id` you
  generate, or an id the harness prints in its JSON stream). Without it there is no resume, only a relaunch that throws
  away the delegate's context. Include the id in your monitoring record and in any handoff note.
- When the launch was `external`, record which CLI the rule chose, next to the id, and tell the caller. A resume goes
  through that CLI and never runs Choosing the external mechanism again: the session exists only in the CLI that started
  it. If that CLI is no longer installed, report the resume as blocked on it rather than resuming elsewhere.
- A stopped turn exits 0, like every completed turn; the caller detects the stop from the final message. Each harness
  file says where the final message is on a resumed turn; it is not always the same place as on the launch.
- Build the resume prompt in a file like any other prompt, pass it the same way, and keep the explicit `< /dev/null`.
  All of the launch-hygiene rules above apply to a resume unchanged, including running it in the background and
  monitoring it. Pass the same model, effort, working-directory, and permission flags as the launch: none of the
  harnesses is verified to restore them from the session, and a resume that lands in the wrong directory edits the wrong
  tree with bypass flags on.
- A resume can come back as a fresh session instead of a continuation: a resumed turn that shows no sign of its earlier
  context, re-reading the task from scratch or asking where it was told to write. Report it to the caller as such;
  classifying it and deciding what happens to the run are the caller's. A harness file adds a mechanism-specific
  signature only where one has been observed.
- Disk is the cause to check first when a run dies for no visible reason. Each isolated worktree of a Rust project costs
  on the order of 1.5 GB of build output, tests leave temp dirs behind, and a fan-out of writers can fill a disk
  mid-turn. Tear down trees promptly once the caller has gated their results and is done with them; a tree whose result
  is still ungated holds the only copy of that result.
