# Agent Permissions

Polyscope runs Claude Code agents with the `--dangerously-skip-permissions` flag. This page explains why, and what we do to mitigate the risks.

## Why Skip Permissions?

Claude Code normally prompts you to approve each potentially dangerous action — writing files, running commands, etc. This interactive approval flow doesn't work well in Polyscope, where multiple agents run in parallel across isolated workspaces. Requiring manual approval for every file edit would defeat the purpose of parallel, autonomous agents.

By using `--dangerously-skip-permissions`, agents can work autonomously without blocking on permission prompts.

## How We Mitigate the Risks

While we can't use Claude Code's built-in permission system, we implement our own safeguards through the Claude Code SDK's `canUseTool` callback.

### Write Tool Directory Jailing

The primary security mechanism restricts all file-writing tools (`Edit`, `MultiEdit`, `Write`, `NotebookEdit`) to a set of allowed directories. Before any write operation executes, Polyscope checks whether the target file path falls within:

1. **The workspace's clone directory** — the isolated copy of your repository
2. **Any linked workspace directories** — other workspaces you've explicitly linked

If the agent attempts to write a file outside these directories, the operation is **blocked** and the agent receives an error message explaining which directories are allowed. These checks use resolved absolute paths to prevent traversal tricks.

### Isolated Workspaces

Each workspace operates on its own clone of the repository (using copy-on-write on macOS). This means an agent's file changes are isolated from your main working copy and from other workspaces. You review and merge changes through PRs, not by the agent writing directly to your source tree.

### Read-Only Mode

For certain operations like [Opinions](/docs/digging-deeper/opinions) analysis, agents run in read-only mode where only `Read`, `Glob`, `Grep`, `WebFetch`, and `WebSearch` tools are available. No file modifications are possible.

### Plan Mode

When plan mode is enabled, agents must submit their plan for your approval before they can execute changes. This gives you a checkpoint to review the agent's intended approach.

## What's Not Covered

These mitigations focus on restricting **where** the agent can write files. They do not prevent all potentially destructive actions:

- **Bash commands are unrestricted** — an agent can still run arbitrary shell commands, including deleting files within (or outside) the workspace directory
- **Git operations** — force pushes, branch deletions, and other destructive git commands are possible if the agent chooses to run them
- **Network access** — agents can make HTTP requests, interact with APIs, and access external services

The system prompt instructs agents to avoid destructive actions and to confirm with you before taking risky steps, but this is a behavioral guardrail, not a technical one. A sufficiently adversarial prompt injection could potentially bypass these instructions.

## Best Practices

- **Review diffs before merging** — always review the changes an agent makes before creating a PR or committing
- **Use plan mode for sensitive work** — enable plan mode when working on critical code to get an approval checkpoint
- **Keep credentials out of the repository** — agents can read any file in the workspace, so avoid committing secrets
- **Monitor agent activity** — watch the activity feed for unexpected commands or file changes