AgentNotify
DemoGet started
Open contract · version 0.2 · public draft

A standard shape for “an agent needs you”.

Every agent framework invents its own way to say a person is required, so every notifier has to learn all of them. ARC is one transport-neutral JSON contract for that moment: what is being asked, what shape the answer takes, and how the answer gets back — without prescribing how any of it is carried, stored, or displayed.

Read the specification JSON Schema

AgentNotify defines ARC and is its first reference implementation. The contract does not depend on the product.

Agent
You

request.created

Run the staging migration? · kind: permission · awaiting: allow | deny

4

event types in the whole contract

6

request kinds

3

answer shapes an agent can ask for

What 0.2 added

0.1 could only say a person was needed.

It had no way to say what was being asked, and no way to carry back what the person said. 0.2 closes that loop, and replaces 0.1 rather than extending it.

An answer the request asks for
A created or updated request can declare that it is waiting, and for which shape: a permission, one of a bounded list of choices, or a short text.
An answer that comes back
response.submitted carries exactly one human answer to the producer, authorised by the request's digest and nonce.
Correlation that survives the hop
turn_id and native_request_id let a host adapter return an accepted answer into the very call that is blocking on it.
Stable conditions, not just events
A request key identifies one unresolved condition. Updates replace it rather than piling up, and resolution records why it closed.
Small enough to emit from a hook
Six required fields. A shell hook, a stdout adapter, an HTTP client, or a message bus can all produce it without a library.
First answer wins
A second answer to the same request is refused, not queued — so the desktop, the phone, and the terminal can all offer the choice safely.
Request kinds

Six kinds cover what agents actually interrupt you for.

The kind says why the agent stopped. Priority, routing, sound, and presentation are the consumer's policy, not the producer's — which is what lets one contract serve a toast, a phone, and a chat room at once.

When an agent should ask

information

Something happened you may want to know. No answer expected.

question

The agent is waiting for a choice or a short text before it continues.

permission

The agent wants to do something consequential and needs a yes or no.

blocked

Work cannot proceed until something outside the agent changes.

failure

An attempt failed in a way a person should see.

completion

The work finished, with the result in the payload.

Deliberately out of scope

What ARC does not try to be.

A contract that covers everything gets implemented by nobody. ARC 0.2 defines no agent telemetry, no model traces, no tool inputs or outputs, no attachments, no authentication, no discovery, no network transport, no broker storage, and no outbound delivery. It also does not define multi-select answers, or unsolicited messages from a person to an agent.

Full specification

request.created · abridged

{
  "arc_version": "0.2",
  "event_type": "request.created",
  "sender": { "id": "claude", "name": "Claude Code" },
  "context": { "project": "checkout-service" },
  "request": {
    "key": "migrate-staging",
    "kind": "permission",
    "title": "Run the staging migration?",
    "response": {
      "kind": "permission",
      "choices": [
        { "id": "allow", "label": "Allow" },
        { "id": "deny",  "label": "Deny"  }
      ]
    }
  }
}