Interfaces

Event Protocol

The JSON contract agents use when proposing moments, approvals, and wiki writes.

Event shape

{
  "kind": "moment",
  "urgency": "normal",
  "title": "Decision from planning review",
  "summary": "The team picked the menu bar review queue as the first agent proposal surface.",
  "detail": "Optional longer context for reviewers.",
  "actor": { "type": "agent", "name": "Codex" },
  "sourceRefs": [
    { "kind": "git", "label": "Repo", "ref": "git@github.com:company/app.git" },
    { "kind": "local_file", "label": "Spec", "ref": "docs/spec.md" }
  ],
  "privacy": {
    "containsCompanyData": true,
    "redaction": "none",
    "consent": "local_user_granted"
  },
  "idempotencyKey": "planning-review:2026-05-19",
  "artifacts": [
    {
      "kind": "markdown_body",
      "contentType": "text/markdown",
      "content": "## Decision\nUse the menu bar review queue first."
    }
  ]
}

Wiki write proposal

Use wiki_write when an agent proposes durable company knowledge. The write should be reviewable: include a path, content, source references, and a justification.

{
  "kind": "wiki_write",
  "urgency": "normal",
  "title": "Save planning decision",
  "summary": "The planning review selected the menu bar review queue as the first agent proposal surface.",
  "actor": { "type": "agent", "name": "Codex" },
  "sourceRefs": [
    { "kind": "git", "label": "Spec", "ref": "git@github.com:company/app.git#docs/spec.md" }
  ],
  "privacy": {
    "containsCompanyData": true,
    "consent": "local_user_granted"
  },
  "artifacts": [
    {
      "kind": "proposed_write",
      "contentType": "text/markdown",
      "content": "# Decision\nUse the menu bar review queue first.\n",
      "metadata": {
        "path": "wiki/decisions/menu-bar-review-queue.md",
        "message": "Save menu bar review decision",
        "justification": "Preserves an approved operating decision for future agents."
      }
    }
  ],
  "idempotencyKey": "planning-review:menu-bar-review-queue"
}

Event kinds

moment: An informational item worth saving or sharing after local approval.
approval: A proposal that needs a workspace-level approve or deny decision.
wiki_write: A proposed write to the company wiki, usually with a proposed_write artifact.
run: A report about an agent run, tool execution, or automation.
source_discovery: A local source or integration discovery event.

Source references

Use source references to explain where the event came from and to help local routing choose the right workspace.

local_file for local paths.
git for repos, remotes, branches, commits, and PR refs.
drive for Google Drive or similar document refs.
s3 for object storage.
app_db for application database objects.
url for web URLs.

Git refs

For commits and pull requests, use kind: "git". Do not invent custom kinds such as git_commit.

Privacy and consent

localOnly: True when the event should remain local and never leave the machine.
containsPersonalData: True when the payload includes personal information.
containsCompanyData: True when the payload includes workspace or customer context.
redaction: One of none, summary_only, or redacted.
consent: One of not_required, local_user_granted, workspace_policy_granted, or pending.

Inference metadata

Events should identify how a proposal was produced. This lets reviewers distinguish a local model, a user-controlled agent, workspace-approved inference, and managed platform inference.

none: No model generated the proposal.
local_model: Inference happened locally on the user's machine.
user_agent: The user's configured AI tool produced the proposal.
workspace_provider: A workspace-approved provider generated the proposal.
mos_cloud: The managed platform generated the proposal under workspace policy.