ory-permissions-onboarding

Onboard Ory Permissions for Agent Tool Calls

Help the user connect Agent Security and roll out explicit native-tool blocks without treating missing grants as denials.

The plugin only reads permissions. It never writes them. The permission model, native-tool blocks, MCP grants, and observe/enforce posture are managed in the Ory Console (Agent Security).

Native policy is simple:

• AgentTool and ShellTool have no users relation.
• Their use permit is !blockedSubjects.includes(subject).
• No matching block means allowed; a matching block means denied.
• observe logs the block and proceeds; enforce vetoes the call.
• MCP permissions and PermissionMode#enforcedSubjects remain grant-based.

1. Connect Agent Security

Copy the connection details shown in the Ory Console under Agent Security:

npx -y -p @ory/claude-code ory-claude configure --project-url <URL> --agent-security-url <URL>

Then inspect the resolved configuration:

npx -y -p @ory/claude-code ory-claude status

Confirm that Agent Security is connected and the public OAuth2 login client is resolved. The plugin needs no workspace privilege or project API key.

2. Review Native Tool Access

npx -y -p @ory/claude-code ory-claude permissions

The report shows:

• The live permission mode and its source.
• The user subject being checked.
• Each built-in native tool as allowed, blocked, or errored.
• A compact allowed/blocked summary for decomposed shell command words.

A fresh project normally reports native tools as allowed. There is no grant coverage step and the local seed writes no baseline AgentTool or ShellTool grants.

3. Add Explicit Blocks in the Console

To block a native tool, write a blockedSubjects relation in the Ory Console:

namespace: AgentTool
object:    <tool name>          e.g. WebFetch
relation:  blockedSubjects
subject:   User:<id>

To block a command word reached through a shell tool:

namespace: ShellTool
object:    <command word>       e.g. curl
relation:  blockedSubjects
subject:   User:<id>