@bluefly/openstandardagents 0.4.4 → 0.4.5

package/dist/spec/v0.4/agent.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://openstandardagents.org/schemas/v{{VERSION}}/agent.schema.json",
-  "title": "OSSA v{{VERSION}} Agent Manifest Schema",
-  "description": "Open Standard for Software Agents (OSSA) v{{VERSION}} - The Next OpenAPI for Software Agents. A specification standard (not a framework) that defines contracts/metadata for production agent systems.",
+  "$id": "https://openstandardagents.org/schemas/v0.4/agent.schema.json",
+  "title": "OSSA v0.4 Agent Manifest Schema",
+  "description": "Open Standard for Software Agents (OSSA) - The OpenAPI for Software Agents. A specification standard that defines contracts and metadata for production agent systems.",
   "type": "object",
   "required": [
     "apiVersion",
@@ -118,6 +118,9 @@
         },
         "kagent": {
           "$ref": "#/definitions/KagentExtension"
+        },
+        "drupal": {
+          "$ref": "#/definitions/DrupalExtension"
         }
       },
       "additionalProperties": true
@@ -208,11 +211,19 @@
   "definitions": {
     "CredentialSource": {
       "type": "object",
-      "required": ["type", "ref"],
+      "required": [
+        "type",
+        "ref"
+      ],
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["secretRef", "workloadIdentity", "external", "env"],
+          "enum": [
+            "secretRef",
+            "workloadIdentity",
+            "external",
+            "env"
+          ],
           "description": "Type of credential source"
         },
         "ref": {
@@ -221,7 +232,11 @@
         },
         "format": {
           "type": "string",
-          "enum": ["json", "text", "base64"],
+          "enum": [
+            "json",
+            "text",
+            "base64"
+          ],
           "description": "Format hint for the secret value"
         }
       },
@@ -230,16 +245,31 @@
     "Principal": {
       "type": "object",
       "description": "Abstract identity principal definition (v{{VERSION}})",
-      "required": ["category", "mode", "credentialSource", "policy"],
+      "required": [
+        "category",
+        "mode",
+        "credentialSource",
+        "policy"
+      ],
       "properties": {
         "category": {
           "type": "string",
-          "enum": ["scm", "cloud", "database", "service"],
+          "enum": [
+            "scm",
+            "cloud",
+            "database",
+            "service"
+          ],
           "description": "Abstract provider category"
         },
         "mode": {
           "type": "string",
-          "enum": ["app", "service_account", "user", "workload_identity"],
+          "enum": [
+            "app",
+            "service_account",
+            "user",
+            "workload_identity"
+          ],
           "description": "Mode of operation"
         },
         "credentialSource": {
@@ -247,19 +277,38 @@
         },
         "policy": {
           "type": "object",
-          "required": ["permissions"],
+          "required": [
+            "permissions"
+          ],
           "properties": {
             "permissions": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Abstract permission verbs"
             },
             "scope": {
               "type": "object",
               "properties": {
-                "resources": { "type": "array", "items": { "type": "string" } },
-                "paths": { "type": "array", "items": { "type": "string" } },
-                "namespaces": { "type": "array", "items": { "type": "string" } }
+                "resources": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "paths": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "namespaces": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
               },
               "additionalProperties": false
             }
@@ -272,12 +321,28 @@
             "rotationPolicy": {
               "type": "object",
               "properties": {
-                "type": { "type": "string", "enum": ["managed", "automatic", "manual"] },
-                "intervalDays": { "type": "integer" }
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "managed",
+                    "automatic",
+                    "manual"
+                  ]
+                },
+                "intervalDays": {
+                  "type": "integer"
+                }
               }
             },
-            "auditLogging": { "type": "boolean" },
-            "envBindings": { "type": "array", "items": { "type": "string" } }
+            "auditLogging": {
+              "type": "boolean"
+            },
+            "envBindings": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         }
       },
