Repository navigation
Define a compact, operationally unambiguous agent-control envelope #333
Description
Parent epic: #338
Canonical v0.17 design issue for the shared agent-control envelope. #323 owns the v0.18 command-by-command rollout and end-to-end coverage; it must apply this shape, not define a second one. The permission model (#335) and current-control pointer (#339) are complete prerequisites.
Problem
A verifier run can simultaneously report:
execution: "succeeded"head_exit_code: 0release_decision.decision: "review_required"control.state: "human_review_required"
Humans and coding agents naturally interpret “succeeded” or exit code 0 as permission to continue. The authoritative operational fields are buried inside thousands of tokens of JSON, causing users to ask whether the run is “done” and whether the agent may push.
The full forensic document is valuable, but it is a poor default control interface for an agent loop.
Proposed direction
Provide a compact, stable agent-control envelope that clearly separates:
- tool execution status;
- release/merge decision;
- publication permissions;
- completion permission;
- next actor and exact next action;
- paths and hashes for detailed forensic artifacts.
Example:
{
"schema_version": "shipgate.agent_control/v1",
"execution_status": "succeeded",
"control_state": "human_review_required",
"ready_to_update_pr": true,
"ready_to_merge": false,
"completion_allowed": false,
"next_actor": "human",
"next_action": {
"kind": "review",
"surface": "github_pull_request",
"why": "..."
},
"artifacts": {
"receipt": {"path": "...", "sha256": "..."},
"verifier": {"path": "...", "sha256": "..."}
}
}Detailed verifier/report JSON should remain available by path, not dominate the default agent stdout.
Acceptance criteria
- A compact format is available and promoted for coding-agent control loops.
- The result explicitly answers: may edit, may commit, may push/update PR, may merge, may report complete?
- Execution success cannot be mistaken for release readiness.
- Human-facing text leads with the operational state and next actor.
- Full forensic artifacts remain content-addressed and discoverable.
- Agent-mode errors and nonterminal results include an exact executable next action.
- The compact control payload has a documented size budget and does not duplicate the full report.
- Exit-code semantics are documented and tested against
passed,review_required,insufficient_evidence, andblocked.
Success measure
A user or coding agent should determine the permitted next action without reading any other artifact or interpreting prose.
Activity
pengfei-threemoonslab commentedon Aug 7, 2026
Overlap alert: this and #323 are the same surface, approached from opposite ends.
init,doctor,scan,detect,verify,checkall speak one control vocabulary. Today onlyverifyandcheckusederive_agent_control(core/agent_control.py:34); the rest bypass it.Both land in
core/agent_control.pyandschemas/agent_control.py, and both propose a schema (shipgate.agent_control/v1here; an embeddedcontrolblock there). Built separately, the result is two envelope definitions and a migration between them. These should be one design and one PR.Recommend this issue absorb #323's scope, since the compact/permission model is the harder constraint and the horizontal rollout is mechanical once the shape is fixed.
Two carry-over constraints from the #323 triage that apply here unchanged:
The envelope must project
release_decision, never restate it. The roadmap non-goal is "no second verdict — nothing gates independently ofrelease_decision.decision."ready_to_mergeandcompletion_allowedmust be derived, not computed in a renderer. #318 is a live example of a projection that started deciding for itself.initanddoctorhave norelease_decisionto project from. They run before any scan, so their control state derives from setup facts. That is legitimate but must be stated, orcontrol_statemeans "the gate says" in one command and "setup says" in another. #325 is the concrete instance and should settle it.Sequencing: this depends on #335. The permission model (
may commit/may push/may merge/may report complete) is what the compact payload reports; designing the payload first would mean guessing at the fields.Re-ranked to P1 for that reason, despite the P0 in the title — not a judgement on importance, only on order. It cannot lead its own epic.
[-][Agent-first UX][P0] Make verifier results compact and operationally unambiguous[/-][+]Define a compact, operationally unambiguous agent-control envelope[/+]feat(control): add the compact shipgate.agent_control/v1 control enve…
fix(agent-mode): close the setup control review findings (#323)
feat(agent-mode): roll the shared control envelope across the setup c…