Allow workflows to narrow safe-output tool schemas (e.g. require per-item fields for add_labels) #62994

Problem

The add_labels MCP tool accepts each labels item as either a plain string or an object with optional rationale, confidence and suggest. The runtime validator checks that labels is an array but not what each item looks like.

Some workflows need a narrower rule. For example, every label must be an object with confidence set, and uncertain additions must set suggest: true. Today the only way to enforce that is:

1. Describe the rule in the prompt, and
2. Add a custom validation step before safe outputs are processed.

The agent still sees gh-aw's looser tool schema, so the prompt and the custom validator can drift apart. When they do, the run fails only after the agent has finished, and every item it produced is lost. We hit exactly this: a stricter validator shipped before the prompt described the new rule, and a scheduled run failed on every label operation.

Proposal

Let a workflow narrow a built-in safe-output schema in frontmatter. gh-aw would then use that narrower schema in two places:

• The MCP tool definition, so the agent sees the rule when it calls the tool.
• The runtime validator, so bad items are rejected in the tool call, where the agent can retry, rather than after the run.

For example:

safe-outputs:
  add-labels:
    allowed: [bug, enhancement]
    item-schema:
      type: object
      required: [name, confidence]
      additionalProperties: false
      properties:
        name: { type: string }
        confidence: { enum: [HIGH, MEDIUM, LOW] }
        suggest: { type: boolean }
        rationale: { type: string }

The narrowed schema would have to stay compatible with the built-in one. It could only tighten types, add required fields, or restrict values.

Related

• The runtime validator could enforce per-item shape even without this feature, for example by rejecting unknown object fields and invalid confidence values.
• remove_labels ignores rationale, confidence and suggest. Documenting that would help workflow authors avoid expecting them to be recorded.

Observed with gh-aw v0.87.9.