Naming agent actions so rules stay manageable

refund.create, deploy.production, email.send_bulk: a naming convention that lets a handful of rules cover an agent, and the mistakes that make rules leak.

· 6 min read

Every request carries an action name, such as refund.create, and rules match on nothing else but the agent’s key and the amount. Name actions well and five rules cover an agent. Name them badly and you need fifty, or worse, a rule meant for one action quietly covers another.

How a rule matches a name

Exactly as the rule engine does it, no more:

  • A rule without a star matches one name, character for character. email.send does not match email.send_bulk, and Email.Send is a different name.
  • A star may appear only once, at the very end, and means “any name that starts with this”. email.* matches every name starting with email..
  • The star needs no dot before it. crm.delete* matches crm.delete and crm.delete_bulk; email* also matches emailer.retry.
  • A lone * matches everything. A name is at most 200 characters.

There is no star in the middle, so *.production is refused. That one fact shapes the whole convention.

A convention: family, verb, qualifier

Write names in lower case, words joined with underscores, parts joined with dots: family.verb, plus a qualifier when rules must tell cases apart.

refund.create
Family refund, verb create.
email.send_bulk
Size as part of the verb: one name for one, another for many.
deploy.production
The environment as the verb's object.
infra.destroy.production
Verb, then environment, so infra.destroy.* groups every destroy.
data.erase.customer
Qualified by how much judgement it needs.

Since a star only works at the end, put what you want to group by first. If every destroy anywhere should need two people, the verb comes before the environment: infra.destroy.production, matched by infra.destroy.*. If instead everything in production should ask, put the environment first. Pick one order per family and keep it.

Split a name when rules must treat cases differently

The question for every action is: will I ever want to allow one case and ask about another? If yes, they need different names, because a rule cannot look inside the request. The usual splits:

  • Size: email.send and email.send_bulk; db.write.small and db.write.large, by a dry-run count.
  • Environment: deploy.staging and deploy.production.
  • Where money goes: payment.invoice and payee.change_bank_details.

Money is the exception: do not split by amount. Send the amount and currency fields and let rule limits do it.

Mistakes that make rules leak

refund.create.order_4471
Data in the name. No rule can cover it, and a remembered answer applies to that one order. Put ids in the summary and details.
email.* allowed
An allow on a family covers names added later, such as email.send_bulk. Allow exact names; ask and deny by family.
Send_Email
Mixed case and no family. It matches none of the email.* rules.
action chosen by the model
An agent steered by a stranger's text can pick a friendlier name. Let your code choose it.

Over MCP, the model writes the action name itself. Make asking the default by writing no catch-all rules, allow only exact names, and put the actions that matter behind code that names them.

Keep a list in code

A name nobody wrote a rule for still works: it waits for a person. So a typo does not fail open, but it does bypass the rule you meant. A type that lists the names catches the typo before it ships:

/** Every action this agent can ask about. A typo is a type error. */
export type Action =
  | "refund.create"
  | "email.send"
  | "email.send_bulk"
  | "crm.update"
  | "crm.update_bulk"
  | "deploy.staging"
  | "deploy.production";

await approvals.guard({ action: "refund.create" satisfies Action, summary, amount, currency }, act);

Names you do not choose

The Claude Code and Codex hooks name actions by tool, so rules for them use these:

shell.run
Bash: Run the command: …
file.write
Write: Write the file …
file.edit
Edit and MultiEdit: Edit the file …; NotebookEdit: Edit the notebook …
web.fetch
WebFetch: Fetch …
mcp.<server>.<tool>
A tool from an MCP server: Use <tool> from the <server> MCP server
tool.<name>
Any other tool: Use the <name> tool

Remembering an answer from the inbox writes a rule for exactly the request’s name and key, and refuses a name that contains a star. Searching the record takes an exact name or a family such as email.*, so good families make the record easier to read as well. More on what rules can say is on Rules; how to decide which tier each name belongs in is in risk tiers for agent actions.