Permission and Tool Scoping Primitives

One-Line Summary: A harness's permission system — which tools a given agent can use, when they require user confirmation, and which paths/commands are off-limits — is enforced at the harness layer (not the model layer) and is the most important security primitive for any agentic deployment.

Prerequisites: Sub-agents as primitives, hooks and lifecycle events, tool use

What Are Permissions and Tool Scoping?

The model produces a tool call — that is the input to a permission decision, not the decision itself. The harness intercepts the call and asks: is this caller allowed to invoke this tool with these arguments? The decision can be allow, prompt user, or deny. Implemented well, this is a hard gate — no clever prompt can bypass it because the model is not the one making the decision.

Tool scoping has two granularities:

Coarse: which tools is this agent allowed to use at all (the agent's tool list).
Fine: for an allowed tool, which arguments are allowed (e.g., Bash is allowed but rm -rf is denied; Edit is allowed only inside the project root).

Coarse scoping is configuration; fine scoping is policy, usually enforced via hooks.

How They Work

In Claude Code, the layered model:

Tool list per agent — the main agent's settings.json permissions.allow and per-sub-agent tools: field define the coarse scope.
Per-tool decision — permissions declares each tool's default action: auto (allow without prompt), prompt (ask the user), deny. Defaults: Bash/Edit/Write → prompt, Read/Grep → auto, network tools → prompt.
PreToolUse hook — for fine scoping, a hook receives the tool call as JSON and prints a permission decision. Examples: deny git push --force, deny Edit outside the project, deny Bash with arguments containing secrets.
Approval modes — Claude Code supports auto-approval modes for trusted contexts (e.g., CI runs).

Ruflo extends this with policy plugins (ruflo-aidefence) that ship pre-built fine-scoping rules: PII gating, CVE blocking, prompt-injection filtering.

Why It Matters

Reliability and safety are largely permission-engineering problems. An agent loop with the right permission system can handle a model that produces the wrong tool call 5% of the time and still ship reliable behavior. The same loop without permission engineering is a rolling outage.

A second observation: permissions are how you safely give an agent more capability. The way to a powerful agent is not weakening permissions but making them precise — allowing the right operations on the right resources at the right time, denying the rest.

Key Technical Details

Sub-agents should run with strictly fewer permissions than the parent: Following the principle of least privilege. A sub-agent dispatched to summarize a file does not need Bash.
Permission decisions are hard gates in any well-engineered harness: the model cannot self-grant; the harness enforces.
PreToolUse hooks are the primary fine-scoping point: They receive the full tool call and can mutate it (rewrite arguments) before allowing it.
Default-deny is the safe default: Listing what is allowed is safer than listing what is denied.
Network tools deserve special treatment: WebFetch, WebSearch, network-capable MCP servers are higher-risk; many harnesses default-prompt them or scope by domain.
Audit logging: Mature harnesses persist every permission decision (allow/prompt/deny) for incident review.
Permission state interacts with sandboxing: A harness may run tools inside a sandbox (gVisor, container, VM) so that even if permissions are wrong, blast radius is bounded.

How Harnesses & Frameworks Implement This

Harness / Framework	Coarse scoping	Fine scoping
Claude Code	Tool list + `permissions` defaults	`PreToolUse` hooks
Claude Agent SDK	Tool list + per-call hooks	Programmatic
ruflo	Inherits Claude Code + `ruflo-aidefence` policy plugins	Policy WASM kernels
LangGraph	Tool binding per node	DIY via guards
AutoGen	`register_for_execution` per agent	DIY
CrewAI	Tool list per agent	Limited
OpenAI Agents SDK	Per-agent tools + guardrails	`input_guardrails`, `output_guardrails`
Codex CLI	Approval modes (manual/auto/on-failure)	Limited
Cursor	Inline approval prompts	Limited

Connections to Other Concepts

sub-agents-as-primitives.md — Sub-agents are the natural unit of scoping.
hooks-and-lifecycle-events.md — Where fine-scoping is enforced.
prompt-injection-defense-in-harnesses.md — The most common reason fine scoping matters.
pii-gating-and-aidefence.md — A specific class of fine scoping.
../../ai-agent-concepts/07-safety-and-control/authorization-and-permissions.md — Foundational coverage.