feat(prime): add prime.disabled so a session can turn off an inherited bd prime hook (#7595)

Claude Code merges a project's hook settings into every session started in that
checkout, including an orchestrator's agent sessions, which get their own
briefing. A higher-precedence settings file cannot remove a lower one's hook, so
such sessions run `bd prime` whether it helps them or not. The only per-session
channel their host controls is the environment.

prime.disabled (BD_PRIME_DISABLED) makes bd prime print nothing, the same as
outside a workspace (an empty envelope under --hook-json), whatever its other
flags. It returns before any workspace or store access. Like the prime memory
caps it is a yaml-only key, and it is validated with strconv.ParseBool, the set
that viper's GetBool reads.

Measured on a copy of a 751-memory store, bytes a hook injects:
- bd prime: 1,251,189 (the default is unchanged);
- BD_PRIME_DISABLED=true bd prime, --full, --memories-only: 0;
- BD_PRIME_DISABLED=true bd prime --hook-json: the empty envelope.

In the Gas City deployment that owns that store, 637 agent sessions in 48 hours
fired the inherited hook 1,271 times. Each firing injected a 2.3 KB preview after
host truncation. On top of that, the sessions read 1.81 MB of the persisted
output. That is about 4.8 MB of context these sessions do not use.

Tests:
- TestPrimeDisabledReadsTheConfigKey.
- TestPrimeDisabledPrintsNothingInAWorkspace. A staged workspace's briefing
  prints when the key is off; the test fails if the early return is removed.
- TestValidateYamlConfigValue_PrimeDisabled.
- The embedded TestEmbeddedPrime/prime_disabled_env and
  /prime_disabled_config subtests.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-16 08:31:08 +00:00 • committed by GitHub
commit 74a67c3c27
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 190 additions and 1 deletions

View file

@ -1023,6 +1023,7 @@ go_test(
"pour_unknown_vars_test.go",
"pour_wisp_var_validation_test.go",
"preflight_test.go",
"prime_disabled_test.go",
"prime_divergence_test.go",
"prime_embedded_test.go",
"prime_gemini_hook_test.go",

View file

@ -1356,6 +1356,7 @@ var recognizedConfigKeys = map[string]bool{
"auto_compact_enabled": true, "schema_version": true,
"output.title-length": true,
"prime.max-memories": true, "prime.max-memory-chars": true,
"prime.disabled": true,
// Opt-in ceiling on the persistent-memory corpus, enforced by `bd
// remember` (0 = off). Yaml-only for the same reason the prime caps are:
// it is read through viper, so a DB-backed write would never be seen.

View file

@ -106,6 +106,11 @@ Config options:
Set via: bd config set agent.profile team-maintainer
Or per-session: BD_AGENT_PROFILE=team-maintainer (env var takes precedence).
See docs/getting-started/ide-setup.md#policy-profiles for what each profile means.
- prime.disabled: When true, bd prime prints nothing, as it does outside a
workspace (an empty envelope under --hook-json), whatever its other flags.
For sessions whose host briefs the agent itself but that inherit a
project's bd prime hook, such as an orchestrator's agent sessions.
Set per-session: BD_PRIME_DISABLED=true. Or: bd config set prime.disabled true
Workflow customization:
- Place a PRIME.md file to override the default workflow text. Checked in this
@ -145,6 +150,15 @@ Memory injection caps:
}
}()
// Before any workspace or store access: a disabled prime costs the
// session nothing, the same as running outside a workspace.
if primeDisabled() {
if primeHookJSONMode {
_ = outputHookJSON(os.Stdout, "")
}
return nil
}
primeMaxMemoriesSet = cmd.Flags().Changed("max-memories")
primeMaxMemoryCharsSet = cmd.Flags().Changed("max-memory-chars")
@ -620,6 +634,17 @@ var primeConfigInt = func(key string) int {
return config.GetInt(key)
}
// primeConfigBool reads a boolean config key (stubbable for tests).
var primeConfigBool = func(key string) bool {
return config.GetBool(key)
}
// primeDisabled reports whether prime.disabled (usually BD_PRIME_DISABLED in
// the session's environment) turns bd prime off.
func primeDisabled() bool {
return primeConfigBool("prime.disabled")
}
// primeMemoryCaps resolves the memory-injection caps. An explicitly passed
// flag wins, including an explicit 0 meaning "force unlimited"; otherwise the
// prime.max-memories / prime.max-memory-chars config keys apply. 0 or unset

View file

@ -0,0 +1,82 @@
package main
import (
"bytes"
"os"
"path/filepath"
"testing"
)
// stubPrimeConfigBool makes primeConfigBool read from a map for one test.
func stubPrimeConfigBool(t *testing.T, values map[string]bool) {
t.Helper()
orig := primeConfigBool
primeConfigBool = func(key string) bool { return values[key] }
t.Cleanup(func() { primeConfigBool = orig })
}
// stagePrimeWorkspace makes a workspace whose briefing is a known custom
// PRIME.md with no memories, so an enabled bd prime visibly prints.
func stagePrimeWorkspace(t *testing.T, briefing string) {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
for name, body := range map[string]string{"config.yaml": "", "PRIME.md": briefing} {
if err := os.WriteFile(filepath.Join(beadsDir, name), []byte(body), 0o644); err != nil {
t.Fatal(err)
}
}
t.Setenv("BEADS_DIR", beadsDir)
origNoMemories, origHookJSON := primeNoMemories, primeHookJSONMode
primeNoMemories = true
t.Cleanup(func() { primeNoMemories, primeHookJSONMode = origNoMemories, origHookJSON })
}
func hookEnvelope(t *testing.T, content string) string {
t.Helper()
var buf bytes.Buffer
if err := outputHookJSON(&buf, content); err != nil {
t.Fatalf("outputHookJSON: %v", err)
}
return buf.String()
}
func TestPrimeDisabledReadsTheConfigKey(t *testing.T) {
stubPrimeConfigBool(t, map[string]bool{})
if primeDisabled() {
t.Fatal("bd prime must be on unless prime.disabled is set")
}
stubPrimeConfigBool(t, map[string]bool{"prime.disabled": true})
if !primeDisabled() {
t.Fatal("prime.disabled=true must turn bd prime off")
}
}
// With prime.disabled, bd prime adds nothing to the session, exactly as it
// does outside a workspace, even though a workspace with a briefing exists.
func TestPrimeDisabledPrintsNothingInAWorkspace(t *testing.T) {
const briefing = "custom briefing\n"
stagePrimeWorkspace(t, briefing)
run := func(hookJSON bool) string {
primeHookJSONMode = hookJSON
return captureStdout(t, func() error { return primeCmd.RunE(primeCmd, nil) })
}
stubPrimeConfigBool(t, map[string]bool{})
if got := run(false); got != briefing {
t.Fatalf("enabled bd prime printed %q, want the workspace briefing %q", got, briefing)
}
if got := run(true); got != hookEnvelope(t, briefing) {
t.Fatalf("enabled bd prime --hook-json printed %q", got)
}
stubPrimeConfigBool(t, map[string]bool{"prime.disabled": true})
if got := run(false); got != "" {
t.Fatalf("disabled bd prime printed %q, want nothing", got)
}
if got := run(true); got != hookEnvelope(t, "") {
t.Fatalf("disabled bd prime --hook-json printed %q, want the empty envelope", got)
}
}

View file

@ -101,6 +101,55 @@ func TestEmbeddedPrime(t *testing.T) {
t.Errorf("expected --memories-only to omit full command guide: %s", out)
}
})
// ===== prime.disabled =====
// A session that sets BD_PRIME_DISABLED gets nothing from the hook line it
// inherits, whatever that line's flags, while the workspace (and its
// memories) stays as it is.
t.Run("prime_disabled_env", func(t *testing.T) {
for _, args := range [][]string{nil, {"--full"}, {"--memories-only"}, {"--hook-json"}} {
cmd := exec.Command(bd, append([]string{"prime"}, args...)...)
cmd.Dir = dir
cmd.Env = append(bdEnv(dir), "BD_PRIME_DISABLED=true")
stdout, stderr, err := runCommandBuffers(t, cmd)
if err != nil {
t.Fatalf("bd prime %v failed: %v\nstderr:\n%s", args, err, stderr.String())
}
out := stdout.String()
if len(args) == 1 && args[0] == "--hook-json" {
if !strings.Contains(out, `"additionalContext":""`) {
t.Errorf("disabled bd prime --hook-json should send an empty envelope, got %s", out)
}
continue
}
if out != "" {
t.Errorf("disabled bd prime %v printed %q", args, out[:min(200, len(out))])
}
}
if out := bdPrime(t, bd, dir, "--memories-only"); !strings.Contains(out, "prime-test-mem") {
t.Errorf("without BD_PRIME_DISABLED the memories come back: %s", out)
}
})
t.Run("prime_disabled_config", func(t *testing.T) {
set := func(value string) {
cmd := exec.Command(bd, "config", "set", "prime.disabled", value)
cmd.Dir = dir
cmd.Env = bdEnv(dir)
if _, stderr, err := runCommandBuffers(t, cmd); err != nil {
t.Fatalf("bd config set prime.disabled %s: %v\n%s", value, err, stderr.String())
}
}
set("true")
if out := bdPrime(t, bd, dir); out != "" {
t.Errorf("prime.disabled=true in config, bd prime printed %q", out[:min(200, len(out))])
}
set("false")
if out := bdPrime(t, bd, dir); !strings.Contains(out, "prime-test-mem") {
t.Errorf("prime.disabled=false must restore the briefing: %s", out[:min(200, len(out))])
}
})
}
// TestEmbeddedPrimeConcurrent exercises prime operations concurrently.

