# Per-Action Approval Thresholds in OpenMontage's Budget Governance System

> Discover OpenMontage's per action approval thresholds. Configure default limits to manage budget governance effectively and prevent excessive spending.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: deep-dive
- Published: 2026-08-30

---

**OpenMontage enforces a default per-action approval threshold of $0.50 USD that triggers a warning when any single operation exceeds this limit, configurable via `single_action_approval_usd` in the `CostTracker` class or project configuration files.**

The budget governance system in OpenMontage prevents runaway costs by evaluating every individual action against a per-action spending cap. This mechanism ensures that expensive operations receive explicit approval before execution, protecting project budgets from unexpected spikes caused by high-cost API calls or compute-intensive pipeline steps.

## How Per-Action Approval Thresholds Work

OpenMontage implements per-action approval thresholds through the `CostTracker` class located in [`tools/cost_tracker.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/cost_tracker.py). When the `reserve()` method estimates costs for an operation, it compares the amount against the `single_action_approval_usd` parameter.

**Default limit:** The system sets a hard default of **$0.50** per individual action. This value is defined in [`lib/config_model.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/config_model.py) at line 39 and documented in [`docs/ARCHITECTURE.md`](https://github.com/calesthio/OpenMontage/blob/main/docs/ARCHITECTURE.md) at line 358.

**Warning trigger:** If an operation's estimated cost exceeds the threshold, the tracker sets `entry["budget_warning"]` to `True` and populates `entry["budget_warning_message"]` with "single-action threshold $0.50 exceeded" (see implementation in [`tools/cost_tracker.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/cost_tracker.py), lines 47-54).

## Configuring the Approval Threshold

You can override the default $0.50 limit at instantiation or through project configuration.

### Via CostTracker Instantiation

Pass the `single_action_approval_usd` parameter when creating a `CostTracker` instance:

```python
from tools.cost_tracker import CostTracker, BudgetMode

# Override the per-action threshold to $2.00

tracker = CostTracker(
    budget_total_usd=10.0,
    mode=BudgetMode.WARN,
    single_action_approval_usd=2.00,
)

estimated_cost = 1.75
entry = {}
tracker.reserve(entry, estimated_cost)     # No warning, because 1.75 < $2.00

print(entry.get("budget_warning", False)) # → False

```

### Via Configuration File

The threshold can also be set globally in the project's [`config.yaml`](https://github.com/calesthio/OpenMontage/blob/main/config.yaml) file, which the configuration model ([`lib/config_model.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/config_model.py)) loads at runtime.

## Practical Implementation Examples

When using the default $0.50 threshold, any operation exceeding that amount triggers governance warnings:

```python
from tools.cost_tracker import CostTracker, BudgetMode

# Create a tracker with the default per-action threshold ($0.50)

tracker = CostTracker(budget_total_usd=10.0, mode=BudgetMode.WARN)

# Simulate an operation that costs $0.75

estimated_cost = 0.75
entry = {}
tracker.reserve(entry, estimated_cost)     # Will set entry["budget_warning"] = True

print(entry["budget_warning_message"])

# → "single-action threshold $0.50 exceeded"

```

## Source Code Architecture

According to the OpenMontage source code, the per-action approval mechanism spans three critical components:

- **[`tools/cost_tracker.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/cost_tracker.py)** — Contains the `CostTracker` class and its `reserve()` method, which implements the threshold comparison logic and warning generation.

- **[`lib/config_model.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/config_model.py)** — Defines the data model default with `single_action_approval_usd = 0.50` at line 39.

- **[`docs/ARCHITECTURE.md`](https://github.com/calesthio/OpenMontage/blob/main/docs/ARCHITECTURE.md)** — Documents the budget governance system and its default thresholds at line 358.

## Summary

- **Default threshold:** OpenMontage limits individual actions to $0.50 USD by default through the `single_action_approval_usd` field.
- **Warning system:** The `CostTracker.reserve()` method marks entries with `budget_warning = True` when costs exceed the threshold.
- **Configurable:** Override defaults via constructor parameters or [`config.yaml`](https://github.com/calesthio/OpenMontage/blob/main/config.yaml).
- **Source locations:** Core logic resides in [`tools/cost_tracker.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/cost_tracker.py) (lines 47-54) with defaults defined in [`lib/config_model.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/config_model.py) (line 39).

## Frequently Asked Questions

### What happens when a single action exceeds the per-action approval threshold?

When an operation's estimated cost exceeds the `single_action_approval_usd` value (default $0.50), the `CostTracker` sets the entry's `budget_warning` flag to `True` and attaches a warning message. In `BudgetMode.WARN`, execution continues but logs the violation; in stricter modes, this could block execution pending approval.

### Can I disable per-action approval thresholds entirely?

While you cannot completely disable the check without modifying the source code, you can effectively neutralize it by setting `single_action_approval_usd` to an arbitrarily high value (e.g., `999999.00`) when instantiating `CostTracker` or in your [`config.yaml`](https://github.com/calesthio/OpenMontage/blob/main/config.yaml) configuration file.

### Where is the default $0.50 value defined in the codebase?

The default value of $0.50 is hard-coded in [`lib/config_model.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/config_model.py) at line 39 within the configuration data model. This default is also referenced in the project documentation at [`docs/ARCHITECTURE.md`](https://github.com/calesthio/OpenMontage/blob/main/docs/ARCHITECTURE.md) line 358 and enforced in the validation logic within [`tools/cost_tracker.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/cost_tracker.py).