approvals

package
v0.64.4 Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package approvals provides pluggable backends that make (or decline to make) automated tool-approval decisions on behalf of the graith daemon.

The daemon intercepts every agent tool call via a PreToolUse-style hook (gr approve-request) and asks the configured backend to decide. A backend returns one of three decisions:

  • "allow" — let the tool run
  • "block" — refuse it (the agent edge maps this to each agent's vocabulary)
  • "defer" — no opinion; the daemon queues the request for a human

Backends never surface "deny": that agent-edge synonym is normalised to "block" before it leaves a backend (see Normalise). Decisions are binary (allow/block) or absent (defer) — there is no "degraded" analog to the sandbox backend's partial-enforcement flag.

The design mirrors internal/sandbox: a small interface plus a BackendByName switch, with fail-closed Availability so a misconfigured backend is loud at session-create rather than silently ignored.

Index

Constants

View Source 
const (
	DecisionAllow = "allow"
	DecisionBlock = "block"
	DecisionDefer = "defer"
)

Decision values that cross a backend boundary.

View Source 
const (
	BackendPrompt    = "prompt"
	BackendCommand   = "command"
	BackendExternal  = "external" // synonym of command
	BackendLocalmost = "localmost"
	BackendBuiltin   = "builtin"
)

Backend names.

Variables

This section is empty.

Functions

func Normalise 

func Normalise(decision string) string

Normalise maps the agent-edge synonym "deny" to "block" and leaves other values untouched. Every decision that crosses a backend boundary passes through this so a backend returning "deny" cannot silently fall through to the human queue instead of blocking.

Types

type Availability 

type Availability struct {
	CanEnforce bool
	Detail     string
}

Availability reports whether a backend can enforce with the given config. A false CanEnforce fails closed at session-create (Detail explains why).

type Backend 

type Backend interface {
	Name() string

	// Availability reports whether this backend can enforce with the given
	// config. An unavailable backend fails closed at session-create.
	Availability(cfg Config) Availability

	// Decide returns a decision. A "defer" decision (or a non-nil error) means
	// "no opinion — queue for the human"; errors fail-safe to the human, never
	// fail-open to allow. Backends normalise "deny" to "block" before returning.
	Decide(ctx context.Context, req Request, cfg Config) (Decision, error)
}

Backend makes (or declines to make) an automated approval decision.

func BackendByName 

func BackendByName(name string) (Backend, error)

BackendByName returns the backend for a resolved backend name. The name is expected to already be validated (see config.Approvals.ResolveBackend); unknown names are an error. An empty name resolves to the prompt backend.

type Config 

type Config struct {
	Backend       string // effective backend name (already resolved)
	Command       string // command/external command, or a localmost path override
	BuiltinConfig string // path to the localmost-format config.json (builtin backend)
}

Config is the resolved approvals configuration a backend needs. The daemon populates it from config.Approvals; this package does not import config, to avoid an import cycle.

type Decision 

type Decision struct {
	Decision string
	Reason   string
}

Decision is what a backend returns. Decision is one of "allow", "block", or "defer" only.

type Request 

type Request struct {
	RequestID   string
	SessionID   string
	SessionName string
	Agent       string
	ToolName    string
	ToolInput   string
	HookPayload string
}

Request is everything a backend needs to decide. The daemon resolves SessionName/Agent before calling. ToolInput is the full, untruncated tool input JSON; HookPayload is the raw agent hook payload (may be empty).

Source Files

View all Source files

Directories

Path Synopsis
Package localmost is a clean-room, behaviourally-compatible reimplementation of the federicotdn/localmost rule engine.
 Package localmost is a clean-room, behaviourally-compatible reimplementation of the federicotdn/localmost rule engine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.