melchizedek-agents 1.0.3 → 1.1.0

package/config/agents/syndicate.schema.json

@@ -47,7 +47,7 @@
           }
         },
         "require_approval": {
-          "description": "Tools from this agent's `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on the orchestrator and on plan-dispatch routes.",
+          "description": "Tools from this agent's `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on any agent but one a workflow map node runs; inside a delegated subagent the pause reaches the caller through its open call (ADR 0110).",
           "type": "array",
           "items": {
             "type": "string",
@@ -156,7 +156,8 @@
             }
           },
           "additionalProperties": {},
-          "description": "Model generation config (@google/genai GenerateContentConfig). Do not set tools here."
+          "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
+          "deprecated": true
         },
         "reasoning": {
           "anyOf": [
@@ -187,13 +188,249 @@
           ],
           "description": "How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
         },
+        "sampling": {
+          "type": "object",
+          "properties": {
+            "temperature": {
+              "description": "Sampling temperature. Replaces generateContentConfig.temperature.",
+              "type": "number"
+            },
+            "top_p": {
+              "description": "Nucleus sampling. Replaces generateContentConfig.topP.",
+              "type": "number"
+            },
+            "max_output_tokens": {
+              "description": "Cap on the reply's tokens. Replaces generateContentConfig.maxOutputTokens.",
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "stop": {
+              "description": "Stop sequences. Replaces generateContentConfig.stopSequences.",
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false,
+          "description": "How this agent samples, on any provider (ADR 0115). Replaces the same keys under generateContentConfig; cannot be combined with them.",
+          "minProperties": 1
+        },
+        "output": {
+          "type": "object",
+          "properties": {
+            "schema": {
+              "description": "JSON Schema the final reply is one object of. Replaces outputSchema; same behaviour beside tools and subagents (ADR 0109).",
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            },
+            "mime": {
+              "description": "application/json: JSON mode without a schema. Replaces generateContentConfig.responseMimeType.",
+              "type": "string",
+              "enum": [
+                "application/json",
+                "text/plain"
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "description": "What this agent's final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.",
+          "minProperties": 1
+        },
+        "model_overrides": {
+          "type": "object",
+          "properties": {
+            "gemini": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            },
+            "anthropic": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            },
+            "openai": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            },
+            "xai": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            },
+            "moonshot": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            },
+            "ollama": {
+              "type": "object",
+              "properties": {
+                "instruction": {
+                  "description": "Replaces the agent's instruction on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "instruction_append": {
+                  "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false,
+              "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+              "oneOf": [
+                {
+                  "required": [
+                    "instruction"
+                  ]
+                },
+                {
+                  "required": [
+                    "instruction_append"
+                  ]
+                }
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Per-provider instruction, keyed by the provider of the agent's model id (lib/models/providerMap.ts). Applied at compile time before the skills index; not to fallback_model, and never to globalInstruction (ADR 0115)."
+        },
         "outputSchema": {
-          "description": "JSON Schema for structured output: the agent answers with one JSON object matching it. Hold it on a leaf; an agent that delegates and holds one ends its turn on that JSON.",
+          "description": "Deprecated v1 spelling (ADR 0115): write output.schema. JSON Schema for structured output: the agent answers with one JSON object matching it. An agent that also calls tools or delegates to subagents does that first, then ends its turn on that JSON: the schema travels beside the tools where the model takes both in one request, as a set_model_response tool elsewhere (the capability matrix's structured_output_with_tools, ADR 0109).",
           "type": "object",
           "propertyNames": {
             "type": "string"
           },
-          "additionalProperties": {}
+          "additionalProperties": {},
+          "deprecated": true
         },
         "mcp_server_url": {
           "description": "MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.",
@@ -208,6 +445,88 @@
             "minLength": 1
           }
         },
+        "mcp_auth": {
+          "description": "The OAuth grant the MCP server takes (ADR 0112). With authorization_code, each user's own token on their own connection, and mcp_tools is required. Needs mcp_server_url; replaces MCP_BEARER_TOKENS for this server.",
+          "type": "object",
+          "properties": {
+            "oauth2": {
+              "type": "object",
+              "properties": {
+                "provider": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
+                  "description": "The credential store's name for the provider (e.g. github). Every tool naming it shares one grant."
+                },
+                "grant": {
+                  "type": "string",
+                  "enum": [
+                    "authorization_code",
+                    "client_credentials"
+                  ],
+                  "description": "authorization_code: each user's own token, granted through the consent pause (ADR 0085). client_credentials: the server's own token, from the token endpoint."
+                },
+                "authorization_url": {
+                  "description": "The provider's authorization endpoint (https). authorization_code only.",
+                  "type": "string",
+                  "format": "uri"
+                },
+                "token_url": {
+                  "type": "string",
+                  "format": "uri",
+                  "description": "The provider's token endpoint (https)."
+                },
+                "client_id": {
+                  "description": "The OAuth client id, written out (it is not a secret). Or client_id_env.",
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "client_id_env": {
+                  "description": "Environment variable holding the client id. Or client_id.",
+                  "type": "string",
+                  "pattern": "^[A-Z_][A-Z0-9_]*$"
+                },
+                "client_secret_env": {
+                  "description": "Environment variable NAME holding the client secret, never the value. Required for client_credentials; omit for a public client (PKCE alone).",
+                  "type": "string",
+                  "pattern": "^[A-Z_][A-Z0-9_]*$"
+                },
+                "scopes": {
+                  "description": "The scopes the grant asks for.",
+                  "maxItems": 64,
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]{1,256}$"
+                  }
+                },
+                "authorization_params": {
+                  "description": "Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.",
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9_.-]{1,64}$"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "maxLength": 512
+                  }
+                }
+              },
+              "required": [
+                "provider",
+                "grant",
+                "token_url"
+              ],
+              "additionalProperties": false,
+              "description": "An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values."
+            }
+          },
+          "required": [
+            "oauth2"
+          ],
+          "additionalProperties": false
+        },
         "skills": {
           "type": "object",
           "properties": {
@@ -320,6 +639,78 @@
                       "name"
                     ],
                     "additionalProperties": false
+                  },
+                  "oauth2": {
+                    "type": "object",
+                    "properties": {
+                      "provider": {
+                        "type": "string",
+                        "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
+                        "description": "The credential store's name for the provider (e.g. github). Every tool naming it shares one grant."
+                      },
+                      "grant": {
+                        "type": "string",
+                        "enum": [
+                          "authorization_code",
+                          "client_credentials"
+                        ],
+                        "description": "authorization_code: each user's own token, granted through the consent pause (ADR 0085). client_credentials: the server's own token, from the token endpoint."
+                      },
+                      "authorization_url": {
+                        "description": "The provider's authorization endpoint (https). authorization_code only.",
+                        "type": "string",
+                        "format": "uri"
+                      },
+                      "token_url": {
+                        "type": "string",
+                        "format": "uri",
+                        "description": "The provider's token endpoint (https)."
+                      },
+                      "client_id": {
+                        "description": "The OAuth client id, written out (it is not a secret). Or client_id_env.",
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 512
+                      },
+                      "client_id_env": {
+                        "description": "Environment variable holding the client id. Or client_id.",
+                        "type": "string",
+                        "pattern": "^[A-Z_][A-Z0-9_]*$"
+                      },
+                      "client_secret_env": {
+                        "description": "Environment variable NAME holding the client secret, never the value. Required for client_credentials; omit for a public client (PKCE alone).",
+                        "type": "string",
+                        "pattern": "^[A-Z_][A-Z0-9_]*$"
+                      },
+                      "scopes": {
+                        "description": "The scopes the grant asks for.",
+                        "maxItems": 64,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]{1,256}$"
+                        }
+                      },
+                      "authorization_params": {
+                        "description": "Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.",
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string",
+                          "pattern": "^[A-Za-z0-9_.-]{1,64}$"
+                        },
+                        "additionalProperties": {
+                          "type": "string",
+                          "maxLength": 512
+                        }
+                      }
+                    },
+                    "required": [
+                      "provider",
+                      "grant",
+                      "token_url"
+                    ],
+                    "additionalProperties": false,
+                    "description": "An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values."
                   }
                 },
                 "additionalProperties": false
