feat(permission): contextual approval with token-aware prefix matching

[GroovyCarrot]

#3077

What This Does

It replaces the old blanket "Allow for session" permission model with granular, context-aware approvals for bash commands.

How it works

When you run a command like cd /tmp && ls ./src && pwd , the system now:

1. Parses the command into individual context tokens:
   • command:cd , command:ls , command:pwd
   • path:/tmp , path:/repo/src
2. Records per-token grants — when you click "Allow for session", it stores each token independently, not as a single blanket approval
3. Auto-approves future requests where all tokens are already granted:
   • Running ls /repo/src alone → ✅ auto-approved (both command:ls and path:/repo/src were approved)
   • Running pwd alone → ✅ auto-approved ( command:pwd was approved)
   • Running ls /other → ❌ still prompts ( path:/other was never approved)
4. Composes conservatively — a command auto-approves only when both its command tokens AND its path tokens are all approved. Approving rm /tmp/x does not auto-approve rm /repo .
5. Supports config-level allowlists — allowed_commands and allowed_paths in crush.json work the same way, using prefix matching ( command:go satisfies command:go test ).

Unsafe constructs (command substitution $() , backticks, redirects, sh -c , eval , loops, conditionals) are fail-closed — they emit an opaque command!:... token that can only be approved by exact match, never auto-approved. I will probably try to improve on this if I find it occurs frequently enough and without good reason but these scenarios only usually trigger for me when doing some analysis / data collection exercise, or a refactor that affects many files, and in these cases I don't mind just hitting approve.

Changes to the Permission Package

The crux of the changes to the permission system is effectively just adding optional context to the tool permission request and recording that context when it is approved for the duration of the session.

What Changed

Request model — CreatePermissionRequest and PermissionRequest now carry a Contexts []string field. This is opaque to the service — it just checks whether every context token
is satisfied. Tools that don't use it leave it empty.

Session grants — PermissionKey gained a Context string field. When a context-aware tool
is approved for the session, one key is stored per context token ( PermissionKey{SessionID, ToolName, Action, Context} ). Legacy tools still use the old key shape (
PermissionKey{SessionID, ToolName, Action, Path} ).

Resolution flow — Request() now has two auto-approval paths:

• If Contexts is non-empty: every token must be satisfied (by config tokens or prior
session grants)
• If Contexts is empty: falls back to legacy {ToolName, Action, Path} key lookup

Grant recording — GrantPersistent records one key per context token when Contexts is populated, otherwise records the legacy key. The Path field is intentionally omitted from contextual keys because location semantics are captured by path: tokens.

Config matching — allowed_commands and allowed_paths from crush.json are translated at startup into command: and path: tokens and checked first in contextSatisfied() .

Impact on bash tool

This is the primary beneficiary. Before, "Allow for session" on cd /tmp && ls ./src && pwd granted just any use of the bash tool.

Now, each constituent command and path is independently reusable. Approve the chain once, and ls /repo/src runs alone later with no prompt. This is the intended behaviour.

Impact on Other Tools

For edit , write , view , multiedit , etc. — no change at all. They never populate Contexts , so they fall through to the legacy {ToolName, Action, Path} lookup. The old "Allow for session" behaviour is preserved because the legacy lookup is still checked in step 6 of Request() .

What It Enables

This design is tool-agnostic. Any tool can start using Contexts without changing the permission service. If a future tool wants to grant file operations by directory, or Git operations by repository, it just emits the appropriate tokens. The service doesn't need to know what the tokens mean.

---

crush.json example

This is the relevant parts of the config I use

{
  "$schema": "https://charm.land/crush.json",
  "permissions": {
    "allowed_tools": [
      "multiedit",
      "view",
      "ls",
      "grep",
      "write",
      "edit"
    ],
    "allowed_commands": [
      "cd",
      "ls",
      "wc",
      "mkdir",
      "sed",
      "awk",
      "grep",
      "head",
      "tail",
      "find",
      "xargs",
      "tee",
      "touch",
      "go fmt",
      "go build",
      "go test",
      "go run",
      "go doc",
      "go list",
      "go vet",
      "go tool",
      "make",
      "yarn run",
      "yarn build",
      "yarn test",
      "yarn tsc",
      "git status",
      "git log",
      "git diff",
      "git show"
    ],
   "allowed_paths": [
     "/tmp"
   ]
}

[charmcli]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[GroovyCarrot]

I have read the Contributor License Agreement (CLA) and hereby sign the CLA.