Skip to content

feat(doctor): session trailer prepare-commit-msg hook via workit doctor --fix - #257

Merged
BrainerVirus merged 13 commits into
mainfrom
feature/session-trailer-hook
Oct 9, 2026
Merged

feat(doctor): session trailer prepare-commit-msg hook via workit doctor --fix#257
BrainerVirus merged 13 commits into
mainfrom
feature/session-trailer-hook

Conversation

@BrainerVirus

@BrainerVirus BrainerVirus commented Oct 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Why

Claude Code's worktree isolation checks refuse workit git in worktree-isolated subagents, and they can't be turned off (https://code.claude.com/docs/en/worktrees#how-claude-code-enforces-isolation). So subagent commits are plain git and lose the Workit-Session trailer. The user approved a hook that adds it.

What

  • workit-core/src/git/session-hook.ts: a POSIX sh prepare-commit-msg hook that appends Workit-Session: <id> (interpret-trailers addIfDifferent, id rules as in host-session.ts).
    • It runs for -m, -F, amend, merge, squash and --no-verify.
    • It skips template commits (keeping git's "you did not edit" abort) and rebase/cherry-pick replays.
    • Comment-only messages are left alone.
  • It never renames, chains or wraps another tool's hook. It installs only into an empty slot, or over its own older script.
    • If husky, lefthook or another hook owns prepare-commit-msg, the slot is reported as blocked with a fix for that owner: one line for .husky/prepare-commit-msg, a ready-to-paste lefthook.yml job, or a generic line.
    • Hooks dirs outside the repo, tracked hooks, and unignored hooks dirs are also blocked.
    • Installs are staged and renamed inside try/finally.
  • workit doctor: an advisory session_hook check, in configured workspaces only. workit doctor --fix installs, and only inside a Workit workspace. There is no uninstall verb: delete the file, whose header names Workit.
  • Docs: delivery guide "Session trailer hook"; hosts guide pointer. On Cursor, raw commits get the trailer only with WORKIT_SESSION_ID set.
  • feat(codex): ship workit agents; doctor checks codex hook trust and the pi extension #253 follow-ups: a verb-level doctor test for the cliVersion wiring; an isolated env in the reliability-report fixture test.

The first design renamed an existing commit-msg hook in order to chain it. Review proved, with real husky 9.1.7 and lefthook 2.1.16, that this silently disables husky's hook and is undone by lefthook install. It was replaced.

Verification

  • workit check lint, typecheck and test pass (1862 pass). bun run knip is clean.
  • bun run build && bun scripts/test.ts packaging: 245 pass.
  • 16 hook tests against real lefthook 2.1.16 and a real husky 9.1.7 stub:
    • the user's own commit-msg checks still reject a bad message after --fix;
    • lefthook install --force leaves our hook working;
    • lefthook taking the slot means blocked, with .old named;
    • each printed manual line works when applied.
  • 5 doctor verb tests.

🤖 Generated with Claude Code

BrainerVirus and others added 5 commits October 8, 2026 23:41
@BrainerVirus @claude
feat(core): commit-msg hook that adds the Workit-Session trailer to p…
233e485 
…lain commits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus @claude
feat(doctor): report the session trailer hook and install it with --fix
49f7417 
doctor --fix installs the commit-msg hook in a Workit workspace only, chaining an
existing hook. Adds a verb-level pi_extension stale test and isolates the
reliability-report doctor env from CODEX_HOME and PI_CODING_AGENT_DIR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus
fix(doctor): name --fix in the doctor usage; copy session-hook into t…
2fd8cf6 
…he installer stub

Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f
@BrainerVirus
refactor(doctor): keep SESSION_HOOK_FIX module-private
d91c235 
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f
@BrainerVirus @claude
fix(doctor): add the session trailer from prepare-commit-msg, never a…
6f16c2d 
…nother tool's hook

The hook moves to the prepare-commit-msg slot and is written only into an
empty slot or over Workit's own script. A husky, lefthook or other hook there
is left untouched and the check prints a tailored manual line. Chaining is
gone; files left by the earlier commit-msg design are reported with recovery
steps. Templates and rebase or cherry-pick replays are left unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus BrainerVirus changed the title feat(doctor): session trailer commit-msg hook via workit doctor --fix feat(doctor): session trailer prepare-commit-msg hook via workit doctor --fix Oct 9, 2026
BrainerVirus and others added 8 commits October 9, 2026 00:41
@BrainerVirus @claude
fix(doctor): run one session-trailer helper from the hook and every m…
2e6b855 
…anual line

doctor --fix writes the trailer logic to <git-common-dir>/workit/session-trailer.sh,
even when the prepare-commit-msg slot is blocked. Workit's hook and the lines
given for husky, lefthook and other hooks are the same one-liner that runs it,
so merge, editor, template, opt-out and id validation behave the same
everywhere. Plain editor commits get no trailer. husky 4-8 hooks are their own
manual target.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus @claude
fix(doctor): keep the session-trailer line silent without the helper …
dbc30c0 
…and pass once it is added

The hook and manual line are a no-op when the helper is missing, also outside a
git repository, so a committed husky line is quiet in teammates' clones. A
foreign hook, husky script or lefthook config that already runs the helper
reports pass (via husky, lefthook or the existing hook). The helper treats
lefthook's literal {2} placeholder as no message source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus @claude
fix(doctor): count a manual session-trailer fix only when it really r…
9380f30 
…uns the helper

Shell targets need a non-comment line that invokes the helper, and a hook git
runs needs the executable bit (husky 9 user scripts do not). lefthook needs a
run: under the top-level prepare-commit-msg key, read indentation-aware from
lefthook(-local) YAML. Comments, TODOs, a non-executable hook, a commented job
or a job under commit-msg stay blocked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus @claude
test(doctor): type the manual-detection outcomes
0864363 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus
Merge branch 'main' into feature/session-trailer-hook
c68d380
@BrainerVirus @claude
fix(doctor): make the lefthook session-trailer job work on Windows an…
106de25 
…d with spaced paths

lefthook on Windows runs a job as "sh" -c "<run>" without escaping, so the
printed job now has no double quote: set -f and an empty IFS keep the helper
path one word. lefthook pastes {1} unquoted, and from a linked worktree it is
an absolute path that can hold a space, so the job single-quotes it. Tests use
long native temp paths and sh-quoted editor scripts on Windows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus @claude
fix(doctor): stop passing lefthook's raw {1} to the session-trailer h…
5a64a9e 
…elper

lefthook pastes {1} unquoted, and from a linked worktree it is an absolute path
that a quote breaks. The job now passes '' {2} {3} and the helper finds the
message file itself: COMMIT_EDITMSG, plus MERGE_MSG when the source is merge
(git merge hands the hook MERGE_MSG). Manual detection now needs sh in command
position, so echo sh $h does not count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Workit-Session: fb894a62-61b7-4f32-a4d0-f47c2e5e300f-w-session-trailer-hook
@BrainerVirus
Merge branch 'main' into feature/session-trailer-hook
ea4e147
@BrainerVirus
BrainerVirus merged commit fd6eb9f into main Oct 9, 2026
12 checks passed
@BrainerVirus
BrainerVirus deleted the feature/session-trailer-hook branch October 9, 2026 05:25
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 8.9.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@BrainerVirus