# PolicyAdvisor Plugins

Customize workspace directory selection and project model tier defaults with small executables in `~/.config/oh-router/plugins/` speaking single-line JSON over `stdin` and `stdout`.

Canonical URL: https://ohrouter.com/docs/plugins

## Discovery and SHA-256 binary pinning

`ohd` discovers regular executable files (`chmod 0700`, non-symlink) inside `~/.config/oh-router/plugins/` and merges them with explicit `plugins` entries in `~/.config/oh-router/config.json`. When an entry specifies `sha256`, `ohd` hashes the plugin binary before every invocation and skips execution if the digest does not match. Every invocation runs under a hard `2000ms` timeout.

**Inspect the built-in PolicyAdvisor specification**

```sh
oh-router policy plugin-spec
oh-router policy plugin-spec --json
```

## Stdio JSONL wire contract (`launch` and `on_limit`)

`ProcessPolicyPlugin` writes one JSON line to the plugin's `stdin` with `event` set to `"launch"` or `"on_limit"`, along with `session` metadata, available workspace `profiles`, the four-tier `models` catalog, and the current `policy` view. The plugin writes a single JSON line to `stdout`.

| Field | Direction | Values & Meaning |
| --- | --- | --- |
| `event` | `stdin` | `"launch"` when spawning a new session, or `"on_limit"` when an active session hits a window hold. |
| `session` | `stdin` | `{ project, kind, model_class, model_tier, profile_id, headless, is_review, requirements }`. |
| `action` | `stdout` | `"proceed"`, `"relaunch"`, `"wait"`, or `"redeem_reset"`. |
| `profile_id` | `stdout` | Optional workspace profile ID (for example mapping a work repository to a dedicated `work` directory). |
| `model_tier` | `stdout` | Optional tier override: `"opus"`, `"sol"`, `"fable"`, or `"astra"`. |

## Core invariants enforced after plugin advice

- Neutral scope: plugins advise workspace directory selection, standard vs frontier tiers, or cross-provider continuation (`Opus` to `Sol`, `Fable` to `Astra`) within `oh-router-core` rules.
- Capability pinning: any session declaring `--require browser-auth` stays pinned to `claude` regardless of plugin output.
- Lane lease validation: an advised `profile_id` must exist on the chosen provider, be signed in, have an uncontended `personal` or `work` `flock` lane, and not have an active hold window.
