Managing Banned AST Patterns

Ban rules are discovered from two sources, both checked by the preToolUse hook:

1. $HOME/.BANNED_AST.md — global rules that apply to all edits, regardless of project.
2. BANNED_AST.md files in any parent directory of the edited file — can contain multiple rules, scoped to that subtree.

Source 1: Global Ban File ($HOME/.BANNED_AST.md)

Place a BANNED_AST.md in your home directory to define rules that apply globally to every edit. It uses the same multi-rule format as directory-scoped files:

---
name: no-eval
message: "Do not use eval(). It poses a security risk and should be replaced with safer alternatives."
---

(call_expression
  function: (identifier) @fn
  (#eq? @fn "eval"))

Creating a Global Ban

1. Open or create ~/.BANNED_AST.md.
2. Add a rule block with --- frontmatter containing name and message, followed by --- and the Tree Sitter query.
3. Multiple rules can be stacked in the same file, each separated by a new frontmatter block.
4. Validate the rule — see Validating Rules below.

Source 2: BANNED_AST.md Files (Directory-Scoped)

Place a BANNED_AST.md file in any directory to ban patterns for all files at or below that directory. The hook walks up from each edited file's directory to the filesystem root, collecting rules from every BANNED_AST.md it finds.

A single BANNED_AST.md can contain multiple rules, each separated by its own frontmatter block:

---
name: no-eval
message: "Do not use eval(). It poses a security risk."
---

(call_expression
  function: (identifier) @fn
  (#eq? @fn "eval"))

---
name: no-console-log
message: "Avoid console.log() in production code."
---

(call_expression
  function: (member_expression
    object: (identifier) @obj
    property: (property_identifier) @prop)
  (#eq? @obj "console")
  (#eq? @prop "log"))

Each rule section starts with --- frontmatter containing name and message, followed by ---, then the Tree Sitter query body. The next --- begins the next rule.

When to Use Which

• ~/.BANNED_AST.md — personal global bans that apply everywhere regardless of file location.
• BANNED_AST.md — scoped bans for subtrees (e.g. ban any in src/ but allow it in tests/).

When both sources define a rule with the same name, the BANNED_AST.md closer to the edited file takes precedence.

Rule Format

Frontmatter Fields

• name (required): A unique identifier for this ban (lowercase, hyphens ok). This is used in justification comments (<name> justification: ...).
• message (required): The rejection message shown when this pattern is detected. Should explain WHY the pattern is banned and suggest alternatives.

Body

The body contains a Tree Sitter query that matches the banned AST nodes. These use S-expression syntax with optional predicates like #eq? and #match?.

Examples

Global ban file (~/.BANNED_AST.md)

---
name: no-eval
message: "Do not use eval(). It poses a security risk. Use Function constructor or a sandboxed interpreter instead."
---

(call_expression
  function: (identifier) @fn
  (#eq? @fn "eval"))

Multi-rule BANNED_AST.md

Place this in a project directory to ban multiple patterns for all files below it:

---
name: no-console-log
message: "Avoid console.log() in production code. Use a structured logging framework instead."
---

(call_expression
  function: (member_expression
    object: (identifier) @obj
    property: (property_identifier) @prop)
  (#eq? @obj "console")
  (#eq? @prop "log"))

---
name: no-any-type
message: "Do not use the 'any' type. Use 'unknown' or a concrete type instead."
---

(predefined_type) @type
(#eq? @type "any")

Validating Rules

…