Human approval gates

Approval gates keep a proposed action from executing until the required decision is available. Ethen’s agent-run helpers support real approval decisions, while the general Approvals page currently labels its queue Private Alpha and its card actions scaffolded and nonpersistable.

The general Approvals surface must not be documented as a complete persistent decision system.

Approval review must preserve the difference between presentation and authority. The general Approvals route can display scaffolded cards and explain the intended record shape, but those controls are not proof of a persisted decision. The authoritative path is the approval service used from an agent run, where the proposal, parameters, risk, evidence, signer, decision, and resulting transition can be correlated. Documentation should direct reviewers to that path and retain the Private Alpha limitation on the general surface.

Why approvals exist

Approval gates keep an agent proposal from gaining authority solely because the agent requested it. They are especially relevant for writes to user content, external side effects, destructive operations, and privileged actions. The tool contract can require no_approval, confirm_once, confirm_every_time, or blocked.

Permission mode and approval are separate. Full access does not eliminate a confirmation requirement, and a blocked tool cannot be approved into execution without a contract or policy change.

Approvals add a human control point before an action with meaningful write, external, destructive, or privileged impact.

The tool contract can require no approval, confirm once, confirm every time, or blocked.

Permission mode alone does not eliminate the approval requirement.

Approvals exist to prevent a proposed action from acquiring authority solely because an agent or tool requested it. Risk, parameters, scope, and evidence should be reviewable before a side effect occurs.

Policy can deny an action, hold it for approval, or allow immediate execution. A rejection can transition the containing run to rejected. A signed decision tied to an agent run carries authority; a scaffolded card on the general Approvals page does not persist a decision.

An approval decision can approve or reject an action. Approval states require proposal, evidence, or metadata context, and the resulting signed decision, run transition, and audit event should remain linked without exposing secrets.

Approval records bind request, workflow run, step, tool or app, and parameters. Approval-required and blocked are different states: one requests a decision, while the other may indicate missing authority or policy.

Approval states

Runs can enter awaiting_approval or partially_approved when the required proposal, evidence, or metadata context exists. The helper can mark an action blocked, request approval, or start it. A signed decision can approve or reject the action, and rejection may transition the run to rejected.

The general /approvals surface is labeled Private Alpha. Its current card actions are scaffolded placeholders and do not persist decisions. Only the agent-run approval service described in the sources should be treated as issuing real signed decisions.

Runs can enter awaiting_approval and partially_approved states when proposal context exists.

Helpers can mark an action blocked, awaiting approval, running, approved, or rejected according to the decision path.

Approval states are not terminal success states.

Awaiting approval and partially approved are explicit run states. A blocked tool decision is different from a proposal that can be approved, and a rejection can transition the run to a terminal rejected state.

Approval-required requests a human decision, while blocked can indicate missing authority or a policy denial. Approval records bind the request, workflow run, step, tool or app, parameters, and final decision.

Real signed decisions are handled by the approval service when issued from an agent run. Rejected work should follow the declared transition rather than being described as a failed provider or tool call.

Approval states require proposal, evidence, or metadata context. Escalation behavior must remain under review when the implementation does not define a persistent reviewer workflow. Review the proposal, action parameters, and associated audit event together when all are available.

Reviewer actions

A signed agent-run decision applies to the proposal and action context presented for review. Approval allows the governed path to continue; rejection moves the execution to the corresponding rejected outcome. The general Approvals page is different: its Private Alpha cards and visible actions are scaffolded and do not persist authoritative decisions. Operators must use the verified run approval path when a durable decision is required.

A reviewer should evaluate the proposed tool or app, parameters, risk, scope, evidence, and expected side effect. Approval authorizes the described proposal; it should not be interpreted as authority for changed parameters or a later unrelated action. Rejection should remain tied to the proposal and resulting run transition.

Reviewer assignment, delegation, escalation timers, and bulk approval remain unverified. Exact UI labels remain under review.

A real decision can approve or reject a proposal originating from an agent run.

