Permissions and Safety

How Nimbalyst permissions keep AI agents in bounds by approving file writes and shell commands, and guarding against prompt injection.

This page explains how permissions control what an AI agent can do in your projects: the settings Claude Code brings with it, the trust and approval layer Nimbalyst adds on top, and how to manage both.

Why Permissions Matter

AI agents can execute code, modify files, and run shell commands. Without guardrails, a prompt injection or a mistake could delete files, leak secrets, or run malicious code. Permissions keep you in control.

How Nimbalyst surfaces and enforces agent permissions is covered on the security feature page.

Claude Code's Built-in Permissions

Claude Code uses settings files to define what the agent can do:

• .claude/settings.json - Project settings (shared with team)

• .claude/settings.local.json - Personal project settings (gitignored)

• ~/.claude/settings.json - Global user settings

Each file can specify:

• allow - Patterns that auto-approve

• deny - Patterns that always block

• additionalDirectories - Folders outside the project the agent can access

Nimbalyst reads and honors these files, so permissions you already set up for Claude Code carry over.

What Nimbalyst Adds

Nimbalyst adds a workspace trust layer on top of the coding agent's permissions:

1. Trust Gate - Projects must be explicitly trusted before the agent can do anything

2. Permission Modes - Choose how much autonomy to grant the agent

3. Inline Confirmations - Approve or deny actions as they happen

Permission Modes

When you first use an agent in a project, Nimbalyst presents four autonomy levels:

Mode	Behavior
Agent-verified (Recommended)	Routine work proceeds without interrupting you. Risky or uncertain actions are evaluated by the provider's automatic reviewer and can still require approval.
Allow everything	Operations run without approval prompts or automatic review. Use only in a project and environment you fully trust.
Allow edits only	File edits proceed automatically. Shell commands and web requests ask first.
Ask every time	Approve each agent action before it runs. Your saved approvals are remembered.

Agent-verified is the default. It keeps normal workflows moving while retaining a second review step for destructive or uncertain operations. Claude Agent and OpenAI Codex use their native automatic reviewers behind the same Nimbalyst mode.

Allowing Web Searches in Allow Edits Only

To allow your coding agent to search and fetch websites, add approved domains to the URL allow list in Agent Permissions. You can use wildcard domain patterns such as *.github.com to allow subdomains, or use Allow All Domains when broad web access is appropriate for the project.

The URL allow list in Agent Permissions. Each entry is a domain pattern, such as *.github.com, and Add URL Pattern adds a new one.

How Approval Works in Ask Every Time

When the agent wants to perform an action in Ask every time:

1. An inline confirmation appears with the action details

2. You choose:

• Deny - Block this request.

• Allow Once - Allow only this request.

• Session - Allow the displayed pattern until you close Nimbalyst.

• Always - Save the displayed pattern to .claude/settings.local.json.

Managing Permissions

Open Settings > Project > Agent Permissions to:

• Change your permission mode

• View and remove approved patterns

• Add additional directories

• Reset to defaults

Permissions are project-specific. Giving an agent more autonomy in one repository does not grant the same access in every project.

Pattern Examples

• Bash(git:*) - Allow git commands

• Bash(npm:*) - Allow npm commands

• Edit - Allow file edits

• WebFetch(domain:github.com) - Allow fetching from github.com

Security Notes

• Sensitive paths (~/.ssh, ~/.aws, etc.) are always blocked

• Compound bash commands get one-time patterns that don't persist

• Untrusted projects deny agent actions until you choose a permission mode