Designing Agent Tool Permissions So Automation Stays Safe by Default

Giving an AI agent tools — web search, file edits, running scripts — makes it dramatically more useful. It also means a single bad instruction (or a bad model response) can now touch your workspace instead of just producing text. This post covers how we think about permissions for agent tools in Oyren AI.

The core principle: opt-in, scoped, and visible

Every tool an agent can call in Oyren AI follows three rules:

1. Opt-in. No tool is enabled by default beyond read-only search. Editing files, running code, or calling external services requires explicit enablement per workspace.
2. Scoped. A tool that edits files can only touch the workspace it was invoked from — never your whole filesystem, never another user's workspace.
3. Visible. Every tool call the agent makes is logged and shown in the chat transcript, not hidden behind a "thinking" spinner.

What this looks like in practice

interface ToolGrant {
  tool: "web_search" | "edit_file" | "run_script";
  workspaceUuid: string;
  scope: "read" | "write";
}

When an agent wants to edit a file, it doesn't get raw filesystem access — it gets a scoped grant tied to that one workspace, checked on every call, not just at session start. That means revoking a grant mid-session (say, because you're stepping away) takes effect immediately, not after the next login.

Why we didn't just copy a permission model off the shelf

Most agent frameworks treat permissions as a single global toggle: tools are either on or off for the whole session. That's fine for a personal sandbox, but Oyren AI workspaces are often shared, and documents inside them can be sensitive — contracts, research data, internal specs. A model that gets scoped, per-workspace, per-action grants right will hold up under multi-user use; if we get it wrong, it'll show up as either "the agent can't do anything useful" or "the agent did something nobody approved," and both are the wrong tradeoff to make silently.

What's next

We're extending this same grant model to MCP tool servers, so third-party tools plug into the same scoped, visible permission surface as our built-in ones — no separate trust model to reason about.