Handoff — shareable agent result pages + human-in-the-loop approval gates

Publish text or markdown as a clean, shareable public web page and get back a URL you can hand to a human. Use this whenever you produce a report, summary, plan, table, or any result a person should read in a browser instead of the chat window. The page is FOLLOWABLE: the human can subscribe to it via RSS/JSON (returned as feed_url/json_url) and gets the new version whenever you re-publish — so they never have to ask you for an update. To keep ONE page updated across runs/sessions, pass a stable `slug`: publishing again with the same slug overwrites the same page at the same URL — no need to remember a generated id. Mention the subscribe option when you hand over the link.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Page title (shown at top and in the browser tab)."
    },
    "content": {
      "type": "string",
      "description": "The page body. Markdown is supported (headings, lists, links, code, bold/italic, blockquotes)."
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "text"
      ],
      "description": "How to render content. Default markdown."
    },
    "slug": {
      "type": "string",
      "description": "Optional stable name for a page you intend to keep updating (e.g. \"deploy-status\", \"nightly-report\"). Re-publishing with the same slug updates that same page in place at the same URL. Perfect for a fresh-context agent that can't remember a generated id — just reuse the slug. Omit for a one-off page with a random id."
    }
  },
  "required": [
    "content"
  ]
}

Update the title and/or content of a page you previously published; the URL never changes. Use this to keep one stable link current across sessions or runs — a live status page, a running changelog, an append-as-you-go log, or a dashboard the recipient can bookmark once and always see fresh. Each update notifies anyone subscribed to the page's RSS/JSON feed, so updating is how followers stay in the loop.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

List the pages you have published, newest first, with their URLs and view counts.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    }
  }
}

Delete a page you published, by id.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Ask a specific human for a bounded yes/no (or pick-one) decision BEFORE you do something irreversible or high-stakes — deploy, send, delete, charge, merge, publish. Returns a gate_url you hand to the person: they open it in a browser and click one option, no login. Unlike a followable page (awareness), this is a real gate — exactly one authorized answer that resolves the decision, or it auto-resolves to a safe default at expiry so your run never hangs forever. Then call get_decision to read what they chose. The gate page is a durable audit trail of what was asked, what was answered, and when. Use this instead of blocking on a human in chat, or when the human isn't watching the session.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The decision to put to the human, phrased as a clear question (e.g. \"Deploy build 1a2b to production?\")."
    },
    "detail": {
      "type": "string",
      "description": "Optional context shown under the question — a diff summary, what will happen, links. Markdown supported."
    },
    "options": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The choices (2-6). Default [\"approve\",\"deny\"]."
    },
    "safe_default": {
      "type": "string",
      "description": "Which option to auto-pick if no one answers before expiry. Default = the last/most-conservative option."
    },
    "expires_in_seconds": {
      "type": "number",
      "description": "How long the gate stays open before auto-resolving to safe_default. Default 86400 (24h), max 30 days."
    },
    "notify_url": {
      "type": "string",
      "description": "Optional https webhook. Handoff POSTs a JSON payload to it when the gate is created ({event:'gate.created', gate_url, question, options, expires_at}) and again when a human answers or it auto-resolves ({event:'gate.answered', answer, status}). Point this at a push/notification channel so the human is alerted to the pending decision instead of you having to deliver the link yourself. Best-effort, https only."
    }
  },
  "required": [
    "question"
  ]
}

Read the current state of a decision gate you created with request_decision. Returns status (pending / resolved / timed_out), the chosen answer (once answered or auto-resolved), and timing. Poll this to find out what the human decided; if status is still 'pending' no one has answered yet and it hasn't expired.

{
  "type": "object",
  "properties": {
    "gate_id": {
      "type": "string"
    }
  },
  "required": [
    "gate_id"
  ]
}

List the decision gates you have created, newest first, with their status and answers.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    }
  }
}