The current general Approvals cards are scaffolded placeholders and do not persist a decision.

Documentation should not instruct readers to treat those card controls as an executed authorization.

Reviewer actions must come through the verified agent-run approval service to create a real signed decision. The Approvals page is Private Alpha and its card buttons are scaffolded placeholders without a fake persistence endpoint.

Approval decisions can approve or reject an action. Presentation controls should never be documented as execution gates unless they write the authoritative decision record.

There are two different approval surfaces in the inspected product. Agent-run helpers can create proposals and receive signed approval or rejection decisions through the approval service. The general /approvals page is labeled Private Alpha, and its visible card actions are scaffolded placeholders that do not persist a real decision. Clicking or displaying those cards must not be documented as authorizing a run.

A reviewer should evaluate the proposed tool, parameters, risk, requested effect, and attached evidence before issuing a decision through the verified agent-run path. Approval permits the guarded action to continue according to the runtime; rejection can move the run to the distinct terminal rejected state. Missing proposal or evidence context should prevent an approval-state transition rather than create an unauditable waiting record.

Evidence

Approval context can include proposal data, evidence, or metadata. Evidence attached to an approval should identify the source and the claim it supports. The reviewer needs enough information to understand the action without exposing unnecessary credentials or private payloads.

After a decision, preserve the proposal, signer, decision, time, action status, run transition, and audit event as separate linked records. A screenshot of a scaffolded card is not a signed decision.

A proposal should bind the request, workflow run, step, tool or app, parameters, risk, and supporting evidence.

Approval evidence may point to source material, visual captures, reports, logs, changes, exports, or audit records, depending on the proposal.

Reviewers should judge the proposed effect and scope rather than only the model’s explanation.

Evidence should support the exact proposed action and parameters. It does not replace reviewer judgment, and untrusted model or tool output should not be promoted into approval authority.

Output, artifact, evidence, audit event, export, and receipt have different provenance and persistence expectations.

For the initial test, review the exact proposed action and evidence, issue the decision through the verified agent-run approval path, and confirm the resulting state transition.

A downstream consumer should verify the producing run or action, final state, format, evidence, and persistence mode.

Escalation

Persistent escalation behavior is not defined in the supplied implementation. Do not promise reassignment, reminders, expiration windows, or supervisory routing. If a decision cannot be made, the safe documented state is that the action remains blocked or waiting according to the current run and policy records.

A support handoff can include the run ID, action ID, proposal ID, current state, risk, redacted parameters, evidence references, and persistence mode. It must not contain raw credentials.

Escalate when the reviewer lacks authority, evidence is incomplete, the requested scope differs from the proposal, or the tool state is unclear.

Do not self-grant authority or bypass a blocked requirement.

No universal escalation role or decision deadline is specified.

Escalation behavior is not fully specified as a general workflow. Preserve the proposal, risk, evidence, current state, and responsible review context rather than inventing timers, reviewer groups, or automatic reassignment.

Failure behavior

A rejected decision and a policy block should remain distinguishable in state and audit history. Neither outcome should be rewritten as a generic execution failure.

Missing proposal or evidence context can make an approval transition invalid. A rejected action can move the run into rejected. A scaffolded card action on the general Approvals page does not change the authoritative run.

When the UI and runtime state differ, rely on the signed agent-run decision, transition log, action record, and audit event. Keep the page’s Private Alpha and scaffolded-decision labels visible until implementation evidence changes.

A denied action can transition the run to rejected.

If the Approvals page cannot persist a card action, return to the originating agent-run record and verified approval service rather than claiming success.

Failure can occur because approval context is missing, a decision is rejected, the tool is blocked, the run is already terminal, or persistence is unavailable. These paths need different remediation.

The general Approvals route is Private Alpha and its card actions are placeholders; they must not be described as persistable approve or reject decisions.

An approval path can fail because the proposal is missing, the evidence is insufficient for the required transition, the decision is rejected, or the visible control is only scaffolded. Those outcomes require different remediation. Do not convert a missing persistable decision into approval by updating a card label or run status manually.