Security & Permissions

hara runs on your machine with your tools, so it's built to be safe by default and to keep a human in the loop.

Approval modes

Mode	Behavior
`suggest` (default)	asks before editing files or running commands
`auto-edit`	edits files freely, still asks before running shell commands
`full-auto`	runs without prompting (used by `-y`, cron, and the gateway)
`plan`	read-only investigation — the model proposes a plan for your approval before anything runs

Set it with --approval, /approval, or hara config set approval <mode> — or cycle with shift+tab in the TUI.

Plan mode

In plan mode the agent gets read-only tools only (read / grep / glob / web) plus one extra: exit_plan. It investigates freely; questions get answered like normal turns. When — and only when — it has a complete, actionable plan, the model itself calls exit_plan: the plan renders as a bordered ╭─ Plan block, and a picker appears —

Yes, and auto-apply edits — switch to auto-edit and execute the plan
Yes, approve each edit — switch to suggest and execute step-by-step
No, keep planning — stay in plan mode and keep refining

Investigation turns that don't produce a plan end quietly back at the prompt, still in plan mode — no nagging. (The handshake mirrors Claude Code's ExitPlanMode and codex's proposed-plan cell.)

Command rules

Pin down exactly which shell commands run unattended with a permissions.json (allow / deny, plus read-only commands that auto-run even in suggest mode):

hara permissions --init             # scaffold a global ~/.hara/permissions.json
hara permissions --init --project   # scaffold .hara/permissions.json (project scope)

Project rules are untrusted by default: they may add deny rules or turn read-only autorun off, but cannot add an allow or enable autorun. HARA_TRUST_PROJECT_CONFIG=1 is required to let a reviewed repository grant access.

Shell sandbox (macOS)

Confine what the shell can touch:

hara --sandbox workspace-write   # writes limited to the working dir
hara --sandbox read-only         # no writes at all

Untrusted content

Output that hara pulls from the outside world — web fetches, file contents — is wrapped and defanged so injected "ignore your instructions" text can't hijack the agent. Sub-agents run read-only by default, closing the approval-gate bypass; the computer (screen-control) tool is never auto-approved.

Secrets

API keys and tokens are stored 0600 (~/.hara/config.json, OAuth token files). Secret-looking paths are denied before normal file-tool approval: .env/.env.*, credential stores, private keys, and private Hara state cannot be read, searched, edited, injected with @file, indexed, checkpointed, or sent as gateway attachments. .env.example, .env.sample, and .env.template remain readable.

Subprocesses get a scrubbed environment and secret-shaped output is redacted. On macOS, Hara also uses Seatbelt to block arbitrary shell reads of existing protected paths. Linux and Windows still apply static admission and built-in tool checks, but arbitrary shell code is not a kernel security sandbox there. HARA_ALLOW_SENSITIVE_FILES=1 is the explicit, launch-time escape hatch for one process. MCP servers and external coding agents are trusted extensions outside this boundary and therefore require confirmation, or HARA_ALLOW_TRUSTED_EXTENSIONS=1 for reviewed automation.

Reporting a vulnerability

Security issues are tracked in the repo's SECURITY.md — please report privately there rather than opening a public issue.