Repository navigation
feat(hooks): orient subagents, drop ignored nudges, move state out of the repo (#184) - #301
Merged
Merged
Conversation
Claude Code never fires SessionStart for subagents, which do most of the code searching, so they started blind. `codemap hook subagent-start` (installed by setup under SubagentStart, no matcher) answers with one envelope: the top-level directories with hub marks, the hub list and the Next line, capped at 2,500 characters. It renders through the existing tree subprocess with a new CODEMAP_TREE_LEAN=dirs level (DirsOnly: no header panel, no file listings, no line counts). It reads the payload's cwd so a worktree-isolated subagent is oriented on its own tree, and on any error or outside a git repo it prints nothing and exits 0. Codex has no subagent-start event, so Codex setup is unchanged. Removed nudges agents ignored: the edit hooks' "Run now:" / "Re-check with:" / "Next codemap:" command lists (followed 0.9% of the time) and the prompt-submit "Next codemap:" block (2.7%). The hub warning, dependents, importer and hub-import lines stay. Prompt-submit no longer emits the fallback check-deps suggestion whose reason was "risk is unknown ..."; the intent marker now carries "suggestions":[] instead of a placeholder, and the Suggestions block prints only for file-specific suggestions. Edit hooks ignore files that resolve outside the project root (both sides canonicalised via projectpath.CanonicalPath), and post-edit no longer records them as agent edits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8DzwM4bQnL7mvk6Fsq
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8DzwM4bQnL7mvk6Fsq
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
- Fit the trailer (legend, hubs, Next) first and cut directory lines to the remaining budget, ending them with "... N more directories". A repo with 61 top-level directories lost the hub list and Next line before. - The tree subprocess runs under exec.CommandContext; subagent-start gives it 3s and prints nothing when it runs out, so a timeout no longer leaves the child running. - The dirs render skips EnsureProjectConfig, so the hook no longer creates .codemap/config.json in repos that never ran setup. Session-start and prompt-submit still auto-write config by design (#184). - projectRelPath canonicalises only the parent directory and accepts a path spelled under root or its canonical form, so in-repo symlinks to files or directories outside the repo count as inside. - The dirs level prints a single-file directory as a directory, not dir/FILE. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8DzwM4bQnL7mvk6Fsq
A repo counts as set up when its policy directory (<setup root>/.codemap, shared by linked worktrees) exists. Only `codemap setup`, `codemap config init` and `codemap skill init` create it. Until then: - projectpath.SelectRuntime resolves machine state (projects/<key>/ state and status, events.log, handoff, hubs.txt, sessions, topology cache, agent_edits.jsonl) to $XDG_CACHE_HOME/codemap/<ProjectKey>/, else the OS user cache dir. Hooks and the daemon share this one resolver, so they agree for symlinked roots and worktrees. agent_edits and the topology root wrappers now go through it instead of joining root/.codemap. - EnsureProjectConfig writes nothing; config falls back to config.Load defaults (no auto-detected `only`), and the setup nudge stays quiet. - The daemon no longer creates the config dir to watch it. Set-up repos keep every path they had. In-repo .codemap/ now carries its own .gitignore (machine state ignored, config.json and skills/ committable), written only when missing, by gitexclude.MkdirAll and the init commands. codemap no longer adds .codemap/ to .git/info/exclude; existing rules stay. Setup and doctor list tracked machine-state files (not config.json or skills/) and print `git rm --cached -- <files>`; neither runs it. Also: state paths printed by pre-compact, session-stop and `watch` are the resolved ones; the walker skips .claude/worktrees/ by path; every test package that can write state points XDG_CACHE_HOME at a temp dir. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
subagent-start rendered the tree on every spawn, 3.96s on a 10k-file repo, which after the 3s deadline meant no block at all. The block is now cached in the project's state directory (subagent-start.json), keyed by HEAD plus a format version: - hit: print the cached block, no render (0.02s here vs 0.54s for a miss) - miss: render under the 3s deadline and store the result atomically - deadline passed: print nothing, start a detached `hook subagent-refresh` that renders under a 60s bound and stores the block; a lock file with a 60s staleness takeover keeps it to one per project - a corrupt or unreadable cache is a miss, never an error Remaining ceiling: keyed on HEAD, so a new uncommitted top-level directory appears only after the next commit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
Tracked .codemap/ file names are repo-controlled, so the printed `git rm --cached` line now carries only names matching known codemap state files in [A-Za-z0-9._/-] (no ".."). Every tracked machine-state file is listed as quoted data; unrecognised names are listed but left out of the command. The user state directory no longer falls back to os.TempDir(): with no absolute XDG_CACHE_HOME and no OS user cache dir, SelectRuntime returns ErrNoStateDir, writes are skipped, reads see no state, and hooks exit 0. The cache root and per-project directory are created 0700, must be real directories owned by the current user (narrowed to 0700 if wider), and carry the project marker the --setup-root branch already uses, so a planted symlink or another user's directory is refused. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
State location no longer depends on whether <root>/.codemap/ exists. That runtime marker caused a split brain when setup ran under a live daemon, made linked worktrees show `?? .codemap/`, let a worktree become "set up" by accident, and cost un-set-up repos their auto-detected `only` filters. - SelectRuntime always resolves <cache>/codemap/<key>/ (explicit --setup-root unchanged). In-repo .codemap/ holds only config.json and skills/, written only by setup, config init and skill init; nothing else writes .gitignore there. Legacy in-repo state is not read. - Auto-detected config is stored once as auto-config.json in the state dir; config.Load and the daemon fall back to it, an in-repo config.json wins. - Getting the state dir: Lstat from the codemap leaf down before canonicalising (links refused, links above the cache root allowed), create at most the cache dir's last component (never a missing home), every level 0700 and state files 0600. Every failure wraps ErrNoStateDir, so hooks stay quiet and exit 0. The daemon registry also never creates home. - A live daemon found only through the registry (an older binary's state layout) counts as not running; `watch start` stops it after the ownership check and starts one, `watch stop` stops it, `watch status` names it. - subagent-start launches the background render before the foreground one, so a hook timeout that ends the process still fills the cache. - doctor prints the state dir; doctor and setup list committed legacy state with the untrack command and untracked leftovers as safe to delete, names escaped as \xNN outside [A-Za-z0-9._/-]. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
…lter State now lives in ~/.codemap/state/<key>/, beside the daemon registry, and XDG_CACHE_HOME / os.UserCacheDir are no longer consulted, so two processes with different XDG values share one daemon. Same guarantees as before: 0700 dirs, 0600 files, Lstat checks from .codemap/state down, owner check, project marker (now published with a hard link so a concurrent reader never sees it empty), no temp fallback, a missing home is never created. The registry records each daemon's state dir, so a daemon under an explicit --setup-root layout is not mistaken for an old-binary daemon. Every state reader and writer goes through internal/runtimefile, which refuses a symlinked or non-regular file (O_NOFOLLOW append on Unix, Lstat plus SameFile on read). Hooks treat ErrUnsafe like a missing state dir and degrade quietly. The auto config is re-derived from the scan `codemap .` already does and rewritten when it changes; hooks and `watch start` never scan for it. The tree prints "auto filter: only ...; codemap config show" when it applies. ReadLatest falls back once, read-only, to the legacy in-repo handoff. subagent-start renders at most once per repo per HEAD: the lock winner launches one detached refresh, every caller waits up to its budget for the cache. A losing `watch start` racer reports the running daemon and exits 0. Doctor only calls known machine-state names safe to delete and lists anything else as unrecognised. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
…filter CI: drop dead helpers staticcheck flagged. Windows failures were test isolation, not the product: subprocesses got only HOME, but os.UserHomeDir reads USERPROFILE there, so state landed in TestMain's shared home and each test's own home stayed empty. Every test helper now sets both. The subagent timeout test holds the render back with a test-only CODEMAP_TEST_SUBAGENT_RENDER_DELAY instead of racing 1ms. Reading state creates nothing (projectpath.StateDir): config.Load, watch status, handoff reads and the subagent cache hit path only check the levels that exist. A plain directory gets no state at all, a git repo one entry. The five TestMains that only hid that are gone. The auto filter is re-derived from git ls-files, unbounded, never from a bounded walk; the tree walks with the stored filter as before, and without git the stored copy stays. Its note prints only for a person (hooks now always set CODEMAP_TREE_LEAN) and only when it hides a file. Removed the in-repo handoff fallback: a cloned repo could feed text to the agent as its own last session. The sessions dir and daemon registry are Lstat-checked before any list, write or cleanup, so a planted link cannot make codemap delete outside the state dir. Every refused state path gets one error naming it and saying to remove it; hooks stay silent and exit 0. The subagent lock records the refresher's pid and is taken over at once when it is dead. With no usable state dir subagent-start renders in the foreground. A losing `watch start` that sees no daemon fails. Doctor counts only known state names as committed machine state. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
Windows refuses to replace an open file, so trimming the event log failed there once the read went through runtimefile.OpenRead. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
The timeout path for session-stop returned the unsafe-state error, so a planted handoff.latest.json link made the hook exit 1. Apply the same degrade rule RunHook uses. The existing test now edits a tracked file so session-stop reaches the handoff write. Also cap the test-only subagent render delay at 5s. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
…tings Claude decides which hooks fire from its settings file, so an upgraded binary alone never got the new SubagentStart event. The session-start hook now adds the entry to any Claude settings file that already holds codemap's own session-start hook, prints one line, and leaves every other settings file untouched. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
Codex 0.163.0 has a SubagentStart hook event with the same hookSpecificOutput.additionalContext shape as Claude Code, so setup now wires it for Codex too. The session-start self-repair covers both agents and prints its notice inside the hook output, so Codex's JSON envelope stays valid. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
A project .codex/hooks.json can be shipped by a cloned repo. Repairing it and printing 'trust it from /hooks' would steer the user into trusting a file codemap did not write. Only the user's own CODEX_HOME hook file is repaired; project-local Codex setups re-run codemap setup. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three changes that came out of measuring how agents actually use codemap in Claude Code transcripts.
1. Subagents get an orientation block at start
SubagentStarthook, wired bycodemap setupfor Claude Code and Codex, for every subagent type.Next:line, capped at 2,500 characters.SubagentStartentry to any Claude or Codex hook file that already has codemap hooks, prints one line, and it is active from the next session (Codex asks for the new hook to be trusted first; only the global Codex hook file is repaired, never a project.codex/hooks.json, which can come from a cloned repo).2. Ignored nudges removed
3. Machine state leaves the repo (fixes #184)
~/.codemap/state/<project key>/, never in the working tree. Directories are 0700, files 0600, and links are refused from the state level down..codemap/holds onlyconfig.json,skills/and a.gitignorethat ignores everything else. Onlycodemap setup,codemap config initandcodemap skill initwrite it..git/info/excludefor.codemap/any more.auto-config.jsonin the state directory instead of an in-repoconfig.json.codemap doctorandcodemap setupreport leftover and tracked state files and print a safegit rm --cachedcommand.Known limits
~/.codemap/stateis not garbage-collected.codemap ..Test plan
go test ./...,go vet ./..., staticcheck: pass locally and in CI (Linux, macOS, Windows).watch start, dead refresh lock takeover.Closes #184
🤖 Generated with Claude Code
https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT