controlzero 1.13.11__tar.gz → 1.13.13__tar.gz

{controlzero-1.13.11 → controlzero-1.13.13}/.gitignore

@@ -141,8 +141,21 @@ site/
 
 # Rust
 target/
-Cargo.lock
 *.rlib
+# Cargo.lock is COMMITTED, deliberately. Cargo's guidance is to commit the
+# lockfile for binaries and applications and omit it only for libraries
+# published to a registry. Nothing here is published to crates.io: every
+# package in this repo is either a cdylib/staticlib compiled into the
+# Python/Node SDKs across the FFI boundary (crates/*) or a shipped binary
+# (services/shadow-ai-scout). Both are applications for lockfile purposes.
+#
+# It was ignored until 2026-08-14, which meant every CI run re-resolved
+# dependencies from scratch. A third party publishing a new version could,
+# and did, break main with no commit to this repo: icu_* 2.3.0 shipped with
+# MSRV 1.88 and `cargo clippy` on our pinned 1.86.0 started failing on a
+# tree nobody had touched. It also meant the artifact that was tested was
+# not provably the artifact that shipped, so a dependency audit of one said
+# nothing about the other.
 
 # Python virtual environments
 venv/

{controlzero-1.13.11 → controlzero-1.13.13}/CHANGELOG.md

@@ -1,5 +1,387 @@
 # Changelog
 
