[FEATURE]: StructuredOutput tool for reliable typed data extraction from sub-agents #20485

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When an orchestrator spawns a sub-agent and needs structured data back (e.g., a list of files found, a JSON analysis result, a typed plan), the sub-agent currently has no dedicated channel for this. It must embed JSON in its prose response, and the parent must parse it manually — which is fragile, breaks on model verbosity variations, and mixes structured output with narrative explanation.

claw-code implements a StructuredOutput tool that accepts arbitrary key-value pairs and returns them as a cleanly serialized, machine-readable artifact that the calling orchestrator can consume directly.

Proposed solution

// packages/opencode/src/tool/structured-output.ts

export const StructuredOutputTool = Tool.define({
  name: "StructuredOutput",
  description: "Return typed structured data to the calling agent or orchestrator. Use this instead of embedding JSON in prose when the caller expects machine-readable output.",
  parameters: z.record(z.unknown()), // accepts any key-value structure
  execute: async (data) => {
    return {
      data: JSON.stringify(data, null, 2),
      structured_output: data
    }
  }
})

Usage examples

// Sub-agent returning a file list
StructuredOutput({
  files: ["src/auth.ts", "src/session.ts"],
  totalMatches: 2,
  summary: "Found 2 auth-related files"
})

// Sub-agent returning a typed analysis
StructuredOutput({
  severity: "high",
  affectedFiles: ["src/api.ts"],
  recommendation: "Add input validation at line 47"
})

Why this matters

• Eliminates JSON-in-prose parsing fragility in multi-agent pipelines
• Orchestrators can pattern-match on StructuredOutput tool results reliably regardless of model verbosity
• Enables typed contracts between agents without requiring a full schema definition per call
• Particularly valuable for agentic data pipelines (analysis, planning, report generation) where structured hand-off is essential

Acceptance criteria

• StructuredOutput tool is registered with ReadOnly permission
• Tool accepts any valid JSON-serializable key-value structure (no fixed schema required)
• The response includes both a pretty-printed data string and the raw structured_output object
• When used by a sub-agent, the parent agent's tool result parser can access structured_output directly without string parsing
• Tool is available in all sub-agent scopes including explore and plan (see [FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483)

Related / cross-reference

• claw-code reference: https://github.com/instructkr/claw-code/tree/main/rust (StructuredOutput tool)
• Sub-agent tool-set isolation: [FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483
• SendUserMessage for async notifications: [FEATURE]: SendUserMessage / Brief tool for proactive async notifications from sub-agents #20482
• Learnings from claude-code source: Lessons from claude-code-main? #20475