Permissions

@alphacro/agent-permissions

Package: packages/agent-permissions

Permission triad: allowedTools + disallowedTools + canUseTool + permissionMode

Overview

Build the permissions plugin. The plugin contributes a single PreToolUse hook that implements the four-layer permission triad:

1. disallowedTools → deny (highest priority; cannot be overridden)
2. allowedTools → allow
3. canUseTool(call) → allow / deny / defer / ask (runtime decision)
4. permissionMode → mode-specific default (see modes.ts)

Each layer short-circuits the next, matching the Claude Code Agent SDK’s evaluation order. Every decision carries a human-readable permissionDecisionReason for audit logs.

The plugin also implements permissions() so a host that introspects composePlugins(...)’s output can see the gate’s config (used by debug overlays and by hosts that want to compose multiple permission policies before plugging them in).

For complex permission policies that need to compose multiple canUseTool callbacks from different plugins, use {@link composeCanUseTool} to build a single deny-wins evaluator and pass it to createPermissionsPlugin.

Contributions

Contribution	Declared
Tools	❌
Hooks	✅
Sub-agents	❌
Slash commands	❌
HTTP routes	❌
RPC methods	❌
Workflows	❌
Permissions	✅
Tool cards	❌
State slice	❌
Reducer	❌
Session start handler	❌
Session end handler	❌
Startup phase	❌
Dependencies	❌

Hooks

• PreToolUse

Source

• Plugin factory: packages/agent-permissions/src/plugin.ts