@@ -465,7 +856,7 @@
             }
           },
           "require_approval": {
-            "description": "Tools from this agent's `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on the orchestrator and on plan-dispatch routes.",
+            "description": "Tools from this agent's `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on any agent but one a workflow map node runs; inside a delegated subagent the pause reaches the caller through its open call (ADR 0110).",
             "type": "array",
             "items": {
               "type": "string",
@@ -574,7 +965,8 @@
               }
             },
             "additionalProperties": {},
-            "description": "Model generation config (@google/genai GenerateContentConfig). Do not set tools here."
+            "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
+            "deprecated": true
           },
           "reasoning": {
             "anyOf": [
@@ -605,13 +997,249 @@
             ],
             "description": "How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
           },
+          "sampling": {
+            "type": "object",
+            "properties": {
+              "temperature": {
+                "description": "Sampling temperature. Replaces generateContentConfig.temperature.",
+                "type": "number"
+              },
+              "top_p": {
+                "description": "Nucleus sampling. Replaces generateContentConfig.topP.",
+                "type": "number"
+              },
+              "max_output_tokens": {
+                "description": "Cap on the reply's tokens. Replaces generateContentConfig.maxOutputTokens.",
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              "stop": {
+                "description": "Stop sequences. Replaces generateContentConfig.stopSequences.",
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false,
+            "description": "How this agent samples, on any provider (ADR 0115). Replaces the same keys under generateContentConfig; cannot be combined with them.",
+            "minProperties": 1
+          },
+          "output": {
+            "type": "object",
+            "properties": {
+              "schema": {
+                "description": "JSON Schema the final reply is one object of. Replaces outputSchema; same behaviour beside tools and subagents (ADR 0109).",
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
+              },
+              "mime": {
+                "description": "application/json: JSON mode without a schema. Replaces generateContentConfig.responseMimeType.",
+                "type": "string",
+                "enum": [
+                  "application/json",
+                  "text/plain"
+                ]
+              }
+            },
+            "additionalProperties": false,
+            "description": "What this agent's final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.",
+            "minProperties": 1
+          },
+          "model_overrides": {
+            "type": "object",
+            "properties": {
+              "gemini": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              },
+              "anthropic": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              },
+              "openai": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              },
+              "xai": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              },
+              "moonshot": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              },
+              "ollama": {
+                "type": "object",
+                "properties": {
+                  "instruction": {
+                    "description": "Replaces the agent's instruction on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "instruction_append": {
+                    "description": "Appended to the agent's instruction, after a blank line, on this provider.",
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "additionalProperties": false,
+                "description": "The instruction on one provider: exactly one of instruction or instruction_append.",
+                "oneOf": [
+                  {
+                    "required": [
+                      "instruction"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "instruction_append"
+                    ]
+                  }
+                ]
+              }
+            },
+            "additionalProperties": false,
+            "description": "Per-provider instruction, keyed by the provider of the agent's model id (lib/models/providerMap.ts). Applied at compile time before the skills index; not to fallback_model, and never to globalInstruction (ADR 0115)."
+          },
           "outputSchema": {
-            "description": "JSON Schema for structured output: the agent answers with one JSON object matching it. Hold it on a leaf; an agent that delegates and holds one ends its turn on that JSON.",
+            "description": "Deprecated v1 spelling (ADR 0115): write output.schema. JSON Schema for structured output: the agent answers with one JSON object matching it. An agent that also calls tools or delegates to subagents does that first, then ends its turn on that JSON: the schema travels beside the tools where the model takes both in one request, as a set_model_response tool elsewhere (the capability matrix's structured_output_with_tools, ADR 0109).",
             "type": "object",
             "propertyNames": {
               "type": "string"
             },
-            "additionalProperties": {}
+            "additionalProperties": {},
+            "deprecated": true
           },
           "mcp_server_url": {
             "description": "MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.",
@@ -626,6 +1254,88 @@
               "minLength": 1
             }
           },
