Skip to main content

Rule anatomy

An ActionRail rule set mirrors an agent’s action surface. Rules are scoped first to a tool, then to the arguments that require protection.

tools:
  issue_refund:
    kind: consequential
    args:
      amount:
        policy: amount <= 200
      order_id:
        ground:
          checks:
            - source: billing-production
              query: >-
                SELECT customer_id, status
                FROM orders
                WHERE order_id = %(value)s
              match:
                - column: customer_id
                  ctx: customer_id
                - column: status
                  value: delivered
    write:
      preview: Refund order {order_id} for {amount}
      report_args: []

Tool rule​

Each key under tools must match the name registered in the Console, declared with ActionDefinition, or discovered by a framework adapter.

tools:
  issue_refund:
    kind: consequential

kind: consequential records that the tool can create a material external effect. ActionRail does not rename the tool or alter its argument schema.

A discovered consequential tool without a saved rule remains pass-through. Use Console coverage and agent health to find those gaps before switching to enforcement.

Argument rule​

Each key under args must match a tool argument. An argument can have policy, grounding, or both:

args:
  amount:
    policy: amount <= 200
  order_id:
    ground:
      checks: []

Rules that refer to unknown policy arguments or invalid policy syntax are rejected. Arguments omitted from the rule are not evaluated.

Choose arguments that determine who, what, where, how much, or which external record the action affects. Avoid adding decorative or model-explanation fields to a safety decision unless they are authoritative.

Grounding checks​

ground.checks is an ordered list of independent Source verifications:

ground:
  checks:
    - source: billing-production
      query: SELECT customer_id FROM orders WHERE order_id = %(value)s
      match:
        - column: customer_id
          ctx: customer_id
    - source: refund-ledger
      path: /refunds?order_id={value}
      match:
        - rows: eq
          value: 0

All checks must pass. They are not alternatives, fallbacks, or an ordered “first match wins” list.

Proposed-effect preview​

write.preview describes the effect for local diagnostics, Activity, and review:

write:
  preview: Refund order {order_id} for {amount}

The local Decision.preview can contain rendered argument values. The model-facing preview always replaces values with [redacted].

Activity and review replace values with [redacted] by default. Export a value only through the explicit reporting allowlist:

write:
  preview: Refund [redacted order] for {amount}
  report_args:
    - amount

With this configuration, amount can appear in the control plane and every other placeholder remains redacted.

Reporting is a data-export decision

Treat write.report_args as sensitive configuration. Add an argument only after confirming that its value is appropriate for the Console’s storage, retention, access, and deployment boundary. Source result fields are never exported through this setting.

Outcome composition​

The tool receives one final decision after all configured argument rules run:

block > hold > allow

A grounding block outranks a policy hold. An action is allowed only if every configured evaluation allows it.