passepartout/org/security-permissions.org

SKILL: Tool Permissions (org-skill-tool-permissions.org)

• Overview: The Authorization Matrix
• Architectural Intent
  • Contract
  • Boundaries
• Implementation
  • Package Context
  • Permission store (tool level)
  • Set permission
  • Get permission
  • Skill Registration
• Test Suite

Overview: The Authorization Matrix

Every cognitive tool (file read, file write, shell execute, etc.) has a permission level: :allow (executed without asking), :ask (user is prompted before execution), or :deny (blocked entirely). Tool Permissions maintains the registry of these levels and provides the permission-gate-check that the Bouncer calls before dispatching a tool action.

The default for any unregistered tool is :ask — cautious by default, permissive by configuration. This prevents a hallucinated tool call from executing without at least giving the user a chance to review it.

Architectural Intent

The Authorization Matrix is the lookup table that maps tool names to permission levels. It is intentionally simple: set, get, default. The complexity lives in the Bouncer (security-dispatcher.org), which consults this table as one of its nine scan vectors.

Contract

1. (permission-set tool-name level): stores level for tool-name in *permission-table*. Tool names are normalized to lowercase.
2. (permission-get tool-name): returns the stored level, or :ask if no entry exists.
3. Tool name matching is case-insensitive — (permission-set :FOO :allow) and (permission-get :foo) return :allow.

Boundaries

• Does NOT enforce permissions — the Bouncer does that.
• Does NOT persist permissions to disk — this is runtime-only.
• Does NOT validate that level is one of (:allow :ask :deny).

Implementation

Package Context

(in-package :passepartout)

Permission store (tool level)

Hash table mapping tool names to their permission level. ;; REPL-VERIFIED: 2026-05-03T13:00:00

(defvar *permission-table* (make-hash-table :test 'equal))

Set permission

Sets the permission level for a specific cognitive tool. ;; REPL-VERIFIED: 2026-05-03T13:00:00

(defun permission-set (tool-name level)
  "Sets the permission level for a tool."
  (setf (gethash (string-downcase (string tool-name)) *permission-table*) level))

Get permission

Retrieves the current permission level for a tool. Defaults to :ask if unset. ;; REPL-VERIFIED: 2026-05-03T13:00:00

(defun permission-get (tool-name)
  "Retrieves the permission level for a tool. Defaults to :ask."
  (gethash (string-downcase (string tool-name)) *permission-table* :ask))

Skill Registration

(defskill :passepartout-security-permissions
  :priority 600
  :trigger (lambda (ctx) (declare (ignore ctx)) nil))

Test Suite

(eval-when (:compile-toplevel :load-toplevel :execute)
  (ql:quickload :fiveam :silent t))

(defpackage :passepartout-security-permissions-tests
  (:use :cl :fiveam :passepartout)
  (:export #:permissions-suite))

(in-package :passepartout-security-permissions-tests)

(def-suite permissions-suite :description "Verification of Tool Permissions")
(in-suite permissions-suite)

(test test-permission-round-trip
  "Contract 1: permission-set stores a level; permission-get retrieves it."
  (permission-set "test-tool" :allow)
  (is (eq :allow (permission-get "test-tool")))
  ;; Clean up
  (permission-set "test-tool" nil))

(test test-permission-default
  "Contract 2: unregistered tools default to :ask."
  (is (eq :ask (permission-get "never-registered-tool-xyz"))))

(test test-permission-case-insensitive
  "Contract 3: tool names are normalized to lowercase."
  (permission-set :CapitalTool :deny)
  (is (eq :deny (permission-get :capitaltool)))
  (permission-set "CapitalTool" nil))