Design decisions on madtea

ADR 0015 - One MCP tool per resource noun, action-dispatched

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1693 OperationSpec registry, 1695 action enum, 1646 call-time git-repo check)

Context

madtea’s MCP server must expose the full Forgejo/Gitea API surface to an agent. Naively mapped, this is upwards of 200 discrete operations across a dozen resource domains. Two competing pressures shape the design:

An agent’s tool-picker is a search space. Every additional tool the model must discriminate among adds latency and increases mis-selection probability. A 200-tool surface is impractical.
A single opaque “call anything” tool loses discoverability. Without structure, an agent cannot learn what operations are available without reading extensive prose; it cannot self-correct from a bad choice; and the schema cannot carry per-operation constraints.

The existing madt_api_call passthrough tool fills the second role when needed, but it carries no first-class operation semantics — it is the escape hatch, not the primary surface.

ADR 0013 - Secure-backend-preferred credential storage

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1726, 1753, 1765; 1718 / ADR 0009)

Context

madtea authenticates to a forge with a token; where and how it is stored sets the blast radius of a leak. Several incidents shaped the model: plaintext tokens written even under a secure backend, a token exposed by git config --get-regexp, and a token read from the wrong git-config scope so the wrong ciphertext was decrypted.

ADR 0011 - Cross-platform support is first-class

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1759, 1731 Linux-assumption regressions); release/install overhaul epic

Context

madtea ships binaries for linux, macOS, and windows (GoReleaser builds linux_{amd64,arm64}, darwin_{amd64,arm64}, windows_amd64). Yet the code carried Unix-only assumptions that surfaced only as Windows bugs:

internal/safeio fsynced the parent directory after a rename — legal on POSIX, unsupported on Windows (FlushFileBuffers on a directory handle errors), so every credentialed write failed on Windows.
internal/selfreplace relied on os.Rename overwriting an existing destination — POSIX-atomic, but Windows refuses, and a locked running .old image blocked the self-update.
madtea install hardcoded /usr/local/bin + sudo cp/chmod — meaningless on Windows.

Each was caught late (by a user on Windows, or by a manual GOOS=windows build during review) because CI only builds and tests on linux (golang:1.26-alpine). The implicit default was “Unix,” and nothing structurally enforced otherwise.

ADR 0024 - Commit file sets are declared, never swept

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-10
Tracking: internal pre-Codeberg tracker (1981)

Context

madt_commit and madt_finish (and madt_add) once offered a blanket-staging mode — all=true on the MCP surface, -A/--all on the CLI — that ran the equivalent of git add -A before committing: stage every modified, deleted, and untracked path in the worktree, then commit the lot. It sat beside the declared form (files=[...] on MCP, --files on CLI), which stages and commits only the named paths.

ADR 0018 - internal/diag is the sole diagnostics emitter

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1528 diagnostics visibility epic, 1549 migration, 1550, 1548)

Context

madtea ships as both a CLI binary and an MCP server (ADR 0014). The two surfaces have different output channels:

CLI: user-facing warnings, notices, and errors go to os.Stderr. ANSI color is appropriate when a TTY is detected.
MCP tool call: there is no stderr the agent can see. Diagnostics must be captured and delivered inside the tool result — a severity-prefixed block that the agent reads as part of the response.

Before the diagnostics visibility work, every warning or notice in the codebase was written as a raw fmt.Fprintf(os.Stderr, "Warning: ...") call. This worked on the CLI surface but was invisible on the MCP surface: an agent calling madt_issues that triggered a credential-fallback warning or a pagination-truncation notice would get the main response with no indication anything was unusual, because the warning had gone to the server’s stderr log and not into the tool result.

ADR 0006 - finish refuses the default branch

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Amended: 2026-07-17 by ADR 0031 — commit joins finish in refusing the default branch (per-call --allow-default-branch override), closing the branch-commit-finish loop at both ends.
Date: 2026-06-24
Tracking: internal pre-Codeberg tracker (1621 formalizes a rule locked on 1601)

Context

madtea finish completes a feature branch: it commits, pushes, opens a PR, merges it, and returns to the default branch. Running it from the default branch is a category error — there is no feature branch to merge, and the only coherent interpretations (open a PR from the default onto itself; push the default with no review) are exactly the unguarded paths finish exists to avoid.

ADR 0019 - Foreign primary checkouts are immutable

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-03
Tracking: internal pre-Codeberg tracker (1912)

Context

