{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/tool-access-policy.json",
  "title": "ToolAccessPolicy",
  "description": "Tool catalog binding for an agent. Defines which tools an agent may call, under which purpose, with which secret-handling pattern, with which prohibited actions, and through which runtime enforcement point. Named in Chapter 13 in the context of Model Context Protocol (MCP) and similar tool-invocation standards.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "ToolAccessPolicy" },
    "metadata": { "$ref": "_common.json#/$defs/metadata" },
    "spec": {
      "type": "object",
      "required": ["agentContractRef", "allowedTools"],
      "properties": {
        "agentContractRef": {
          "type": "string",
          "description": "Reference to the AgentContract this policy binds to."
        },
        "allowedTools": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["toolId"],
            "properties": {
              "toolId": { "type": "string" },
              "purpose": { "type": "string" },
              "actions": {
                "type": "array",
                "items": { "type": "string" }
              },
              "rateLimit": {
                "type": "object",
                "properties": {
                  "perMinute": { "type": "integer", "minimum": 1 },
                  "perDay": { "type": "integer", "minimum": 1 }
                },
                "additionalProperties": true
              },
              "humanApprovalRequiredFor": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "additionalProperties": true
          }
        },
        "prohibitedTools": {
          "type": "array",
          "items": { "type": "string" }
        },
        "prohibitedActions": {
          "type": "array",
          "items": { "type": "string" }
        },
        "secretHandling": {
          "type": "object",
          "properties": {
            "pattern": {
              "type": "string",
              "examples": ["broker-injected", "ephemeral-token", "vault-fetched"]
            },
            "rotationDays": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": true
        },
        "enforcementPoint": {
          "type": "string",
          "description": "Where the policy is enforced at runtime (gateway, broker, agent runtime)."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}