# `AgentSessionManager.Policy.Policy`
[🔗](https://github.com/nshkrdotcom/agent_session_manager/blob/v0.8.0/lib/agent_session_manager/policy/policy.ex#L1)

Declarative policy definition for runtime enforcement.

Supports `on_violation` actions: `:cancel`, `:request_approval`, and `:warn`.

# `limit`

```elixir
@type limit() ::
  {:max_total_tokens, non_neg_integer()}
  | {:max_duration_ms, non_neg_integer()}
  | {:max_tool_calls, non_neg_integer()}
  | {:max_cost_usd, float()}
```

# `on_violation`

```elixir
@type on_violation() :: :cancel | :request_approval | :warn
```

# `t`

```elixir
@type t() :: %AgentSessionManager.Policy.Policy{
  limits: [limit()],
  metadata: map(),
  name: String.t(),
  on_violation: on_violation(),
  tool_rules: [tool_rule()]
}
```

# `tool_rule`

```elixir
@type tool_rule() :: {:allow, [String.t()]} | {:deny, [String.t()]}
```

# `merge`

```elixir
@spec merge(t(), keyword() | map()) :: t()
```

# `new`

```elixir
@spec new(keyword() | map()) ::
  {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}
```

# `stack_merge`

```elixir
@spec stack_merge([t()]) :: t()
```

Merges a stack of policies into a single effective policy.

Policies are merged left-to-right (first policy is the base,
subsequent policies override).  Deterministic merge semantics:

- `name`: joined with `" + "` separator
- `limits`: later policies override limit types that appear in both;
  limits unique to either side are preserved
- `tool_rules`: concatenated (all rules apply)
- `on_violation`: the **strictest** action wins (`:cancel` > `:request_approval` > `:warn`)
- `metadata`: deep-merged (later keys override)

Returns a single `%Policy{}`.

## Examples

    {:ok, org} = Policy.new(name: "org", limits: [{:max_total_tokens, 100_000}])
    {:ok, team} = Policy.new(name: "team", tool_rules: [{:deny, ["bash"]}])
    {:ok, user} = Policy.new(name: "user", on_violation: :warn)

    effective = Policy.stack_merge([org, team, user])
    # effective has org token limit, team deny rule, org cancel action
    # (cancel is stricter than warn)

---

*Consult [api-reference.md](api-reference.md) for complete listing*