config

Documentation

Overview

Package config loads and layers gatekeeper TOML configuration.

Config is harness-neutral: the same gatekeeper.toml is consulted by the claude, codex, and grok adapters. Paths are resolved with a harness-neutral canonical location plus a back-compatible ~/.claude fallback so existing Claude installs keep working unchanged.

Index

• Constants
• func EnsureGlobalConfig(templatePath string) error
• func GlobalConfigPath() string
• func GlobalOnError() canonical.Decision
• type Config
  • func Load(projectDir string) (*Config, error)
  • func LoadFile(path string) (*Config, error)
  • func (c *Config) OnErrorDecision() canonical.Decision
• type Rule

Constants

const (
	OnErrorAbstain = "abstain" // default: on any gatekeeper error, emit no verdict
	OnErrorDeny    = "deny"    // opt-in hard posture: on any error, emit an explicit deny
)

OnError values for the [on_error] knob.

Functions

func EnsureGlobalConfig

func EnsureGlobalConfig(templatePath string) error

EnsureGlobalConfig copies templatePath to the back-compat global config path (~/.claude/gatekeeper.toml) if no global config already exists (in either the XDG or the ~/.claude location). This provides seamless defaults on first run when installed as a plugin.

func GlobalConfigPath

func GlobalConfigPath() string

GlobalConfigPath returns the back-compatible global config write target, ~/.claude/gatekeeper.toml. Reads prefer the XDG canonical path when present (see resolveGlobalPath); writes stay at ~/.claude so existing Claude installs are undisturbed.

func GlobalOnError

func GlobalOnError() canonical.Decision

GlobalOnError returns the on_error decision from the GLOBAL config alone, best-effort. It returns canonical.Abstain on any problem (no global config, or an unparseable one). It is used on the error paths where the full (global+project) Load could not be trusted but a deployment's global on_error="deny" posture should still be honoured when it is readable.

Types

type Config

type Config struct {
	// OnError controls the verdict emitted on a gatekeeper error (unparseable
	// stdin, missing/unparseable config, bad rule regex, evaluate error,
	// panic). "abstain" (default) emits no verdict so the harness's native
	// permission system decides; "deny" emits an explicit deny. A clean
	// "no rule matched" is NOT an error and always abstains.
	OnError string `toml:"on_error"`
	Rules   []Rule `toml:"rules"`
}

Config is the top-level configuration.

func Load

func Load(projectDir string) (*Config, error)

Load builds the final config by layering the resolved global and project files. A MISSING config file is skipped silently (a clean absence, not an error); an UNPARSEABLE config file returns an error so the caller can apply its on_error posture. Later layers (project) override earlier (global) for scalar fields like on_error; rules accumulate.

func LoadFile

func LoadFile(path string) (*Config, error)

LoadFile parses a TOML config from the given path.

func (*Config) OnErrorDecision

func (c *Config) OnErrorDecision() canonical.Decision

OnErrorDecision returns the canonical decision to emit on a gatekeeper error, per the on_error knob. Any value other than "deny" (including the empty default and an unrecognised value) resolves to Abstain — the safe posture that never decides FOR the native permission system.

type Rule

type Rule struct {
	Tool              string `toml:"tool"`
	Input             string `toml:"input"`
	Decision          string `toml:"decision"`
	Reason            string `toml:"reason"`
	Precondition      string `toml:"precondition,omitempty"`
	PreconditionMatch string `toml:"precondition_match,omitempty"`
}

Rule is a single permission rule.