pkl read?("env:...") results are cached, but the environment is not part of the cache key

[christopher-buss]

Summary

hk caches the resolved pkl config, but the cache key does not include anything about the environment. A config that branches on read?("env:...") therefore has its result frozen by whichever process evaluates it first, and every later run reuses that answer regardless of its own environment.

The evaluation itself is correct. Only the invalidation is wrong — HK_CACHE=0 produces the right answer every time.

Reproduction

hk 1.53.0, Windows 11, default pklr backend.

amends "package://github.com/jdx/hk/releases/download/v1.53.0/hk@1.53.0#/Config.pkl"

profiles = if (read?("env:MY_AGENT") != null) List("agent") else List()

hooks {
  ["check"] {
    steps {
      ["noop"] { check = "echo noop" }
    }
  }
}

$ MY_AGENT= hk config explain profiles   # cold
Current value: []
$ MY_AGENT=1 hk config explain profiles  # warm — expected ["agent"]
Current value: []

It fails in both directions. In a fresh directory with the same config, seeding the cache the other way sticks just as hard:

$ MY_AGENT=1 hk config explain profiles  # cold
Current value: ["agent"]
$ MY_AGENT= hk config explain profiles   # warm — expected []
Current value: ["agent"]

Confirming that only caching is at fault:

$ MY_AGENT=1 HK_CACHE=0 hk config explain profiles
Current value: ["agent"]

This is not limited to config explain. With profiles = List("agent") on a step, the wrongly-cached value decides whether the step actually runs in a real git commit.

Where it comes from

The config cache key is assembled from:

• BASE_CACHE_KEYS (src/cache.rs:30-35) — the hk version only.
• pkl-backend:{HK_PKL_BACKEND} (src/config.rs:254).
• One fresh-file key per config file and per transitive local import.

Fresh-file keys hash file bytes. Nothing observes environment variables, so a read?("env:...") result is invisible to invalidation. pkl already reports what a module read via analyze imports-style dependency output, and hk already has the machinery to persist a dependency set — analyze_imports caches an ImportAnalysis in a sidecar (src/config.rs:222-230). Env reads look like they could ride the same path: record the names read, then add name=value pairs to the cache key.

Why this is easy to hit and hard to notice

The symptom is silent and non-deterministic across machines. Nothing errors; steps simply run or do not run.

The pattern that triggers it is a natural one — gate expensive steps on whether an AI coding agent is driving the commit:

profiles = if (read?("env:CLAUDECODE") != null || read?("env:AI_AGENT") != null) List("agent") else List()

In a project doing exactly this, the main checkout and a second worktree disagreed while holding byte-identical hk.pkl and the same hk version. Whichever environment ran hk first after the last hk.pkl edit won, permanently. Agents silently skipped typecheck/build/test, or human commits paid for all three, depending only on that accident of ordering.

Interaction with #1034

#1034 proposes dropping the absolute path from the cache key so byte-identical configs share one entry. That is a good idea on its own terms, but it makes this bug strictly worse.

Today the path component accidentally limits the blast radius: each checkout freezes its own wrong answer. Fully content-address the key and every checkout, worktree, and CI job sharing that config also shares one frozen env-derived answer — so a single cold evaluation in the wrong environment can poison an entire fleet.

Note the shared resolved-config.json slot already does something close to this when has_untracked_imports is false (src/config.rs:248-258). Configs amending a package:// URL take the path-keyed branch, which is why the divergence above is per-directory rather than global.

Whatever key scheme wins, env reads need to be in it. Worth resolving these two together.

What I would expect

Either of:

1. Env vars read during evaluation become part of the cache key, so the entry invalidates when they change. Values, not just names, since the branch depends on the value.
2. If tracking them is not practical, hk detects that a config performed an env read and declines to cache that config, or warns.

Silently caching a value that depends on unrecorded inputs is the part that bites.

Workarounds

For anyone finding this later, both work:

• HK_CACHE=0 — correct, but gives up config caching entirely.
• Stop branching inside pkl. HK_PROFILE / HK_PROFILES sit above the pkl layer in the precedence chain (hk config explain profiles) and are read at runtime, outside the cache. Setting HK_PROFILE from the environment — via mise's [env] with a template, for instance — resolves per run and is immune to this. That is what the project above ended up doing.

The second is arguably better config design anyway, but the failure mode still seems worth fixing: the pkl form looks correct, is documented-adjacent, and fails silently.

Environment

• hk 1.53.0
• Windows 11 Pro 26100, Git Bash
• HK_PKL_BACKEND unset (default pklr). Not tested against the pkl CLI backend.

[christopher-buss]

Disclosure: this report was researched and written by Claude Code (Opus 5), directed and reviewed by me before posting.

Everything above comes from an actual run rather than from reading the source alone — the repro, the both-directions failure, the HK_CACHE=0 isolation, and the cited line numbers in src/cache.rs and src/config.rs were each verified first. The pkl CLI backend is called out as untested because it genuinely was not tested, not as hedging.

Flagging it in case you weigh AI-assisted reports differently, and happy to run further experiments against this if any claim needs checking.

[jdx]

this isn't that important to me, but since I own the pkl library it sounds reasonable if you want to make a PR that adds env var tracking to that and then consume it in hk