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
}

GateDeps bundles the collaborators an ApprovalGate needs. The production binary wires all four; 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 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.