Execution Gate Deep Dive
The execution gate is the component that decides whether an action is allowed, denied, or must wait for human approval. No action runs until the gate returns a positive outcome. This aligns with the Faramesh Core Specification v1.0 (DOI: 10.5281/zenodo.18371591) §9 (fail-closed), §10 (decisions and lifecycle), and §16 (MGRP-1 optional profile). This document covers the decision flow, outcomes, reason codes, and decide-only usage.
Role of the gate
The gate sits inside the authorization boundary. Every request passes through:
Canonicalize — Normalize the action into a deterministic form and compute a request hash (or CAR hash).
Profile evaluation (if used) — Check tool allowlists and profile-level rules.
Policy evaluation — Run the policy engine; first matching rule determines the outcome.
Version binding — Attach policy version, profile version, and provenance so the decision is auditable and replayable.
Only then is the outcome returned: EXECUTE, HALT, or ABSTAIN.
Decision outcomes (Spec §10.1)
The spec requires exactly one decision per action:
Outcome | Meaning | What happens |
|---|---|---|
EXECUTE | Action allowed | Executor runs the action; result returned to the caller. |
HALT | Action denied | No execution. Caller receives a denial (e.g. HTTP 403 or error with reason). |
ABSTAIN | Requires human approval | Action is not run yet. Status becomes pending_approval; after a human approves or denies, execution may proceed or be blocked. |
Policy rules use allow / deny / require_approval; they map to EXECUTE / HALT / ABSTAIN. Default: if no rule matches, the outcome is HALT (default deny, Spec §7.3). High-risk upgrade (Spec §8.3): if risk_level is high and the policy would otherwise yield EXECUTE, the final decision is ABSTAIN.
Reason codes
Every decision includes a machine-readable reason code so you can log, alert, or replay correctly:
Code | Meaning |
|---|---|
| A policy rule explicitly allowed the action. |
| A policy rule explicitly denied the action. |
| Policy requires human approval for this match. |
| Tool is not in the execution profile allowlist. |
| No policy rule matched; default is deny. |
| Internal error (e.g. parse failure); fail-closed, so deny. |
| Request body could not be parsed. |
| Request did not match the expected schema. |
These are used in audit logs, DPRs (Decision Provenance Records), and replay.
Decide-only endpoint
You can ask “what would the gate do?” without creating an action record or executing anything:
POST /v1/gate/decide — Request body: same as an action (agent_id, tool, operation, params, context). Response: outcome, reason_code, reason, request_hash, policy_version (or policy_hash), profile info, provenance_id.
Use this for:
Pre-flight checks in your agent or UI.
Testing policy changes (run decide with sample payloads).
Logging “would have been allowed/denied” without persisting an action.
Version-bound decisions
Each decision is bound to:
Policy version (or policy hash) — So you know which policy was active.
Profile version (if profiles are used).
Runtime / server version — Faramesh version.
Provenance ID — Ties the decision to the Merkle chain / DPR for replay and proof.
That way you can later answer “why was this allowed?” and “would the same action be allowed with today’s policy?” (see Cryptographic provenance and replay).
Fail-closed semantics
The gate is fail-closed:
Parse or schema errors → HALT (no execution).
Profile not found → HALT.
Policy engine or internal error → HALT.
So “anything we don’t understand or can’t evaluate” results in deny, not allow.
Relation to authorization boundary and CAR
The execution gate is inside the authorization boundary; it is the logic that produces the allow/deny/approval decision.
It consumes canonicalized actions and request hashes produced by the Canonical Action Representation pipeline, so the same action always gets the same hash and a deterministic decision.
For provenance and replay APIs, see Cryptographic provenance.