---
name: patrono-control
description: Lead OpenCode agent workflow for planning, running, and inspecting deterministic Patrono workflows.
tags: [patrono, opencode, mcp, planner, orchestration, run-control]
---

# Patrono Control

The main OpenCode agent is the lead and owns decisions, approval, and user communication. Patrono owns worker processes, isolated worktrees, commits, integration, validation, and review execution.

## Non-Negotiable Boundaries

- Never create, inspect, modify, merge, cherry-pick, delete, or otherwise manage Patrono-owned worktrees, branches, commits, or integration state.
- Never launch, signal, wait on, or clean up worker subprocesses. Use `run_cancel` or `task_cancel`; Patrono terminates the process group.
- Never manually resolve an integration conflict. Inspect results and report a blocked run to the user.
- Do not reproduce Patrono's dependency scheduling or manually inject ledger findings into workers. The runtime compiles contracts and starts dependent tasks deterministically.
- `run_start` and `task_start` are asynchronous. Save returned IDs. Do not poll; request status only when the user asks for an update.
- Do not report success until the run is terminal and its final integration and required review result have been retrieved.

## Pipeline

```text
goal → run_plan → inspect plan (run_explain) → approve
     → run_start → monitor (run_status/run_snapshot/ledger_read)
     → retrieve result (run_result/task_result)
```

### 1. Plan

Request a structured workflow from the planner:

```
run_plan { goal: "<user goal>" }
```

Returns a `plan_id` and the generated workflow YAML. Do not invent a plan.

### 2. Inspect and approve

Validate the proposed workflow without executing:

```
run_explain { plan: "<workflow YAML>" }
```

Check each task has a concrete verifiable goal, dependencies respect ordering, writable scopes do not overlap, and profiles are appropriate. Use `worker_explain { profile }` when the contract matters. Add a `strict-review` task dependent on implementation tasks when the user wants verification.

Do not execute an invalid plan. Ask the planner to regenerate.

After user approval, start exactly the validated YAML:

```
run_start { plan: "<validated workflow YAML>" }
```

Record `run_id`. Patrono dispatches tasks, enforces `max_workers`, runs dependents after dependencies succeed, performs integration, and runs validation.

### 3. Monitor

On user request for progress:

```
run_status { run_id }
task_status { task_id }
```

View findings published by completed tasks:

```
ledger_read { run_id }
run_snapshot { run_id }
```

Cancel all work with `run_cancel { run_id }`, or one worker with `task_cancel { task_id }`.

### 4. Retrieve final result

After the run is terminal:

```
run_result { run_id }
```

If the plan includes `strict-review`, retrieve its verdict:

```
task_result { task_id }
```

The run is successful only when final integration succeeds and the review verdict is `approved`. Treat `changes_requested` (bounded repair trigger — one automatic pass), `rejected`, failed, blocked, cancelled, or timed-out results as non-success.

The `task_result` response includes `worker_result.review_verdict` for the strict-review task.

## Tool Roles

| Tool | Lead-agent use |
|---|---|
| `run_plan` | Request a structured workflow from the planner for a goal. |
| `run_explain` | Validate and explain proposed workflow YAML without execution. |
| `run_start` | Start an approved, validated multi-task workflow. |
| `run_status` | One requested run-level progress snapshot. |
| `run_snapshot` | Retrieve repository snapshot for a run. |
| `run_cancel` | Cancel every active task in a run. |
| `run_result` | Retrieve terminal run status and final integration outcome. |
| `run_list` | List all runs. |
| `task_start` | Start a single worker (for independent additions). |
| `task_status` | One requested task-level progress snapshot. |
| `task_cancel` | Cancel one active worker. |
| `task_result` | Retrieve a terminal task result, including review verdict. |
| `worker_explain` | Inspect a profile contract before assigning it. |
| `ledger_read` / `ledger_search` | Inspect run findings. |
| `ledger_publish` | Publish verified coordination findings only. |