Structured Output
A subagent run can be given a result schema. The child then returns its result through a
StructuredOutput tool call instead of free text, and the parent (the host) checks that result
itself before using it.
This is a runner capability: code that calls the subagent extension's runAgent passes
schema. Script workflows use it for agent(..., { schema }); the
subagent tool, /workflows and YAML workflows do not expose it.
What a schema may contain
The schema is checked before any child starts. A schema that fails the check makes runAgent
reject with a StructuredSchemaError that lists every problem; nothing is launched or charged.
- The root must be an object schema:
"type": "object". A union such as["object", "null"]is refused. - Every name in
requiredmust be a key ofpropertiesat the same level. - Only these keywords may appear, at any depth:
$schema,title,description,type,const,enum,required,properties,additionalProperties,items,minItems,maxItems,minLength,maxLength,minimum,maximum,pattern. Anything else (oneOf,anyOf,$ref,format, ...) is refused, because the validator would not check it. - Values must be well formed:
typenames a JSON type, the length and range keywords are finite numbers,patterncompiles as a regular expression both with and without theuflag (pi validates tool arguments with it), andpropertiesis an object. - A schema-valued
additionalPropertiesneedspropertiesat the same level, because the validator applies it only there;trueandfalseare accepted anywhere. - The check runs on the schema's JSON form, which is what the child reads from its schema file.
- Nesting deeper than 32 levels and schemas whose JSON is longer than 64 KiB are refused.
Pattern limits
The host tests every pattern against text the child model wrote, in the root pi process, so
patterns are limited:
- At check time, a
patternlonger than 256 characters is refused, and so is one with a backreference (\1...\9,\k<name>) or with a repeating quantifier (*,+,{n,}, or{n,m}with m > 1) on a group that contains a quantifier or an alternation at any depth, such as(a+)+,(a|b)*or(-[a-z]+)*. The check is syntactic and conservative: it also refuses some harmless patterns. Use a character class ([ab]+) or an optional group ([a-z]+(-[a-z]+)?) instead.?and{0,1}on such a group are allowed. - At check time, a
patternwith more than 16 choice points is refused. A choice point is a quantifier whose minimum and maximum differ (?,*,+,{n,},{n,m}with n < m) or a|; fixed counts such as{4}are not counted. This cap bounds compile time. V8 compiles a pattern the first time it is used, the time limit below cannot interrupt that, and compile time grows exponentially with a run of optional atoms ahead of literals:a?50 times thena50 times compiles in about 5 s on node 26. For a long list of fixed alternatives, useenum. - When validating, a string longer than 65536 characters (UTF-16 code units) under a
patternfails without the pattern being run. - Matching runs under a
node:vmtime limit of 100 ms per test, and all pattern tests of one validation share 1 s. A test that is cut off fails validation ("took too long to test"). This is the backstop for patterns the check allows but that are slow to match, such asa*a*a*$. The limit covers matching only, not compilation, which the check-time caps bound.
The limits on strings and matching time are in the validator
(packages/extensions/third_party/subagent/schema.ts); the check-time caps apply to subagent
result schemas. tests/workflow-structured-smoke.ts (check 1b) pins each limit, including that
the slow-to-compile a? run is refused at check time.
How a run works
- The host writes the schema to
result-schema.json(mode 0600) in the run's temporary directory and names it inPI_KIT_STRUCTURED_OUTPUT_SCHEMAfor the child. The file is removed when the attempt ends. A run without a schema removes an inheritedPI_KIT_STRUCTURED_OUTPUT_SCHEMAfrom its child's environment, so a structured child's own children do not get the tool. - The child is launched as usual through delegation-guard, with one addition:
-eloadsthird_party/subagent/structured-output/index.ts. When the role has an explicit tool list,StructuredOutputis added to--tools. This happens after the launch has been charged, so the extra tool does not change which budget the launch counts against. The role's system prompt gains one paragraph telling the child to return its result through the tool. - Inside the child the tool exists only when
PI_KIT_INTERNAL_CHILD=1and the schema file can be read and passes the same check. A root session never has it. Its arguments are{"output": <result>}. The result is wrapped because the tool firewall reads top-level fields such ascommandandpathas actions, and a result field with one of those names must stay data. - The child checks the arguments as the model wrote them, before pi coerces any types, with the
vendored validator (
third_party/subagent/schema.ts). A rejected call is an error result that lists the problems, so the model can call again. An accepted call ends the child's turn. - The host does not trust the child's answer. From the child's JSON event stream it takes the
arguments of
tool_execution_startforStructuredOutputand keeps them only when the matchingtool_execution_endreportsisError: false. It validates the last such call again with its own copy of the validator, and only a value that passes becomesresult.structured. - If the child finished normally but no call passed, the host launches it once more. The
retry is charged against the effort budget like any launch, and its task says what was wrong.
If the retry also fails,
result.structuredisnullandresult.structuredErrorssays why. A child that failed (error exit, timeout, stream cap, abort, stop or a refused launch) is not retried for its result. Itsstructuredisnulltoo.
The tool firewall allows StructuredOutput (risk_class: "verdict") in both policy copies,
packages/extensions/src/tool-firewall/default-policy.json and
packages/core/policies/default.json.
Tests
tests/workflow-structured-smoke.ts(npm run smoke:workflow-structured) covers the schema checks, the pattern limits, when the child-only tool registers, the raw and executed argument checks, the host's own validation, the single charged retry, andnullafter it.
Not covered here: the vendored validator is a copy of an upstream source that this repository does
not carry. The test compares the two byte for byte only where that source exists, so in this tree
nothing pins the copy against it.
- tests/tool-firewall-smoke.ts checks that StructuredOutput is allowed headlessly and that a
result with command and path fields is not read as a command or a credential read.