permission

type ApprovalRequest ¶

type ApprovalRequest struct {
	ID               string // empty on input — Broker.Request assigns one
	AgentID          string // who's asking (root or subagent ID)
	ToolName         string
	ToolInput        []byte // raw JSON; UI summarises to ~200 chars
	InputDescription string // model-supplied `description` field from ToolInput; "" when absent
	Mode             Mode
	Reason           string // from Decide() — why we're asking
	Hint             Hint   // pre-computed classification (Bash only today)
	PlanContent      string // ExitPlanMode-only; markdown plan body
}

ApprovalRequest is what the TUI needs to render the prompt.

PlanContent is non-empty only for ExitPlanMode requests — the tool fills it with the markdown body it read from <workdir>/.evva/plans/current.md so the approval overlay can render the plan inline. Other tools leave it empty; the overlay's plan branch keys off the non-empty check.

InputDescription carries the model-supplied `description` field from the tool input (Bash today; any future tool whose input schema includes a top-level `description` string gets the same treatment). It explains what THIS call is about to do — not what the tool does in general — so it's the right size for a user-facing approval prompt. Empty when the input has no such field; the overlay skips the line.

type Behavior ¶

type Behavior string

Behavior is the outcome of a Rule match or a Decide() call.

const (
	BehaviorAllow Behavior = "allow"
	BehaviorDeny  Behavior = "deny"
	BehaviorAsk   Behavior = "ask"
)

type Broker ¶

type Broker interface {
	// Request blocks until the user responds OR ctx is cancelled.
	// Returns Deny if the context is cancelled (the caller surfaces the
	// ctx error to the LLM as a failed tool call).
	Request(ctx context.Context, req ApprovalRequest) (Decision, error)

	// Respond delivers the user's choice to the blocked Request. Idempotent
	// per id — a second Respond for the same id is a no-op (covers the
	// race where the user clicks while ctx cancellation is already in flight).
	Respond(id string, d Decision) error

	// Cancel discards a pending request without delivering a Decision.
	// Used internally by Request when ctx is cancelled.
	Cancel(id string) error
}

Broker is the back-channel between the gate (blocked tool goroutine) and the TUI (user interaction). When Decide returns BehaviorAsk, the gate calls Request and parks on the reply channel; the TUI later calls Respond with the user's choice.

Implementations are safe for concurrent Request/Respond/Cancel calls. A single Broker is shared by the root agent and all subagents — request IDs disambiguate.

func NewBroker() Broker

type Decision ¶

type Decision struct {
	Behavior Behavior
	Reason   string
	AddRule  *Rule // non-nil when user chose "Allow for this session"
}

Decision is the resolved outcome. Behavior is always Allow or Deny after Decide() returns (Ask is resolved by the Broker before reaching the agent loop). Source is set when the user chose "Allow for this session" so the caller knows where to write the new rule.

func Decide(call ToolCall, mode Mode, store *Store, hint Hint, workdir, memDir string) Decision

type Hint ¶

type Hint struct {
	IsReadOnly  bool
	IsCommonFS  bool
	IsDangerous bool
	Matched     string // entry that triggered the classification, for UI
	Reason      string
}

Hint carries pre-computed classification info from a tool-specific classifier. Today only Bash sets this; other tools see a zero-value Hint.

IsCommonFS marks commands like `mkdir`, `mv`, `cp` — they mutate but at a level the user has typically already approved of when picking `accept_edits`. `default` mode still asks for these.

type Mode ¶

type Mode string

Mode is one of the four permission stances. The model is intentionally small: each mode pins a clear safelist, and the gate's pipeline (deny rules → ask rules → mode safelist → allow rules → ask) is the same across every mode.

• ModeDefault: read-only tools and agent self-coordination (subagent, task_*, todo_*, tool_search, skill, ask_user_question) auto-allow. Bash auto-allows when the classifier reports a read-only command. Everything else asks. Safe for beginners and sensitive work.
• ModeAcceptEdits: ModeDefault + edit/write/notebook_edit auto-allow, plus common filesystem bash commands (mkdir, touch, mv, cp, ln, chmod, chown, rmdir). Best for iterating on code under review.
• ModePlan: same read-only safelist as ModeDefault, plus read-only bash commands via the classifier. Any other non-safelist tool is denied outright (no prompt). Best for exploring a codebase before deciding what to change.
• ModeBypass: every tool call runs with no prompting — except calls matching a deny rule, which are still rejected (deny rules bind in every mode; bypass silences prompts, not prohibitions). Dangerous- command classification still happens and is logged, but never blocks. Use only inside isolated containers or VMs.

