Agent interface contract: parent-facing skill, schema enforcement, and discovery

[krisrowe]

Problem

The privacy-guard agent produces structured JSON output but there is no interface contract telling callers what to expect, how to interpret results, or how to present them. The parent agent receives a blob of text and has to guess.

This is a known limitation of Claude Code — agent frontmatter has no output schema field. MCP tools gained output schema support in the June 2025 spec revision, but agents have no equivalent.

Current state

• The agent's output format is defined only in its system prompt (agents/privacy-guard.md Step 8)
• No parent-facing documentation or skill for invoking the agent and interpreting results
• No schema validation at invocation time
• The output includes a version field (proposed in SCHEMA-PROPOSAL.md) but nothing consumes it

Approaches to investigate

1. Parent-facing skill (Agent Card equivalent)

A skill (e.g., invoke-privacy-guard) that guides the parent agent on:

• How to spawn the subagent and what arguments to pass
• What the structured JSON output looks like (field descriptions, not the schema itself)
• How to present findings to the user (group by category, highlight severity, show rule attribution)
• What the containment rules mean in practice (don't echo scan targets, do show matched values)

This is functionally an A2A Agent Card — a metadata document describing the agent's interface for its callers. Claude Code has no native Agent Card mechanism, but a skill serves the same purpose.

2. --json-schema enforcement at invocation

Claude Code supports --output-format json --json-schema <schema> to force output to conform to a specific JSON Schema. Investigate:

• Can this be used when spawning a subagent via the Agent tool?
• Can the test harness pass a schema file to get schema validation for free at invocation time, rather than asserting on shape in every test?
• Where would the schema file live? (docs/agents/privacy-guard/schema.json is the natural location)
• Does schema enforcement conflict with the agent's fenced code block output format (privacy-guard-result)?

If this works, it would catch schema violations (missing fields, wrong types) without any test code — the harness would fail before assertions even run.

3. Self-describing output (_meta or $schema)

The output could include a reference to its own schema:

• "$schema": "./docs/agents/privacy-guard/schema.json" — SARIF convention, points to a JSON Schema file in the repo
• "version": "2.0" — already proposed, lets consumers branch on schema version

This is the weakest option alone (the consumer has to know to look for it), but combined with option 1 (the skill tells the consumer to check version) it provides runtime confirmation.

4. MCP tool wrapper

Instead of invoking privacy-guard as a subagent, expose it as an MCP tool with a proper outputSchema. MCP tools have native schema support (input and output) since the June 2025 spec. This would give callers a machine-readable interface contract.

Trade-offs:

• Requires an MCP server to wrap the agent invocation
• Adds infrastructure complexity
• But provides the cleanest interface contract — callers discover the tool via tools/list with full input/output schema, exactly like any other MCP tool

5. Future: agent frontmatter output schema

If Claude Code adds output schema support to agent frontmatter (analogous to MCP tool outputSchema), the proposed schema would slot directly in. Track this as a platform feature to monitor, not something to build.

Recommendation

Start with option 1 (parent-facing skill) — it's the lowest-effort, highest-impact change. It requires no platform features, no infrastructure, and immediately helps any parent agent or user invoking privacy-guard.

Investigate option 2 (--json-schema) as a test infrastructure improvement — if it works with the Agent tool, it replaces a class of test assertions with invocation-time validation.

Options 3-5 are complementary and can be layered on later.

Work breakdown

• Investigate whether --json-schema works with claude --agent invocation
• Create parent-facing skill with invocation guidance, output interpretation, and presentation rules
• Create docs/agents/privacy-guard/schema.json (JSON Schema file) for both --json-schema enforcement and $schema reference
• Add version field to agent output (depends on schema redesign issue)
• Document MCP wrapper as a future option in SCHEMA-PROPOSAL.md

Related

• SCHEMA-PROPOSAL.md — proposed output schema with SARIF-inspired rules/results model
• Agent should own PII categories and reason from any input, not just structured YAML #2 — agent should own PII categories (attribution, source field)
• Update debug-agent-tests skill: log review as verification on every run #3 — validate-privacy-guard skill update (log review, verification)
• CONTRIBUTING.md — subagent containment principle