ADR 0007 (structural fail-closed, multi-repo) introduced dir= targeting: a madtea agent can name any other on-disk git repository as the target of a mutating local-git tool (madt_branch_create, madt_commit, madt_push, …). ADR 0009 (non-overridable guards) established that the agent-facing safety hooks are structurally enforced with no opt-out.

The cross-repo intent contract (ADR 0007 amendment) extended dir= to any repository on disk — not just siblings sharing a workspace root — and built the worktree flow as the sanctioned mechanism for agents contributing to a foreign repo:

ADR 0016 - Names match gh/tea verbatim

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1225 batch rename to parity, 1572 stale CLAUDE.md vs deliberate bareword, 1593 no-negative-steers, 1604, 1605 param-name ergonomics)

Context

madtea exposes two surfaces — the Cobra CLI (madtea …) and the MCP server (madt_<noun> tools) — and every operation appears on both. Without a deliberate naming rule, each surface accumulates its own vocabulary as contributors pick names that feel natural or internally consistent. Over time this creates two problems:

ADR 0030 - git-mirrored commands match git's argument shape

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #171

Context

ADR 0016 pins CLI subcommand, flag, and MCP action names to gh then tea verbatim, with one refinement for git-mirrored commands: madtea’s thin wrappers over local git commands (branch, tag, checkout, stash, worktree, …) match git’s vocabulary, not gh/tea’s, because they are git — an agent or human reaching for them arrives with git’s muscle memory. That refinement is recorded in naming-conventions.md.

Names are not the only muscle memory a git-mirrored command inherits. The argument shape — which operands are positionals versus flags, and what a positional means — is just as load-bearing, and ADR 0016 does not speak to it. madtea worktree add diverged here: it took the branch as a positional (add <path> [branch]) and had the service layer silently decide the meaning — an existing branch was checked out, a missing one was created (git worktree add -b). Raw git’s signature is git worktree add <path> [<commit-ish>]: the positional after the path is a commit-ish to check out (an existing ref, never a silent create), and creating a new branch is the explicit -b <branch>. madtea’s worktree add had no -b at all.

ADR 0022 - Hermetic test guard

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: internal pre-Codeberg tracker (2034)

Context

A handler test called issuesDevelop without sandboxing. Because serviceissue.Develop operates on the process working directory’s git repo and resolves credentials from the ambient environment, the test — run from the real madtea checkout — resolved real issue #42 through the live forge API, created and checked out a branch, and pushed it to origin. It did this silently, through a full green gate, twice (origin gained issue-42-phase-3-git-commands-migration).

ADR 0020 - Identifier arity is a hard boundary

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: internal pre-Codeberg tracker (2029 / PR 2035; builds on ADR 0005 and the FlexIDs lineage 881, 884, 1327)

Context

The FlexIDs lineage made identifier value shapes liberal: multiple input forms for a number list are normalized to []string. For example, numbers accepts 441, "441", [441], ["441"], and "441, 442" interchangeably. ADR 0005 codified the complementary rule for names: parameter names are strict (gh/tea/API-anchored), with only a bounded did-you-mean. The identifier arity sweep extended shape liberality across operation arity in one direction: every single-target action accepts a single-element numbers=[N] as equivalent to number=N (resolveOneNumber), because that input’s meaning is unambiguous.

ADR 0027 - Launch scope is the credential boundary

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted (owner ruling 2026-07-15; enforcement tracked in #90, issue-filing carve-out implementation in #59)
Date: 2026-07-15
Tracking: #90
Amended 2026-07-17 (#155): a third enumerated read-only carve-out — the whoami-scoped local-resolution report (see “Carve-out 3” below).
Amended 2026-07-19 (#263): the residual-risk paragraph in Consequences restated honestly - the boundary is host-scoped by credential, not clone-scoped (the on-disk clone is fabricable friction, not authorization).
Amended 2026-07-19 (#264): carve-out 2’s repo-prefix is now enforced structurally client-side - the dir= report client is confined by gitea.WithRepoScope, which refuses any request outside the target repo’s own subtree, not just by convention of which methods the carve-out handlers call.

Context

dir= began as a repo selector for local-git tools (ADR 0007) and was extended to any git repo on disk, with ADR 0019 clamping foreign primaries to the worktree→finish contribution flow. Separately, ADR 0025 made credential resolution host-keyed and per-checkout: a clone of a Codeberg repo can carry working Codeberg credentials while the session’s launch checkout is authed to a different forge — or to nothing at all.

ADR 0014 - CLI and MCP are thin surfaces over one service layer

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1492 SoC audit, 1493 client-construction dedup, 1495 assignee set-merge dedup)

Context

madtea ships two distinct user-facing surfaces: the Cobra CLI (internal/cmd) and the MCP server (internal/mcp). Before the SoC audit, both surfaces contained business logic, API client construction calls, and result-assembly code that was either duplicated or subtly divergent. Concrete examples found in the audit:

gitea.NewClientWithConfig was called directly in individual MCP tool files, duplicating the exact same construction logic the CLI used.
Assignee set-merge (build a map[string]struct{}, loop-add, loop-delete, reconcile with an assignee identifier) was copy-pasted into multiple locations across both internal/mcp and internal/cmd.

Neither of these duplications was caught by any test; behavior could drift between surfaces silently. The immediate risk is that a change to business logic is applied to one surface and not the other, making the CLI and MCP behave differently for the same operation.

ADR 0001 - Agent conventions live in the MCP layer

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-02
Tracking: internal pre-Codeberg tracker (1316 agent self-sufficiency, 1317 “decide first” sub-issue)
Amended: 2026-07-02 — the Tier taxonomy below is forked by ADR 0008; see “ADR 0008 update” at the end of this document for what changed and what didn’t.

Context

madtea ships as both a CLI binary and a Model Context Protocol (MCP) server, and as a Claude Code plugin that bundles skills and PreToolUse hooks around that same binary. The plugin manifest advertises support for “Claude Code, OpenAI Codex CLI, and Google Gemini CLI”, and the README documents install paths for those plus Cursor, Windsurf, Cline, Zed, and “any MCP client”.

ADR 0009 - Agent-facing guards are non-overridable

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Amended: 2026-07-07 by ADR 0021 — pure-read local-git steering demoted to non-blocking advisory; blocking guards (mutation, credential-exposure, shared-state) are unchanged.
Date: 2026-06-28
Tracking: internal pre-Codeberg tracker (1721)

Context

madtea’s Claude Code plugin ships four PreToolUse Bash hooks (check-git-{commit,local,cli,remote}.sh). They intercept the agent’s Bash tool and either steer raw git / madtea CLI calls to the credential-safe madt_* tools, or hard-block the raw remote ops that would leak a credential token embedded in a remote URL.

ADR 0008 - The operation registry is the source of record

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-28
Tracking: internal pre-Codeberg tracker (1693)

Context

madtea ships as both a CLI binary and an MCP server, and today maintains two independently-authored help corpora:

CLI help — Cobra Short/Long/flag-usage strings, hand-written per command in internal/cmd.
MCP help — ActionSpec.Summary and jsonschema param tags, authored in internal/mcp.

The parity test (internal/parity) keeps names aligned across surfaces but never description text, so the two corpora drift freely. Concrete divergences today: pr merge exposes four boolean flags (--squash, --rebase, --rebase-merge, --ff-only) on the CLI versus a single strategy enum on MCP; the CLI flag --admin appears as force_merge in MCP; issues create is described as “Create a new issue.” on the CLI and “Create an issue.” in MCP. MCP summaries are also deliberately richer — a drift guard mandates that footgun keywords appear inline — but that policy runs against MCP alone and cannot protect the CLI description.

ADR 0025 - Origin-first forge resolution and host-keyed credentials

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-12
Tracking: epic #30
Amends: 0013 (credential keying), 0007 (extends the structural workspace detection to forge selection)

Context

madtea resolves a repository’s path (owner/name) from its origin remote, but resolves the API server from the single madtea.url config value. The two can disagree, and when they do madtea silently queries the wrong forge.

Observed failure (2026-07-12): a workspace holds clones from two forges — a self-hosted Gitea (the configured madtea.url) and Codeberg. In a clone whose origin is codeberg.org/<org>/<repo>:

ADR 0005 - Proactive parameter-name schema clarity

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-24
Tracking: internal pre-Codeberg tracker (1604, 1605; builds on 1577 bounded did-you-mean, 1593 no negative steers)

Context

Agents reach for a “natural” argument name that is not the tool’s canonical parameter, the JSON unmarshaler silently drops it, and a wasted round-trip follows. Recurring, real instances:

madt_finish is keyed by title; an agent passed commit_message (and message) — “the commit message” is the reflex word for a commit subject.
madt_search is keyed by q; an agent passed query.

Each time one of these surfaces, the reflex is to reach for the reactive side — extend the unknown-argument did-you-mean with another synonym, a compound/_-token splitter, or a broad alias table — until “no guess ever fails.” That instinct keeps getting re-explored from scratch, and it pulls toward exactly the failure mode we want to avoid: a never-fail matcher that is confidently wrong (user_message → body?, review_id → id). This ADR records the decision so a future “wrong parameter name” bug resolves by reference.

ADR 0021 - Pure-read steering is advisory

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: internal pre-Codeberg tracker (2044, 2047)

Context

madtea’s Claude Code plugin ships a local-git steering hook (hooks/scripts/check-git-local.sh) that intercepts the agent’s Bash tool and redirects raw git forms to the madt_* MCP tool that does the same job. Initially it did this by hard deny — permissionDecision: "deny", no agent-reachable opt-out (ADR 0009).

Over time the hard-deny set grew to cover a large read surface: git status, git branch read/list, git rev-parse HEAD, git log (every read form), git worktree list, git ls-tree, git show <ref>:<path>, git grep <pattern> <ref>, git tag -l, git diff <ref>, git ls-files --deleted, and git sparse-checkout list. The read-steering audit classified every hard-blocked git form and found twelve pure reads blocked purely for MCP-tool steering — they cannot mutate the object DB, refs, working tree, index, config, or stashes, and never contact a remote. Their block carried no mutation, credential, or shared-state rationale; the only reason was economics (steer the agent onto the one-call structured madt_* tool).

ADR 0031 - Recoverable guards refuse by default, override per call

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #222

Context

ADR 0029 pinned the rule for unrecoverable acts: they are omitted from every madtea surface. It deliberately said nothing about a second class this repo keeps meeting: acts that destroy nothing but are almost always workflow wreckage. The motivating incident (2026-07-17): a process with a confused working directory committed a feature snapshot directly onto the local default branch. Nothing was lost - the commit was branched off and the ref reset by the user - but the damage cost real recovery work: a diverged local main, a broken local build, and untangling by hand. Remote branch protection never entered the picture; the commit was never pushed, and protection fires at push time anyway, after work has stacked on the wrong base. Not every repo configures protection at all.

ADR 0010 - Tag-driven releases, one blessed install

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1711 release-mess report); release/install overhaul epic filed on acceptance

Context

Every release left a trail on the default branch: a docs(changelog): backfill [Unreleased] PR, a chore: prepare release PR, and their merge commits. Two coupled causes:

The changelog was hand-maintained. CHANGELOG.md’s [Unreleased] section was updated per-PR by hand, so the discipline lapsed and a backfill scramble preceded every cut (and release.sh refuses on an empty [Unreleased]).
release.sh committed to a protected branch. It bumped .claude-plugin/plugin.json, promoted [Unreleased] → [version], and regenerated docs — all commits, so on a branch-protected main they went through their own release PR.

But the commit-to-main step is unnecessary:

ADR 0012 - Release signing and trust-on-first-use updates

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: internal pre-Codeberg tracker (1266 release signing key); release/install overhaul epic (ADR 0010)

Context

madtea update downloads a release and replaces the running binary. Without integrity verification, a tampered release or a man-in-the-middle on the download runs arbitrary code as the user. madtea depends on no third-party update service and publishes to a self-hosted forge, so the trust model must be self-contained in the binary plus the release artifacts.

ADR 0002 - Safe inline body updates

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-03
Tracking: internal pre-Codeberg tracker (1349 RFC / brainstorm; supersedes 1348 CLI body-edit divergence / checklist toggle)

Context

madtea lets an agent or a human edit issue bodies, pull-request bodies, and comment bodies. The motivating failure is clobbering: an agent regenerates a tracking issue’s body from a stale read and silently discards everything that was there — closed sub-issue checkboxes, hand-written notes, a progress counter. The blunt fix that shipped earlier blocks issue-body edits on the MCP (agent) surface entirely and tells the agent to use a comment instead. That stopped the clobbering, but it also forbade every legitimate inline update (tick a box, fix a typo, append a section, sync a checklist), so tracking-issue bodies rot while the truth lives in comments — exactly the state on several affected tracking issues at the time.

ADR 0028 - Semver tiers within 0.x

Mon, 01 Jan 0001 00:00:00 +0000

Within 0.x, breaking changes bump MINOR and all other releasable types bump PATCH; the cadence gate counts releasable commits regardless of tier.

Status: Accepted (owner ruling 2026-07-17); Amended 2026-07-17 (#244)
Date: 2026-07-17
Tracking:

Amendment (2026-07-17, #244)

Two changes to the original decision:

0.x MINOR tier narrowed to breaking-only. The original text said “breaking or feat bumps MINOR”. The amended rule is: only a breaking change (type!: / BREAKING CHANGE) bumps MINOR within 0.x; feat: and every other releasable type (fix/ux/perf) bump PATCH. Post-1.0 mapping is unchanged. The cadence score weights are NOT affected - a feat still scores 3 pts while releasing as a patch.

ADR 0023 - Shipped strings are self-contained

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-10
Tracking: internal pre-Codeberg tracker (2130)

Context

madtea ships strings to users in three compiled-in forms: hook steering text (the plugin’s PreToolUse scripts), error/refusal returns from the CLI and the madt_* tools, and MCP tool/parameter descriptions. The house habit — natural while the project was internal-only — has been to justify a rule by citing the governance artifact behind it: “ADR 0009”, "the removed all=true, #1964", "see #1862". Those citations resolve only inside the org: they point at ADR files in this repo and issues on an internal forge.

ADR 0003 - Side-effect confirmation is structural

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-03
Tracking: internal pre-Codeberg tracker (1370 epic, 1371 this ADR; implementation 1372-1381)

Context

A command that performs a side-effect must tell the caller what it did — otherwise the caller re-runs work that already happened. The concrete failure that prompted this: madtea finish ends by running git checkout <default> && git pull (returnToDefaultBranch), but its output says only “Returned to <default>” — never that it pulled, or to which commit. A caller can’t tell the pull happened and re-runs madtea pull (an observed redundancy).

ADR 0017 - Target the standard Gitea API v1

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: forgejo-15-actions-probe.md

Context

madtea targets the standard Gitea API v1 endpoints that Forgejo maintains for compatibility, working with both platforms without modification. In practice, the two platforms are close but not identical. Forgejo is a soft fork of Gitea that maintains compatibility with the Gitea API v1 for the vast majority of endpoints but has not implemented some Actions-family endpoints that Gitea ships (verified empirically in forgejo-15-actions-probe.md against Forgejo 15).

ADR 0029 - No surface carries a work-destroying override

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #206 (epic), #207

Context

madtea’s destructive-operation surfaces grew case by case, and by mid-2026 three different safety models coexisted with no ADR pinning any of them:

Omission - force-delete of a local branch exists on NO madtea surface. The MCP madt_branch_delete tool has no force parameter, and the CLI madtea branch -d refuses -D/--force-delete, redirecting to raw git branch -D in the user’s own shell (internal/cmd/git/branch.go). The plugin hooks then steer agents off raw git. Two independent layers, neither depending on the other behaving.
Machine-proof destruction - madtea prune deletes a ref only after content-verifying it is contained in the default branch, and madtea push --force rides --force-with-lease. Refs die; work provably does not.
Consent-gated presence - madt_worktrees remove force= (#168) and the madt_delete tool (repo/issue/release/tag/wiki page) DO exist on the agent surface, guarded by an elicitation dialog.

Model 3 leaked twice, and both leaks are structural, not incidental:

ADR 0007 - Structural fail-closed in multi-repo workspaces

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-25
Tracking: internal pre-Codeberg tracker (1631)

Mutating local-git MCP calls fail closed when the server cwd is a structurally detected multi-repo workspace and no caller-repo signal is present, closing a dead-zone that signal-only guards could not cover.

Context

The wrong-repo guard (internal/mcp/repoguard.go) fails closed only when it has a caller-repo signal that differs from the repo the server resolved from its launch-fixed cwd. In our actual deployment that signal effectively never exists, so the block path has — outside tests — never fired:

ADR 0004 - A terminal-closure signal on completed results

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-23
Tracking: internal pre-Codeberg tracker (1597)

Context

A side-effecting command already confirms what it did (ADR-0003): finish names its merge and pull, a close says “Closed issue #42”. That cured the caller re-running a step the tool had already performed — but it did not cure a second, subtler redundancy: after a result that ends a unit of work, an agent re-verifies the outcome. The concrete failure that prompted this: madt_finish reported a clean merge, and the agent then ran go build to re-confirm the merged tree compiled — work the finish had already validated and landed. The same instinct fires after a release publish (re-fetch the release), an issue close (re-get the issue), a branch delete (re-list branches).

ADR 0026 - Guard texts are terminal or forwarding

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-14
Tracking: #15

Context

madtea steers agents away from raw, credential-unsafe or shared-state-unsafe git through two families of guards: the Claude Code plugin’s PreToolUse hooks (they deny/advise on the Bash tool) and the madt_* tool refusals (they reject an unsafe call and teach the safe one). Each guard was written well on its own. The failure mode is at the seams between them.

A live case study (an agent in a foreign-repo worktree, mid-merge-conflict):