agent-safe-pipeline / rules

---
description: "Put AgentSafe in front of an agent's writes: register native executors, pin a route to a published policy, start in shadow, and stop on BLOCK and ESCALATE."
globs: **/agentsafe*.yaml,**/agentsafe*.yml,**/agentsafe*.json,infra/azure/agentsafe/**,apps/web/app/docs/agentsafe/**
alwaysApply: false
---

<!-- Generated by Decionis. Installing a newer version replaces this file. -->

# AgentSafe Implementation

AgentSafe puts authorization in front of every write an agent makes. The agent sends its action to AgentSafe instead of the target. Decionis decides the exact action, and AgentSafe runs it once, holds it for a person, or refuses it. AgentSafe decides nothing itself, and the agent never receives a grant or a credential.

Source and full docs: `https://github.com/decionis/agent-safe-pipeline`.

## Pick the shape

- **HTTP interception (`agentsafe proxy`).** Put the gateway in front of an API. Every `POST`, `PUT`, `PATCH` and `DELETE` becomes an intent. On ALLOW it is forwarded byte for byte, once, under a single-use grant. BLOCK is refused, ESCALATE is held. Only `GET`, `HEAD` and `OPTIONS` pass without a decision.
- **Proposal executor (`agentsafe serve`).** Register a handler per action. The handler does the provider call and nothing else.
- **Library (`@decionis/agent-safe-pipeline`).** `SafeExecutor`, `ActionRegistry`, `IntentCapture`, `DecionisGate`, `DecionisGrantVerifier`, `ShadowPipeline` and `AuditRecorder` inside your own service.

```bash
npm install -g @decionis/agentsafe
agentsafe proxy --upstream http://localhost:3000 --port 8080
agentsafe doctor
```

Without a Decionis key the proxy runs a local demo authority with a synthetic policy and says so on every line. With `DECIONIS_API_KEY` and `DECIONIS_TENANT_ID` (or `agentsafe login`) it asks Decionis.

## Register an action

```ts
registry.register("create_payout", {
  parametersSchema: JsonObjectSchema,
  execute: ({ intent, parameters, authorization, dispatch }) =>
    dispatch.run(async (idempotencyKey) => {
      // The provider call, and nothing else. Send idempotencyKey to the provider.
    }),
  reconcile: async ({ idempotencyKey }) => {
    // Read-only: ask the provider what happened to this key. Never send again.
  },
});
```

- Validate parameters with a schema. Never trust fields the agent sends for policy selection.
- Always pass the idempotency key to the provider, and implement `reconcile` as a read-only lookup.
- Credentials come from the runtime per request. Handlers never hold their own.

## The executor contract

New executors follow `agent-safe.executors.native/1` (`spec/executors/native/v1`). Every run ends in exactly one of six outcomes:

| Outcome                   | Meaning                                           | Retry?                               |
| ------------------------- | ------------------------------------------------- | ------------------------------------ |
| `BLOCKED`                 | No valid execution authority reached the executor | Fix the authority first              |
| `HELD`                    | Admitted; the grant waits for the native boundary | No                                   |
| `FAILED_BEFORE_DISPATCH`  | A grant was used and nothing was sent             | Only with a fresh decision and grant |
| `COMPLETED`               | The platform did the action                       | No                                   |
| `DEFINITELY_NOT_EXECUTED` | The platform refused; nothing happened            | Only with a fresh decision and grant |
| `UNKNOWN_AFTER_DISPATCH`  | The write left and the result is unknown          | No; reconcile first                  |

`EffectAdapter` is deprecated. Use `NativeExecutor` with `style: "dispatch"`.

## Pin a route to a policy

A route can select the published Decionis policy that decides it. `action` names what rules match; it does not select a policy.

```yaml
interception:
  routes:
    - path: /decide
      action: payment.decide
      methods: [POST]
      policyId: "<published policy bundle UUID>"
      policyVersion: "<exact published version>"
```

The gateway binds these as `parameters.policy_id` and `parameters.policy_version` before hashing. Fields in the request body cannot override them.

## Roll out

1. **Shadow first.** Shadow records what Decionis would have allowed, held and refused, and executes nothing. `agentsafe status` shows the shadow report.
2. **Review the report** with the policy owner. Change the policy, not the gateway, when outcomes are wrong.
3. **Enforce** with the switch the report names.

## Rules

- Stop on BLOCK and ESCALATE. Never route around AgentSafe through another tool, API, browser or script.
- An unreachable authority is its own state, never a verdict. Do not treat it as ALLOW.
- Never rename ALLOW, ESCALATE or BLOCK, and never map them to other words in code.
- Never put keys, tokens or customer payloads in configuration files, logs or examples.