Policy Guide

Rule shape#

Read a rule as: when this event happens, optionally for this exact tool name, inspect this field, compare it with this operator, then return this severity and message.

{
  "id": "org-block-curl-pipe-sh",
  "enabled": true,
  "locked": true,
  "event": "PreToolUse",
  "tool": "Bash",
  "severity": "error",
  "match": {
    "field": "command",
    "operator": "contains",
    "value": "| sh"
  },
  "message": "Blocked curl piped to shell."
}

Rule id#

The rule id is the stable identifier shown in audit events, evidence exports, dry-run results, and local AgentLint output. Use a short slug such as org-block-curl-pipe-sh. If you publish another rule with the same id from the builder, it replaces that rule in the current policy body.

Event#

The event tells AgentLint when to evaluate the rule. PreToolUse is the most common enforcement event because it runs before a tool action. PostToolUse records after an action. UserPromptSubmit evaluates prompt text when available. Stop runs at the end of an agent session.

Fields#

• 01command: shell command text when present.
• 02file_path: path for read, write, or edit events.
• 03prompt: sanitized user prompt text when available.
• 04tool_name: exact tool name reported by the coding agent.
• 05event: hook event name.
• 06tool_input.command and tool_input.file_path: safe nested payload paths.

Operators#

• 01equals: exact string match. Use when the field value must be identical to the policy value.
• 02contains: substring match. Use for domains, command fragments, and prompt phrases.
• 03starts_with: prefix match. Use for commands or paths with a stable beginning.
• 04ends_with: suffix match. Use for file extensions or suffixes.
• 05glob: shell-style wildcard match, for example src/**/*.py.
• 06path_under: matches a directory and anything inside it.
• 07command_verb: compares the first shell token, for example rm.
• 08package_name: case-insensitive exact package name matching.

Tool names#

Tool names vary by coding agent. In the builder, choose Any to match all tools. In JSON, all-tools matching means the tool field is omitted. Use a preset for common names or enter a custom exact name such as Shell, RunCommand, Search, or FileWrite.

AgentChute does not alias Bash, Shell, and RunCommand yet because different agents may assign different semantics to those names.

Severity#

• 01error blocks locally.
• 02warning allows the action and records an advisory finding.
• 03info records context without interrupting normal adoption.

Match value#

The match value is the string compared by the selected operator. For contains it is a substring such as internal-forbidden.example. For path_under it is a directory such as src/secrets. For command_verb it is the executable name such as rm. For package_name it is the package name without the install command.

Developer message#

The message is the developer-facing explanation shown when the rule fires. Write it as an instruction, not an accusation. Good messages explain the approved path: “Blocked by workspace policy. Use the approved internal endpoint.”

Locked rules#

Locked rules are workspace minimums. Local config may add stricter rules, but it cannot disable, downgrade, or weaken locked workspace policy. Use locked for team standards that should apply everywhere.

Builder to JSON#

The builder is a safe UI for producing the same declarative JSON that AgentLint evaluates locally from cache.

// Builder: Tool = Any
{
  "event": "PreToolUse",
  "severity": "warning",
  "match": { "field": "command", "operator": "contains", "value": ".example" }
}

// Builder: Tool = Custom, Custom tool = RunCommand
{
  "event": "PreToolUse",
  "tool": "RunCommand",
  "severity": "error",
  "match": { "field": "command", "operator": "contains", "value": "| sh" }
}

Required packs#

Required packs reference maintained AgentChute feeds or OSS rule packs. Policy decides what to enforce, feeds provide security intelligence, and AgentLint enforces the cached result locally.