Glossary
Vocabulary that recurs across the docs. Grouped by where the term first appears in the pipeline.
Tool names
What each client calls each tool type.
| Term | Meaning |
|---|---|
Bash | Claude Code's shell-command tool. The dominant input to tool-gates. |
Monitor | Claude Code's long-running command tool (background tail, watch loops). Gated by the same rules as Bash. |
Read / Write / Edit | Claude Code's file-operation tools. Write and Edit pass through the security-reminders scanner; Read is checked against file guards. |
Glob / Grep | Claude Code's file-search tools. Default tool-blocks redirect to fd / rg. |
Skill / activate_skill | Slash-command activation. Auto-approved via [[auto_approve_skills]] with project-directory conditions. |
apply_patch | Codex CLI's canonical edit tool. Payload is a unified diff in tool_input.command; tool-gates parses out each *** Add/Update/Delete File: header. |
run_command / view_file / write_to_file / replace_file_content | Antigravity CLI (agy) tool names for shell, read, write, and edit. tool-gates maps them onto its Bash / Read / Write / Edit engine. |
run_shell_command | Gemini CLI's shell tool (deprecated). Same engine as Bash on Claude. |
mcp__<server>__<tool> | MCP tool name. Double underscore separator on Claude / Codex; single on Gemini (mcp_*). |
Hook events
When tool-gates fires.
| Term | Meaning |
|---|---|
PreToolUse | Claude Code's primary gate. Decides allow / ask / deny before the call executes. |
PermissionRequest | Claude Code's subagent gate. Subagents ignore PreToolUse's allow; this hook re-applies the same policy. |
PermissionDenied | Auto-mode classifier denied a command; tool-gates checks if its own engine would have allowed it, returns retry: true if so. |
PostToolUse | Fires after execution. Tracks successful asks into the pending queue; scans Write/Edit bodies for Tier 2 anti-patterns. |
Antigravity PreToolUse | Antigravity CLI's single gate hook. No PermissionRequest event and no usable post payload, so PreToolUse runs the whole gate. Selected via --client antigravity. |
BeforeTool | Gemini CLI's single installed hook (deprecated). It covers the main gate path; tool-gates does not install an AfterTool hook because Gemini post output is unused. |
Permission modes
What the assistant is allowed to do without prompting.
| Term | Meaning |
|---|---|
default | Normal gate flow. Known-safe commands can allow, dangerous commands deny, and unknown or mutating commands ask or defer; Codex prompt visibility also depends on approval_policy. |
plan | Read-only planning mode. tool-gates allows read-only exploration but denies Write/Edit/apply_patch and mutating shell asks, defers, unknowns, and unapproved Claude acceptEdits bases. |
acceptEdits | Path-safe file-editing commands can auto-allow inside allowed directories. tool-gates extends this to scoped MCP tools via [[accept_edits_mcp]]; Codex does not currently emit this mode and uses [codex] accept_project_edits separately. |
auto | Claude Code's classifier-driven mode. Asks are decided silently by a server-side classifier instead of prompting. tool-gates promotes hard-asks to deny and emits retry hints when classifier denials disagree with the gate engine. |
bypassPermissions | Client-specific bypass mode. If the client still invokes hooks, tool-gates hard denies and configured block rules remain the floor. |
approval_policy (Codex) | Codex's own axis for whether a tool-gates ask surfaces a prompt: untrusted prompts for every non-safe command, on-request and on-failure lean on the sandbox and mostly don't, never never asks. See the Codex approval model. |
Decisions
What tool-gates returns.
| Term | Meaning |
|---|---|
| Allow | Run without prompting. Read-only and known-safe operations. |
| Ask | Pause for approval (Yes / No, two buttons). Mutations and unknown commands. |
| Block | Deny outright regardless of settings. |
| Defer | Omits permissionDecision entirely. Lets the client's own resolver run, which lights up the third "don't ask again for X" button on Claude Code. |
warn | Marker on an ask rule (warn = true) flagging a dangerous-but-recoverable operation (git push --force, git reset --hard). Surfaces in the Security floor cross-cut. |
Pipeline
How the engine works.
| Term | Meaning |
|---|---|
| Raw-string pass | Pre-AST security checks for pipe-to-shell, eval, head/tail pipe, etc. Runs before tree-sitter; catches patterns the parser would treat as syntactically valid. |
| Hard-ask | An ask the raw-string pass promotes to deny when permission_mode == auto. No legitimate use case in autonomous operation. |
| Hard-deny | Patterns gated by features.head_tail_pipe_block (and similar). Block before the gate engine runs. |
| tree-sitter | The Bash AST parser. tree-sitter-bash extracts CommandInfo with program + args + raw form; handles compound commands. |
CommandInfo | The internal struct each gate handler receives: program, args, raw. |
| Gate | One of 13 specialised handlers. Most logic is declarative TOML; complex cases use a Rust check_* function. |
| Custom handler | A Rust function in gates/<gate>.rs registered via TOML's [[custom_handlers]]. Handles logic TOML can't express (path normalisation, method-aware HTTP, SQL parsing). |
| Strictest wins | For compound commands (&&, ||, |, ;) the harshest per-segment decision becomes the whole-command decision. block > ask > allow > skip. |
Storage and state
Where state lives.
| Term | Meaning |
|---|---|
~/.claude/settings.json | Claude Code permission rules. tool-gates respects every explicit allow / deny / ask before applying its own gate decision. |
~/.codex/hooks.json | Codex CLI hook configuration. |
~/.gemini/config/hooks.json | Antigravity CLI (agy) shared user hook configuration. Keyed by hook name; tool-gates owns the tool-gates entry. Project scope writes .agents/hooks.json. |
~/.gemini/antigravity-cli/settings.json | Antigravity CLI native settings, including the permissions.allow list. tool-gates agy allowlist --apply merges command(<prog>) rules here to stop prompts for read-only commands (a hook allow cannot). Distinct from the hooks file. |
~/.gemini/settings.json | Gemini CLI hook configuration (deprecated). |
~/.config/tool-gates/config.toml | User configuration for feature toggles, tool blocking, MCP / Skill auto-approval, file guards, hints, cache, git aliases. |
~/.cache/tool-gates/pending.jsonl | The pending-approval queue. Successful asks land here for promotion via tool-gates review. |
~/.cache/tool-gates/tracking.json | PreToolUse → PostToolUse correlation (24h TTL). |
~/.cache/tool-gates/available-tools.json | Modern-CLI tool detection cache (7-day TTL). |
~/.cache/tool-gates/hint-tracker.json | Session-scoped deduplication state for modern-CLI hints and security warnings. |
tool_use_id | Claude Code's per-call identifier used to correlate PreToolUse with PostToolUse. Gemini doesn't provide one (so tracking is Claude-only). |
Other
Less common but worth knowing.
| Term | Meaning |
|---|---|
| Subagent | A delegated Claude Code agent. Ignores PreToolUse's allow; the PermissionRequest hook re-applies policy. |
| Worktree | A .claude/worktrees/<id> directory used for subagent isolation. tool-gates auto-approves Edit/Write inside the worktree's cwd. |
| Pattern specificity | Length of the non-wildcard prefix in a settings.json pattern. When ask and allow both match, the longer wins; ties go to ask. |
$HOME expansion | Settings patterns containing $HOME are expanded to the actual home directory before matching. |
| Drift gate | A CI step that runs git diff --exit-code on generated files. Fails the build if a TOML edit didn't trigger a re-run of the generator. |
| Tier 1 / 2 / 3 | The three security-reminder severities. T1 denies source writes before they land and warns on doc-file secrets after write; T2 nudges after via system-reminder; T3 informs via additionalContext. See the Security reminders page. |