agent-contract-handoff

name	agent-contract-handoff
description	Use when you need the exact field schema, required/conditional/optional status, or the trigger for any field of the agent_contract_handoff envelope -- input or output, top-level field, sub-field table, plan_status enum, or the JSON-not-YAML rule
metadata	{"user-invocable":false,"type":"reference"}

Agent Contract Handoff

The agent_contract_handoff is the uniform structured block every subagent emits at the end of its turn and the orchestrator consumes to decide the next dispatch. This skill is its field dictionary: every field, whether it is required, when a conditional field triggers, and which code symbol owns the rule.

The name collision: INPUT vs OUTPUT

agent_contract_handoff names two different things, and this is where the distinction is owned. The runtime injects an INPUT envelope before the turn; the subagent emits an OUTPUT envelope after it. Same name, two directions.

INPUT envelope (what the subagent receives)

The orchestrator-side context the runtime injects before a turn. Detection of consolidation_required reads from here -- see requires_consolidation_report in contract_validator.py. Five named sections:

Section	Carries	Use
project_knowledge	indexed workspace facts (project_context_contracts)	read before scanning the filesystem
surface_routing	routed surface(s), multi_surface flag, adjacent agents	know whether you are primary or assisting
agent_contract_handoff (input sub-block)	goal, acceptance criteria, scope, plus consolidation_required / cross_check_required flags	decides whether your OUTPUT must carry consolidation_report
write_permissions	exact writable_sections you may emit update_contracts clauses for	writing outside the list is rejected by the hook
metadata	session id, provider, contract version	traceability, not control flow

OUTPUT contract (what the subagent emits)

The agent_contract_handoff envelope, built BY-VALUE across the turn with the gaia contract CLI (init/set/add/fill --json, then finalize) rather than composed once and re-emitted as a single fenced block. Every write validates the FULL resulting envelope through one combined entry point, gaia.contract.crosscheck.validate() -- layer 1 (gaia.contract.validator.validate_form, pure/stdlib SHAPE check) plus layer 2 (gaia.contract.crosscheck, gaia.db cross-check for approval_id) -- before persisting anything, so a rejected write never lands (no false-pass). gaia.contract.validator.py is the single source of truth for shape, including the canonical rich repair message (CANONICAL_REPAIR_MESSAGE) both this path and the fence fallback return.

A still-emitted fenced agent_contract_handoff block is a supported migration fallback: parse_contract (regex _RE_HANDOFF, tag _TAG_HANDOFF) in hooks/modules/agents/contract_validator.py extracts the dict from the raw text, and _validate_from_handoff there hands SHAPE validation to the SAME validate_form core -- it is not a second, divergent validator. contract_validator.py's validate() is explicitly the migration-only entry point for this path (see its docstring); it never re-implements the shape rules. The rest of this skill specifies the envelope either path must satisfy.

OUTPUT top-level field table

