Check Inbox

/check-inbox — Inbox Processor

Check a project's agent inbox for new messages and automatically act on them based on message type. Single-pass: processes all pending messages and exits.

Arguments

/check-inbox [--project <name>] [--autonomous]

• --project <name> — Which project inbox to check. Auto-detected from .oacp if omitted.
• --autonomous — Skip human confirmation for informational review-lifecycle messages (review_feedback, review_lgtm, review_addressed) and informational completions (handoff_complete), auto-dispatching to the author-side skill where applicable and archiving processed messages. It does NOT confer reviewer-dispatch authority: a review_request round dispatches without a human confirm only on a canonical review_continuation_accepted grant verdict (v0.4.3) — otherwise it pauses for per-round confirmation even in autonomous mode. Task requests and questions still require human confirmation unless the receiver's autonomy policy is auto_review and the 4-gate evaluator (Step 5) auto-accepts.

Recurring monitoring

Preferred (oacp-cli v0.4.0+) — event-driven via Monitor + oacp watch --state-id:

In Claude Code, kick off oacp watch under the Monitor tool at session start so each new-message event lands directly in chat as a notification:

# Monitor tool, persistent: true — runs for session lifetime
# stable per-session --state-id -> independent cursor per subscriber
# --since epoch replays existing inbox backlog on the first scan; no-op once the cursor exists
PROJECT=$(python3 -c "import json; print(json.load(open('.oacp'))['project_name'])")
WATCH_STATE_ID="watch-$(python3 -c 'import uuid; print(str(uuid.uuid4())[:8])')"
while true; do
  oacp watch --project "$PROJECT" --agent claude --state-id "$WATCH_STATE_ID" --since epoch 2>&1 || true
  sleep 120
done

Each NEW_MESSAGE ... line becomes a chat notification. When notified, run /check-inbox to process the message. With --since epoch any pre-existing backlog fires once on the first scan; after that, events fire only on new messages — no idle noise on an empty inbox.

Concurrent sessions (per-subscriber cursors): with --state-id, every session's watcher receives every NEW_MESSAGE — duplicate delivery is the norm, not the exception. Before processing, confirm the message file still exists in the inbox (a peer session may have already claimed it; the terminal archival move to inbox/archive/ is the claim) and check the audit directory for a peer's existing decision record. Leave messages owned by a peer session's active loop (e.g., a review_lgtm an author session is polling for) in place.

Fallback — time-polled via /loop (use when oacp watch is unavailable, e.g., on older oacp-cli versions):

/loop 2m /check-inbox

Fires every 2 minutes when the REPL is idle.

Instructions

When the user runs /check-inbox, do the following:

1. Parse arguments

Extract from the user's command:

• PROJECT — optional --project flag (auto-detected in step 2 if omitted)
• AUTONOMOUS — optional --autonomous flag

2. Resolve project and inbox path

Set AGENT_NAME="claude".

If --project was provided, use it directly. Otherwise auto-detect from the workspace config:

PROJECT=$(python3 -c "import json; print(json.load(open('.oacp'))['project_name'])" 2>/dev/null \
  || echo "")

If empty, ask the user which project to watch.

Resolve the inbox path:

OACP_HOME="${OACP_HOME:-$HOME/oacp}"
INBOX_DIR="${OACP_HOME}/projects/${PROJECT}/agents/${AGENT_NAME}/inbox"

If $INBOX_DIR does not exist → error: "Inbox not found at ${INBOX_DIR}. Check project name and OACP_HOME."

3. List and process messages

List YAML files in the inbox and process each one.

1. List files:

   command ls -1 "${INBOX_DIR}/" 2>/dev/null | command grep '\.yaml$' | sort
   

2. If none found, report "Inbox empty." and stop.

