Approvals & Safety

Kepler classifies every tool call into a risk tier and decides whether to auto-approve, checkpoint, or prompt you for confirmation. This protects your codebase from accidental damage while keeping you in the loop.

Risk Tiers

Every tool call is assigned one of eight tiers. The tier determines what happens before the tool executes.

Tier	Behavior	Examples
`read`	Auto — proceeds silently	`read_file`, `search_code`, `grep`, `list_files`
`sensitive-read`	Prompt required — no default	`read_file` on `.env`, `.pem`, `secrets/*`
`local-edit`	Auto with checkpoint — proceeds but records undo info	`edit_file`, `write_file`, `write_project`
`shell-safe`	Auto — proceeds silently	`ls`, `cat`, `pwd`, `git status`, `npm test`
`shell-medium`	Prompt safe — Enter to approve	`npm install`, `git add`, `pip install`
`shell-dangerous`	Prompt explicit — must type `y`	`rm -rf`, `chmod`, `sudo`, `kill`
`destructive`	Prompt explicit — must type `y`	`delete_file`, `rm -rf /`
`network`	Prompt safe — Enter to approve	`curl`, `wget`, `git clone`, `npm publish`

Tier classification happens locally on your machine — the backend never decides what’s dangerous. This means dangerous intent can’t be hidden behind a friendly description.

Approval Prompt

When Kepler needs your approval, you’ll see a prompt like this:

┌──────────────────────────────────────┐
│  Kepler wants to run: rm -rf node_modules         │
│                                      │
│  [Enter] approve  [y] yes  [s] skip  │
│  [a] always allow  [t] tell me more  │
│  [r] reject  [n] no  [?] help        │
└──────────────────────────────────────┘

Key	Action
`Enter`	Approve (safe prompts)
`y`	Yes, approve
`n`	No, reject
`r`	Reject permanently
`s`	Skip this tool call
`a`	Always allow this tool from this agent
`t`	Show me more context about what’s happening
`?`	Show help for the prompt

Permission Modes

Set the permission mode with --permission-mode <mode> to control how strictly Kepler requires approval.

Mode	Description
`default`	Prompt for anything not pre-approved (safe fallback)
`bypassPermissions`	No approval prompts — all tool calls proceed
`acceptEdits`	Auto-approve file edits, prompt for shell commands
`plan`	Block all write operations — read-only planning mode
`auto`	Use tier-based defaults (see risk tiers above)
`dontAsk`	Never prompt — reject anything that isn’t auto-approved

Freeswim Mode

The --freeswim-open-waters flag (aliases: --freeswim, --yes) skips all approval prompts. Every tool call proceeds without confirmation.

Use this when:

You’re in a trusted environment (e.g., a disposable VM)
You’re running automated benchmarks
You’ve reviewed the agent’s plan and want to execute without delays

Caution: Freeswim mode disables all safety prompts. Destructive commands like rm -rf will execute without warning.

Human-in-the-Loop (HITL)

Kepler supports several HITL patterns beyond the tier system:

/plan / --plan — Start in planning mode. Kepler analyzes the task and presents a structured plan before any code is written. You can accept, request revisions, or cancel.
Diff preview — Kepler shows a diff before applying changes, so you can review exactly what will be modified.
/review — Summarize what changed in the current session.
Trust system — When you use a (always allow), Kepler trusts that tool from that agent for the session. Use /revoke to clear all auto-approvals.

When to Review Carefully

Always review diffs before confirming for:

File deletions
Large-scale renames
Changes to configuration files (.env, package.json, tsconfig.json)
Dependency updates
Security-sensitive files (auth, secrets, credentials)

Approval Log

All approval decisions are logged to .kepler/approvals.log in the project directory. This file is not git-committed by default.

[2025-03-15T10:32:14Z] APPROVED | write_file | src/app/page.tsx | auto
[2025-03-15T10:32:18Z] APPROVED | shell | npm install | prompt-safe
[2025-03-15T10:32:22Z] REJECTED | shell | rm -rf node_modules | prompt-explicit

Sensitive Reads

Kepler treats certain files as sensitive and will prompt for approval before reading them, even though reading is normally auto-approved:

.env, .env.*
*.pem, *.key, *.cert
secrets/**, credentials/**
~/.ssh/*, ~/.aws/*

Shell Command Classification

Shell commands are classified by their risk:

Risk	Examples
Safe (auto)	`ls`, `cat`, `pwd`, `echo`, `git status`, `npm test`, `python --version`
Medium (prompt-safe)	`npm install`, `git add`, `git commit`, `pip install`, `cargo build`
Dangerous (prompt-explicit)	`rm -rf`, `chmod -R`, `sudo`, `kill`, `dd`, `mkfs`, `>:`, `\|` redirects to critical paths

Commands → CLI Flags — Full list of permission-related flags
Getting Good Results → HITL — Best practices for review workflows
Automation & CI/CD — Headless mode auto-approves all tools

Choosing a Model Skills