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.senddoes not matchemail.send_bulk, andEmail.Sendis 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 withemail.. - The star needs no dot before it.
crm.delete*matchescrm.deleteandcrm.delete_bulk;email*also matchesemailer.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.sendandemail.send_bulk;db.write.smallanddb.write.large, by a dry-run count. - Environment:
deploy.staginganddeploy.production. - Where money goes:
payment.invoiceandpayee.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.