+          "mcp_auth": {
+            "description": "The OAuth grant the MCP server takes (ADR 0112). With authorization_code, each user's own token on their own connection, and mcp_tools is required. Needs mcp_server_url; replaces MCP_BEARER_TOKENS for this server.",
+            "type": "object",
+            "properties": {
+              "oauth2": {
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
+                    "description": "The credential store's name for the provider (e.g. github). Every tool naming it shares one grant."
+                  },
+                  "grant": {
+                    "type": "string",
+                    "enum": [
+                      "authorization_code",
+                      "client_credentials"
+                    ],
+                    "description": "authorization_code: each user's own token, granted through the consent pause (ADR 0085). client_credentials: the server's own token, from the token endpoint."
+                  },
+                  "authorization_url": {
+                    "description": "The provider's authorization endpoint (https). authorization_code only.",
+                    "type": "string",
+                    "format": "uri"
+                  },
+                  "token_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "The provider's token endpoint (https)."
+                  },
+                  "client_id": {
+                    "description": "The OAuth client id, written out (it is not a secret). Or client_id_env.",
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512
+                  },
+                  "client_id_env": {
+                    "description": "Environment variable holding the client id. Or client_id.",
+                    "type": "string",
+                    "pattern": "^[A-Z_][A-Z0-9_]*$"
+                  },
+                  "client_secret_env": {
+                    "description": "Environment variable NAME holding the client secret, never the value. Required for client_credentials; omit for a public client (PKCE alone).",
+                    "type": "string",
+                    "pattern": "^[A-Z_][A-Z0-9_]*$"
+                  },
+                  "scopes": {
+                    "description": "The scopes the grant asks for.",
+                    "maxItems": 64,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]{1,256}$"
+                    }
+                  },
+                  "authorization_params": {
+                    "description": "Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.",
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_.-]{1,64}$"
+                    },
+                    "additionalProperties": {
+                      "type": "string",
+                      "maxLength": 512
+                    }
+                  }
+                },
+                "required": [
+                  "provider",
+                  "grant",
+                  "token_url"
+                ],
+                "additionalProperties": false,
+                "description": "An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values."
+              }
+            },
+            "required": [
+              "oauth2"
+            ],
+            "additionalProperties": false
+          },
           "skills": {
             "type": "object",
             "properties": {
@@ -738,6 +1448,78 @@
                         "name"
                       ],
                       "additionalProperties": false
+                    },
+                    "oauth2": {
+                      "type": "object",
+                      "properties": {
+                        "provider": {
+                          "type": "string",
+                          "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
+                          "description": "The credential store's name for the provider (e.g. github). Every tool naming it shares one grant."
+                        },
+                        "grant": {
+                          "type": "string",
+                          "enum": [
+                            "authorization_code",
+                            "client_credentials"
+                          ],
+                          "description": "authorization_code: each user's own token, granted through the consent pause (ADR 0085). client_credentials: the server's own token, from the token endpoint."
+                        },
+                        "authorization_url": {
+                          "description": "The provider's authorization endpoint (https). authorization_code only.",
+                          "type": "string",
+                          "format": "uri"
+                        },
+                        "token_url": {
+                          "type": "string",
+                          "format": "uri",
+                          "description": "The provider's token endpoint (https)."
+                        },
+                        "client_id": {
+                          "description": "The OAuth client id, written out (it is not a secret). Or client_id_env.",
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 512
+                        },
+                        "client_id_env": {
+                          "description": "Environment variable holding the client id. Or client_id.",
+                          "type": "string",
+                          "pattern": "^[A-Z_][A-Z0-9_]*$"
+                        },
+                        "client_secret_env": {
+                          "description": "Environment variable NAME holding the client secret, never the value. Required for client_credentials; omit for a public client (PKCE alone).",
+                          "type": "string",
+                          "pattern": "^[A-Z_][A-Z0-9_]*$"
+                        },
+                        "scopes": {
+                          "description": "The scopes the grant asks for.",
+                          "maxItems": 64,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]{1,256}$"
+                          }
+                        },
+                        "authorization_params": {
+                          "description": "Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.",
+                          "type": "object",
+                          "propertyNames": {
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9_.-]{1,64}$"
+                          },
+                          "additionalProperties": {
+                            "type": "string",
+                            "maxLength": 512
+                          }
+                        }
+                      },
+                      "required": [
+                        "provider",
+                        "grant",
+                        "token_url"
+                      ],
+                      "additionalProperties": false,
+                      "description": "An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values."
                     }
                   },
                   "additionalProperties": false
@@ -831,7 +1613,7 @@
             "additionalProperties": false
           },
           "yaml_reference": {
-            "description": "A whole nested syndicate (filename under the agents dir) used as this subagent.",
+            "description": "A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate's gates anywhere, a dispatch syndicate's on its classifier (its routes never run nested), and a workflow's ask_user nodes and gates when it is delegated to as a subagent.",
             "type": "string",
             "minLength": 1
           },
@@ -1166,6 +1948,12 @@
       "exclusiveMinimum": 0,
       "maximum": 9007199254740991
     },
+    "max_concurrency": {
+      "description": "Subagent calls from one orchestrator step that run at once; the rest wait their turn, in call order. Default 4; 1 runs them one after another. A delegate syndicate only (ADR 0116).",
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 32
+    },
     "bundled_references": {
       "description": "Written by the registry publisher, not by hand: every nested yaml_reference this syndicate reaches, as it was when published, so a registry version is one unit (ADR 0018). Nested references load from here instead of from files.",
       "type": "object",