beads/docs/reference
Julian Knutsen 74a67c3c27
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>
2026-10-16 08:31:08 +00:00
..
advanced.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
antivirus.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
configuration.md feat(prime): add prime.disabled so a session can turn off an inherited bd prime hook (#7595) 2026-10-16 08:31:08 +00:00
events-journal.md fix(events): journal delete and cascade dep_remove rows carry the request actor; notice when reading a disabled journal (#5985) (#6061) 2026-08-29 04:14:23 -07:00
faq.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
git-integration.md Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
index.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
json-schema.md fix(mol): molecule reads, auto-close and close --continue over http through issueops entries (S16) (#7513) 2026-10-12 19:50:34 +00:00
observability.md refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859) 2026-08-03 00:05:06 -07:00
protected-branches.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
troubleshooting.md fix(close): verify bead gates on the proxied-server route (#5861 item 1) (#6962) 2026-10-08 06:01:18 +00:00
worktrees.md fix(hooks): identify the index context behind tracked-file refusals (#6457) 2026-09-27 18:07:43 -07:00