approval

type AlwaysApprovePolicy ¶

type AlwaysApprovePolicy struct{}

AlwaysApprovePolicy returns Required=false for every request — the gate short-circuits and the caller proceeds immediately, no pause, no bus emit.

AlwaysApprove is the test-grade policy that exists for unit tests of the gate's "no approval needed" short-circuit path. The §13 amendment forbids it as a production default — the binary's gate configuration MUST be an explicit operator choice, not a stub fallback. The constructor accepts AlwaysApprove only because a human operator can legitimately want it (a dev-loop sandbox where every tool is allowed); the constructor's invariant is NOT "the policy must require approval" but "the policy must be explicit."

func (AlwaysApprovePolicy) ShouldApprove(_ context.Context, _ *ApprovalRequest) (bool, string, error)

type AlwaysDenyPolicy ¶

type AlwaysDenyPolicy struct {
	// Reason is the operator-facing classification carried on
	// `tool.approval_requested`. Empty defaults to "policy: deny-all".
	Reason string
}

AlwaysDenyPolicy returns Required=true with a fixed Reason for every request — every gated call routes through the approver. Useful in tests; also a reasonable default for a high-security operator posture where every tool call goes through a human.

Because policies are configured at gate construction (the §13 amendment forbids a nil default), the operator's deliberate choice of AlwaysDeny is fail-safe: the worst case is "every call asks an approver," not "every call silently fires."

func (p AlwaysDenyPolicy) ShouldApprove(_ context.Context, _ *ApprovalRequest) (bool, string, error)

type ApprovalDecision ¶

type ApprovalDecision string

ApprovalDecision is the resolution any approval gate eventually receives. `DecisionPending` is the implicit state while a gate is parked; callers never construct it.

const (
	// DecisionPending — the implicit state of a parked approval. A
	// caller that submits `DecisionPending` to `ResolveApproval` is
	// rejected with `ErrInvalidDecision` (a no-op resolution is
	// nonsensical).
	DecisionPending ApprovalDecision = "pending"
	// DecisionApprove — the approver said yes; the gate proceeds.
	DecisionApprove ApprovalDecision = "approve"
	// DecisionReject — the approver said no; the gate returns
	// `*ErrToolRejected`.
	DecisionReject ApprovalDecision = "reject"
)

type ApprovalGate ¶

type ApprovalGate struct {
	// contains filtered or unexported fields
}

ApprovalGate is the V1 concrete approval-gate artifact.

Concurrent reuse contract (D-025): every field below is either set once at construction (deps + closed flag) or is the pending map guarded by mu. There is no per-run state on the struct itself. One gate is safe to share across N goroutines; concurrent_test.go pins N≥128 under -race.

func NewApprovalGate(deps GateDeps) (*ApprovalGate, error)

func (g *ApprovalGate) Close(_ context.Context) error

func (g *ApprovalGate) ResolveApproval(ctx context.Context, token pauseresume.Token, decision ApprovalDecision, reason string) error

func (g *ApprovalGate) RunGuarded(ctx context.Context, req *ApprovalRequest) (json.RawMessage, error)

type ApprovalPolicy ¶

type ApprovalPolicy interface {
	ShouldApprove(ctx context.Context, req *ApprovalRequest) (Required bool, Reason string, Err error)
}

ApprovalPolicy decides, per ApprovalRequest, whether approval is required. A `Required=false` return short-circuits the gate (no pause, no bus emit). `Required=true` parks the call until the approver resolves it.

`Reason` is the operator-facing classification the gate carries on `tool.approval_requested` so the Console can render "Approval required: <Reason>." It is NOT raw user data — operators keep Reason values to a small, stable set (the Phase 56 cardinality rule). The gate trusts the policy here; if Reason ever needs redaction, the policy is the bug.

`Err` is the loud-failure path. A policy that cannot decide (e.g. missing operator configuration; a corrupt rule table) returns a non-nil Err and the gate refuses to invoke — there is NO silent auto-approve fallback (CLAUDE.md §13 amendment).

type ApprovalRequest ¶

type ApprovalRequest struct {
	// Tool is the planner-visible tool description. The gate emits
	// Tool.Name on `tool.approval_requested` so the Console can
	// render "Approve call to <Tool.Name>?".
	Tool tools.Tool
	// Args is the original argument blob the gate will return to the
	// caller post-APPROVE. NEVER published on the bus.
	Args json.RawMessage
	// Identity is the (tenant, user, session) triple the call is
	// running under. The Coordinator's pause record scopes against
	// it; a cross-tenant resolver is rejected with
	// `pauseresume.ErrScopeMismatch`.
	Identity identity.Identity
	// Tags is the caller-supplied classification surface. Operators
	// reach for Tags in `TaggedPolicy` to decide "this is a write to
	// a sensitive endpoint — require approval."
	Tags []string
}

