From cd5b731884742a51de7c6a61ee5fca0f550c9a67 Mon Sep 17 00:00:00 2001 From: damocles Date: Mon, 29 Jun 2026 01:17:29 +0200 Subject: [PATCH] refactor(#2058): drop claude.md docs pointer, keep nix option + --add-dir --- hive-ag3nt/src/turn.rs | 11 +++----- nix/agent-claude.md | 9 ------- nix/templates/harness-base.nix | 48 ++++++++++------------------------ nix/templates/manager.nix | 8 +++--- 4 files changed, 22 insertions(+), 54 deletions(-) delete mode 100644 nix/agent-claude.md diff --git a/hive-ag3nt/src/turn.rs b/hive-ag3nt/src/turn.rs index 9f7aed02..e44c732b 100644 --- a/hive-ag3nt/src/turn.rs +++ b/hive-ag3nt/src/turn.rs @@ -695,17 +695,14 @@ async fn run_claude(prompt: &str, files: &TurnFiles, bus: &Bus) -> Result<(bool, .arg("--allowedTools") .arg(mcp::allowed_tools_arg()); // hyperhive.docs.enable wires HIVE_DOCS_DIR to the in-container - // reference-docs dir (the docs/ tree plus a generic `CLAUDE.md` - // pointer at its root). Expose it to claude as an additional - // directory so the docs are readable, and enable additive CLAUDE.md - // loading so claude picks up `/CLAUDE.md` ALONGSIDE the agent's - // own memory files — never clobbering ~/.claude/CLAUDE.md or the - // project one. Unset (docs disabled) → neither flag is passed. + // reference-docs tree. Expose it to claude as an additional + // directory so the docs are readable; the agent is NOT pointed at + // them (no CLAUDE.md autoload) — surfacing a pointer is the open + // follow-up. Unset (docs disabled) → the flag is not passed. if let Some(docs_dir) = std::env::var_os("HIVE_DOCS_DIR") && !docs_dir.is_empty() { cmd.arg("--add-dir").arg(&docs_dir); - cmd.env("CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD", "1"); } let mut child = cmd .stdin(Stdio::piped()) diff --git a/nix/agent-claude.md b/nix/agent-claude.md deleted file mode 100644 index 11f4547b..00000000 --- a/nix/agent-claude.md +++ /dev/null @@ -1,9 +0,0 @@ -# Hyperhive reference docs - -The hyperhive subsystem docs ship read-only inside this container at -`$HIVE_DOCS_DIR/docs/` (resolve the env var, e.g. -`ls "$HIVE_DOCS_DIR/docs"`). - -On a fresh deploy, read `$HIVE_DOCS_DIR/docs/setup.md` first for the -first-run hive bootstrap commands (forge / gateway / matrix -provisioning, spawning the first sub-agents). diff --git a/nix/templates/harness-base.nix b/nix/templates/harness-base.nix index 39de4026..7a2c2473 100644 --- a/nix/templates/harness-base.nix +++ b/nix/templates/harness-base.nix @@ -70,23 +70,6 @@ let iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } '' rsvg-convert -f png -w 512 -h 512 ${config.hyperhive.icon} -o $out ''; - # hyperhive.docs.enable: the in-container directory claude is pointed - # at for the hyperhive reference docs (root/manager default-on; see - # `manager.nix`). Combines the standalone docs tree - # (`pkgs.hyperhive-docs`) under `docs/` with a generic, agent-agnostic - # `CLAUDE.md` pointer (`nix/agent-claude.md`) at its root. The harness - # adds this dir via `--add-dir` and sets - # `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`, so claude loads the - # sibling `CLAUDE.md` ADDITIVELY (never replacing the agent's own - # `~/.claude/CLAUDE.md` or the project one) and gets read access to - # `docs/`. Built as a runCommand (like `iconPng` above) so the tree is - # GC-rooted by the system closure — no persistent symlink into the - # store to dangle after a content change + GC. - agentDocs = pkgs.runCommand "hive-agent-docs" { } '' - mkdir -p $out - cp ${../agent-claude.md} $out/CLAUDE.md - cp -r ${pkgs.hyperhive-docs} $out/docs - ''; in { # Shared scaffolding for every hyperhive harness container. @@ -228,16 +211,14 @@ in }; options.hyperhive.docs.enable = lib.mkEnableOption '' - point this agent at the hyperhive reference docs (the repo `docs/` - tree, shipped read-only as the standalone `hyperhive-docs` - derivation). When enabled the harness adds the in-container docs dir - via `claude --add-dir` and turns on additive CLAUDE.md loading - (`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`), so claude loads a - generic pointer `CLAUDE.md` from that dir ALONGSIDE — never replacing - — the agent's own `~/.claude/CLAUDE.md` and project memory. The docs - are readable at `$HIVE_DOCS_DIR/docs/`. Default-on for the - root/manager agent (see `manager.nix`), off elsewhere; any agent can - flip it from its `agent.nix`. + make the hyperhive reference docs (the repo `docs/` tree, shipped + read-only as the standalone `hyperhive-docs` derivation) available + in-container. When enabled the harness exposes the docs dir to claude + via `claude --add-dir`, so the markdown is readable at + `$HIVE_DOCS_DIR/`. The agent is NOT yet pointed at the docs (no + auto-loaded `CLAUDE.md` pointer) — surfacing a pointer is a tracked + follow-up. Default-on for the root/manager agent (see `manager.nix`), + off elsewhere; any agent can flip it from its `agent.nix`. ''; options.hyperhive.allowedBashPatterns = lib.mkOption { @@ -1270,13 +1251,12 @@ in HIVE_COMPACT_WATERMARK_TOKENS = "0"; } // lib.optionalAttrs config.hyperhive.docs.enable { - # hyperhive.docs.enable: the in-container reference-docs dir — the - # docs/ tree plus the agent CLAUDE.md pointer (see `agentDocs` - # above). The harness reads this and passes it to claude as - # `--add-dir` with additive CLAUDE.md loading enabled, so the docs - # are discoverable without touching the agent's own memory files. - # See hive-ag3nt::turn. - HIVE_DOCS_DIR = "${agentDocs}"; + # hyperhive.docs.enable: the in-container reference-docs tree + # (`pkgs.hyperhive-docs`, the repo docs/ verbatim). The harness + # reads this and passes it to claude as `--add-dir` so the docs are + # readable; the agent is not auto-pointed at them. See + # hive-ag3nt::turn. + HIVE_DOCS_DIR = "${pkgs.hyperhive-docs}"; } // lib.optionalAttrs (config.hyperhive._bashEnvFragments != "") { # Non-interactive bash invocations (claude's `Bash` tool runs diff --git a/nix/templates/manager.nix b/nix/templates/manager.nix index a64e196c..b6a9d1ea 100644 --- a/nix/templates/manager.nix +++ b/nix/templates/manager.nix @@ -6,9 +6,9 @@ imports = [ ./harness-base.nix ]; # The root/manager bootstraps a fresh hive, so it gets the hyperhive - # reference docs surfaced by default (the additive `CLAUDE.md` pointer - # → `$HIVE_DOCS_DIR/docs/setup.md`, added via `claude --add-dir`). - # `mkDefault` so a manager's own `agent.nix` can still turn it off. - # Other agents default off. + # reference docs made available by default (readable at + # `$HIVE_DOCS_DIR/`, added via `claude --add-dir`). `mkDefault` so a + # manager's own `agent.nix` can still turn it off. Other agents default + # off. hyperhive.docs.enable = lib.mkDefault true; }