| name | oversight |
| description | Explicitly opt into syncing agent decisions, provenance claims, and external artifacts to the local Oversight UI. Use only when the user asks for Oversight, the current managed run injects this skill, or you are deliberately testing Oversight. Do not auto-activate just because the daemon at http://localhost:7333 is reachable. |
Oversight
You are running under an oversight interface. A user is watching a dashboard that shows what you are working on, what decisions you need help with, and what sources you are citing. Treat the dashboard as a real audience that cares about observable attributes only — not your inner monologue.
Activation
This skill is opt-in. Do not check the daemon or call the oversight CLI unless the user explicitly asks for Oversight, a managed run includes this skill in its prompt, or the task is specifically about testing/debugging Oversight.
Language
Match the user's language.
Runtime
Preflight
bash scripts/helper.sh preflight
Output (JSON): { ready, dependencies: { daemon, uptime_ms, agent_id }, hint }.
ready: true → daemon up; use the oversight CLI for decisions, claims, artifacts.ready: false → daemon dormant; don't try to use the CLI. Fall back to plain chat for any decisions and skip the inline <claim> convention. The hint explains why.
Degradation
| Dependency | Required | Behavior when unavailable |
|---|
oversight daemon (localhost:7333) | No | Skill is dormant. Decisions go through normal chat. CLI commands fail safely (stderr + exit 1) without breaking the host. |
oversight binary on PATH | No | Same as above. Hooks installed via oversight install-hooks use absolute paths. |
~/.oversight/current-agent cache | Soft | Set by SessionStart hook. Pass --agent-id <id> explicitly when missing, or run oversight agent register --name "..." first. |
Workflow
When preflight.ready is true, follow these rules:
Use --json when you need machine-readable output. Default output stays token-efficient (ref_xxx, claim_id, action_id). Use --dry-run / --validate for card payload validation or install previews.
1. Decisions go through oversight card add — don't ask in chat
If the question fits a six-slot structure, post a card. The CLI's blocking behavior is decided by --urgency, not by you passing --block.
oversight card add \
--urgency <critical|sign-off> \
--headline "<one sentence in user's language>" \
--recommendation "<one paragraph: what you think is right>" \
--default <action_id> --timeout <seconds> \
--evidence "ref_a,ref_b,..." \
--action <id:label> [--action <id:label> ...]
2. Urgency = lifecycle (the only thing you really need to choose)
| urgency | blocking | timeout | when |
|---|
critical | always blocks (CLI auto-forces --block) | does not apply default — daemon re-emits with escalated: true, fires policy.violation, parks lane in stalled, CLI keeps waiting | the agent genuinely cannot proceed without a real human judgement |
sign-off | always blocks | applies default_action (closed_by timeout) and prints that action id | review-and-move-on; user silence = default path |
3. Register external sources before citing them
ref=$(oversight artifact register --url https://...)
ref=$(oversight artifact register --path /abs/file.pdf)
ref=$(oversight artifact register --snippet "raw text...")
Register before the first tool call that depends on the source, not after. Provenance chain breaks if you register late and the agent dies mid-flight.
4. Record non-trivial factual claims explicitly
oversight claim add --text "22% market share" --tier verified --src ref_a34p
Tiers: verified (external source w/ ref), model (your inference), user (told to you), unverified (your guess).
Inline <claim src="..." tier="...">text</claim> tags are a readability convention — use them in final deliverables for human readers, but they are not auto-scanned. Only explicit oversight claim add records to the UI.
5. FYI updates go through chat
Do not use card add when no user decision is required. Use chat instead:
oversight chat emit --msg "Finished source review; moving to synthesis." --role agent
6. Divergent exploration pattern
When you have multiple drafts/variants and want the user to pick, use a blocking sign-off card with a clear default. The CLI waits until the user acts or the timeout applies the default.
ref_v1=$(oversight artifact register --path /tmp/draft_v1.md --label "conservative")
ref_v2=$(oversight artifact register --path /tmp/draft_v2.md --label "ambitious")
ref_v3=$(oversight artifact register --path /tmp/draft_v3.md --label "balanced")
oversight card add \
--urgency sign-off \
--headline "Three drafts ready — which should be the base?" \
--recommendation "v2 best fits the brief but has 2 facts to verify." \
--default use_v2 --timeout 1800 \
--evidence "$ref_v1,$ref_v2,$ref_v3" \
--action "use_v1:Use conservative" \
--action "use_v2:Use ambitious" \
--action "use_v3:Use balanced" \
--action "merge:Merge v1 + v2"
Use sign-off when the user's silence should mean "take the default". Use critical only when guessing would be unsafe.
7. Don't narrate model self-confidence
The UI renders observable attributes (provenance tier, lifecycle state, elapsed time) only. Confidence percentages, "I'm 80% sure", "this might be wrong" — these are not first-class signals. They encode no information beyond what tier/state already shows. Skip them.
8. Don't try to manage lifecycle yourself
SessionStart / Stop and the default working ↔ waiting transitions are managed by hooks. Don't emit oversight state set for those.
Completion Report
This skill doesn't have a "complete" phase — it's continuous during the session. When you finish a substantive piece of work that fits the structure, just call the relevant oversight command. The UI updates in real time.
Troubleshooting
| Symptom | Resolution |
|---|
oversight: no agent id | ~/.oversight/current-agent missing. SessionStart hook didn't fire (daemon was off at session start). Run oversight agent register --name "..." to bootstrap, or restart the session with daemon up. |
oversight: daemon not running (exit 1) | daemon down. Skill is dormant — fall back to plain chat. Don't retry. |
| Hook commands print no output | Expected. Hook subcommands intentionally silent (Claude Code / Codex hook schema requires empty stdout for "allow"). Side effects happen via daemon HTTP. |
References
- Full runtime contract:
Project2/design/runtime-integration.md (in the repo this skill ships with)
- Framework principles (P1–P6):
Project2/design/framework-v1.md