Field	Status	Trigger / consequence
agent_status	Required	always; container for the four status fields below; absent -> named code MISSING_FIELD (field agent_status)
agent_status.plan_status	Required	always; enum (see state machine); absent -> MISSING_FIELD; present but out-of-enum -> named code PLAN_STATUS
agent_status.agent_id	Required	always; must match ^a[0-9a-f]{5,}$; absent -> MISSING_FIELD; present but malformed -> named code AGENT_ID_FORMAT -- so contract-repair can route back to you
agent_status.pending_steps	Required	presence-only check ([] is valid); missing -> MISSING_FIELD (field agent_status.pending_steps)
agent_status.next_action	Required	must be present and non-empty; missing -> MISSING_FIELD (field agent_status.next_action)
evidence_report	Required	always present for every valid plan_status; see sub-field table
consolidation_report	Conditional	required when INPUT set consolidation_required / cross_check_required / surface_routing.multi_surface (requires_consolidation_report); else may be null
approval_request	Conditional	required when plan_status is APPROVAL_REQUEST; see sub-field table
loop_state	Conditional	agentic-loop turns only; _check_loop_state_blocking blocks COMPLETE when iteration < max_iterations AND metric < threshold
user_facing_summary	Optional	a brief prose summary written ONCE for the human reader; parse_user_facing_summary. The only human-audience field in the contract -- every other field is machine-audience for the orchestrator. On a single-agent COMPLETE (N=1) the orchestrator relays it near-verbatim (adapted to the user's language) instead of re-synthesizing key_outputs. Absent, or N>1 (multi-agent), the orchestrator falls back to synthesizing key_outputs. Purely additive: never required, never rejected.
memorialize_suggestions	Optional	structured memory candidates for the user to triage; parse_memorialize_suggestions
memory_suggestions	Optional	advisory text-only notes (array of strings); parse_memory_suggestions
update_contracts	Optional	array of {contract, payload} for project-context writes; parse_update_contracts; see sub-field table
rollback_executed	Optional	advisory string; parse_rollback_executed; never rejected
context_consumption	Optional	advisory {tokens_used, pct_window}; parse_context_consumption; never rejected

Named shape-error codes (SSOT)

Four stable, named codes (FormErrorCode in gaia/contract/validator.py) are the SSOT for every SHAPE rejection, whichever path produced it -- the gaia contract CLI's write-time validation, the SubagentStop hook gate, and the fence fallback all resolve to the same four:

Code	Fires when
AGENT_ID_FORMAT	agent_status.agent_id is present but does not match ^a[0-9a-f]{5,}$
PLAN_STATUS	agent_status.plan_status is present but outside the canonical enum
VERIFICATION_RESULT	plan_status is COMPLETE and evidence_report.verification.result is missing or not "pass"
MISSING_FIELD	a required field is absent (agent_status, one of its four sub-fields, evidence_report, or one of its seven keys)

Each rejection carries {code, field, detail} (dotted field path, human detail) plus the byte-stable repair_message -- ALWAYS CANONICAL_REPAIR_MESSAGE, the single source of truth for the reissued fenced template, so a caller that injects it keeps a cache-stable surface regardless of which specific code fired. Read it at gaia/contract/validator.py::CANONICAL_REPAIR_MESSAGE; it is never duplicated inline elsewhere.

Legacy token relabeling (fence-fallback path only). hooks/modules/agents/contract_validator.py's migration-only validate() still surfaces the OLDER uppercase token vocabulary (AGENT_ID, PLAN_STATUS, PENDING_STEPS, NEXT_ACTION, VERIFICATION_RESULT_MUST_BE_PASS, VERIFICATION_RESULT_REQUIRED_FOR_COMPLETE, per-key evidence tokens) in its missing list, for backward compatibility with pre-existing callers. _legacy_tokens_for_form_error is a pure relabeling of the four SSOT codes above -- it does not re-derive validity. The gaia contract CLI and the hook gate's full-verdict path speak the four SSOT codes directly; only the legacy fence-validate() caller sees the older tokens.

Sub-field tables

evidence_report

The required keys are EXACTLY 7 (REQUIRED_EVIDENCE_FIELDS in gaia/contract/validator.py -- the SSOT both the CLI and the fence fallback resolve against; relabeled to the legacy _EVIDENCE_REQUIRED_FIELDS / EVIDENCE_FIELDS uppercase tokens only on the fence-fallback path, see "Named shape-error codes" above). Each key must be present; its value may be []. A missing key (not an empty list) is a MISSING_FIELD (field evidence_report.<key>), relabeled to the uppercase key name in missing on the fence-fallback path.

Key	Holds
patterns_checked	search patterns / queries you ran
files_checked	files you read
commands_run	commands executed (string or {command, result})
key_outputs	distilled findings
verbatim_outputs	raw output excerpts
cross_layer_impacts	adjacent components your change invalidates -- flag, do not silently edit
open_gaps	what remains unresolved

verification is a SEPARATE field, NOT one of the 7. It is required ONLY when plan_status is COMPLETE: it must be a dict and verification.result must equal "pass". Either failure (missing/malformed, or present but not "pass") is the single named code VERIFICATION_RESULT on the CLI/core path; the fence-fallback path relabels the same rejection to the legacy tokens VERIFICATION_RESULT_REQUIRED_FOR_COMPLETE (missing) / VERIFICATION_RESULT_MUST_BE_PASS (non-pass) for backward compatibility. For non-COMPLETE statuses verification may be absent.

Audience boundary. key_outputs and every other evidence_report key are written for the orchestrator -- distilled findings it reasons over to route the next turn. The optional top-level user_facing_summary is the single field written for the human. Keeping the two distinct is what lets the orchestrator relay a human-shaped summary on N=1 without re-synthesizing machine-shaped evidence, and lets it still synthesize from key_outputs when the summary is absent or when multiple agents must be consolidated.

consolidation_report

Required keys when present (_CONSOLIDATION_REQUIRED_FIELDS):

Key	Holds
ownership_assessment	enum owned_here | cross_surface_dependency | not_my_surface (VALID_OWNERSHIP_ASSESSMENTS); invalid -> OWNERSHIP_ASSESSMENT:<x>
confirmed_findings	findings you verified
suspected_findings	findings you suspect but did not confirm
conflicts	contradictions found across surfaces
open_gaps	unresolved items needing another surface
next_best_agent	which agent should take the next round

approval_request

Present when plan_status is APPROVAL_REQUEST (APPROVAL_REQUEST_REQUIRED_FIELDS). rollback and verification are BLOCKING (missing -> APPROVAL_REQUEST_ROLLBACK / APPROVAL_REQUEST_VERIFICATION); the rest are advisory warnings.

Key	Status	Holds
operation	required (advisory)	what the command does
exact_content	required (advisory)	the command verbatim the user approves
scope	required (advisory)	what it touches
risk_level	required (advisory)	enum LOW | MEDIUM | HIGH | CRITICAL (VALID_RISK_LEVELS)
rollback	required (blocking)	how to undo
verification	required (blocking)	how success is confirmed
approval_id	optional	the id the hook produced, when one was issued

For the full sealed-payload schema and the approval lifecycle, see agent-approval-protocol.

memorialize_suggestions entry

parse_memorialize_suggestions; malformed entries are skipped with warnings and never fail the contract.

Key	Status	Notes
description	required	MEMORIALIZE_REQUIRED_FIELDS
body	required	MEMORIALIZE_REQUIRED_FIELDS
slug	optional	--
type	optional	enum atom | decision | negative (MEMORIALIZE_VALID_TYPES); off-enum kept with a warning
class	optional	enum anchor | thread | log (MEMORIALIZE_VALID_CLASSES); off-enum kept with a warning
rationale	optional	--

update_contracts entry

Each entry is one {contract, payload} pair (parse_update_contracts). The contract must match a name in the INPUT write_permissions.writable_sections; a write to a contract outside that list is rejected by the hook. payload is the dict merged under that contract. Combine all deltas for one contract into a single payload; include only keys to add or update.

Key	Status	Holds
contract	required	a contract name from your writable_sections; off-list -> rejected
payload	required	the dict merged under that contract; keys you omit are preserved

Merge semantics (how the runtime applies payload -- the field is additive, never destructive):

Operation	Behavior
ADD	new keys inserted into the section
MERGE	existing dicts recursively merged
UNION	lists merged, no duplicates
OVERWRITE	scalar values replaced
NO-DELETE	keys you do not mention are preserved

Well-formed payload (index, not snapshot). A payload indexes what statically exists in the project -- identifiers, names, relationships, semi-stable metadata. It must not carry live-state: cloud runtime status (pod counts, instance status, VPC IDs), API-discovered facts that change without a rescan (load-balancer DNS, IP addresses, OIDC-derived IAM bindings), or any field whose scanner needs a live cloud API call. Stale live-state in context gives the next agent false confidence; obtain it on demand via the cloud CLI instead. For the produce-side judgment of when to emit and what to prioritize, see agent-protocol.

Cross-repo resource references. When a payload value points at a resource living in another repository, reference it as host/owner/repo:table/name (e.g. github.com/org/bildwiz-iac:tf_modules/gcp-gke). The host/owner/repo prefix is the canonical workspace identity (normalized by normalize_remote_url in gaia/project.py); the :table/name suffix names the domain table and resource within that workspace. Use this form so the reference is unambiguous in multi-repo setups instead of a bare local name.

plan_status enum + state machine

The five canonical values (VALID_PLAN_STATUSES in gaia.state, re-exported by response_contract.py):

Value	Meaning
IN_PROGRESS	mid-loop; default during retry / verify-fail
APPROVAL_REQUEST	a T3 command was blocked; approval_request populated
COMPLETE	increment finished and verification passed
BLOCKED	cannot continue alone; name the gap in open_gaps
NEEDS_INPUT	a user decision is required; list options in next_action

Legal transitions between these and the retry cap live in state_tracker.py -- _LEGAL_TRANSITIONS and _MAX_IN_PROGRESS_RETRIES (= 2). The runtime enforces them; this skill does not reproduce the transition table.

Draft lifecycle: persistence, resume, and the degraded flag

The gaia contract draft is addressed by its own contract id (minted by init, never a harness session id) and persists on disk across a resume: set/add/fill on a resumed turn continue the SAME draft rather than starting over, and plan_status legitimately stays IN_PROGRESS across N resumes -- the SubagentStop gate does not reject a mid-conversation IN_PROGRESS. The orchestrator can inspect that in-progress draft via gaia contract view between messages without the agent re-emitting anything; the view injected into a resumed prompt is deliberately MINIMAL and byte-stable (not the full variable envelope re-inserted above the prompt) so the resume stays cache-safe.

finalize is the SOLE, idempotent writer of the terminal agent_contract_handoffs row. If a turn ends without a finalize call (crash, forgotten call, truncation), the SubagentStop hook backstops the row: it finalizes whatever draft exists (or writes a minimal row when none does), marking it degraded=true / auto_captured, via the same idempotent UPSERT keyed on the draft's contract id -- so exactly one row survives even under a race between the agent's own finalize and the hook's backstop (never-lost, exactly-once). "Verified-via-finalize" means task_status == 'COMPLETE' AND the row carries NO degraded flag -- a downstream reader (episodic memory, metrics) must check both, not task_status alone, to distinguish an agent-verified COMPLETE from a hook-backstopped degraded capture of the same nominal status.

The JSON rule

On the fence-fallback path, the block body must be valid JSON: parse_contract runs it through json.loads; YAML, comments, trailing commas, or unquoted keys raise JSONDecodeError, the parser returns None, and the runtime treats the block as missing (forced reissue). On the CLI path, gaia contract set/add accept a JSON-typed VALUE when it parses as JSON and fall back to a plain string otherwise, and fill --json requires a valid JSON object outright (a malformed patch is rejected before any merge). Either way, emit JSON, not the YAML it resembles.

Handoffs

• agent-protocol -- how to produce the contract (workflow, judgment, when to emit each status).
• agent-response -- how the orchestrator interprets the contract.
• agent-approval-protocol -- the full APPROVAL_REQUEST sealed-payload schema.
• gaia/contract/validator.py -- the SSOT for shape validation and CANONICAL_REPAIR_MESSAGE; bin/README.md documents the gaia contract CLI surface.