Approvals

Kavi includes an approval gateway that intercepts tool calls from agents before they execute. This gives you control over what agents can do, especially for destructive or sensitive operations.

Approval Gateway

When an agent attempts to use a tool (file write, shell command, etc.), the call passes through the approval gateway. The gateway evaluates the call against the current rule set and either:

• Allows it silently (the agent proceeds without interruption)
• Denies it silently (the agent receives a denial and must adapt)
• Prompts the operator for a decision (the call is held pending approval)

The gateway operates transparently -- agents are not aware of the approval mechanism. They simply receive success or failure responses to their tool calls.

Per-Tool Rules

Approval rules are defined per tool and per agent. You can create rules that:

• Allow specific tools unconditionally (e.g., file reads are always safe)
• Deny specific tools unconditionally (e.g., never allow rm -rf /)
• Require approval for specific tools (e.g., prompt before any shell command)

Rules can also be scoped by arguments. For example, you might allow file writes within src/ but require approval for writes to config/ or root-level files.

Pending Approval Inbox

When a tool call requires operator approval, it appears in the TUI's approval inbox. The inbox shows:

• The agent requesting approval
• The tool being called
• The arguments (file path, command, etc.)
• The task context (what the agent is trying to accomplish)

You can approve or deny each request individually, or batch-process multiple pending approvals.

Remember Decisions

When you approve or deny a tool call, you can choose to remember the decision. Remembered decisions create new rules that apply for the remainder of the session:

• Remember allow -- future calls to this tool with similar arguments are auto-approved
• Remember deny -- future calls to this tool with similar arguments are auto-denied

This reduces approval fatigue as the session progresses. Early in a session, you may need to approve several calls, but remembered decisions quickly reduce the number of prompts.

Remembered decisions are stored in the approval rules ledger and persist within the session.

Full-Access Mode

For trusted workflows or when approval prompts are too disruptive, you can start Kavi in full-access mode:

kavi --approve-all

In full-access mode, all tool calls are automatically approved. The approval gateway still logs every call for audit purposes, but no prompts are shown.

Use full-access mode when:

• You trust the agents and the task is low-risk
• You want uninterrupted execution (e.g., running a plan overnight)
• You are working in a sandboxed or disposable environment

Avoid full-access mode when:

• Agents are working with production data or credentials
• The task involves irreversible operations
• You are unfamiliar with the agents' behavior on this type of task

Approval Rules Ledger

All approval decisions (both explicit and remembered) are recorded in the approval rules ledger. The ledger provides:

• A history of every approval decision in the session
• The current active rule set
• Audit trail for security review

The ledger is part of the session's persistent state and can be inspected through the TUI or by examining the session event log.

Default Behavior

Without any custom rules, Kavi's default approval behavior is:

• File reads are allowed
• File writes within the project directory are allowed
• Shell commands prompt for approval
• Network access prompts for approval
• Destructive operations (delete, overwrite) prompt for approval

You can customize these defaults through the project config or by building up remembered decisions during a session.