const (
	ModeDefault     Mode = "default"
	ModeAcceptEdits Mode = "accept_edits"
	ModePlan        Mode = "plan"
	ModeBypass      Mode = "bypass"
)

func ParseMode(s string) (Mode, bool)

func (m Mode) Next() Mode

func (m Mode) Valid() bool

type OnRequest ¶

type OnRequest func(req ApprovalRequest)

OnRequest is the callback the broker invokes when a new request is created (after the ID is assigned). The TUI subscribes here to render the approval overlay. Set via Broker.(*broker).SetOnRequest before any Request fires.

type PlanModeState ¶

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

PlanModeState collects the per-session state that plan mode needs in order to drive the per-turn <system-reminder> attachment system and restore the prior permission stance on exit.

The struct exists so that every callsite that flips the permission mode — the TUI's Shift+Tab handler, the EnterPlanMode / ExitPlanMode tools, future SDK control messages — funnels through a single side- effect hub (Transition). Without it, side effects (stashing prePlanMode, queuing the exit reminder, resetting reminder counters) end up scattered at every callsite and drift over time. Ports the design of ref/src/utils/permissions/permissionSetup.ts:transitionPermissionMode.

All fields are guarded by an internal mutex; safe for concurrent access from the agent loop and the TUI.

func NewPlanModeState() *PlanModeState

func (s *PlanModeState) AttachmentsSinceExit() int

func (s *PlanModeState) ConsumePendingExitReminder() bool

func (s *PlanModeState) ConsumeReentry() bool

func (s *PlanModeState) HasExited() bool

func (s *PlanModeState) PlanName() string

func (s *PlanModeState) PrePlanMode() Mode

func (s *PlanModeState) RecordAttachmentEmitted()

func (s *PlanModeState) RecordTurnWithoutAttachment()

func (s *PlanModeState) SetPlanName(name string)

func (s *PlanModeState) SetPrePlanMode(m Mode)

func (s *PlanModeState) Transition(from, to Mode)

func (s *PlanModeState) TurnsSinceLastAttachment() int

type Rule ¶

type Rule struct {
	ToolName string
	Content  string
	Behavior Behavior
	Source   Source
}

Rule is one allow/deny/ask entry. ToolName must match a tool's wire name (see internal/tools/name.go). Content is tool-specific — for Bash it's a shell pattern; for Read/Write/Edit it's a path glob; empty means "every call to this tool."

type Source ¶

type Source string

Source tells you where a Rule came from. Used to scope a "Allow for this session" decision: a project rule goes to <workdir>/.evva/permissions.json, a session rule lives in memory only.

const (
	SourceProject Source = "project"
	SourceUser    Source = "user"
	SourceSession Source = "session"
)

type Store ¶

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

Store holds the active set of allow/deny/ask rules across all three Sources. Project + User rules are populated by Load(); Session rules are added at runtime by the broker when the user picks "Allow for this session."

All Store operations are safe for concurrent use — the gate runs in dispatchToolCalls' parallel goroutines.

func NewStore() *Store

func (s *Store) AddSessionRule(r Rule)

func (s *Store) ReplaceAll(rs []Rule)

func (s *Store) Snapshot() []Rule

type ToolCall ¶

type ToolCall struct {
	Name  string
	Input []byte // raw JSON; tool-specific matchers parse what they need
}

ToolCall is the minimum shape Decide() needs to evaluate a rule. The agent loop fills this in from llm.ToolCall before calling Decide.

type Warning ¶

type Warning struct {
	Path string
	Err  error
}

Warning is a non-fatal load error. The caller surfaces these on stderr like memdir / skill warnings; the agent still starts so a malformed permissions.json doesn't brick the session.

func (w Warning) Error() string