permissions

type ApprovalLog ¶

type ApprovalLog struct {
	Tool     string
	Key      string
	Decision Decision
	At       time.Time
}

ApprovalLog is one entry in the gate's per-session approval audit. It records every interactive permission decision the user made (excluding denials) so callers can later offer a "review approvals + recommend" workflow.

type Decision ¶

type Decision int

Decision is the user's choice in an interactive permission prompt.

const (
	DecisionDeny             Decision = iota // reject this call
	DecisionAllowOnce                        // allow this call, ask again next time
	DecisionAllowSession                     // allow this exact request for the rest of the session
	DecisionAllowSessionTool                 // allow EVERY call to this tool for the rest of the session, regardless of args
	DecisionAllowAlways                      // persist a permanent allowlist entry, then allow
)

func (d Decision) String() string

type Gate ¶

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

Gate is the central permission chokepoint consulted before each tool call. It holds the configured policy, the path scope, the bash denylist (built-in), and an optional Prompter for interactive use.

Gate is safe for concurrent use; tool handlers run in the agent's event-iteration goroutine, but the prompter call may yield while waiting for the user.

func FromConfig(cfg *config.Config, projectRoot, userRoot string, prompter Prompter) (*Gate, error)

func New(opts Options) *Gate

func (g *Gate) Approvals() []ApprovalLog

func (g *Gate) CheckBash(ctx context.Context, command string) error

func (g *Gate) CheckFileRead(ctx context.Context, toolName, path string) error

func (g *Gate) CheckFileWrite(ctx context.Context, toolName, path string) error

func (g *Gate) CheckGeneric(ctx context.Context, toolName, key string) error

func (g *Gate) HasPrompter() bool

func (g *Gate) Mode() Mode

func (g *Gate) Scope() *PathScope

type Mode ¶

type Mode string

Mode mirrors the permission modes recognized by config.PermissionsConfig.

const (
	ModeAsk   Mode = "ask"
	ModeAllow Mode = "allow"
	ModeYolo  Mode = "yolo"
)

type Options ¶

type Options struct {
	Mode     Mode
	Policy   *Policy
	Scope    *PathScope
	Prompter Prompter // nil = no interactive path; ask-mode unresolved → deny
}

Options configures a Gate at construction time. All fields are optional; sensible defaults apply when omitted.

type Outcome ¶

type Outcome int

Outcome is the result of consulting the policy. It is used by the gate to decide what to do next; it is not the final say (the gate also consults the bash denylist, the path scope, and the mode).

const (
	OutcomeUnmatched Outcome = iota // no allow/deny rule matched
	OutcomeAllow
	OutcomeDeny
)

type PathScope ¶

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

PathScope restricts file tool access to a defined set of paths: the project root, the user-home root, and any explicit pattern in path_scope.allow. Out-of-scope access escalates to a prompt (in interactive mode) or fails immediately (in headless without a prompter).

Patterns supported in the allow list:

• Exact absolute paths.
• Directory trees ending with `/...` (e.g. "/etc/myapp/...").
• Standard filepath glob patterns (passed through path/filepath.Match).

func NewPathScope(projectRoot, userRoot string, allow []string) (*PathScope, error)

func (s *PathScope) AddAlwaysAllow(pattern string)

func (s *PathScope) AllowList() []string

func (s *PathScope) Contains(path string) (bool, error)

func (s *PathScope) Roots() []string

type Policy ¶

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

Policy interprets the allow/deny pattern lists from .agents/config.json's `permissions` block.

Pattern grammar:

<tool>:<glob>     — applies only when the request is for <tool>
<glob>            — applies to any tool (matched against request key)

`<glob>` is matched with path/filepath.Match, so it understands `*`, `?`, and character classes. The "key" of a request depends on the tool: for bash it is the command string, for file tools it is the resolved absolute path. Wildcards work the same for both.

func NewPolicy(allow, deny []string) (*Policy, error)

func (p *Policy) Match(tool, key string) Outcome

type PromptKind ¶

type PromptKind int

PromptKind classifies what the gate is asking the user about.

const (
	PromptKindBash      PromptKind = iota // mutating shell command
	PromptKindFileWrite                   // file write/edit/create
	PromptKindPathScope                   // file access outside the in-scope roots
	PromptKindGeneric                     // anything else
)

type PromptRequest ¶

type PromptRequest struct {
	Kind        PromptKind
	ToolName    string
	Detail      string // user-facing description (the bash command, the file path, etc.)
	PersistTool string // tool name to use when adding to allowlist (e.g. "bash")
	PersistKey  string // pattern to add to allowlist
}

PromptRequest carries everything the host needs to render a prompt.

The persistence target — what would be written to .agents/config.json if the user picks DecisionAllowAlways — is held in PersistKey/PersistTool so the prompter doesn't have to re-derive it from Detail.

type Prompter ¶

type Prompter interface {
	AskApproval(ctx context.Context, req PromptRequest) (Decision, error)
}

Prompter is implemented by hosts that can interact with the user. Headless callers may pass nil; the gate treats a nil prompter as "no interactive path available".

func StdinPrompter(in io.Reader, out io.Writer) Prompter

y         allow once
s         allow this exact request for the rest of the session
t         allow every call to this tool for the rest of the session
a         allow always (persist to the project's config allowlist)
n / empty deny

type Recommendation ¶

type Recommendation struct {
	Pattern  string   // e.g. "bash:git *", "read_file:internal/tui/**"
	Reason   string   // one-line human explanation of what this covers
	Evidence []string // sample keys that motivated the recommendation
}

Recommendation describes one suggested allowlist entry the user could persist into .agents/config.json's `permissions.allow` block. Pattern is in the existing tool:glob form so a recommendation can be appended verbatim. Reason and Evidence let a picker explain WHY before the user agrees to broaden their permanent allowlist.

func Recommend(approvals []ApprovalLog) []Recommendation