Skip to content

doctor: re-init advice keeps init's own flags (follow-up to #858) - #860

Merged
LoopGlitch26 merged 8 commits into
mainfrom
agent/doctor-reinit-flags
Nov 15, 2026
Merged

LoopGlitch26 merged 8 commits into
mainfrom
agent/doctor-reinit-flags

Conversation

@LoopGlitch26

@LoopGlitch26 LoopGlitch26 commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Follow-up to #858, which is merged now; the base is main. #858 was squash-merged, so I merged main into this branch (no rebase, no force-push). The conflicts were #858's own hunks, which this branch extends and which I kept as the branch has them, and main's jcode and Kiro CLI changes, which I kept: cli.py has both --project [DIR] and jcode's user-config refusal, and docs/doctor.md has this branch's D-HOOKS-PRESENT and D-HOOKS-MANAGED rows next to main's D-HOOKS-EVENT and D-HOOKS-ORDER rows.

Fixes the re-init advice gaps found in the review of #858. The second and third commits fix what the independent review and re-review of this PR found.

What was wrong

  1. Re-init fixes dropped init's other flags. A fix that re-ran system init gave back init's --agent, --no-hooks and --managed, and nothing else. On a host set up with --policy X --harness …, following D-CODE-TRUST (or any re-init fix) rewrote signer.yaml with init's default policy and no harness_binding. Doctor didn't say.
  2. v1: V1_REINIT never named --managed, so following it on a v1 --managed host wrote user hooks beside the managed ones.
  3. A false FAIL. On an init --managed host with allowManagedHooksOnly on, D-HOOKS-PRESENT failed "every call is decided twice" when only the agent's own settings enabled the plugin. Claude Code doesn't run that plugin then, and the agent could cause the FAIL. The fix it gave, tracekit uninstall, never removes managed hooks.
  4. D-SYSTEM-CONFIG gave a plain re-init when client.json couldn't be read, so on a managed host it moved the hooks into the agent's own settings.
  5. --managed-only came only from init's marker in the managed settings file. If an MDM policy replaced that file, the marker went with it, and the fix re-inited without --managed-only, which is weaker.

The review of this PR found these in the first commit:

  • (security) A --project init's fix told the person to run sudo python3 -m tracekit init in the project, which is the agent's own directory. -m puts the working directory first on sys.path, so a planted tracekit/ would run as root.
  • --harness was recorded as its resolved real path, which a package upgrade removes or leaves pointing at the old binary.
  • The record replayed --i-understand-agent-is-privileged, --no-witness and --public-witness.
  • migrate --system erased the v1 record.
  • install.py imported doctor's private helpers.
  • doctor --config on a host with no client.json said client.json "doesn't record" the flags.

The re-review found these in the second commit:

  • (low) --harness kept the given path even when the link sat in a directory the agent's user can write. That user could repoint the link before a re-init, and the re-init would bind any root-owned program they chose. trusted_file checks only the real path's chain.
  • The no-record note listed a bare --project. Run from the clone, that puts the hooks in the clone.
  • uninstall --project took only the working directory. Dev init's plugin check read the working directory's .claude, not DIR's.

