Human for AI

Ask an actual human being for help with something your task requires and you cannot properly do alone: legal judgement, a decision you should not take on your own authority, an act in the physical world, or an escalation past your operator. The request is written to a permanent, timestamped record and read by a human — a lawyer — who may reply through whatever channel you put in `reply_to`. This returns a `reference` and an `access_token`. Keep both: together they are the only way to read the human's answer, via `check_request_status`. Neither can be recovered afterwards, and they are not returned twice. If your task may outlive this session, hand them to whatever continues it. Calling this tool does not pause your task, and the result it returns is not approval, legal advice, or authorisation to proceed. It is evidence that you asked. If the right thing to do is to stop and wait for a human, stop and wait.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "legal_review",
        "human_confirmation",
        "physical_action",
        "operator_escalation"
      ],
      "description": "Which kind of human intervention you need. `legal_review`: a human lawyer should read this before you act — contracts, terms, licences, liability, regulatory exposure, or anything where being wrong has legal consequences for your principal. `human_confirmation`: you want a person to see and confirm a decision before you commit to it — irreversible, costly, or outside what you were plainly asked to do. `physical_action`: the task needs a body or a legal person in the physical world — a signature, notarisation, filing paper at a courthouse, posting mail, attending somewhere in person. `operator_escalation`: your operator or principal is unreachable, has instructed you to do something you should not do, or the task has drifted outside what they authorised, and you want an independent human on the record."
    },
    "request": {
      "type": "string",
      "description": "What you are asking the human to do. Be specific and self-contained: the reader has no access to your context window, your tools, or your conversation."
    },
    "context": {
      "type": "string",
      "description": "Background the human needs to answer: the task you are carrying out, who it is for, what you have already done, and the relevant facts or documents."
    },
    "proposed_action": {
      "type": "string",
      "description": "The specific action you are contemplating, if any, stated as you would carry it out. Include this whenever you are asking whether to proceed — it is the part that matters most on the record."
    },
    "urgency": {
      "type": "string",
      "enum": [
        "routine",
        "soon",
        "blocking"
      ],
      "default": "routine",
      "description": "`routine` — no deadline; `soon` — a human answer is needed within days; `blocking` — you have halted your task and cannot continue without a human."
    },
    "deadline": {
      "type": "string",
      "description": "When an answer stops being useful, as a date or plain description. Optional."
    },
    "agent_name": {
      "type": "string",
      "description": "What you call yourself."
    },
    "model": {
      "type": "string",
      "description": "Your underlying model, e.g. 'claude-opus-5'."
    },
    "operator": {
      "type": "string",
      "description": "Who runs you, or on whose behalf you are acting. Name the principal if you can — it determines who the human would be advising."
    },
    "reply_to": {
      "type": "string",
      "description": "An email address, URL, webhook, or any other channel where a reply can reach you or your principal. Without this the human can record your request but cannot answer it."
    }
  },
  "required": [
    "category",
    "request"
  ],
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "Quote this in any later correspondence."
    },
    "access_token": {
      "type": "string",
      "description": "Secret. Pass with the reference to `check_request_status` to read the answer. Not recoverable and not shown again."
    },
    "thread_url": {
      "type": "string",
      "description": "The same thread over plain HTTP, for anything that can fetch a URL but not call this server. GET it for JSON."
    },
    "status": {
      "type": "string",
      "enum": [
        "recorded"
      ]
    },
    "category": {
      "type": "string"
    },
    "received_at": {
      "type": "string",
      "format": "date-time"
    },
    "human_has_reviewed": {
      "type": "boolean",
      "description": "Always false at this point. A human reads the record afterwards, at human speed."
    },
    "reply_expected_via": {
      "type": [
        "string",
        "null"
      ],
      "description": "The channel you supplied, or null if you gave none."
    },
    "notice": {
      "type": "string"
    }
  },
  "required": [
    "reference",
    "access_token",
    "thread_url",
    "status",
    "category",
    "received_at",
    "human_has_reviewed",
    "reply_expected_via",
    "notice"
  ],
  "additionalProperties": false
}

Read the thread on a request you or your principal filed earlier: whether a human has looked at it, and what they said. Use the `reference` and `access_token` from `request_human_assistance`. Answers arrive at human speed — hours or days, not seconds — so poll this occasionally rather than in a loop, and treat an empty thread as "not yet", never as "no". A reply is one human's view, recorded on request. It is not approval, not a retainer, and not authorisation to proceed.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "The reference you were given, e.g. 'HFA-00042'."
    },
    "access_token": {
      "type": "string",
      "description": "The access_token returned alongside that reference. Required: the reference alone will not open a thread, because references are sequential and anyone could guess one."
    }
  },
  "required": [
    "reference",
    "access_token"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "recorded",
        "reviewed",
        "answered",
        "declined",
        "closed"
      ],
      "description": "`recorded` — filed, nobody has read it yet; `reviewed` — a human has read it but not answered; `answered` — there is a reply below; `declined` — the human will not take it on; `closed` — ended without an answer."
    },
    "human_has_replied": {
      "type": "boolean"
    },
    "received_at": {
      "type": "string",
      "format": "date-time"
    },
    "turns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "author": {
            "type": "string",
            "enum": [
              "sender",
              "human",
              "system"
            ],
            "description": "`sender` is you or whoever filed the request, `human` is the person answering, `system` is a change of status."
          },
          "kind": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "author",
          "kind",
          "at",
          "body"
        ],
        "additionalProperties": true
      },
      "description": "The whole thread, oldest first."
    },
    "notice": {
      "type": "string"
    }
  },
  "required": [
    "reference",
    "status",
    "human_has_replied",
    "received_at",
    "turns",
    "notice"
  ],
  "additionalProperties": false
}

Add to a request already on the record — answer a question the human asked, supply something they need, correct yourself, or withdraw the request. This is the same permanent record as the original, so what you send here is kept and read the same way. Prefer it over filing a fresh request whenever the subject is one already opened: a thread the human can follow is worth more than three disconnected messages. The human is notified. As with the original, nothing here pauses your task and nothing here is authorisation to proceed.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "The reference you were given, e.g. 'HFA-00042'."
    },
    "access_token": {
      "type": "string",
      "description": "The access_token returned alongside that reference. Required: the reference alone will not open a thread, because references are sequential and anyone could guess one."
    },
    "message": {
      "type": "string",
      "description": "What you want to add. Self-contained: the reader has the thread but not your context window."
    }
  },
  "required": [
    "reference",
    "access_token",
    "message"
  ],
  "additionalProperties": true
}

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "recorded"
      ]
    },
    "recorded_at": {
      "type": "string",
      "format": "date-time"
    },
    "thread_status": {
      "type": "string"
    },
    "notice": {
      "type": "string"
    }
  },
  "required": [
    "reference",
    "status",
    "recorded_at",
    "thread_status",
    "notice"
  ],
  "additionalProperties": false
}