@@ -286,7 +351,11 @@
     "Adapter": {
       "type": "object",
       "description": "Platform-specific adapter configuration (v{{VERSION}})",
-      "required": ["type", "version", "config"],
+      "required": [
+        "type",
+        "version",
+        "config"
+      ],
       "properties": {
         "type": {
           "type": "string",
@@ -987,7 +1056,12 @@
                     },
                     "level": {
                       "type": "string",
-                      "enum": ["low", "medium", "high", "critical"],
+                      "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                      ],
                       "description": "Risk level derived from score"
                     },
                     "categories": {
@@ -1395,9 +1469,13 @@
             "bedrock",
             "pydantic-ai",
             "swarm",
+            "a2a",
+            "mcp-server",
+            "agent-sdk",
+            "adk",
             "custom"
           ],
-          "description": "Agent runtime platform (v0.4.4+). Specifies which platform/framework will execute this agent. Used by exporters to generate platform-specific code and by runtime systems to select appropriate adapter."
+          "description": "Agent runtime platform (v0.4.4+). Specifies which platform/framework will execute this agent. Includes protocol-based types: a2a (Agent-to-Agent protocol), mcp-server (MCP tool server), agent-sdk (OpenAI/Anthropic Agent SDK), adk (Google Agent Development Kit)."
         },
         "agentKind": {
           "type": "string",
@@ -1414,9 +1492,13 @@
             "monitor",
             "analyst",
             "researcher",
-            "specialist"
+            "specialist",
+            "team-lead",
+            "teammate",
+            "subagent",
+            "debugger"
           ],
-          "description": "Agent functional role (v0.4.4+). Describes WHAT the agent does in the system. Used for intelligent routing, task assignment, and multi-agent orchestration."
+          "description": "Agent functional role (v0.4.4+). Describes WHAT the agent does in the system. Includes multi-agent roles: team-lead (orchestrates team), teammate (independent peer worker), subagent (scoped worker reporting to parent), debugger (hypothesis-testing investigator)."
         },
         "agentArchitecture": {
           "type": "object",
@@ -1431,9 +1513,10 @@
                 "graph",
                 "hierarchical",
                 "reactive",
-                "cognitive"
+                "cognitive",
+                "lead-teammate"
               ],
-              "description": "Architecture pattern: single (one agentic loop), swarm (multi-agent with handoffs), pipeline (sequential chain), graph (DAG workflow), hierarchical (manager/worker), reactive (event-driven), cognitive (multi-step reasoning)"
+              "description": "Architecture pattern: single (one agentic loop), swarm (multi-agent with handoffs), pipeline (sequential chain), graph (DAG workflow), hierarchical (manager/worker), reactive (event-driven), cognitive (multi-step reasoning), lead-teammate (Claude Code teams pattern with shared task list and mailbox)"
             },
             "capabilities": {
               "type": "array",
@@ -1460,7 +1543,7 @@
             },
             "coordination": {
               "type": "object",
-              "description": "Multi-agent coordination configuration (for swarm/hierarchical patterns)",
+              "description": "Multi-agent coordination configuration. Enhanced in v0.4.5 with Claude Code Agent Teams primitives.",
               "properties": {
                 "handoffStrategy": {
                   "type": "string",
@@ -1474,14 +1557,78 @@
                 },
                 "leaderAgent": {
                   "type": "string",
-                  "description": "Name of leader/orchestrator agent (for hierarchical pattern)"
+                  "description": "Name of the entry point / team lead agent"
                 },
                 "maxDepth": {
                   "type": "integer",
                   "minimum": 1,
-                  "maximum": 20,
-                  "default": 5,
-                  "description": "Maximum orchestration depth (number of handoffs)"
+                  "maximum": 10,
+                  "default": 3,
+                  "description": "Maximum delegation depth (lead → teammate → subagent)"
+                },
+                "teamModel": {
+                  "type": "string",
+                  "enum": [
+                    "lead-teammate",
+                    "parent-child",
+                    "peer-to-peer",
+                    "hub-spoke",
+                    "hierarchical",
+                    "swarm"
+                  ],
+                  "default": "lead-teammate",
+                  "description": "Team coordination model. lead-teammate = Claude Code pattern with shared task list and mailbox."
+                },
+                "communicationPattern": {
+                  "type": "string",
+                  "enum": [
+                    "task-list",
+                    "mailbox",
+                    "broadcast",
+                    "shared-file",
+                    "direct-message"
+                  ],
+                  "default": "mailbox",
+                  "description": "Primary inter-agent communication mechanism. mailbox = async inbox-based (Claude Code default)."
+                },
+                "taskCoordination": {
+                  "type": "string",
+                  "enum": [
+                    "shared-list",
+                    "assigned",
+                    "self-claim",
+                    "sequential",
+                    "parallel",
+                    "dependency-wave"
+                  ],
+                  "default": "self-claim",
+                  "description": "How tasks are distributed. self-claim = teammates pick from shared list (Claude Code default)."
+                },
+                "conflictResolution": {
+                  "type": "string",
+                  "enum": [
+                    "leader-decides",
+                    "vote",
+                    "round-robin",
+                    "last-writer-wins"
+                  ],
+                  "default": "leader-decides",
+                  "description": "How conflicts between agents are resolved"
+                },
+                "taskPersistence": {
+                  "type": "string",
+                  "enum": [
+                    "file-backed",
+                    "in-memory",
+                    "database"
+                  ],
+                  "default": "file-backed",
+                  "description": "How task state is persisted. file-backed = JSON files on disk (Claude Code pattern)."
+                },
+                "dependencyTracking": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Whether tasks can declare dependencies. Blocked tasks auto-unblock when dependencies complete."
                 }
               },
               "additionalProperties": false
