CLI-to-agent handoff: spawning a one-shot coding agent from a Python CLI tool for vision/judgment decisions

When a CLI pipeline hits a decision that requires vision, judgment, or multi-step reasoning (e.g. which direction to rotate a video, whether a generated image looks right), you can spawn a one-shot coding agent as a subprocess rather than building a bespoke ML pipeline or requiring user interaction.

Pattern (Python, works with omp/claude agents):

def run_harness_oneshot(prompt: str, *, cwd: Path, timeout: int = 600) -> int | None:
    harness = find_harness()  # shutil.which('omp') or shutil.which('claude')
    if not harness:
        return None
    cmd = [harness, '-p', prompt, '--auto-approve']
    r = subprocess.run(cmd, cwd=str(cwd), timeout=timeout)
    return r.returncode

Key details:

1. -p (print mode): agent runs non-interactively, prints result, exits. No terminal UI.
2. --auto-approve: auto-approves tool calls within the working directory. Safe when the agent only runs known idempotent/reversible commands.
3. Skill file as instruction: point the prompt at a skill file (Read skill://<name> and follow it) containing the canonical procedure. The agent reads it and follows step-by-step. This decouples the decision logic from the CLI code.
4. Don't trust the exit code for correctness: rc=0 means the agent ran and exited, not that it made the right choice. Always re-verify programmatically after the agent finishes (e.g. re-probe the file, check dimensions, run a validator).
5. Recursion guard: check $OMPCODE/$CLAUDECODE env vars before spawning — if already inside an agent session, print instructions instead of nesting sessions.
6. Manifest markers: record the outcome ('ok'/'fixed'/'manual') so re-runs skip already-handled items. rc=0 + verified = 'fixed'; rc=0 + still wrong = 'manual' (needs human); rc≠0 = leave unmarked for retry.

This pattern worked well for orientation fixing (vision decision: which way to rotate) but generalizes to any CLI step that needs judgment: image QA, content classification, data validation with context.