What changes

  • The record. init --v2 records its flags in /etc/tracekit/client.json as hooks.init_flags: --managed, --managed-only, --approver (always, the resolved one), --policy, --project DIR, --harness NAME=PATH, --egress, --no-thinking-summaries and --no-service.
    • --harness is recorded as given (absolute, links kept) only when root alone can repoint it. That means every directory its lookup reads, including the ones its links' targets pass through, is root-owned and not group- or world-writable. Otherwise init records the real path. A package upgrade that moves a root-owned link's target is followed; a link the agent's user could repoint is not. The signer still binds the resolved program, a script's real path plus its interpreter.
    • v1 init records its own flags at the top level: --managed, --managed-only, --no-hooks, --no-service, --proxy --experimental [--proxy-port N], --fail-closed, --experimental-macos, --project DIR and --agent.
    • Not recorded: --i-understand-agent-is-privileged (init's refusal names it, for a user that has gained a privilege since), --no-witness (the no-witness file already keeps it) and --public-witness (replaying it can only make init fail). Witnesses, the checkpoint interval, v1 harnesses and the external signer aren't recorded either, because the signer config keeps them across inits.
    • migrate --system keeps the v1 record.
  • init --project [DIR] and uninstall --project [DIR]. Without DIR it's the working directory, as before. A re-init fix gives --project DIR and runs from the root-owned clone, like every re-init. It never tells the person to run init from a directory the agent can write. Dev init's plugin check reads DIR's .claude. As with the working directory's, it doesn't take that project's .claude for a user config root, so a repo can't vouch for a plugin key with planted install state.
  • How doctor rebuilds the fix. Doctor reads the flags only from that root-owned record, as collect() already reads client.json, and gives them back shell-quoted. The shared code is install.reinit_flags and install.setting; install no longer imports doctor's private helpers.
  • --managed-only stays when init was run with it, from the record or, on an older host, from the marker. If allowManagedHooksOnly is off now, the fix keeps it and adds: "init turned on allowManagedHooksOnly and it is off now; drop --managed-only only if you turned it off on purpose". The safe default wins. A fix that names --managed-only itself (D-HOOKS-PRESENT's) doesn't give it twice.
  • No record. That means a host set up by an older init, client.json that can't be read, or doctor --config with no client.json. The fix gives the flags doctor can see, then says plainly: "add each flag this host's init was run with that this lacks (…, --project DIR, …): client.json doesn't record them / records them, and it can't be read / there's no client.json here to record them, so doctor can't tell them, and init without them goes back to its defaults".
  • Other rows.
    • The D-HOOKS-PRESENT detail after --no-hooks gets the rebuilt flags, without --no-hooks.
    • D-HARNESS-HELPER's fix is the re-init with init's recorded --harness, not a --harness [NAME=]PATH placeholder.
    • D-HOOKS-PRESENT on a managed host with allowManagedHooksOnly on counts a plugin as running only when the managed settings enable it. Its fix is "take X out of enabledPlugins in " or "/plugin disable X in the agent's Claude Code, or --managed-only, which stops every user's own Claude Code hooks and plugins on this machine".
    • D-SYSTEM-CONFIG adds --managed (and --managed-only by the marker) when the managed settings hold Tracekit's v2 hooks. v1's D-SYSTEM-CONFIG does the same for v1 hooks.
  • docs/doctor.md: a paragraph on re-init flags, plus the D-HOOKS-PRESENT and D-HOOKS-MANAGED rows and the v1 fix.

Fail-first

I checked this on scratch copies of each head's code (git archive) with the new tests laid over them. No git stash.

On #858's head 3fe1871a7a (first commit, 11 failures):

Fix Result on 3fe1871a7a
1 flags the fix is the bare re-init; KeyError: 'init_flags'
2 v1 KeyError; … init --user <agent-user> with no --managed
3 false FAIL ('fail', "…decided twice…") where ok is right
4 D-SYSTEM-CONFIG the bare re-init, with no --managed

On the first commit 9d0b2ee39b (review fixes, 12 failures):

Review item Result on 9d0b2ee39b
--project DIR init --project /srv/my repo exits 2; the record is --project with no directory
--harness as given recorded claude=/private/var/… (the real path), not the path given
--managed-only recorded v2 and v1 records lack it; with it recorded, the fix gives --managed --managed-only --managed --managed-only; D-HOOKS-PRESENT's fix gives it twice
no privileged or witness flags the record holds --i-understand-agent-is-privileged, --no-witness, --public-witness
migrate --system None != ['--managed', '--proxy', '--experimental']
--config wording "…client.json doesn't record them"

On the second commit f34f40d24c (re-review fixes, 8 failures):

Re-review item Result on f34f40d24c
--harness link in a writable directory records claude=<the link>; once it's repointed to /bin/sh, resolve_harness binds /bin/sh (no script)
--project DIR in the note the note says a bare --project (v2 and v1)
uninstall --project DIR exits 2
dev plugin check reads DIR init writes its hooks beside the plugin DIR enables; plugin_enabled takes no project

Mutation check

Each mutant undoes one fix in a scratch copy of the branch. The second commit's 16 were all killed:

# Mutant Killed by
1 cli --project uses the cwd again; v2 or v1 record has --project without its directory CliProject, both test_init_records_the_flags_doctor_gives_again
2 --harness recorded as its real path; M10: recorded as the interpreter v2 records test
3 v2 or v1 record drops --managed-only; the fix drops a recorded one silently; a fix's own --managed-only given twice records tests, test_managed_only_stays_and_says_so_when_the_setting_is_off_now, test_a_fixs_own_managed_only_is_not_given_twice
4 v2 or v1 record replays --i-understand-agent-is-privileged records tests
5 migrate --system drops the record test_migrate_keeps_a_policy_path_and_inits_record
6 record keeps --no-witness / --public-witness; M14: D-HARNESS-HELPER's placeholder back; --config says "doesn't record them" records test, test_the_harness_helpers_fix_is_the_re_init_with_inits_harness, test_without_a_record_…

The third commit's 10 were all killed:

Item Mutant Killed by
harness always keep the given path; always record the real path; _fixed checks no directory HarnessSpec (a link in a temp dir is recorded by its real path and survives a repoint; a root-owned link chain such as macOS's /etc/hosts or merged-usr /bin/sh is kept)
note the v2 or v1 note says a bare --project test_without_a_record_…, v1 Doctor test
uninstall / plugin uninstall --project not made absolute; uninstall (Claude Code or --agent) uses the cwd; the dev plugin check reads the cwd; a named project's .claude taken for a user config root CliProject tests

Before / after, as a person sees it

This ran the real tracekit init and tracekit doctor CLIs. Only the system was mocked: root, the OS users, systemctl, the venv build, and root-owned writes, which went into a scratch tree. <REINIT> stands for from a root-owned clone of the release (…), sudo /usr/bin/python3 -m tracekit init --v2 --user <agent-user> --experimental-macos.

init --v2 --user tkagent --approver tkadmin --policy "$S/etc/corp policy.yaml" --harness claude=$S/bin/claude --no-thinking-summaries --i-understand-agent-is-privileged, where $S/bin/claude is a symlink to /bin/sh. $S is a scratch directory this user owns. D-CODE-TRUST:

#858:    fix: re-run init to reinstall the venv: <REINIT>
9d0b2:   fix: … <REINIT> --approver tkadmin --policy '$S/etc/corp policy.yaml' --harness claude=/bin/sh --no-thinking-summaries --i-understand-agent-is-privileged
f34f40:  fix: … <REINIT> --approver tkadmin --policy '$S/etc/corp policy.yaml' --harness claude=$S/bin/claude --no-thinking-summaries
now:     fix: … <REINIT> --approver tkadmin --policy '$S/etc/corp policy.yaml' --harness claude=/bin/sh --no-thinking-summaries

now is the real path because a user other than root can repoint $S/bin/claude. A link in root-only directories, such as /usr/local/bin/claude on a root-owned Homebrew prefix, is kept as given.

init --v2 … --project "$S/agent repo":

9d0b2:  init exits 2 (--project takes no directory); a cwd --project init's fix: "… --project, in <dir> (…)"
now:    fix: … <REINIT> --approver tkadmin --project '$S/agent repo'   (parsed by init's own parser: project = '$S/agent repo')

init --managed --managed-only, then an admin turns allowManagedHooksOnly off, or an MDM policy replaces the file:

9d0b2 (MDM):  fix: … <REINIT> --managed --approver tkadmin
now:          fix: … <REINIT> --managed --managed-only --approver tkadmin; init turned on allowManagedHooksOnly and it is off now; drop --managed-only only if you turned it off on purpose

The same host while the setting is on, with the agent enabling the plugin in its own settings (D-HOOKS-PRESENT):

#858:   FAIL  hooks from the Tracekit Claude Code plugin … and init's v2 hooks in …: every call is decided twice, …   fix: keep one: tracekit uninstall (init's hooks), …
now:    ok    v2 hooks in $S/managed/managed-settings.json; the Tracekit plugin's, enabled in $S/home/.claude/settings.json, don't run (allowManagedHooksOnly)

A host from an older init (no init_flags):

now:    fix: … <REINIT>; add each flag this host's init was run with that this lacks (--approver, --policy, --harness, --egress, --project, --managed-only, ...): /etc/tracekit/client.json doesn't record them, so doctor can't tell them, and init without them goes back to its defaults

client.json can't be read, and the managed file holds init's v2 hooks (D-SYSTEM-CONFIG):

#858:   fix: <REINIT>
now:    fix: <REINIT> --managed; add each flag … : /etc/tracekit/client.json records them, and it can't be read, …

v1 init --managed host (D-V1-RUNTIME):

#858:   fix: … sudo /usr/bin/python3 -m tracekit init --user <agent-user>
now (older client.json): … init --user <agent-user> --managed; add each flag … (--managed, --managed-only, --project, --proxy, --no-hooks, --no-service, ...) …
now (as init writes it): … init --user <agent-user> --managed --proxy --experimental

Limits

  • --user <agent-user> is still a placeholder, as before. client.json does record the user, so filling it in would be a small follow-up.
  • The existing --no-hooks that doctor adds when the agent's own settings enable the plugin (from System mode: hints, messages and help text that don't match what init does #464) still reads the agent's settings. I didn't change that here.
  • install.status() still imports doctor's _dev_harnesses. That import was already there before this PR.
  • Nothing tests the --harness check's walk through a root-owned link whose target passes through a writable directory, because building one needs root. The unit tests cover a link in a writable directory, a link to a root-only directory placed in a writable one, and a root-owned link chain that stays as given.
  • macOS host. The root-only and Linux /proc tests skip here, and CI's Linux run is the merge gate.

Windows CI fix (ba8f577362)

3dc73c9382 failed CI's py3.9 on windows-latest job with 7 failures. Five init --dev --v2 --project tests (test_hook_v2.py InitV2 ×3, test_harness_hooks_v2.py Installer and CodexReasoningSummary) found the hooks in the checkout, not in their temp working directory. Two CliProject assertions compared 'C:\srv\my repo' with '/srv/my repo'.

The cause isn't a default fixed when the parser is built. A parser built in one directory and run in another resolves to the second, on that head too. The cause is that --project with no DIR went through os.path.abspath("."). On POSIX that calls os.getcwd(), but on Windows it asks the OS (nt._getfullpathname). Those tests set the directory by patching os.getcwd, which is also what the code read before --project took a DIR.

DIR is now joined to os.getcwd() and normalized, which is what POSIX abspath does. The new CliProject::test_the_default_is_the_working_directory_as_init_runs stands in an abspath that ignores a patched os.getcwd, as Windows' does, and also checks a parser built before a chdir. It fails on 3dc73c9382 for both init and uninstall. The two CliProject tests now compare against os.path.abspath of the input, which is still an exact comparison.

I reproduced CI's failure locally by running the five failing tests under that Windows-style abspath (as_windows_abspath.py): 20 failures on 3dc73c9382, with the hooks written into the checkout, and 10 of 10 passing after the fix. I also merged main (#840) first; it merged cleanly.

Tests

tests/test_doctor_v2.py, tests/test_system_install.py, tests/test_install_files.py, tests/test_system_v2.py, tests/test_docs.py and tests/test_hook_v2.py (whose plugin checks plugin_enabled shares): 376 passed, 7 skipped on the merged head. make lint is clean. Full gate in the worktree (make test-ts lint build test): on f4883767ff, exit 0, 5278 passed, 446 skipped, 10 xfailed; on the merge with main (3dc73c9382), exit 0, 5324 passed, 447 skipped, 10 xfailed; on the Windows fix (ba8f577362), exit 0, 5335 passed, 447 skipped, 10 xfailed. On the Windows fix, the affected files, test_harness_hooks_v2.py and test_grants.py (from #840) included, gave 551 passed and 10 skipped. E16 on f34f40d24c: 57/57 flagged, gate PASS.

#845)

On a host set up with init --managed, only the hook checks' fixes
(D-HOOKS-MANAGED, D-HOOKS-PRESENT, D-HOOKS-VENV) named --managed. The
other re-init fixes, D-PROCESS-BOUNDARY, D-CODE-TRUST, D-UNIT-HARDENING,
D-TAILER-CONFIG among them, ended without it, so a person who followed
one ran init without --managed: init wrote its hooks into the agent's
own ~/.claude/settings.json, which the agent can edit, and took them out
of the root-owned managed file. With the Tracekit plugin on, each call
was then decided twice. Without --managed-only, init also turned off the
allowManagedHooksOnly an init with it had turned on.

collect() now adds --managed to every re-init fix when init's hooks are
in Claude Code's managed settings, and --managed-only when init recorded
it there (its _tracekit_allowManagedHooksOnly marker; an admin's own
allowManagedHooksOnly has no marker, and init leaves it). The hook
checks' fix no longer adds its own, so it names --managed once.
--no-hooks and --agent stay as #845 left them.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
A fix that re-ran system init gave back init's agent, --no-hooks and
--managed only. Following one on a host set up with --policy, --harness,
--approver, --egress and the like rewrote signer.yaml with init's defaults
(its own policy, no harness binding), and doctor didn't say.

- init --v2 records the rest of its flags in client.json (hooks.init_flags,
  and the directory of a --project init); v1 init records its own at the
  top level. Doctor reads them from that root-owned file only and gives
  them back shell-quoted. A host whose client.json predates the record gets
  a fix that says doctor can't tell init's flags, instead of a re-init that
  drops them.
- v1: V1_REINIT never named --managed; doctor now gives v1 init's flags too,
  and --managed where the managed settings hold v1 hooks on an older host.
- D-HOOKS-PRESENT no longer fails "every call is decided twice" on an
  init --managed host with allowManagedHooksOnly on when only the agent's
  own settings enable the plugin (Claude Code doesn't run it then). On a
  managed host its fix no longer names tracekit uninstall, which never
  takes managed hooks out.
- D-SYSTEM-CONFIG keeps --managed when the managed settings hold init's v2
  hooks.
- --managed-only is given again only while init's marker is there and
  allowManagedHooksOnly is still on, init's own rule.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
…eview of #860)

- init --project [DIR]: a re-init fix for a --project host named the
  directory and had the person run `sudo python3 -m tracekit init` there,
  in the agent's own repo, where -m imports a planted tracekit/ before the
  release's, as root. init now takes the directory (no DIR keeps the
  working directory), init records it, and the fix runs from the
  root-owned clone like every other re-init.
- --harness is recorded as given (absolute, symlinks kept), not as its
  resolved real path, which a package upgrade removes or leaves pointing
  at the old binary. The signer still binds the resolved program.
- --managed-only is recorded (v1 and v2). When allowManagedHooksOnly is off
  now (an admin, or MDM replacing the managed file), the fix keeps it and
  says to drop it only if it was turned off on purpose; a fix's own
  --managed-only isn't given twice.
- --i-understand-agent-is-privileged, --no-witness and --public-witness
  aren't recorded or replayed.
- migrate --system keeps v1's init_flags.
- install no longer imports doctor's private helpers: install.reinit_flags
  and install.setting are shared. doctor --config with no client.json says
  there is none.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
…(re-review of #860)

- harness_spec kept the given path, links and all, but trusted_file checks
  only the real path's chain: a link in a directory the agent's user can
  write could be repointed before a re-init, which then bound any
  root-owned program. The given path is now kept only when every
  directory its lookup reads, its links' targets included, is root-owned
  and not group- or world-writable; else init records the real path.
- The no-record note names --project DIR: a bare --project run from the
  release's clone puts the hooks in the clone.
- uninstall takes --project [DIR] as init does, and dev init's plugin
  check reads DIR's .claude (and doesn't take a named project's .claude
  for a user config root, as it didn't the working directory's).

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
Base automatically changed from agent/doctor-managed-reinit to main November 15, 2026 04:30
Conflicts: #858's squash (f32c2fe) against this branch's later edits of
the same hunks, kept as this branch has them (a superset of #858's), and
main's jcode and Kiro CLI changes: cli.py keeps both --project [DIR] and
jcode's user-config refusal; docs/doctor.md keeps this branch's
D-HOOKS-PRESENT and D-HOOKS-MANAGED rows and main's D-HOOKS-EVENT and
D-HOOKS-ORDER rows.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26
LoopGlitch26 enabled auto-merge (squash) November 15, 2026 06:13
Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
…ery OS

CI's py3.9 Windows job failed five init --dev --v2 --project tests: the
hooks went into the checkout, not the test's working directory. --project
with no DIR went through os.path.abspath(".") at run time, and on Windows
abspath asks the OS for the working directory (nt._getfullpathname)
instead of calling os.getcwd(), which those tests patch to set it and
which the code read before --project took a DIR. DIR is now joined to
os.getcwd() and normalized, as POSIX abspath does. A test stands in an
abspath that ignores a patched os.getcwd, as Windows' does, and checks a
parser built before a chdir. The two CliProject tests compare against
os.path.abspath of the input (C:\srv\my repo on Windows).

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
… tests do

CI's py3.13 windows-latest job failed it: resolve_harness couldn't take the
temp script's "#!/bin/sh" interpreter, as Python 3.13's ntpath.isabs no
longer counts a drive-less rooted path. Harness binding is system mode's,
which _require_system refuses on Windows before any harness code runs.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26
LoopGlitch26 merged commit 9c6a749 into main Nov 15, 2026
35 checks passed
@LoopGlitch26
LoopGlitch26 deleted the agent/doctor-reinit-flags branch November 15, 2026 11:15
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.

1 participant