A Codex subagent finishes its assignment. Its answer looks sensible in the conversation. Then your application rejects it because the response contains a Markdown fence, an unexpected field, or a string where a list should be.
The model call may have succeeded. The handoff to your software has not.
This distinction matters when DeepSeek Harness coordinates work across models. A parent agent can understand a paragraph that a database importer cannot accept. A response that reads well is therefore only one part of a working integration.
For @deepseek-ai/dsh-subagent-codex, there is also a concrete capability boundary. The current package documentation says this provider returns selected answer text and does not support the shared service’s optional output-schema capability. Asking for JSON in its task description does not turn that text response into a schema-enforced result. See the official Codex subagent package reference. GitHub
The practical solution is to make acceptance explicit. Keep execution status, JSON parsing, field validation, and factual verification separate. Then decide whether the task needs a Codex agent at all.
*Technical references checked on November 20, 2026. Harness package behavior can change; compare the linked references with your installed version.*
The missing contract sits between the agent and your application
Consider an internal API migration dashboard. A parent agent asks a Codex subagent to inspect provider notes and identify the protocols used by two application services. The dashboard expects a small object containing the source identifier and a list of routes.
The child instead returns an explanation followed by a JSON example. A human can extract the answer. Your importer cannot safely assume which part is authoritative.
There are four separate questions:
| Check | What it establishes | What it does not establish |
|---|---|---|
| The delegated run completed | The execution reached a reported terminal outcome | The response meets your data contract |
| The response parses as JSON | The complete text is valid JSON syntax | Required fields or correct types |
| The object passes validation | The accepted fields satisfy your application rules | The claims are supported by the source |
| The claims match evidence | The extracted facts can be checked | Permission to perform a downstream action |
Treating these checks as one “success” flag makes failures difficult to explain. It also encourages retries at the wrong layer. Repeating a successful repository inspection because its final answer used a code fence can consume another model run without fixing the underlying contract.
If no final result has arrived, start with the existing guide to locating Codex subagent results. The workflow below begins after you have obtained the selected final answer from a completed run.
A model feature does not automatically become a Harness feature
“The model supports structured outputs” is not enough information to configure a delegated workflow.
The Harness subagent contract declares outputSchema as an optional provider capability. It rejects unsupported requests at startup. A successful structured capture, where supported, is represented separately from ordinary answer content.
That contract belongs to the delegation layer. A model endpoint has its own interface and restrictions.
For example, OpenAI’s Structured Outputs documentation distinguishes schema-constrained output from JSON mode. Supported schema constraints apply to completed, non-refusal responses. Applications still need to handle refusal and incomplete-output states. OpenAI API
DeepSeek’s JSON Output guide documents response_format with type: json_object, a JSON instruction in the prompt, and an adequate output allowance. That is a specific API request mode. It is not evidence that every Harness adapter or external subagent exposes the same option.
Before using a capability, identify all three parts: the model, the API protocol, and the adapter that sends the request. An API gateway can provide access to a compatible route. It cannot add an unimplemented outputSchema capability to a Codex subagent provider.
For endpoint setup, use the existing guide to connecting an agent harness to other models. Keep this result-contract investigation separate from a working connection configuration.
Give the child one small, inspectable assignment
Start with a synthetic file named provider-notes.txt:
Source ID: migration-notes-v1
The support summarizer uses Chat Completions at /v1/chat/completions.
The repository assistant uses Responses at /v1/responses.
The document service has not selected an API protocol.These are example application notes, not claims about a live service. The unresolved document service is intentional. It tests whether the model can leave a missing fact unresolved instead of inventing an endpoint.
Use this task description when delegating through your configured Codex subagent:
Read provider-notes.txt in the selected workspace.
Return one JSON object only, without Markdown fences or commentary.
The object must contain exactly:
- source_id: the Source ID from the file
- routes: an array of objects with protocol, path, and evidence
Allowed protocol values:
chat_completions, responses, anthropic_messages, gemini
For every route, quote one complete supporting sentence as evidence.
Omit services whose protocol is unresolved. Do not infer an endpoint.
Do not edit files, install packages, or call external services.The instruction narrows the task. It does not enforce permissions or guarantee formatting. Use the runtime’s actual permission controls for the execution boundary.
An accepted example would contain two route records and no invented document-service record. Keep the source file and task description together. A result cannot be evaluated meaningfully if the source changes while you are checking it.
In a real project, bind the run to an application-generated task ID and a source snapshot or hash. Do not rely only on an identifier repeated by the model. A model can copy an identifier correctly while extracting the wrong information.
Validate the returned text before it reaches the dashboard
The following Python example uses only the standard library. Save it as validate_handoff.py. Save the selected final answer as child-result.txt, without editing its contents to make the test pass.
The validator rejects duplicate JSON keys, nonstandard numeric constants, unexpected fields, unsupported protocol labels, and evidence that is absent from the source. It also limits the input size for this deliberately small result contract.
import json
from pathlib import Path
PROTOCOLS = {
"chat_completions", "responses", "anthropic_messages", "gemini"
}
def reject_constant(value):
raise ValueError(f"Nonstandard JSON constant: {value}")
def unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError(f"Duplicate key: {key}")
result[key] = value
return result
def validate(raw, source, expected_source_id):
if len(raw.encode("utf-8")) > 32_768:
raise ValueError("Result exceeds this contract's 32 KiB limit")
data = json.loads(
raw,
object_pairs_hook=unique_object,
parse_constant=reject_constant,
)
if not isinstance(data, dict) or set(data) != {"source_id", "routes"}:
raise ValueError("Unexpected top-level shape")
if data["source_id"] != expected_source_id:
raise ValueError("Source identity mismatch")
if not isinstance(data["routes"], list) or len(data["routes"]) > 20:
raise ValueError("routes must be a list with at most 20 records")
seen = set()
for row in data["routes"]:
if not isinstance(row, dict) or set(row) != {
"protocol", "path", "evidence"
}:
raise ValueError("Unexpected route shape")
if not all(isinstance(v, str) and v.strip() for v in row.values()):
raise ValueError("Route values must be nonempty strings")
if row["protocol"] not in PROTOCOLS:
raise ValueError("Unknown protocol")
if not row["path"].startswith("/"):
raise ValueError("Expected an endpoint path")
if row["evidence"] not in source:
raise ValueError("Evidence is absent from the source")
identity = (row["protocol"], row["path"])
if identity in seen:
raise ValueError("Duplicate route")
seen.add(identity)
return data
if __name__ == "__main__":
source = Path("provider-notes.txt").read_text(encoding="utf-8")
raw = Path("child-result.txt").read_text(encoding="utf-8")
accepted = validate(raw, source, "migration-notes-v1")
print(json.dumps(accepted, ensure_ascii=False, indent=2))Python’s JSON documentation explains the decoder hooks used here. For a larger contract shared by multiple services, define a JSON Schema and use a maintained validator. The JSON Schema object reference explains required properties and restrictions on additional properties.
This example deliberately does not fetch a URL, update a provider configuration, or execute anything returned by the model. Acceptance produces data for the next review stage.
It also does not prove semantic correctness. A response could quote the correct sentence while attaching the wrong protocol label. It could omit a documented route. For this fixture, separately assert that the two expected protocol/path pairs are present and the unresolved service is absent. For production notes, add business checks or human review appropriate to the consequence of an error.
Test failures before adding more model calls
Use a short set of controlled responses to check the consumer independently of the model.
| Test response | Expected decision |
|---|---|
| Correct object with the two documented routes | Accept the contract; then check factual completeness |
| The same object inside a Markdown fence | Reject as a format failure |
A valid object whose routes value is a string | Reject the field type |
| A record quoting a sentence absent from the file | Reject the evidence |
Two source_id keys | Reject the ambiguous object |
| Correct syntax but an invented document-service endpoint | Reject during factual review |
Do not silently repair every failure. Removing arbitrary text before the first opening brace can hide a refusal or select the wrong object from a multi-part answer. It can also turn an ambiguous result into apparently clean data.
If your product intentionally accepts fenced JSON, define that as an explicit input format with its own tests. Record whether normalization occurred. The accepted contract should be visible in code, rather than emerging from increasingly permissive string manipulation.
A formatting retry should have a limit and a reason. If another model reformats the answer, record it as another model call with its own result. Do not describe an unverified repair as recovered truth.
The existing article on agent harness token costs provides the broader cost model. Here, the useful measure is narrower: how many completed child runs produce evidence-backed records that your consumer accepts without manual reconstruction?
Use an agent when the task needs tools; use a direct API when it needs extraction
The fixture above is intentionally small. Sending that entire task through an agent would often be unnecessary in a production service.
If your application already has a short text document and only needs fields extracted, a direct model request may be easier to control. Select a model and endpoint with the required output capability, provide the contract, inspect its terminal state, and validate the returned data.
A Codex subagent becomes more relevant when the assignment requires repository exploration, reading related files, or running permitted local checks before producing a result. In that case, the agent’s tools contribute something beyond text transformation.
This distinction gives a multi-model system a useful division of work. A tool-using agent can gather evidence. A separate API stage can transform approved evidence into an application-specific object. That second stage is optional and adds latency and cost. Use it only when it improves your measured acceptance rate enough to justify the extra request.
When considering DeepSeek, GPT, Claude, Gemini, Qwen, or GLM for extraction, compare actual model IDs and supported request formats. Model-family recognition is not a capability test. The existing model and API gateway selection guide can help organize that evaluation.
Put the gateway at the model-access boundary
Treerouter is an API gateway option for accessing model routes. In this workflow, its role belongs to the requests you deliberately send through it. Local validation remains application code, and a delegated Codex session follows its own configured connection.
Start with the model directory. Confirm the exact model ID, protocol, and output features for the route you plan to test. For a Codex connection, use the custom API configuration guide, checking version-sensitive settings against current product documentation.
Keep one small record per attempt: task ID, source snapshot, selected route, execution outcome, parsing outcome, validation outcome, and available request identifiers. Avoid copying credentials into that record. This gives a developer a concrete answer when a business user asks why a dashboard entry is missing.
For an initial trial, create an account and test one supported route against the same small fixture. Expand to more models after the consumer reliably distinguishes a good answer from an acceptable record.
The useful deliverable is a result your software can explain: which source it describes, which model route produced it, which checks it passed, and which decisions still require review.






