Skip to content

feat(hooks): orient subagents, drop ignored nudges, move state out of the repo (#184) - #301

Merged
JordanCoin merged 15 commits into
mainfrom
feat/subagent-orientation
Nov 15, 2026
Merged

JordanCoin merged 15 commits into
mainfrom
feat/subagent-orientation

Conversation

@JordanCoin

@JordanCoin JordanCoin commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

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

  • New SubagentStart hook, wired by codemap setup for Claude Code and Codex, for every subagent type.
  • Block is top-level directories with hub stars, the hub list and a Next: line, capped at 2,500 characters.
  • Existing installs repair themselves: the session-start hook adds the SubagentStart entry 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).
  • Cached per HEAD in the state directory and refreshed by one detached process, so large repos do not stall a subagent start.

2. Ignored nudges removed

  • The "Run now", "Re-check with" and "Next codemap" lines are gone (followed 0.9% to 2.7% of the time). Hub warnings stay.
  • Prompt hook no longer prints "risk is unknown".
  • Edit hooks ignore files outside the project.

3. Machine state leaves the repo (fixes #184)

  • State now lives in ~/.codemap/state/<project key>/, never in the working tree. Directories are 0700, files 0600, and links are refused from the state level down.
  • In-repo .codemap/ holds only config.json, skills/ and a .gitignore that ignores everything else. Only codemap setup, codemap config init and codemap skill init write it.
  • Nothing edits .git/info/exclude for .codemap/ any more.
  • Auto-detected file filter is stored as auto-config.json in the state directory instead of an in-repo config.json.
  • codemap doctor and codemap setup report leftover and tracked state files and print a safe git rm --cached command.
  • No safe state directory degrades features quietly; hooks always exit 0.

Known limits

  • Old in-repo state, including the last saved handoff, is not migrated.
  • ~/.codemap/state is not garbage-collected.
  • The auto filter refreshes only on codemap ..
  • The subagent block is cached per commit.
  • The Codex subagent hook is checked against the 0.163.0 hook schema, not exercised in a live Codex subagent.
  • Windows skips directory ownership checks; filesystems without hard links run with state disabled.

Test plan

  • go test ./..., go vet ./..., staticcheck: pass locally and in CI (Linux, macOS, Windows).
  • Six rounds of independent review plus hands-on adversarial checks: planted file and directory links, linked worktrees, data-heavy repos, 20,000 untracked files, concurrent watch start, dead refresh lock takeover.

Closes #184

🤖 Generated with Claude Code

https://claude.ai/code/session_01FWQw8CwnpBLPW6jJiDE7BT

JordanCoin and others added 2 commits November 14, 2026 22:07
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
@codecov-commenter

codecov-commenter commented Nov 15, 2026 •

Copy link
Copy Markdown

JordanCoin and others added 10 commits November 14, 2026 22:17
- 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
@JordanCoin JordanCoin changed the title feat(hooks): orient subagents at start, drop ignored nudges feat(hooks): orient subagents, drop ignored nudges, move state out of the repo (#184) Nov 15, 2026
JordanCoin and others added 3 commits November 15, 2026 05:52
…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
@JordanCoin
JordanCoin merged commit 9e0de7e into main Nov 15, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

hygiene: codemap leaves .codemap/ state in every repo it touches, unignored and sometimes committed; agent worktrees pollute scans

2 participants