## TL;DR

The agent upgraded every package past the pins your project depends on. Restore packages.yml from git, delete package-lock.yml, re-run plain dbt deps to get the pinned versions back, and take --upgrade out of the agent's allowed commands.

## Error

```text
agent ran dbt deps --upgrade and broke the pinned dbt-utils version
```

## Steps

1. Restore packages.yml from git: git checkout -- packages.yml (or revert the agent's commit).
   Expected: The pinned versions are back in the file.

2. Delete package-lock.yml so the upgraded resolutions do not linger.
   Expected: No lock file pointing at the upgraded versions.

3. Run plain dbt deps (no --upgrade) and then dbt compile.
   Expected: Pinned package versions install; the project compiles on the known-good set.

4. Remove --upgrade from what the agent may run; package upgrades become a deliberate human task with testing.
   Expected: Agents cannot upgrade packages unilaterally again.

## When to use

- an agent ran dbt deps --upgrade and package versions moved
- macros from dbt-utils changed behavior after an agent run
- CI started failing after an agent touched packages

## When not to use

- you intentionally upgraded packages (then fix the resulting breakage deliberately)
- the registry is down (that is connectivity, not --upgrade)
- a package version was yanked (repin to an existing version)

## Tool compatibility

- git to restore packages.yml
- dbt deps without --upgrade respects pins
- package-lock.yml deletion to clear upgraded resolutions

## Variant phrasings

### agent upgraded dbt-core itself
Bigger blast radius: restore the environment (venv, container image) to the pinned dbt-core, not just packages.

### upgrade broke only one macro's behavior
Pin that package tighter and override the macro in your macros/ dir if you need the old behavior while planning the upgrade.

## Why it happens

--upgrade ignores your pins and takes the latest compatible everything, which is exactly what pins exist to prevent. Agents run it because a stale package caused some error and upgrading felt like fixing. Package upgrades need testing, not automation.

## Edge cases

- If packages.yml had no pins (just package names), --upgrade changes nothing about your process but you still have no reproducibility; add pins.
- After restoring, diff dbt_modules against the lock to confirm the versions actually rolled back.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kFAvGGGkAwnjLfiXN2QWrw