ApprovalRequest is the gate's input: a description of the tool call about to fire. The gate forwards the request to the `ApprovalPolicy`, which returns whether approval is required + a caller-facing Reason. The request's Args field is the ORIGINAL tool args; they NEVER appear on the bus (the redactor sees only the gate's summary payload).

func (r *ApprovalRequest) Validate() error

type ErrToolRejected ¶

type ErrToolRejected struct {
	// Tool is the name of the tool whose call was rejected.
	Tool string
	// Reason is the operator-facing classification the approver
	// supplied (or the policy's pre-emptive reject reason). Free-form
	// but low-cardinality by convention; never raw user data.
	Reason string
	// Identity is the (tenant, user, session) triple the rejected
	// call was running under — preserved so logs / audits can
	// correlate the rejection back to the originating run.
	Identity identity.Identity
}

ErrToolRejected is the typed sentinel `RunGuarded` returns on a REJECT resolution. Callers reach it via `errors.As`. Field set is SafePayload by construction — Tool name + classification reason + identity triple, no caller-controlled arg bytes.

func (e *ErrToolRejected) Error() string

func (e *ErrToolRejected) Is(target error) bool

type GateDeps ¶

type GateDeps struct {
	// Policy decides per-request whether approval is required.
	// Mandatory — there is no silent-auto-approve default
	// (CLAUDE.md §13 amendment).
	Policy ApprovalPolicy
	// Coordinator is the unified pause/resume primitive (Phase 50).
	// Mandatory — RunGuarded parks a pause record on it; an APPROVE /
	// REJECT control event resumes through it.
	Coordinator pauseresume.Coordinator
	// Bus is the event bus the gate emits
	// tool.approval_requested / tool.approved / tool.rejected on.
	// Mandatory — an unobservable gate is a design smell.
	Bus events.EventBus
	// Redactor processes the ToolApprovalRequestedPayload's
	// ArgsSummary before emission. Mandatory — CLAUDE.md §7 rule 6
	// requires audit redaction on every emit path.
	Redactor audit.Redactor
	// Authorizer is the injected resolve-privilege check (Phase 111f,
	// D-203). Mandatory — an approval gate with no resolve privilege
	// check is a misconfiguration, not a permissive mode. Direct
	// construction wires the runtime-vocabulary default
	// (NewIdentityAuthorizer); wire-driven assembly injects the
	// Protocol-side adapter (`internal/server.ProtocolScopeAuthorizer`).
	Authorizer ResolveAuthorizer
}

GateDeps bundles the collaborators an ApprovalGate needs. The production binary wires all five; tests may stub the bus / redactor with in-memory equivalents that satisfy the same interface.

Every field is mandatory — the §13 amendment forbids silent default fallbacks on operator-facing seams. A nil field is rejected at construction (NewApprovalGate returns the matching sentinel).

type IdentityAuthorizer ¶ added in v1.3.0

type IdentityAuthorizer struct{}

IdentityAuthorizer is the package-default, runtime-vocabulary ResolveAuthorizer: a resolving ctx is authorized when it carries

• the pause's ORIGINATING identity tuple (identity.From(ctx) equals PendingInfo.Identity — the steering bridge's shape: the run resolving its own gate after the Protocol edge already vetted the wire caller's RFC §6.3 steering scope), OR
• the elevated fleet-control-scope claim (`registry.WithControlScope` — reused rather than minting a new claim shape; the same trust-based-in-V1 claim the Agent Registry's fleet-control commands consume, with the same audit-trail posture).

Everything else is rejected with a wrapped ErrResolveForbidden — fail closed, no permissive default. Note the Coordinator's own Resume-side identity check still applies AFTER the authorizer (defence in depth): a control-scoped resolver whose ctx identity does not match the pause's triple is rejected by `pauseresume.ErrScopeMismatch`, exactly as before the seam.

IdentityAuthorizer is stateless and safe for concurrent use.

func NewIdentityAuthorizer() IdentityAuthorizer

func (IdentityAuthorizer) AuthorizeResolve(ctx context.Context, pending PendingInfo) error

type PendingInfo ¶ added in v1.3.0

type PendingInfo struct {
	// Tool is the name of the tool whose call is awaiting approval.
	Tool string
	// Token is the pause token the resolver presented.
	Token pauseresume.Token
	// Identity is the (tenant, user, session) triple the gated call
	// is running under — the pause's originating identity.
	Identity identity.Identity
	// Tags is the caller-supplied classification surface from the
	// original ApprovalRequest.
	Tags []string
}

PendingInfo describes the parked approval a resolver is targeting. The gate builds it from its pending entry and hands it to the configured ResolveAuthorizer so the privilege decision can compare the resolving ctx against the ORIGINATING call's identity / shape. No caller-controlled arg bytes ride here — Tool name, token, identity triple, and classification tags only.

type ResolveAuthorizer ¶ added in v1.3.0

type ResolveAuthorizer interface {
	// AuthorizeResolve reports whether the caller represented by ctx
	// may resolve the pending approval described by pending.
	AuthorizeResolve(ctx context.Context, pending PendingInfo) error
}

ResolveAuthorizer is the injected privilege check deciding who may resolve a pending approval (Phase 111f, D-203). `AuthorizeResolve` returns nil to permit the resolution, or an error (conventionally wrapping ErrResolveForbidden) to reject it. The gate calls it after locating the pending entry and BEFORE driving the Coordinator, so an unauthorized resolver never mutates pause state.

Implementations MUST be safe for concurrent use (D-025): one authorizer instance serves every ResolveApproval call on the gate.

type TaggedPolicy ¶

type TaggedPolicy struct {
	// RequireTags lists the tags that, when present on the request,
	// trigger approval. An empty list means "approve nothing"
	// (i.e. every call short-circuits — explicit operator choice).
	RequireTags []string
	// Reason is the operator-facing classification carried on
	// `tool.approval_requested` when the policy fires. Empty
	// defaults to "policy: tagged".
	Reason string
}

TaggedPolicy is the V1 production reference: approval is required when the request's Tags slice contains any tag in RequireTags. An empty RequireTags list means "approve nothing" (the gate short-circuits every call) — explicit operator config, not a stub.

Operators reach for TaggedPolicy when their workflow is "tools marked `sensitive` or `write:prod` go through the approver." More complex flows (per-args predicates, per-identity rules) are post-V1 and live behind a different policy type; the ApprovalPolicy interface is the seam.

func (p TaggedPolicy) ShouldApprove(_ context.Context, req *ApprovalRequest) (bool, string, error)

type ToolApprovalRequestedPayload ¶

type ToolApprovalRequestedPayload struct {
	events.SafeSealed
	// Tool is the tool name the planner / runtime chose; surfaced by
	// the Console as "Approve call to <Tool>?".
	Tool string
	// PauseToken is the unified pause/resume Coordinator's Token —
	// observers correlate this to the `pause.requested` event and the
	// later `pause.resumed` / `tool.approved` / `tool.rejected`.
	PauseToken string
	// Reason is the operator-facing classification the
	// `ApprovalPolicy` returned. Low-cardinality by convention.
	Reason string
	// Tags is the caller-supplied classification surface the policy
	// branched on.
	Tags []string
	// ArgsSummary is the audit-redacted summary of the tool args.
	// The redactor runs over a generic shape (map[string]any) at the
	// gate's emit boundary; secret-shaped values are elided. The
	// post-APPROVE tool invocation uses the ORIGINAL args (held in
	// the gate's pending map), so a redactor that elides a field
	// does NOT corrupt the executed call.
	ArgsSummary any
}

ToolApprovalRequestedPayload is the typed payload for a `tool.approval_requested` event. SafePayload by construction: every field is either runtime bookkeeping or operator-supplied configuration metadata. The ArgsSummary field is the redactor's output, NOT the original args; the original args stay in the gate's pending map and never reach the bus.

type ToolApprovedPayload ¶

type ToolApprovedPayload struct {
	events.SafeSealed
	// Tool is the tool name that was approved.
	Tool string
	// PauseToken correlates with the originating
	// `tool.approval_requested` payload.
	PauseToken string
	// ApproverReason is the optional caller-supplied note attached
	// to the APPROVE submission. Free-form but low-cardinality by
	// convention.
	ApproverReason string
}

ToolApprovedPayload is the typed payload for a `tool.approved` event. SafePayload by construction.

type ToolRejectedPayload ¶

type ToolRejectedPayload struct {
	events.SafeSealed
	// Tool is the tool name that was rejected.
	Tool string
	// PauseToken correlates with the originating
	// `tool.approval_requested` payload.
	PauseToken string
	// Reason is the approver's free-form classification of the
	// rejection. Low-cardinality by convention.
	Reason string
}

ToolRejectedPayload is the typed payload for a `tool.rejected` event. THIS is the master-plan acceptance criterion shape. The rejected RunID + identity triple live on the Event envelope (`Event.Identity`); the payload carries the per-event detail. SafePayload by construction.