# `Cairnloop.Governance.ToolProposal`
[🔗](https://github.com/szTheory/cairnloop/blob/main/lib/cairnloop/governance/tool_proposal.ex#L1)

Durable proposal record capturing a governed tool invocation intent, propose-time
snapshots, and idempotency key. Mirrors the `ReviewTask` idiom exactly (D-20).

Status is denormalized onto the proposal for read-your-writes; the full audit timeline
lives in the append-only `ToolActionEvent` table (D-21).

Phase 16 reserved columns (`attempt`, `oban_job_id`, `result_state`, `result_summary`)
are present but unused in Phase 13 — execution is deferred to Phase 16 (D-22).

Snapshot fields (`input_snapshot`, `scope_snapshot`, `policy_snapshot`) are three
discrete `:map` fields — no opaque blob mixing trust categories (D-24).

# `blocked_changeset`

Changeset for persisting a blocked proposal outcome (scope_invalid / policy_denied).
Sets a non-`:proposed` status while keeping all other validation (D-18, D-23).

# `changeset`

Standard changeset for creating or updating a `ToolProposal`.
Requires: `tool_ref`, `idempotency_key`, `risk_tier`, `approval_mode`, `actor_id`.
Status defaults to `:proposed`.

# `status_values`

Returns the locked Phase 13 proposal status values.
Referenced by `ToolActionEvent` for cross-schema enum validation.

---

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