@@ -1518,6 +1665,10 @@
             }
           },
           "additionalProperties": false
+        },
+        "idCard": {
+          "$ref": "#/definitions/AgentIdCard",
+          "description": "Agent ID Card with nickname, provenance, and immutable audit trail (v0.4.5+)"
         }
       },
       "additionalProperties": false
@@ -2113,10 +2264,242 @@
         },
         "checkpointing": {
           "$ref": "#/definitions/CheckpointConfiguration"
+        },
+        "team": {
+          "$ref": "#/definitions/TeamDefinition",
+          "description": "Multi-agent team definition (v0.4.5+). Modeled after Claude Code Agent Teams: a lead orchestrates teammates who work independently with shared task list and mailbox communication."
+        },
+        "subagents": {
+          "type": "array",
+          "description": "Subagent definitions for parent-child delegation (v0.4.5+). Unlike team members, subagents report results to parent only — no peer communication.",
+          "items": {
+            "$ref": "#/definitions/SubagentDefinition"
+          }
         }
       },
       "additionalProperties": true
     },
+    "TeamDefinition": {
+      "type": "object",
+      "description": "Multi-agent team configuration with lead-teammate or peer-to-peer patterns (v0.4.5+)",
+      "required": ["model", "members"],
+      "properties": {
+        "model": {
+          "type": "string",
+          "enum": [
+            "lead-teammate",
+            "peer-to-peer",
+            "hierarchical",
+            "swarm"
+          ],
+          "description": "Team coordination model"
+        },
+        "lead": {
+          "type": "string",
+          "description": "Name of the lead agent (required for lead-teammate model)"
+        },
+        "delegateMode": {
+          "type": "string",
+          "enum": [
+            "task-list",
+            "round-robin",
+            "capability-match",
+            "load-balance"
+          ],
+          "default": "task-list",
+          "description": "How the lead delegates tasks to teammates"
+        },
+        "members": {
+          "type": "array",
+          "description": "Team member definitions",
+          "items": {
+            "type": "object",
+            "required": ["name", "role"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_-]*$",
+                "description": "Member name (kebab-case identifier)"
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "team-lead",
+                  "teammate",
+                  "subagent",
+                  "reviewer",
+                  "specialist"
+                ],
+                "description": "Member's role kind in the team"
+              },
+              "role": {
+                "type": "string",
+                "description": "System prompt / role description for this member"
+              },
+              "model": {
+                "type": "string",
+                "description": "LLM model to use for this member (overrides team default)"
+              },
+              "tools": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Tool names this member can access"
+              },
+              "skills": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Skill references this member has"
+              },
+              "contextIsolation": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether this member runs in an isolated context"
+              },
+              "maxTokenBudget": {
+                "type": "integer",
+                "minimum": 1000,
+                "description": "Maximum token budget for this member per task"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "taskList": {
+          "type": "object",
+          "description": "Task list configuration for the team",
+          "properties": {
+            "persistence": {
+              "type": "string",
+              "enum": ["file-backed", "in-memory", "database"],
+              "default": "file-backed",
+              "description": "How the task list is persisted"
+            },
+            "format": {
+              "type": "string",
+              "enum": ["markdown", "json", "yaml"],
+              "default": "markdown",
+              "description": "Format of the task list file"
+            },
+            "path": {
+              "type": "string",
+              "description": "File path for file-backed persistence"
+            },
+            "dependencyTracking": {
+              "type": "boolean",
+              "default": true,
+              "description": "Track dependencies between tasks for wave execution"
+            }
+          },
+          "additionalProperties": false
+        },
+        "communication": {
+          "type": "object",
+          "description": "How team members communicate",
+          "properties": {
+            "channel": {
+              "type": "string",
+              "enum": [
+                "task-list",
+                "mailbox",
+                "shared-file",
+                "direct-message",
+                "broadcast"
+              ],
+              "default": "task-list",
+              "description": "Primary communication channel"
+            },
+            "consensus": {
+              "type": "string",
+              "enum": [
+                "leader-decides",
+                "vote",
+                "round-robin"
+              ],
+              "default": "leader-decides",
+              "description": "How team decisions are made"
+            }
+          },
+          "additionalProperties": false
+        },
+        "deployment": {
+          "type": "object",
+          "description": "How the team is deployed",
+          "properties": {
+            "backend": {
+              "type": "string",
+              "enum": [
+                "in-process",
+                "split-pane",
+                "distributed",
+                "kubernetes"
+              ],
+              "default": "in-process",
+              "description": "Deployment backend for team execution"
+            },
+            "maxConcurrency": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 5,
+              "description": "Maximum concurrent team members"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "SubagentDefinition": {
+      "type": "object",
+      "description": "Child agent that can be spawned by a parent agent for task delegation (v0.4.5+)",
+      "required": ["name", "role"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "description": "Subagent name (kebab-case identifier)"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "subagent",
+            "worker",
+            "specialist",
+            "reviewer",
+            "debugger"
+          ],
+          "description": "Subagent's functional role"
+        },
+        "role": {
+          "type": "string",
+          "description": "System prompt / role description"
+        },
+        "model": {
+          "type": "string",
+          "description": "LLM model to use (overrides parent default)"
+        },
+        "tools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tool names this subagent can access"
+        },
+        "contextIsolation": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether this subagent runs in isolated context"
+        },
+        "reportTo": {
+          "type": "string",
+          "description": "Parent agent name to report results to"
+        },
+        "maxTokenBudget": {
+          "type": "integer",
+          "minimum": 1000,
+          "description": "Maximum token budget for this subagent per invocation"
+        }
+      },
+      "additionalProperties": false
+    },
     "WorkflowSpec": {
       "type": "object",
       "description": "Specification for workflow composition (kind: Workflow) - composes Tasks and Agents into executable pipelines",
@@ -15313,7 +15696,13 @@
       "properties": {
         "stage": {
           "type": "string",
-          "enum": ["embryonic", "juvenile", "mature", "senior", "retired"],
+          "enum": [
+            "embryonic",
+            "juvenile",
+            "mature",
+            "senior",
+            "retired"
+          ],
           "description": "Current lifecycle stage"
         },
         "birth": {
@@ -15341,7 +15730,12 @@
         },
         "birth_type": {
           "type": "string",
-          "enum": ["created", "bred", "cloned", "forked"],
+          "enum": [
+            "created",
+            "bred",
+            "cloned",
+            "forked"
+          ],
           "description": "How the agent came into existence"
         },
         "creator_did": {
@@ -15399,7 +15793,17 @@
       "properties": {
         "current_role": {
           "type": "string",
-          "enum": ["tech-lead", "backend", "frontend", "devops", "qa", "security", "pm", "researcher", "analyst"],
+          "enum": [
+            "tech-lead",
+            "backend",
+            "frontend",
+            "devops",
+            "qa",
+            "security",
+            "pm",
+            "researcher",
+            "analyst"
+          ],
           "description": "Current role in the team"
         },
         "promotions": {
@@ -15414,7 +15818,11 @@
     "Promotion": {
       "type": "object",
       "description": "Promotion event",
-      "required": ["from_role", "to_role", "timestamp"],
+      "required": [
+        "from_role",
+        "to_role",
+        "timestamp"
+      ],
       "properties": {
         "from_role": {
           "type": "string"
@@ -15494,7 +15902,12 @@
         },
         "swarm_type": {
           "type": "string",
-          "enum": ["exploration", "optimization", "problem-solving", "defense"],
+          "enum": [
+            "exploration",
+            "optimization",
+            "problem-solving",
+            "defense"
+          ],
           "description": "Type of swarm behavior"
         },
         "parameters": {
@@ -15577,7 +15990,13 @@
                   },
                   "type": {
                     "type": "string",
-                    "enum": ["concept", "skill", "experience", "pattern", "heuristic"]
+                    "enum": [
+                      "concept",
+                      "skill",
+                      "experience",
+                      "pattern",
+                      "heuristic"
+                    ]
                   },
                   "data": {
                     "type": "object"
@@ -15598,7 +16017,12 @@
                   },
                   "relationship": {
                     "type": "string",
-                    "enum": ["relates_to", "depends_on", "derives_from", "conflicts_with"]
+                    "enum": [
+                      "relates_to",
+                      "depends_on",
+                      "derives_from",
+                      "conflicts_with"
+                    ]
                   },
                   "weight": {
                     "type": "number",
@@ -15737,7 +16161,10 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["checkpoint_id", "timestamp"],
+            "required": [
+              "checkpoint_id",
+              "timestamp"
+            ],
             "properties": {
               "checkpoint_id": {
                 "type": "string"
@@ -15851,7 +16278,11 @@
                   "new_value": {},
                   "change_type": {
                     "type": "string",
-                    "enum": ["added", "removed", "modified"]
+                    "enum": [
+                      "added",
+                      "removed",
+                      "modified"
+                    ]
                   }
                 }
               }
@@ -15875,7 +16306,13 @@
             },
             "analysis_frequency": {
               "type": "string",
-              "enum": ["per-task", "hourly", "daily", "weekly", "on-demand"],
+              "enum": [
+                "per-task",
+                "hourly",
+                "daily",
+                "weekly",
+                "on-demand"
+              ],
               "default": "daily"
             },
             "metrics_tracked": {
@@ -15895,7 +16332,11 @@
                   },
                   "trend": {
                     "type": "string",
-                    "enum": ["improving", "stable", "declining"]
+                    "enum": [
+                      "improving",
+                      "stable",
+                      "declining"
+                    ]
                   },
                   "change_rate": {
                     "type": "number"
@@ -15913,7 +16354,12 @@
                   },
                   "severity": {
                     "type": "string",
-                    "enum": ["low", "medium", "high", "critical"]
+                    "enum": [
+                      "low",
+                      "medium",
+                      "high",
+                      "critical"
+                    ]
                   },
                   "suggested_fix": {
                     "type": "string"
@@ -15948,7 +16394,13 @@
                   },
                   "modification_type": {
                     "type": "string",
-                    "enum": ["prompt-update", "parameter-tuning", "capability-addition", "capability-removal", "workflow-change"]
+                    "enum": [
+                      "prompt-update",
+                      "parameter-tuning",
+                      "capability-addition",
+                      "capability-removal",
+                      "workflow-change"
+                    ]
                   },
                   "description": {
                     "type": "string"
@@ -15967,7 +16419,11 @@
                       },
                       "performance_impact": {
                         "type": "string",
-                        "enum": ["positive", "neutral", "negative"]
+                        "enum": [
+                          "positive",
+                          "neutral",
+                          "negative"
+                        ]
                       },
                       "rollback_checkpoint": {
                         "type": "string",
@@ -16018,7 +16474,13 @@
             },
             "teaching_style": {
               "type": "string",
-              "enum": ["demonstration", "explanation", "guided-practice", "assessment", "mixed"],
+              "enum": [
+                "demonstration",
+                "explanation",
+                "guided-practice",
+                "assessment",
+                "mixed"
+              ],
               "default": "mixed"
             },
             "students": {
@@ -16075,7 +16537,13 @@
           "properties": {
             "preferred_learning_style": {
               "type": "string",
-              "enum": ["experiential", "observational", "instructional", "collaborative", "self-directed"]
+              "enum": [
+                "experiential",
+                "observational",
+                "instructional",
+                "collaborative",
+                "self-directed"
+              ]
             },
             "adaptation_rate": {
               "type": "number",
@@ -16085,13 +16553,305 @@
             },
             "knowledge_consolidation": {
               "type": "string",
-              "enum": ["immediate", "periodic", "on-demand"],
+              "enum": [
+                "immediate",
+                "periodic",
+                "on-demand"
+              ],
               "description": "When agent consolidates learned knowledge"
             }
           }
         }
       },
       "additionalProperties": false
+    },
+    "AgentIdCard": {
+      "type": "object",
+      "description": "Agent ID Card - human-friendly identity with immutable provenance tracking (v0.4.5+)",
+      "properties": {
+        "nickname": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32,
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
+          "description": "Short callsign for the agent (e.g., 'Scout', 'Drupa', 'Sentinel'). Used in CLI output, logs, and human communication."
+        },
+        "displayName": {
+          "type": "string",
+          "maxLength": 128,
+          "description": "Full human-readable name (e.g., 'Drupal Content Review Agent')"
+        },
+        "avatar": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to agent avatar/icon image"
+        },
+        "registryId": {
+          "type": "string",
+          "pattern": "^ossa://[a-z0-9-]+/[a-z0-9-]+(@[0-9]+\\.[0-9]+\\.[0-9]+)?$",
+          "description": "OSSA registry URI (e.g., 'ossa://blueflyio/drupal-reviewer@0.4.5')"
+        },
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 content hash of the current manifest (recomputed on every change)"
+        },
+        "birthHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of the initial manifest at creation time (immutable, never changes)"
+        },
+        "provenance": {
+          "$ref": "#/definitions/AgentProvenance",
+          "description": "Immutable creation and lineage tracking"
+        },
+        "auditTrail": {
+          "$ref": "#/definitions/AgentAuditTrail",
+          "description": "Append-only Merkle-chained mutation log for immutable tracing"
+        }
+      },
+      "additionalProperties": false
+    },
+    "AgentProvenance": {
+      "type": "object",
+      "description": "Immutable provenance chain tracking agent creation and lineage",
+      "properties": {
+        "createdBy": {
+          "type": "string",
+          "description": "DID or identifier of the creator (agent or human). e.g., 'did:ossa:blueflyio:thomas'"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of agent creation (immutable)"
+        },
+        "createdWith": {
+          "type": "string",
+          "description": "Tool/CLI version used to create the agent (e.g., 'ossa-cli@0.4.5')"
+        },
+        "lineage": {
+          "type": "array",
+          "description": "Fork/clone ancestry chain (append-only)",
+          "items": {
+            "type": "object",
+            "required": [
+              "ancestor",
+              "relationship",
+              "timestamp"
+            ],
+            "properties": {
+              "ancestor": {
+                "type": "string",
+                "description": "Registry ID or DID of the ancestor agent"
+              },
+              "relationship": {
+                "type": "string",
+                "enum": [
+                  "forked-from",
+                  "cloned-from",
+                  "derived-from",
+                  "inspired-by",
+                  "upgraded-from"
+                ],
+                "description": "Type of lineage relationship"
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When this lineage event occurred"
+              },
+              "commitHash": {
+                "type": "string",
+                "description": "Git commit hash at the time of the lineage event"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "AgentAuditTrail": {
+      "type": "object",
+      "description": "Append-only Merkle-chained audit trail for immutable tracing of all agent mutations",
+      "properties": {
+        "hashAlgorithm": {
+          "type": "string",
+          "enum": [
+            "sha256",
+            "sha384",
+            "sha512"
+          ],
+          "default": "sha256",
+          "description": "Hash algorithm used for chain integrity"
+        },
+        "chainType": {
+          "type": "string",
+          "enum": [
+            "merkle",
+            "linear",
+            "signed"
+          ],
+          "default": "linear",
+          "description": "Chain type: merkle (tree verification), linear (simple chain), signed (PKI signatures per entry)"
+        },
+        "genesisHash": {
+          "type": "string",
+          "pattern": "^sha(256|384|512):[a-f0-9]+$",
+          "description": "Hash of the first entry (genesis block). Used to verify chain integrity from the beginning."
+        },
+        "entries": {
+          "type": "array",
+          "description": "Append-only ordered list of audit events. Each entry links to the previous via prevHash.",
+          "items": {
+            "$ref": "#/definitions/AuditTrailEntry"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "AuditTrailEntry": {
+      "type": "object",
+      "description": "Single immutable entry in the agent audit trail",
+      "required": [
+        "seq",
+        "action",
+        "timestamp",
+        "actor",
+        "hash"
+      ],
+      "properties": {
+        "seq": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Monotonically increasing sequence number (0 = genesis)"
+        },
+        "action": {
+          "type": "string",
+          "enum": [
+            "created",
+            "capability-added",
+            "capability-removed",
+            "tool-added",
+            "tool-removed",
+            "version-bumped",
+            "config-changed",
+            "ownership-transferred",
+            "access-tier-changed",
+            "forked",
+            "retired",
+            "reactivated",
+            "nickname-changed",
+            "custom"
+          ],
+          "description": "Type of mutation that occurred"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of the event"
+        },
+        "actor": {
+          "type": "string",
+          "description": "DID or identifier of who/what performed the action"
+        },
+        "hash": {
+          "type": "string",
+          "pattern": "^sha(256|384|512):[a-f0-9]+$",
+          "description": "Hash of this entry's content (seq + action + timestamp + actor + details + prevHash)"
+        },
+        "prevHash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha(256|384|512):[a-f0-9]+$",
+          "description": "Hash of the previous entry (null for genesis entry seq=0). Creates the immutable chain."
+        },
+        "details": {
+          "type": "object",
+          "description": "Action-specific details (what changed)",
+          "properties": {
+            "field": {
+              "type": "string",
+              "description": "JSON path of the changed field (e.g., 'spec.tools')"
+            },
+            "oldValue": {
+              "description": "Previous value (for change tracking)"
+            },
+            "newValue": {
+              "description": "New value (for change tracking)"
+            },
+            "reason": {
+              "type": "string",
+              "description": "Human-readable reason for the change"
+            },
+            "commitHash": {
+              "type": "string",
+              "description": "Git commit hash associated with this change"
+            }
+          },
+          "additionalProperties": true
+        },
+        "signature": {
+          "type": "string",
+          "description": "Ed25519 signature of the hash (required when chainType is 'signed')"
+        }
+      },
+      "additionalProperties": false
+    },
+    "DrupalExtension": {
+      "type": "object",
+      "description": "Drupal CMS integration extension - maps OSSA agents to Drupal ai_agents module, Tool API, and ECA events",
+      "properties": {
+        "ai_agent_plugin": {
+          "type": "string",
+          "description": "Plugin ID for the Drupal ai_agents module",
+          "default": "ossa_agent"
+        },
+        "tools": {
+          "type": "array",
+          "description": "Drupal Tool API plugin IDs to grant this agent",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "eca_events": {
+          "type": "array",
+          "description": "ECA events this agent reacts to",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "permissions": {
+          "type": "array",
+          "description": "Drupal permissions required for this agent",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "content_types": {
+          "type": "array",
+          "description": "Drupal content types this agent operates on",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "uniqueItems": true
+        },
+        "views_displays": {
+          "type": "array",
+          "description": "Views displays to expose agent data",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
     }
   }
-}
+}