approval

package
v0.1.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package approval binds durable user decisions to exact coding operations.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrApprovalRequired means a controlled operation needs an interactive decision.
	ErrApprovalRequired = &Error{message: "coding approval: user approval required", code: "approval_required"}
	// ErrOutcomeUnknown means an earlier operation may have run and cannot be replayed automatically.
	ErrOutcomeUnknown = &Error{message: "coding approval: command outcome is unknown", code: "outcome_unknown"}
	// ErrInvalidResolution means the decision is stale or invalid for the current state.
	ErrInvalidResolution = &Error{message: "coding approval: invalid resolution", code: "invalid_resolution"}
	// ErrJournalCorrupt means approval lifecycle data failed strict replay.
	ErrJournalCorrupt = &Error{message: "coding approval: journal lifecycle is malformed", code: "journal_corrupt"}
	// ErrDenied means policy or the user rejected the operation.
	ErrDenied = &Error{message: "coding approval: command denied", code: "approval_denied"}
)

Functions

This section is empty.

Types

type Choice

type Choice string

Choice is an explicit user response to Review or Unknown state.

const (
	ChoiceAllowOnce    Choice = "allow_once"
	ChoiceAllowSession Choice = "allow_session"
	ChoiceDeny         Choice = "deny"
	ChoiceRetry        Choice = "retry"
	ChoiceMarkFailed   Choice = "mark_failed"
	ChoiceAcknowledge  Choice = "acknowledge"
)

Supported user choices.

type Controller

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

Controller owns every registerable wrapper for approval-controlled tools.

func New

func New(
	ws workspace.Workspace,
	journal Journal,
	resolver Resolver,
	pending PendingRunner,
	policy execution.Policy,
	executor *execution.Executor,
	handlers ...Handler,
) (*Controller, error)

New constructs a controller for one durable session and workspace.

func (*Controller) BeforeTool

func (c *Controller) BeforeTool(ctx context.Context, info agent.ToolCallInfo) agent.ToolDecision

BeforeTool is the agent.WithBeforeTool gate for controlled calls.

func (*Controller) Reconcile

func (c *Controller) Reconcile(ctx context.Context, sink execution.Sink) (State, error)

Reconcile repairs durable completions and processes pending calls until the first review or unknown barrier.

func (*Controller) Resolve

func (c *Controller) Resolve(
	ctx context.Context,
	resolution Resolution,
	sink execution.Sink,
) (State, error)

Resolve applies a user decision to the currently displayed durable state.

func (*Controller) SetPendingResultHook

func (c *Controller) SetPendingResultHook(hook PendingResultHook)

SetPendingResultHook installs the hook applied after an approval-paused controlled call executes. Call it during runtime setup, before the controller is used. Passing nil clears the hook.

func (*Controller) Tool

func (c *Controller) Tool(name string) (agent.Tool, bool)

Tool returns the only registerable wrapper for a controlled handler.

type DetachDecider added in v0.1.9

type DetachDecider interface {
	// Detaches reports whether this call takes the detached path.
	Detaches(call agent.ToolCall) bool
}

DetachDecider is implemented by a DetachedHandler that detaches only for some calls. The controller consults it before taking the detached branch; a call it answers false for runs through the synchronous path, on the same prepared execution. A handler that does not implement it always detaches, which is the monitor's contract.

type DetachedHandler added in v0.1.9

type DetachedHandler interface {
	Handler
	// Detach owns the prepared operation: it either runs it once, from any
	// goroutine, or closes it before returning. ctx is the Tool call's own
	// context, which ends when the call returns; a detached run must strip its
	// cancellation rather than derive from it directly.
	Detach(ctx context.Context, call agent.ToolCall, prepared PreparedExecution) ([]ai.Part, error)
}

DetachedHandler is implemented by a controlled handler whose process run outlives the Tool call that started it. The controller prepares and journals the operation exactly as it does for any controlled call, then hands the prepared execution to the handler and returns the handler's receipt instead of waiting for the process.

type Error

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

Error is a stable approval error with a coding-tool result code.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

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

Is supports errors.Is against the package sentinels.

func (*Error) ToolErrorCode

func (e *Error) ToolErrorCode() string

ToolErrorCode lets coding tools preserve the stable error class without a package dependency on approval.

type Handler

type Handler interface {
	Decl() ai.Tool
	Operation(context.Context, agent.ToolCall) (execution.OperationSpec, error)
	Render(execution.Result, error) ([]ai.Part, error)
}

Handler prepares one controlled tool and renders bounded execution results. A Handler is intentionally not an agent.Tool.

type Journal

type Journal interface {
	Path() []harness.Entry
	Pending() ([]ai.ToolCallPart, error)
	AppendCustom(string, ai.JSON) (string, error)
}

Journal is the durable session surface required by Controller.

type Kind

type Kind string

Kind classifies the action required before conversation continuation.

const (
	StateReady   Kind = "ready"
	StateReview  Kind = "review"
	StateUnknown Kind = "unknown"
)

Controller states.

type PendingResultHook

type PendingResultHook func(context.Context, agent.ToolCall, []ai.Part, bool) ([]ai.Part, bool)

PendingResultHook observes and may replace the result of a controlled tool call after it resumes from the approval boundary. It runs only for calls executed by executePending; direct calls are handled by the agent's normal after-tool hook chain.

type PendingRunner

type PendingRunner interface {
	RunPending(context.Context, agent.ToolCall, execution.Sink) ([]ai.Part, error)
}

PendingRunner executes an uncontrolled pending call with the application's immutable tool/hook snapshot.

type PreparedExecution added in v0.1.9

type PreparedExecution interface {
	Run(context.Context, execution.Sink) (execution.Result, error)
	Close() error
}

PreparedExecution owns one single-use execution plan. Run consumes and closes it; Close abandons it before Run.

type Resolution

type Resolution struct {
	RequestID string
	Choice    Choice
	// Reason is persisted only with a denial so a durable policy decision can
	// render the same model-visible result after recovery.
	Reason string
}

Resolution applies one choice to the currently displayed request.

type Resolver

type Resolver interface {
	ResolveToolCalls(...agent.ToolResolution) error
}

Resolver durably answers selected pending calls.

type Review

type Review struct {
	RequestID string
	Call      agent.ToolCall
	Operation execution.Operation
}

Review describes a current pending operation requiring a user decision.

type State

type State struct {
	Kind    Kind
	Review  *Review
	Unknown *Unknown
}

State is one immutable projection of durable approval state.

func (State) NonInteractiveError

func (s State) NonInteractiveError() error

NonInteractiveError projects a durable state into the fail-fast contract used by non-interactive callers. Interactive callers should render Review or Unknown and pass an explicit Resolution instead.

type Unknown

type Unknown struct {
	RequestID   string
	CallID      string
	Tool        string
	Fingerprint execution.Fingerprint
	Attempt     int
	Pending     bool
	Reason      string
	Recoverable bool
}

Unknown describes an operation that may have started without a durable result. Pending false means the original arguments are unavailable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL