# Context

- Agent/Pi: The coding harness that loads and runs this extension
- Author: A person who writes user-level or project-level permission modules
- Approver: The person running the Pi session who sees permission prompts and approves or rejects tool use
- Permission module: A TypeScript module loaded by `pi-permissions` that registers permission hooks
- User-level: In the context of an individual user's machine; typically within `~/.pi/agent` folder
- Project-level: In the context of an individual project/repo/folder; may have project-specific settings/permissions
- Package-level: In the context of an external pi package; may provide its own permissions, similar to extension, skills, etc
- Trusted directory: Pi concept that determines if Pi, and by extension this extension, loads settings that are present in a project/directory
- Permission hook: A registered check that can inspect one tool call and return a permission decision
- Enabled: Whether a permission hook is active for evaluation in the current session branch; newly seen hooks default to enabled
- Permission decision: The terminal result of a permission hook: block or request; hooks return `undefined` when they do not decide
- Request: A permission decision that asks the Approver whether a tool call should proceed
- Guidance: Optional request-specific text an Author adds to a prompt in addition to the hook description
- Highlight: Optional patterns or span-producing callbacks a request provides to emphasize the offending fragment of the tool detail in a prompt; computed only against the proposed command
- Prompt: The text and labels shown to the Approver for a request, in totality
- Approve/Reject: Prompt outcomes where the Approver accepts or rejects an execution
- Edit: A prompt outcome where the Approver rewrites a bash command before execution; implies approval and skips hook re-evaluation
- Note: Approver-authored text attached to a prompt outcome and relayed to the agent alongside the tool result
- Permission root: The directory that contains the permission module or permission package currently handling a hook
- Custom tool: A non-built-in Pi tool registered by an extension
- Program: The effective executable of a simple command, determined after skipping wrappers and variable assignments
- Wrapper: A program whose purpose is to run its argument as a command (e.g. `command`, `sudo`, `env`, `xargs`); skipped when determining the program
- Subcommand: The first non-flag argument of a simple command, after skipping flags that consume a value (e.g. `add` in `git -C /repo add`)