View file

@ -88,7 +88,7 @@ The full namespaces routed to YAML are:
Plus these individual keys:
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, `memories.budget-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`, `notion.token`.
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, `prime.disabled`, `memories.budget-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`, `notion.token`.
Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `password` is treated as a secret: it is refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`. Prefer exporting the value as an environment variable instead (e.g. `LINEAR_API_KEY`).
@ -108,6 +108,7 @@ Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `passwor
| `agent.profile` | — | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority: `conservative`, `minimal`, `team-maintainer`; invalid values fall back to `conservative` |
| `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by `bd prime` (0 = unlimited) |
| `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by `bd prime`, at whole-memory boundaries (0 = unlimited) |
| `prime.disabled` | — | `BD_PRIME_DISABLED` | `false` | When true, `bd prime` prints nothing, as outside a workspace (an empty envelope under `--hook-json`), whatever its other flags. Set it in the environment of sessions whose host briefs the agent itself but that inherit a project's `bd prime` hook |
| `memories.budget-chars` | — | `BD_MEMORIES_BUDGET_CHARS` | `0` | Ceiling on the whole persistent-memory corpus, in bytes of `len(key)+len(content)` summed over every memory (0 = off). `bd remember` refuses a write that would cross it — pass `--force` to store anyway — and warns on a write that lands at or above 80% of it. Read at `bd remember` time only; `bd prime` injection is capped separately by `prime.max-memory-chars` |
| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | `off\|on\|batch`: `on` creates a Dolt history commit after each successful write; `batch`/`off` defer it to `bd dolt commit` (see [below](#auto-commit-sql-commits-vs-dolt-commits)) |
| `dolt.auto-push` | — | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in; see [below](#auto-push)) |

View file

@ -78,6 +78,9 @@ var YamlOnlyKeys = map[string]bool{
// the database is reachable, so they must live in yaml)
"prime.max-memories": true,
"prime.max-memory-chars": true,
// Turns bd prime off for sessions whose host briefs the agent itself;
// read at session start like the caps, usually as BD_PRIME_DISABLED.
"prime.disabled": true,
// Memory-corpus budget enforced by `bd remember` (0 = off). Yaml for the
// same reason the prime caps are: it is read through viper (config.GetInt),
@ -1601,6 +1604,11 @@ func validateYamlConfigValue(key, value string) error {
if n < 0 {
return fmt.Errorf("prime.max-memory-chars must be a non-negative integer (0 = unlimited), got %q", value)
}
case "prime.disabled":
// The set viper's GetBool reads, so a stored value means what it says.
if _, err := strconv.ParseBool(value); err != nil {
return fmt.Errorf("prime.disabled must be true or false, got %q", value)
}
case "memories.budget-chars":
n, err := strconv.Atoi(value)
if err != nil {

View file

@ -1,6 +1,7 @@
package config
import (
"fmt"
"os"
"os/exec"
"path/filepath"
@ -882,6 +883,27 @@ func TestValidateYamlConfigValue_PrimeMaxMemories(t *testing.T) {
}
}
// TestValidateYamlConfigValue_PrimeDisabled: prime.disabled takes exactly the
// strings viper's GetBool reads, so `bd config set` cannot store a value that
// bd prime would silently read as false.
func TestValidateYamlConfigValue_PrimeDisabled(t *testing.T) {
if !IsYamlOnlyKey("prime.disabled") {
t.Fatal("prime.disabled must be yaml-only: bd prime reads it through viper before any store is open")
}
for _, value := range []string{"true", "false", "TRUE", "False", "1", "0", "t", "f"} {
if err := validateYamlConfigValue("prime.disabled", value); err != nil {
t.Errorf("value %q: unexpected error %v", value, err)
}
}
for _, value := range []string{"", "yes", "off", "tRuE", "2"} {
err := validateYamlConfigValue("prime.disabled", value)
want := fmt.Sprintf("prime.disabled must be true or false, got %q", value)
if err == nil || err.Error() != want {
t.Errorf("value %q: got error %v, want %q", value, err, want)
}
}
}
// TestValidateYamlConfigValue_PrimeMaxMemoryChars tests validation of prime.max-memory-chars
func TestValidateYamlConfigValue_PrimeMaxMemoryChars(t *testing.T) {
tests := []struct {