+## Unreleased
+
+## 1.13.13 (2026-08-16): a read-class METHOD could satisfy an allow the SQL would deny
+
+**Security fix. If you use a `database:read` allow rule, read this.**
+
+Our own documented read-only-database recipe permitted `DROP TABLE`. Driven
+against the published 1.13.12 wheel, using that page's own policy and its own
+verification command:
+
+    controlzero test database --method query --policy policy.yaml \
+        --args '{"sql":"DROP TABLE users"}'   ->  ALLOW, policy_id=read-only-db
+
+    same policy, no --method                  ->  DENY
+
+The alias table maps `read -> [query, SELECT, ...]`. A caller-supplied
+`method="query"` is itself a read-class alias, so `database:read` was injected
+FROM THE METHOD and satisfied the allow before the SQL extractor's `admin`
+class was consulted. "Most dangerous class wins" is the documented semantics;
+it did not happen whenever a method was supplied -- which is the SDK call shape
+we document (`cz.guard("database", method="query", args={"sql": ...})`).
+
+**Not a regression.** The `query -> read` alias predates the recipe. It has
+never worked. All releases up to and including 1.13.12 are affected.
+
+**Fixed:** when a method-derived class and an argument-derived class are both
+present, the most dangerous now governs. Method-only calls keep legacy alias
+expansion; concrete SQL overrides a stale caller-supplied semantic context.
+Python and Node.
+
+**If you cannot upgrade yet,** put explicit denies ahead of the allow. Verified
+on the vulnerable 1.13.12 build: DROP / DELETE / TRUNCATE / GRANT and the
+`SELECT 1; DROP TABLE x` piggyback all deny, while `SELECT` still allows.
+
+    rules:
+      - id: no-destructive-sql
+        deny: 'database:admin'
+      - id: no-writes
+        deny: 'database:write'
+      - id: read-only-db
+        allow: 'database:read'
+
+A `deny: 'database:admin'` rule was never affected -- it matches the
+argument-derived class regardless of the method. Only the allow-only shape was
+vulnerable.
+
+Tests: 124 explicit cells (31 method modes x 4 SQL classes) plus the four
+literal CLI cases, mirrored in Node. Adding a class or a method alias fails the
+matrix until its cells are filled.
+
+
+## 1.13.12 (2026-08-16): your audit trail now states whether the HOST enforced, and deny rules that never fired now fire
+
+Two things in this release change what a customer can conclude from what we
+ship. Read them before the rest.
+
+**1. The audit row used to claim a block the host never performs (#2113, #2114,
+#2236).** The row is the artefact an auditor reads to decide whether a customer
+was protected. Until this release, every decision row that REACHED the host-event
+branch came out `enforcement_outcome: enforced`,
+`enforcement_reason: host_enforced`, `enforced: True` -- and on the observe-only
+surfaces that was false.
+
+Stated precisely, because the scope matters: this was never all rows. The
+pre-fix `resolve_enforcement` returned earlier and correctly for a non-blocking
+effect (`not_applicable / effect_not_blocking`), a post-execution event
+(`not_enforced / post_execution_event`) and an unknown tier
+(`indeterminate / unknown_tier`), none of which depend on the declaration. The
+rows that were wrong are the ones those guards let through: a blocking effect,
+on a known tier, at a pre-execution event -- which is exactly the population an
+auditor cares about, because it is the set where a block was supposedly imposed.
+
+#2203 taught `resolve_enforcement` to consult each adapter's own
+`CoverageDecl`, then wired it into two of its three consumers: the resolver and
+the deny message. The third -- the audit row -- was missed. `client.py` had been
+reading `raw_event` / `deciding_events` / `observe_events` out of
+`context["cz_enforcement_ctx"]` since #2203, but nothing ever put them there.
+Every row was therefore resolved against an empty
+`EventDeclaration(raw="", deciding=(), observe=())`, `declares_anything` was
+False on every row ever written, so the two declaration-dependent branches --
+`not_enforced / event_declared_observe` and
+`indeterminate / event_not_declared_deciding` -- could not fire at all, and any
+row reaching them fell through to the affirmative default instead.
+
+Driven on pristine `origin/main`, `kiro_cli` + `userPromptSubmit`:
+
+    enforcement_outcome : enforced
+    enforcement_reason  : host_enforced
+    enforced            : True
+
+`KiroCLIAdapter` declares that exact event OBSERVE-ONLY, and kiro-cli 2.16.2 was
+driven answering the prompt after BOTH an exit-2 hook and a structured stdout
+deny. The same row now reads:
+
+    enforcement_outcome : not_enforced
+    enforcement_reason  : event_declared_observe_only
+    enforced            : False
+
+**What this means for you.** Rows already in your audit store that say
+`enforced / host_enforced` for a prompt-submission event on an observe-only host
+are not evidence the call was blocked. Nothing about the host's behaviour
+changed in this release -- kiro-cli did not start or stop enforcing anything.
+What changed is that the record now distinguishes "the host imposed this" from
+"we asked and cannot establish that it was imposed". If you query or alert on
+`enforced`, expect observe-only surfaces to move from True to False, and treat
+that as the field becoming correct rather than as a regression.
+
+**2. A deny rule naming a host tool name was inert on the shipped hook path
+(#2245).** `deny: Read` was accepted by `validate`, previewed as DENY by
+`test`, and silently ALLOWED by the real `controlzero hook-check`. Three
+surfaces told the customer they were protected while the enforcement path
+ignored the rule, and the audit row for the allowed call was byte-identical to
+one written with no rule authored at all. Measured across the shipped security
+template -- 11 template tool names -- the base enforced 4 of 11 bare names; this
+release enforces 11 of 11, and `controlzero test` now agrees with the hook
+because both build the subject through the hook's own factory.
+
+### Changed: what an audit row asserts about enforcement (#2113, #2114, #2236)
+
+- **Enforcement is now bound to the host's own event declaration.** The
+  `cz_enforcement_ctx` keys the audit path has always read are now actually
+  populated, so the per-host branch can fire.
+
+- **An absent enforcement-context key is silence, not an empty declaration
+  (#2218).** "This host declared nothing" and "this host declared an explicitly
+  empty deciding set" are different facts and are now encoded in the TYPE rather
+  than in a flag, so the two cannot collapse into one another.
+
+- **`render()` now receives the host event.** It previously did not, so the WIRE
+  posture was resolved against an empty `EventDeclaration` while the audit row
+  used the real one. A single `hook-check` run could put
+  `indeterminate / event_not_declared_deciding` on the wire and write
+  `enforced / host_enforced` to the row -- two answers to "was the customer
+  protected?" out of one process, on 7 of the 9 shipped adapters. The method's
+  own docstring said this could not happen.
+
+- **`CursorCLIAdapter.render` no longer drops the posture.** Its override could
+  not accept the event pair and rebuilt its `RenderResult` without
+  `enforcement`, silently downgrading the ask-path posture to NOT_FINALIZED. A
+  control applied at one point on one path, hidden in a subclass override.
+
+- **A contradictory declaration is now a named posture, INDETERMINATE.** An
+  adapter declaring one event both deciding and observe was previously resolved
+  by EVALUATION ORDER -- `is_declared_observe()` is tested first, so the observe
+  branch won by position over a contradiction nobody was told about. A
+  contradictory declaration is not evidence the host let the call through, and
+  `_enforcement_notice` now carries a specific line for it that says it is our
+  defect to fix, instead of inheriting the generic "could not confirm" that
+  reads identically to the host merely being unobservable. No shipped adapter is
+  currently self-contradictory, and that is asserted in both directions.
+
+### Fixed
+
+- **A deny rule naming a HOST tool name was inert on the hook path (#2245).**
+  The originally-filed hypothesis -- a colon-less subject -- is REFUTED and
+  pinned as such: every matcher formats `tool:method` unconditionally, and
+  `Read:*` already matched the empty-method subject `Read:`. The real mechanism
+  is an alias-resolution asymmetry: the hook resolved the HOST name to its
+  canonical family name (`Read` -> `file_read`) and discarded the host spelling
+  before the gate ran, while the rule kept the host spelling. `Bash` survived
+  only because it is its own canonical name. The gate is now asked about every
+  name the call actually carried -- the host spelling AND its canonical family
+  name -- and NEVER about sibling aliases, because the alias map is many-to-one
+  and canonicalising the RULE would make `deny: Edit` also block `Write`. Both
+  directions are pinned. The widening ships behind a phase-1 monotone-closing
+  gate: closing flips ship, opening flips are suppressed and counted as
+  `match_semantics=new_suppressed`.
+
+- **The #2245 phase gate could not see the context axis, and a deny became an
+  allow (#2320).** #2245 injects `subject_origin` into the decision context.
+  Rule conditions merge the whole context, so a rule can match on a key that did
+  not exist before -- and `_choose_match`'s monotone-closing gate enumerated the
+  ACTION axis only, so it could not observe a flip caused that way. Driven on
+  `main`:
+
+      base   c99dba92e  rc=2  DENY   policy_id=old-deny     (no match_semantics)
+      main   6dd972815  rc=0  ALLOW  policy_id=origin-allow  match_semantics=unchanged
+      fixed             rc=2  DENY   policy_id=old-deny      match_semantics=new_suppressed
+
+  The audit stamped `unchanged` on the exact call whose effect flipped. That is
+  worse than an absent field: the record actively asserted the false thing. The
+  fix declares, per `SubjectOrigin`, which context keys pre-existed
+  (`PRE_WIDENING_CONTEXT_KEYS`, sourced from the pre-fix tree) and evaluates the
+  rule walk against both contexts. It is a positive set with import-time
+  exhaustiveness, so a new origin is unshippable until declared. `unchanged` is
+  now true BY CONSTRUCTION rather than by assumption, and `match_semantics`
+  gains `indeterminate` for "the pre-widening verdict could not be established".
+  The 11 x 3 action matrix is unchanged at 33/33, so #2245 loses nothing.
+
+- **Kiro sub-agent SPAWNS were not gated at `preToolUse` (#2331).**
+  `_KIRO_V3_PRE_TOOL_MATCHERS` wired `execute_bash` / `fs_write` / `fs_read` /
+  `use_aws` only, so an operator who wrote `deny: use_subagent` had a rule that
+  could not fire. Driven on kiro-cli 2.18.1: with the old matcher list
+  `use_subagent` reached `preToolUse` ZERO times and the sub-agent completed;
+  with the spawn matchers added it reaches `preToolUse` and exit 2 blocks it
+  ("PreToolHook blocked the tool execution").
+
+  **This is admission control in SCOPE, not enforcement in strength**, and the
+  limit was observed rather than theorised: in the same run the model responded
+  to the blocked spawn by doing the identical work through its own
+  `execute_bash`. The Kiro coverage tier stays `partial`.
+
+  **`use_subagent` is the only spawn tool established as real on kiro-cli
+  2.18.1.** The matcher tuple carries five names. Do not read that as five
+  gateable spawn surfaces:
+
+  - `delegate` -- INERT. Experimental and disabled; the binary says so verbatim
+    ("Delegate tool is experimental and not enabled. Use /experiment to enable
+    it").
+  - `agent_crew` -- INERT. Present in the binary's alias table but not exposed.
+  - `spawn_session` -- INERT, and structurally so: it is not a tool name at all
+    but a `command` enum value inside the `session_management` tool, which makes
+    it wrong as a MATCHER rather than merely unused.
+  - `session_management` -- **status NOT ESTABLISHED.** The driven enumeration
+    accounted for the three names above; it recorded nothing either way about
+    this one, and the shipped Kiro template still carries commented guidance
+    naming it. It is neither claimed as coverage nor asserted to be inert here,
+    because neither has been driven. Treat it as unproven until it is.
+
+  Driven: the agent's own tool enumeration returned 13 tools and none of the
+  three named INERT above, and declaring all four explicitly surfaced none of
+  them. They are carried so the matcher is already in place if a future kiro-cli
+  exposes them. Today only `use_subagent` is shown to gate anything, and this
+  release claims nothing more.
+
+- **`controlzero verify --prove` certified enforcement from an exit code we
+  produce (#2305).** Driven on a box where all seven host binaries were ABSENT,
+  with the hook repointed at a script whose entire body is
+  `cat > /dev/null; exit 2`, it reported `[GREEN] claude_code -- effective gate
+  holds + real deny blocked` and `status: ENFORCING`, exit 0. The same shim
+  exiting 0 produced RED, which is what establishes that no host was in the loop
+  at any point. Three states that must never collapse -- ENFORCING /
+  NOT_ENFORCING / UNVERIFIABLE -- were two, and the collapse always resolved
+  optimistically. `ENFORCING` is now reachable from ONE point in one resolver,
+  and the gate there is deliberately NOT "some host evidence exists" -- that
+  weaker gate shipped in the first draft of this module and was refuted, because
+  "a config file has a foreign key" unlocked the same sentence as an executed
+  binary. Evidence licenses NAMED claims, and an affirmative requires the
+  specific `HOST_PRESENT` claim, plus `effective_state_ok` and `probe_blocked`
+  both true -- so the verdict object cannot be constructed while asserting
+  something it does not hold. `HostEvidence` is produced by collectors that read
+  an artifact the HOST emitted, and evidence collected from one adapter cannot
+  certify another. Stated exactly rather than absolutely: this closes the
+  accidental paths, not a determined one -- the private sentinel can be imported
+  deliberately, so this is a chokepoint, not a proof of unforgeability. Also
+  fixed in the same pass: probe
+  errors collapsed into "did not block"; `doctor` rendered a bare all-clear
+  having examined nothing and swallowed reader exceptions; antigravity presence
+  tested a path the installer never writes; and install self-checks claimed a
+  host blocked something.
+
+- **Cross-SDK prompt vocabulary is now pinned (#2331).** Every test asserted one
+  SDK against literals it restated itself, so a rename on either side left both
+  suites green -- the #2071 shape that let #2108 be closed while still live in
+  Python. The Node suite now EXTRACTS the vocabulary from Python source at run
+  time and drives Node against it, asserting an exact-set IFF over a bounded
+  pool rather than one-way containment, with a match-count and uniqueness
+  assertion on every extraction so a moved symbol fails loudly instead of
+  passing vacuously.
+
+### Changed (AUDIT SCHEMA BREAK: the per-finding `masked` boolean is gone)
+
+- **A DLP finding's `masked: True` is replaced by `mask_state` (#2096).**
+  `masked` was stamped from the RULE'S ACTION (`m.action == "mask"`), which is
+  what the rule says to DO -- never evidence that anything was done. A call
+  DENIED on `mask_unsupported_on_host` redacted nothing and never ran, yet
+  produced a findings array byte-identical to one for a call that really was
+  redacted. `args_hash` is taken over the ORIGINAL arguments on every path, so
+  nothing else in the row discriminated either. Established by driving
+  `Client.guard` against pristine `origin/main`: four deny scenarios and one
+  allow scenario all emitted `'masked': True`.
+
+  A boolean cannot carry this truth, so it is now a closed vocabulary, matching
+  the Node SDK exactly and asserted against the shared cross-SDK manifest
+  `tests/parity/dlp_control_outcomes.json`:
+
+  | `mask_state`             | meaning                                                                                                                                       |
+  | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `applied`                | the caller acknowledged consuming the redacted args via `decision.apply_masked_args()`. The ONLY value that asserts that acknowledgement.        |
+  | `declared_not_confirmed` | the SDK redacted into `decision.masked_args` and the caller declared `supports_arg_rewrite=True`; whether it forwards them is not observable.    |
+  | `not_applied`            | a mask rule matched and NOTHING was redacted (the call was denied instead).                                                                     |
+  | `not_applicable`         | the rule's action is `detect`/`block`, or this is a post-execution output observation or a third-party export scan.                              |
+
+  Treat any unrecognised value as NOT `applied`.
+
+  **What `applied` does NOT mean.** It is one link short of "the tool received
+  redacted bytes", deliberately. `apply_masked_args()` emits the record and then
+  returns the args, so a caller can acknowledge and still forward the originals.
+  No value in this vocabulary asserts delivery to the tool, because the SDK
+  cannot observe what the caller does next.
+
+- **`DLPScanner.get_findings_for_audit(matches)` now REQUIRES a second
+  argument**, `mask_state`, and rejects both `"applied"` and any value outside
+  the vocabulary with a `TypeError` before a single finding is built. The
+  posture for an unknown value is REJECT, not downgrade and not pass-through.
+
+- **Every decision audit row now carries `dlp_mask_state`**, including rows with
+  no DLP findings at all (`not_applicable`). Absence is not a state: "no mask
+  was in play" and "a mask fired and was not honoured" are separate, queryable
+  facts.
+
+- **`decision.masked_args` is deep-cloned and frozen** before `guard()` returns.
+  An in-place mutation through the ordinary mapping and sequence operations
+  raises the new, exported `MaskedArgsFrozenError` (a `TypeError` subclass) at
+  the line attempting it, rather than succeeding and leaving the
+  `dlp_mask_applied` record describing bytes the caller never forwarded. Take
+  `dict(decision.masked_args)` for a mutable copy. Chosen over a hash comparison
+  deliberately: a comparison detects the tamper only if someone remembers to
+  call it.
+
+  **The guarantee is BOUNDED, and the bound is stated rather than implied.**
+  Python has no true deep freeze. The protection covers the JSON-shaped tree,
+  which is the only shape a redaction is produced in; it is not a claim that
+  every in-place mutation is impossible. Specifically: a `set` / `frozenset`
+  leaf and a custom mutable object leaf are returned BY IDENTITY, so mutating
+  one the caller still holds does change the tree the acknowledgement returns.
+  Both are left alone deliberately -- neither is JSON-representable, so neither
+  can survive the RFC 8785 canonicaliser or any host envelope, meaning a mask
+  decision cannot legitimately carry one.
+
+### Added
+
+- **`decision.apply_masked_args()`** -- the single producer of
+  `mask_state: "applied"`. Present only on a decision that carries a redaction;
+  `None` everywhere else, so "there is nothing to acknowledge" and "the caller
+  declined to acknowledge" stay distinguishable. Calling it emits a
+  `dlp_mask_applied` audit event carrying `args_hash` + `masked_args_hash` (the
+  pair an auditor joins on to see that the bytes actually changed) and returns
+  the frozen redacted arguments.
+
+- **`controlzero.MaskedArgsFrozenError`** is exported from the package root.
+
+### Known limitations, stated plainly
+
+- The Python SDK's DLP decision fields -- `dlp_findings`, `dlp_status`,
+  `dlp_masked` and now `dlp_mask_state` -- are written to the LOCAL audit log
+  only. `audit_remote._build_wire_entry` is an explicit allowlist and forwards
+  none of them, so none of this is visible in a hosted audit trail today. That
+  is pre-existing behaviour and unchanged here; #2096 corrects what the record
+  SAYS, not where it is shipped.
+
+- The Go SDK's `GetFindingsForAudit` gained the same closed vocabulary, but it
+  still has NO first-party caller: the Go `Guard` attaches no findings to any
+  decision or audit row, so no Go audit row carries a `mask_state`. That is a
+  declared gap, pinned by a test that fails the day anyone wires it up. The Go
+  SDK also left the build on 2026-08-14 (#2291) and is not published from this
+  release.
+
+- **Kiro sub-agent coverage is CONFIG-SCOPED, not absent, and one path stays
+  ungated.** It would be wrong in both directions to say sub-agents were
+  previously ungoverned. Driven on kiro-cli 2.18.1, 19 legs, each with a nonce
+  side-effect proving the call actually ran: a sub-agent that runs an agent
+  config carrying our hooks DOES fire `preToolUse` and `postToolUse` inside the
+  sub-agent (leg G), and a child hook exiting 2 blocks the sub-agent's own tool
+  call (leg J). Hooks resolve from the SUB-AGENT'S OWN config and are not
+  inherited from the parent.
+
+  The genuine gap is leg K: a sub-agent spawned WITHOUT an explicit `agent_name`
+  runs an implicit config that carries no hooks, and setting
+  `chat.defaultAgent` to a hooked agent does not help -- leg K establishes that
+  the implicit agent does not resolve to it, so the path cannot be reached by
+  writing hooks anywhere on disk. That is kiro **#7755**, which is OPEN with no
+  maintainer response and no assignee. Do not cite #7671 for this: it is CLOSED
+  AS COMPLETED, was filed against 0.11.130, and the behaviour it describes
+  ("hooks will not trigger in subagents") is contradicted by the 2.18.1 binary.
+  The vendor documentation still carries that sentence; for a claim about what
+  ships today, the binary outranks the doc.
+
+  Gating the SPAWN is what makes `deny: use_subagent` reachable, and it narrows
+  the ungoverned surface rather than eliminating it.
+
+- **Scope of every driven Kiro claim in this release: kiro-cli 2.18.1 on
+  macOS**, `chat --no-interactive`, `chat.enableSubagent=true`. It is NOT a
+  claim about the whole `>=2.1.0,<3.0.0` range the adapter declares.
+
+- **Kiro matches by ALIAS FAMILY, not literal matcher name.** Observed on
+  2.18.1 in two independent pairs: an `execute_bash` matcher fired on
+  `tool_name` `shell`, and `fs_write` fired on `write`. Each matcher must stay
+  a single tool-name token -- a regex-style `shell|execute_bash` alternation
+  matches a tool LITERALLY named that, which is to say nothing at all, and
+  would silently disable enforcement.
+
 ## 1.13.11 (2026-08-10): kiro_cli prompts were never actually scanned
 
 1.13.10 said "Prompt submission is now a scanned surface on the hosts that
@@ -610,7 +992,7 @@ coverage declaration intentionally remains observe-only.
 
 ### Fixed
 
-- **kiro-cli Windows / non-UTF-8 install crash (Ken Lee report).** `controlzero
+- **kiro-cli Windows / non-UTF-8 install crash (customer report).** `controlzero
   kiro init` captured kiro-cli's output in text mode using the OS locale codec, so
   kiro-cli's UTF-8 output crashed the install's subprocess reader thread on
   non-UTF-8 Windows locales (Korean CP949, Japanese SJIS, Chinese GBK). That crash

{controlzero-1.13.11 → controlzero-1.13.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.13.11
+Version: 1.13.13
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.13.11 → controlzero-1.13.13}/controlzero/__init__.py

@@ -19,7 +19,7 @@ for framework examples (LangChain, LangGraph, OpenAI Agents, Anthropic, CrewAI,
 AutoGen, Pydantic AI, MCP servers, and more).
 """
 
-from controlzero.client import Client
+from controlzero.client import Client, MaskedArgsFrozenError
 from controlzero.errors import (
     PolicyDecision,
     PolicyDeniedError,
@@ -41,10 +41,11 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.13.11"
+__version__ = "1.13.13"
 
 __all__ = [
     "Client",
+    "MaskedArgsFrozenError",
     "PendingApproval",
     "SecretRef",
     "SecretStr",

{controlzero-1.13.11 → controlzero-1.13.13}/controlzero/_internal/action_aliases.py

@@ -87,6 +87,68 @@ for cls, aliases in _CLASSES.items():
     _CANONICAL_TO_LEGACY[canon] = {_canonical(a) for a in aliases}
 
 
+# Conflict-only ordering for a caller method versus the class derived from the
+# concrete SQL arguments (#2340). ``admin`` and ``exec`` are both privileged,
+# top-tier classes: neither may be treated as safer than the other. When they
+# conflict, the argument-derived class wins the tie because it describes the
+# SQL that will actually execute; the caller method is compatibility metadata.
+_DATABASE_CLASS_DANGER: dict[str, int] = {
+    "read": 0,
+    "write": 1,
+    "admin": 2,
+    "exec": 2,
+}
+
+
+def _database_classes_for_action(action: str) -> set[str]:
+    """Return canonical database classes represented by one action."""
+    if not isinstance(action, str) or not action or ":" not in action:
+        return set()
+    tool, method = action.split(":", 1)
+    if tool != TOOL:
+        return set()
+    if method in _DATABASE_CLASS_DANGER:
+        return {method}
+    return {
+        canonical_action.split(":", 1)[1]
+        for canonical_action in _LEGACY_TO_CANONICAL.get(method, ())
+    }
+
+
+def resolve_database_class_conflict(
+    method_action: str,
+    argument_action: str,
+) -> str | None:
+    """Return the sole governing action for a method/argument class conflict.
+
+    ``None`` means there is no explicit conflict to resolve: at least one side
+    is unclassified, or both sides represent exactly the same single class. In
+    those cases callers retain the additive compatibility behavior.
+
+    A returned action is a canonical ``database:<class>``. The evaluator must
+    build candidates from that action alone, making a less-dangerous method
+    alias absent rather than hoping a later deny rule detects it.
+    """
+    method_classes = _database_classes_for_action(method_action)
+    argument_classes = _database_classes_for_action(argument_action)
+
+    # Explicit positive gate: conflict resolution only applies when BOTH
+    # sources carry recognized classes and the argument side is unambiguous.
+    if not method_classes or len(argument_classes) != 1:
+        return None
+    argument_class = next(iter(argument_classes))
+    if method_classes == {argument_class}:
+        return None
+
+    method_class = max(method_classes, key=_DATABASE_CLASS_DANGER.__getitem__)
+    if (
+        _DATABASE_CLASS_DANGER[argument_class]
+        >= _DATABASE_CLASS_DANGER[method_class]
+    ):
+        return _canonical(argument_class)
+    return _canonical(method_class)
+
+
 def expand_candidate_actions(actions: Iterable[str]) -> list[str]:
     """Expand an iterable of candidate actions to include every known alias.
 
@@ -162,4 +224,9 @@ def alias_table_json() -> str:
     return json.dumps(payload, indent=2, sort_keys=False)
 
 
-__all__ = ["TOOL", "expand_candidate_actions", "alias_table_json"]
+__all__ = [
+    "TOOL",
+    "alias_table_json",
+    "expand_candidate_actions",
+    "resolve_database_class_conflict",
+]