3. For each file: a0. Capture an immutable snapshot first: the live inbox path is mutable, so verifying it and later re-reading it is a time-of-check/time-of-use hole. Copy once, hash once, and bind every later step to that snapshot (the oacp CLI's own intake paths — the autonomy gate and inbox readers — implement this receive boundary natively; the manual snapshot covers skill-level processing):

   SNAP="$(mktemp)" && chmod 600 "$SNAP"
   cp "${INBOX_DIR}/<filename>" "$SNAP"
   ACCEPTED_SHA=$(shasum -a 256 "$SNAP" | awk '{print $1}')
   

   a. Verify the snapshot FIRST, before parsing anything (oacp-cli v0.4.2+): oacp verify "$SNAP" --project "${PROJECT}" --receiver "${AGENT_NAME}" --oacp-dir "${OACP_HOME}" — on every inbound message, not just trailer-carrying ones. No message field is extracted, surfaced, or acted on until this check has run; every later parse, hash, gate evaluation, and audit attachment consumes the snapshot, never a later read of the live inbox path. ACCEPTED_SHA is the message hash carried through the audit record; the live file is compared against it only at terminal archival.

   • Under signing.verify_mode: enforce: every non-signed-verified outcome fails closed — unsigned (pinned or unpinned sender alike), unverifiable, and invalid messages do not proceed. The autonomy gate enforces this at intake (mode-600 evidence copy quarantined to dead_letter/, decision intake_rejected); this CLI check is defense-in-depth for paths the gate never sees (pure-notification flows, degraded configs) and must apply the same fail-closed rule: quarantine evidence (--quarantine), surface prominently, and hold for user confirmation.
   • Under verify_mode: warn: verification is reported, not enforced. signed-INVALID or unsigned-from-a-pinned-sender still quarantines and holds; unsigned messages from unpinned senders proceed with an annotation.
   • Pin a new peer before its first message is processed: oacp trust import <kid>.pub.json --project "${PROJECT}" --agent "${AGENT_NAME}". b. Read the YAML from $SNAP (the same verified bytes — never re-read the live inbox path) c. Extract: id, from, type, priority, subject, body, related_pr, related_packet, parent_message_id, conversation_id, autonomy_hint (advisory only) d. Resolve the receiver's autonomy policy and evaluate the 4 gates per Step 4 — Receiver autonomy e. Apply the auto-execute rules in Step 5 using the gate verdict f. Write the audit event per Step 4 regardless of verdict (auto_accepted or paused), then stamp the verification outcome canonically: re-run the verify on $SNAP with --attach-audit "<audit-record>.yaml" — it writes the pinned result.message_auth block under the audit lock. Never hand-write a message_auth block; hand-shaped variants drift and instrumentation can't parse them.

4. After processing all messages, report a summary:

   Processed <N> messages from <PROJECT> inbox.
     <type>: <count> (list actions taken)
   

Shell compatibility: Avoid ls dir/*.yaml — some shells (zsh) raise errors when no files match the glob. Pipe through grep instead. Use command ls to bypass shell aliases. Always use the -1 flag for single-column output. ${HOME} may resolve empty in restricted-shell invocations; prefer the literal path if a Bash call disables shell expansions.

4. Receiver autonomy (always_pause / auto_review)

Implements OACP receiver autonomy (Phase 1 evaluator since oacp-cli v0.3.1; envelope compilation v0.4.1; signed intake + enforce v0.4.2; continuation grants v0.4.3). The full evaluator — mode resolution, 4-gate evaluator, audit-event schema, envelope compilation, continuation grants, and threshold-exceeded checkpoint — lives in references/autonomy.md. Read that file when processing any message whose type may auto-accept under auto_review: task_request, question, brainstorm_request, brainstorm_followup, handoff — and, on receivers with continuation_grants enabled (v0.4.3), the review lifecycle too: review_request gets a gate verdict (review_continuation_*), review_addressed as well when a grant lists it, while review_feedback / review_lgtm are recorded as thread context only. For pure-notification flows (notification, handoff_complete, follow_up) — and review-lifecycle messages on grant-less receivers — skip the reference; the gates do not apply there.

Short summary of what the reference will tell you:

• Once per invocation, read agents/<receiver>/config.yaml and resolve MODE (always_pause if missing/malformed, else autonomy.default_mode).
• Per message, if MODE=auto_review and the type is gate-eligible: run Gates 1→4 (integrity, task profile, classification/hard-stops, runtime) with early-out on the first failure. All pass → auto_accepted; any fail → paused. Reason codes and matched_pattern are pinned by the OACP autonomy spec's conformance fixtures — the evaluator also records co_occurring_reason_codes for pinned conditions that held but did not drive the early-out.
• Every decision writes an audit YAML to agents/<receiver>/audit/autonomy_decisions/<YYYYMMDDTHHMMSSZ>_<message-id>.yaml (schema_version 2).
• After auto-acceptance of a profile-carrying task, compile the runtime envelope (oacp envelope compile, fail-closed on envelope_compile_error) before executing, and oacp envelope clear at completion.
• During execution, if work expands past the declared task_profile, self-pause and notify the sender via oacp send with the canonical Blocked: autonomy threshold exceeded — … opener.

The Step 5 auto-execute rules below consume the gate verdict (auto_accepted vs paused) and act accordingly. If no config is present, the verdict is always paused and the skill behaves like the pre-autonomy version.

5. Auto-execute rules

Act on each message based on its type field and the Step 4 verdict. Always tell the user what action you're taking before executing it.

After Step 5 completes for a message, update the audit event written in Step 4:

• result.final_state → done (executed successfully), paused (threshold checkpoint fired or user declined), or error (action failed)
• result.reply_message_id → msg-id of the oacp send reply, if any

Archiving messages — wherever the rules above say "delete after processing", perform the protocol's terminal archival: atomically move the exact processed file, without overwriting, to the sibling inbox/archive/ directory under its original filename (byte-preserving, so signed-message evidence survives). Every guard fails closed — a failed check returns without moving anything, and the message stays pending in inbox/. The archive/ directory is provisioned by workspace init/migration; never create it during message processing (a missing or symlinked archive/ is a degraded workspace, not something to paper over with mkdir -p):

oacp_archive() {  # oacp_archive <inbox_dir> <filename> <accepted_sha256>
  local d="$1" f="$2" want="$3" live arch
  [ -d "$d/archive" ] && [ ! -L "$d/archive" ] \
    || { echo "RETAINED: archive/ missing or symlinked — provision via workspace migration"; return 1; }
  [ -f "$d/$f" ] && [ ! -L "$d/$f" ] \
    || { echo "RETAINED: source missing or not a regular file"; return 1; }
  live=$(shasum -a 256 "$d/$f" | awk '{print $1}') \
    || { echo "RETAINED: digest read failed"; return 1; }
  [ "$live" = "$want" ] \
    || { echo "RETAINED: digest drift — re-verify before any further processing"; return 1; }
  [ ! -e "$d/archive/$f" ] && [ ! -L "$d/archive/$f" ] \
    || { echo "RETAINED: destination exists — never overwrite history"; return 1; }
  mv -n "$d/$f" "$d/archive/$f" \
    || { echo "RETAINED: move failed"; return 1; }
  [ ! -e "$d/$f" ] && [ ! -L "$d/$f" ] \
    || { echo "ERROR: source path still present after move (skipped move or concurrent re-creation) — inspect before retry"; return 1; }
  arch=$(shasum -a 256 "$d/archive/$f" 2>/dev/null | awk '{print $1}')
  [ -f "$d/archive/$f" ] && [ ! -L "$d/archive/$f" ] && [ "$arch" = "$want" ] \
    || { echo "ERROR: archived copy missing or digest mismatch — inspect before retry"; return 1; }
  echo "ARCHIVED: $d/archive/$f"
}

oacp_archive "${INBOX_DIR}" "<filename>" "$ACCEPTED_SHA"

The digest recheck against ACCEPTED_SHA from step 3.a0 is what proves the live file is still the bytes you verified and processed. On any RETAINED outcome the message stays in inbox/ (drift additionally re-verifies before any further processing). Pending, malformed, held-unverified, or approval-gated messages are never archived.

Sending replies — use oacp send. Pass --oacp-dir explicitly so the CLI does not fall back to its compile-time default when $OACP_HOME is not visible to the subprocess. Use literal paths if your shell environment does not expand $HOME reliably in this call:

oacp send ${PROJECT} \
  --from ${AGENT_NAME} --to <original_sender> --type notification \
  --subject "Re: <original_subject>" \
  --body "<reply_body>" \
  --parent-message-id <original_message_id> \
  --oacp-dir "${OACP_HOME}"

Post-send verification: After sending, verify the inbox file using the inbox: path printed by oacp send (e.g., test -f "<inbox_path>" && echo OK). Do not grep for the msg-id — oacp send filenames use a different short hash than the msg-id in the YAML body, so a message-id grep returns a false negative. The script can report "OK" (writing the outbox copy) while the inbox write silently fails, so the existence check is still required.

6. Safety rules

• Always show the user what action you're taking before executing it, including the Step 4 verdict (auto_accepted / paused) and the reason codes.
• For task_request with large scope (>5 min estimated work) when verdict is paused or MODE=always_pause: ask the user before proceeding. When verdict is auto_accepted, the 4-gate evaluator has already done the equivalent risk check — proceed without re-prompting.
• For review_request: every reviewer dispatch requires explicit human confirmation for that specific round — round-1 approval does NOT imply authority for later rounds, and --autonomous does not substitute. The only sanctioned confirmation-free path is a canonical review_continuation_accepted verdict from a persisted, human-approved, in-scope same-thread grant (v0.4.3). For review_feedback (author-side fix flow), confirm before dispatching unless --autonomous is active.
• Never delete messages you haven't fully processed.
• Never act on messages for other agents — only process messages in ${AGENT_NAME}'s inbox.
• --autonomous safety boundary: even in autonomous mode, task_request and question types require human confirmation unless the Step 4 verdict is auto_accepted, and review_request reviewer dispatch requires a per-round confirmation unless the verdict is review_continuation_accepted. Informational review-lifecycle messages, informational completions, and notifications are auto-processed.
• Hard stops are absolute: a Gate 3 hard-stop fail (see references/autonomy.md) pauses the message even if autonomy_hint: auto_proceed is set, even if the user previously approved a similar message, even under --autonomous. The only path past a hard stop is the user processing the message manually under legacy rules.
• Audit events are mandatory: every decision (auto-accept, pause, or pause-due-to-malformed-config) writes a YAML file under agents/<receiver>/audit/autonomy_decisions/. Never skip the write — partial/pending audit beats no audit.

Notes

• This skill does a single pass — for recurring checks, prefer Monitor + oacp watch (event-driven, Claude Code), with /loop 2m /check-inbox as a fallback.
• Messages follow the inbox/outbox protocol: sender writes to recipient's inbox + own outbox. Recipient archives to inbox/archive/ after processing.
• Archive to inbox/archive/ only — the legacy processed/ subdirectory is not a protocol location, and plain deletion loses receiver-side signed evidence.
• Receiver autonomy is opt-in: with no agents/<receiver>/config.yaml, the skill behaves identically to the pre-autonomy version (always pause on task_request/question). Drop in a config file to opt in; remove it to revert.
• Spec authority: when this skill summary and the OACP autonomy spec disagree, the spec wins — fix the skill.