{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.connectsoft.ai/reference/schemas/tool-invocation.schema.json",
  "title": "Tool invocation and receipt (tool-invocation-v1, tool-receipt-v1)",
  "description": "Every tool call passes the governed executor (GW-05, BC-08, ADR-0022). The request carries scope, the policy decision and an idempotency key; the receipt records the effect, including uncertain outcomes.",
  "$defs": {
    "ToolInvocation": {
      "type": "object",
      "required": ["invocationId", "toolId", "schemaVersion", "scope", "runId", "stepId", "attemptId", "sideEffectClass", "idempotencyKey", "arguments", "argumentsHash", "policyDecision"],
      "additionalProperties": false,
      "properties": {
        "invocationId": { "type": "string", "format": "uuid" },
        "toolId": { "type": "string" },
        "schemaVersion": { "type": "string" },
        "mcpServerId": { "type": "string" },
        "scope": { "$ref": "execution-scope.schema.json" },
        "runId": { "type": "string", "format": "uuid" },
        "stepId": { "type": "string", "format": "uuid" },
        "attemptId": { "type": "string", "format": "uuid" },
        "agentId": { "type": "string" },
        "sideEffectClass": { "enum": ["read", "sandbox", "shared-write", "external", "production", "publication", "spend"] },
        "idempotencyKey": { "type": "string", "description": "Unique per scope + tool + operation; same key and same argumentsHash returns the prior receipt." },
        "arguments": { "type": "object" },
        "argumentsHash": { "type": "string" },
        "policyDecision": { "$ref": "policy-decision.schema.json" },
        "approvalId": { "type": "string", "format": "uuid", "description": "Required when sideEffectClass is shared-write or above (D21)." },
        "timeoutSeconds": { "type": "integer" },
        "sandbox": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "egressProfile": { "type": "string" } } }
      }
    },
    "ToolReceipt": {
      "type": "object",
      "required": ["invocationId", "status", "startedAt", "receiptHash"],
      "additionalProperties": false,
      "properties": {
        "invocationId": { "type": "string", "format": "uuid" },
        "status": { "enum": ["Succeeded", "Failed", "Denied", "TimedOut", "Uncertain"] },
        "startedAt": { "type": "string", "format": "date-time" },
        "finishedAt": { "type": "string", "format": "date-time" },
        "effect": {
          "type": "object",
          "description": "What happened in the world; required for side-effecting classes.",
          "properties": { "kind": { "type": "string" }, "externalReference": { "type": "string", "description": "e.g. PR URL, deployment id" }, "reversible": { "type": "boolean" }, "effectHash": { "type": "string" } }
        },
        "resultRef": { "type": "string", "description": "Artifact reference holding the (classified) result; results are never inlined into events." },
        "sanitized": { "type": "boolean", "description": "Result passed the untrusted-content sanitizer (trust tier: tool result)." },
        "usage": { "type": "object", "properties": { "durationMs": { "type": "integer" }, "bytesIn": { "type": "integer" }, "bytesOut": { "type": "integer" } } },
        "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } },
        "receiptHash": { "type": "string" }
      }
    }
  },
  "oneOf": [{ "$ref": "#/$defs/ToolInvocation" }, { "$ref": "#/$defs/ToolReceipt" }]
}