{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://zeroclaw.dev/schemas/handoff.json",
  "title": "AgentHandoff",
  "description": "Structured task delegation between agents. Every delegation uses this shape so messages stay debuggable. Free-form chat between agents is avoided.",
  "type": "object",
  "required": ["task_id", "from", "to", "goal", "definition_of_done"],
  "additionalProperties": false,
  "properties": {
    "task_id": {
      "type": "string",
      "description": "AOS task ID (e.g. AOS-1423). Ties all tool calls, logs and approvals together.",
      "pattern": "^AOS-\\d+$"
    },
    "from": {
      "type": "string",
      "description": "Agent name handing off (e.g. 'orchestrator', 'ads-lead').",
      "minLength": 1
    },
    "to": {
      "type": "string",
      "description": "Agent name receiving the task.",
      "minLength": 1
    },
    "goal": {
      "type": "string",
      "description": "One-sentence statement of what 'done' looks like, in business terms.",
      "minLength": 1
    },
    "inputs": {
      "type": "array",
      "description": "References to inputs the receiving agent can read (AOS IDs, asset folders, brief IDs).",
      "items": { "type": "string" }
    },
    "constraints": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "budget_eur": { "type": "number", "minimum": 0, "description": "Hard spend cap in EUR for this task. 0 = no spend allowed." },
        "max_tokens": { "type": "integer", "minimum": 0, "description": "Token cap for this task's agent calls." },
        "deadline": { "type": "string", "format": "date-time" },
        "autonomy": { "enum": ["L0", "L1", "L2"], "description": "Overrides the agent's default autonomy for this task. L3 not used initially." }
      }
    },
    "definition_of_done": {
      "type": "array",
      "description": "Checklist of concrete, verifiable outcomes. Empty array is invalid.",
      "minItems": 1,
      "items": { "type": "string" }
    },
    "output_format": {
      "enum": ["aos_deliverable", "report", "draft", "review_verdict", "data"],
      "description": "How the result must be shaped so the caller can consume it without re-parsing."
    },
    "needs_approval_for": {
      "type": "array",
      "description": "Specific actions in this task that MUST pause for human approval (spend, publish, send, revoke, delete, deploy...).",
      "items": { "type": "string" }
    },
    "context_refs": {
      "type": "array",
      "description": "Optional AOS records to load into context (client_id, project_id, contract_id).",
      "items": { "type": "string" }
    }
  }
}