oversight

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_xxx
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"
# CLI blocks. It prints the selected action id, or use_v2 after 30 minutes.

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