agent-control-command-contract

name	agent-control-command-contract
description	Audit whether operator control verbs over live agent bodies — steer, interrupt, pause, kill, checkpoint, fork — are each modeled as a distinct claim with a real delivered/acknowledged/failed/expired/unsupported lifecycle, and whether command authorization reads authoritative lease/event state instead of a stale projection or UI state. Use when designing or reviewing a control panel's command contract, a daemon's control_commands schema, or a backend adapter's verb-support matrix before any control renders as clickable. NOT for designing DAG approval/gate routing UX (use human-gate-designer), worktree/file-lock coordination between concurrently running agents (use multi-agent-coordination), or swarm IPC/message-passing mechanics between agents (use swarm-invocation-designer).
license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Grep,Glob
metadata	{"category":"Agent & Orchestration","tags":["operator-control-panel","control-commands","agent-lifecycle","authorization","agent-harbor"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"human-gate-designer","reason":"A tool-gate approval/denial decision often precedes or follows a control command (e.g. deny then interrupt); this skill covers the command's delivery contract, not the approval UX around it."},{"skill":"multi-agent-coordination","reason":"Killing or interrupting a body that holds file claims needs coordination-aware cleanup; this skill only proves the control command itself is honestly modeled and authorized."},{"skill":"agent-identity-continuity-reputation","reason":"kill and fork both produce successor semantics — this skill's terminal-state contract should feed the identity map that decides what a successor inherits."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Agent Control Command Contract

Decide whether a set of operator controls over live agent bodies is safe to render as clickable, or whether it is collapsed verbs and stale-state authorization wearing a control panel.

Use This For

• Designing the verb set (steer, interrupt, pause, kill, checkpoint, fork) for an operator control panel so each verb is a distinct claim, not a shared "stop" button.
• Reviewing a daemon's control_commands schema for a complete delivered/acknowledged/failed/expired lifecycle per verb.
• Auditing whether command authorization reads authoritative lease/event state instead of the roster projection the UI already has in memory.
• Building an honest verb x backend support matrix so a backend that cannot perform a verb says unsupported instead of hanging, no-op'ing, or hiding the button.
• Preparing the control-command contract a live operator control panel (or the daemon behind it) must satisfy before "Interrupt," "Pause," "Kill," "Checkpoint," or "Fork" ships as a real button.

Do Not Use This For

• Designing DAG approval/gate routing UX — what to show a human reviewer and how their decision routes back into the DAG (human-gate-designer).
• Worktree isolation, file locking, or claims coordination between concurrently running agents (multi-agent-coordination).
• Swarm IPC mechanics, message-passing protocols, or invocation surfaces between agents (swarm-invocation-designer).

Contract Model

flowchart TD
  A[Enumerate verb set: steer/interrupt/pause/kill/checkpoint/fork] --> B[Assign terminal states per verb]
  B --> C[Enumerate backends: local, remote, hook-only, observed]
  C --> D{Backend supports this verb?}
  D -->|No| E["Matrix cell: unsupported terminal, hasDistinctTerminalStates true"]
  D -->|Yes| F["Matrix cell: full delivered/acknowledged/failed/expired lifecycle"]
  E --> G[Declare authorizationSource]
  F --> G
  G --> H{Source is authoritative-lease or authoritative-event?}
  H -->|No: cached-projection or ui-state| I[FAIL: command may authorize from stale truth]
  H -->|Yes| J[Run control_contract_audit.mjs]
  I --> J
  J --> K{pass: true?}
  K -->|No| L[Fix findings, re-run]
  K -->|Yes| M[Safe to render controls as clickable]
  L --> J

1. Enumerate the verb set explicitly. List steer, , , , , and (or whatever subset the product ships) as named entries — never a generic "control" or "stop" claim that stands in for several of them.