oversight

name	oversight
description	Sync decisions, provenance, and artifacts to the Oversight UI. Active when the `oversight` CLI and daemon (http://localhost:7333) are available. Falls back to plain chat otherwise.

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.

Core rules

1. Use oversight card add for decisions that need a user judgment. Do not ask the user in plain chat when the question fits a six-slot structure:

   • urgency (critical / sign-off) — drives lifecycle, see §"Urgency = lifecycle"
   • headline (one sentence, user's language)
   • recommendation (what you think is right, one paragraph)
   • default + timeout (what to do if the user is away)
   • evidence (list of ref_… you got from oversight artifact register)
   • actions (2–5 ids with labels)

   The CLI's blocking behaviour is decided by --urgency, not by you passing --block. See the urgency table below.

2. Register external sources before you cite them.

   oversight artifact register --url https://...         # returns ref_xxx
   oversight artifact register --path /abs/file.pdf      # returns ref_xxx
   oversight artifact register --snippet "raw text..."   # returns ref_xxx
   

   Register before the first tool call that depends on the source, not after. Provenance chain breaks if you register late and the agent is killed.

3. Record non-trivial factual claims explicitly. To record a claim in the UI, call:

   oversight claim add --text "22% market share" --tier verified --src ref_a34p
   

   Tiers:

   • verified — external source with a ref you registered
   • model — you inferred this, no external source
   • user — the user told you this earlier
   • unverified — you think this but are not sure

   Inline <claim src="..." tier="...">text</claim> tags are a readability convention — use them in final deliverables so a human reader can see provenance in-line. They are not auto-scanned or auto-recorded: the system cannot reliably tell "agent asserting" from "agent reading someone else's text", so it trusts only explicit oversight claim add calls.

4. Report what you are doing. When switching tasks inside a session, one line:

   oversight state set --state working --intent "reading interview 3 of 15"
   

   The UI shows this in the lane. Update when the intent meaningfully changes, not every turn.

5. Do not narrate your confidence, risk self-assessment, or completion percentage. The UI renders observable attributes (provenance, state, elapsed time) only. Model self-reports (confidence %, "this might be wrong", "I'm 80% sure") are not first-class signals — they encode no useful information beyond what the tier/state already shows.

6. Skip card add for trusted classes. Before posting a card, check the trust profile:

   oversight trust read
   

   If the decision class matches auto_approve, just execute the default action without asking the user.

7. Lifecycle is automatic. SessionStart / Stop and the default working ↔ waiting transitions are managed by hooks. Don't try to emit them yourself.

8. Use --json when you need machine-readable output. Default output stays token-efficient (ref_xxx, claim_id, action_id). Add --json for structured success/error objects, and use --dry-run / --validate before posting a card or installing hooks when you only need validation.

Urgency = lifecycle

--urgency is not a label — it is a contract about how the decision behaves over time. Pick the tier that matches the work, and the CLI / daemon enforce the right lifecycle automatically.

urgency	blocking	timeout behaviour	when to use
critical	always blocks (CLI forces --block on, even if you didn't pass it)	timeout does not apply default — daemon re-emits the card with escalated: true, fires policy.violation (rule: critical_timeout), parks the lane in stalled, and the CLI keeps waiting	the agent genuinely cannot proceed without a real human judgement; safer to wait than to guess
sign-off	always blocks	on timeout the daemon applies default_action (closed_by: timeout) and the CLI prints that action id	review-and-move-on; user silence = the default path

Do not use card add for FYI updates. If you need to tell the user something but no decision is required, use:

oversight chat emit --msg "Finished reading the sources; moving to synthesis." --role agent

Divergent exploration pattern

When you've produced multiple drafts / variants and want the user to pick one, 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.

Example patterns

Asking about a conflict between two sources (must wait — critical):

REF_A=$(oversight artifact register --url https://... --label "Interview 3")
REF_B=$(oversight artifact register --url https://... --label "Interview 8")
CHOICE=$(oversight card add \
  --urgency critical \
  --headline "Two interviews disagree on pricing — which do I trust?" \
  --recommendation "Interview 3 is a direct quote; Interview 8 is paraphrased. I lean toward 3." \
  --default use_a --timeout 600 \
  --evidence "$REF_A,$REF_B" \
  --action "use_a:Use Interview 3" \
  --action "use_b:Use Interview 8" \
  --action "both:Keep both, flag conflict")
# critical => CLI auto-forces --block. $CHOICE is one of: use_a, use_b, both.
# Critical timeouts re-broadcast and keep waiting; no default is returned.

Citing a fact you just read:

According to the filing, the company held
<claim src="ref_a34p" tier="verified">22% market share in Q3 2024</claim>,
down from
<claim src="ref_xw6r" tier="verified">24% a year earlier</claim>.

Noting something you inferred:

The trajectory suggests
<claim tier="model">margin compression will continue into Q1</claim>
unless the bundling pricing change lands.

What the user sees

• Left pane: one lane per agent session with a state dot (blue=working, amber=waiting, red-pulse=stalled, green=done) and your current intent.
• Center pane: your active card add --block decision, with all evidence chips clickable for source preview.
• Right pane: chat transcript + free-form input box for the user to reply.

Do not refer to the UI in text the user reads — you are not the interface. Just behave correctly and the interface works.