feat(permissions): add tool permission policy system

[yai-dev]

Summary

Implements Issue #67 — a rule-based tool permission policy system that intercepts tool calls before execution and supports allow, deny, and ask decisions.

What's included

• @agentrail/capabilities — new permissions/ module with:

  • types.ts — ToolPermissionPolicy, PermissionRule, PermissionMode
  • rule-parser.ts — parses DSL strings like "Bash(git:*)" into PermissionRule[]
  • rule-engine.ts — evaluates deny → ask → allow → default priority chain
  • path-safety.ts — workspaceAnchor validates paths against rootDir using nearest-ancestor traversal
  • shell-safety.ts — isDangerousCommand, isReadOnlyCommand, normalizeBashCommand (converts "git status" → "git:status" so git:* DSL patterns match correctly)
  • All sandboxed file tools (Bash, Read, Write, Edit) and non-sandboxed tools wired to checkPermissions

• @agentrail/core — PermissionDecision type + .checkPermissions() builder method on RuntimeTool; tool-executor enforces the hook after interceptors; RuntimeEvent.permission_request emitted on ask

• @agentrail/app — permissionPolicy? option on createAgentApp / createStreamRoute / createChatRoute; AgentrailPermissionsConfig parsed from agentrail.yaml; configPermissionsToPolicy() exported for converting config → runtime policy

Bash DSL convention

Rules use a verb:args form — Bash(git:*) matches any command starting with git. The tool normalises "git status" → "git:status" before pattern matching so glob patterns work as documented.

Loading from agentrail.yaml

permissions:
  mode: default
  allow:
    - "Bash(git:*)"
    - "Bash(npm:*)"
  deny:
    - "Bash(rm:*)"
  ask:
    - "Write"
    - "Edit"

import { createAgentApp, loadAgentrailConfig, configPermissionsToPolicy } from "@agentrail/app";

const config = loadAgentrailConfig();
const app = createAgentApp({
  permissionPolicy: config.permissions
    ? configPermissionsToPolicy(config.permissions)
    : undefined,
});

Test plan

• pnpm --filter @agentrail/capabilities test -- permissions — rule-engine, path-safety, shell-safety (including Bash DSL colon-convention end-to-end)
• pnpm --filter @agentrail/core test -- tool-executor — deny/ask paths in executor
• pnpm --filter @agentrail/app test — config parsing, configPermissionsToPolicy, assembly-hop (profileCtx.permissionPolicy → CapabilityBuildContext.permissionPolicy)
• pnpm test — full suite green (240 tests across all packages)
• pnpm typecheck — no errors

Closes #67

[gemini-code-assist]

Code Review

This pull request introduces a structured, rule-based tool permission policy system across the Agentrail ecosystem. It adds a checkPermissions hook to the tool execution lifecycle, a new permission_request event for interactive approvals, and a comprehensive rule engine for evaluating access to file and shell operations. Feedback highlights several critical issues in the permission engine, including a wildcard implementation that breaks the Bash DSL for paths containing separators, a policy evaluation order that prevents strict allowlist configurations, and potential cross-platform inconsistencies in path resolution. Additionally, improvements were suggested for regex escaping and shell command normalization to handle various whitespace characters.