Before
The worklist guard filenames and directories do not consistently advertise provider ownership.
Current names mix a generic Claude adapter name with provider-specific Codex names:
app/__shell/worklist-guard.py is the canonical Claude guard, but the filename looks provider-neutral.
.claude/hooks/worklist-guard.py is the installed Claude hook copy, also generic.
app/shell/worklist-guard-codex.py is the canonical Codex guard, but uses a different provider suffix pattern.
~/.bram/codex-worklist-guard.py is the installed Codex hook and does announce Codex.
That makes the architecture harder to read. The policy and state are provider-neutral, but these scripts are provider-specific hook adapters and should say so in their names.
The directory split adds another layer of confusion:
app/__shell/ is mostly the browser-served shell asset namespace (/__shell/...), but it also contains Claude provider hook sources.
app/shell/ is mostly unserved shell/support material, but it contains Codex provider hook sources.
That means provider hook ownership is split across two similarly named directories for reasons unrelated to provider behavior.
After
Move provider hook adapter sources into a dedicated provider-hook directory, then rename and document them so provider identity is explicit and uniform.
Target canonical layout:
- Claude canonical source:
app/provider-hooks/claude-worklist-guard.py
- Claude permission-menu hook source:
app/provider-hooks/claude-permission-menu-hook.py
- Codex canonical source:
app/provider-hooks/codex-worklist-guard.py
- Codex permission-menu hook source:
app/provider-hooks/codex-permission-menu-hook.py
Target installed/runtime layout:
- Claude installed hook:
.claude/hooks/claude-worklist-guard.py
- Claude installed permission-menu hook:
.claude/hooks/claude-permission-menu-hook.py
- Codex installed hook:
~/.bram/codex-worklist-guard.py
- Codex installed permission-menu hook:
~/.bram/codex-permission-menu-hook.py
Keep directory meanings clean:
app/__shell/ remains for served shell/runtime assets such as helpers.js and conventions.md.
app/shell/ must either be justified or removed. Keep it only if every remaining file is shell-launch support and the docs say that plainly: claude-code-shellrc and claude-code-profile.ps1 configure the shell process used to launch Claude Code, and codex-startup-instructions.md is startup text injected into Codex sessions. If those files are better classified as provider assets during implementation, move them too and delete app/shell/.
- Provider hook adapters live under
app/provider-hooks/.
Update all setup/build/runtime references together:
src-tauri/build.rs hook sync.
src-tauri/src/lib.rs setup constants, installed-copy checks, stale/drift detection, registration command strings, diagnostics, and tests.
.claude/settings.json registration in this source repo.
- Docs and conventions that describe source-of-truth versus installed copies.
- Any UI helper text that recognizes guard filenames.
Migration/compatibility:
- Existing
.claude/hooks/worklist-guard.py installs should be treated as legacy and replaced or removed by Setup when claude-worklist-guard.py is installed.
- Existing
.claude/hooks/permission-menu-hook.py installs should be treated as legacy and replaced or removed by Setup when claude-permission-menu-hook.py is installed, unless Claude has a hard filename constraint. If there is a constraint, document it next to the registration code.
- Existing
app/shell/worklist-guard-codex.py and app/shell/codex-permission-menu-hook.py references should move to app/provider-hooks/; any migration tolerance should be documented if old names remain accepted temporarily.
- Error messages should say "Claude worklist guard" or "Codex worklist guard" rather than implying a provider-neutral
worklist-guard.py.
Verification should cover:
- Setup/build refreshes
.claude/hooks/claude-worklist-guard.py from app/provider-hooks/claude-worklist-guard.py.
- Claude hook registration points at the renamed installed hook.
- Codex hook registration still points at
~/.bram/codex-worklist-guard.py.
- Old Claude generic hook entries are pruned or migrated.
- Self-tests still run for both provider adapters.
- Repo search no longer finds provider-ambiguous
worklist-guard.py references except in explicit legacy/migration notes.
- Run Setup/regression against
~/sample-target-app and verify the generated/installed artifacts there use the new Claude hook names, Codex hook names, and registration paths without leaving stale generic hook registrations behind.
Before
The worklist guard filenames and directories do not consistently advertise provider ownership.
Current names mix a generic Claude adapter name with provider-specific Codex names:
app/__shell/worklist-guard.pyis the canonical Claude guard, but the filename looks provider-neutral..claude/hooks/worklist-guard.pyis the installed Claude hook copy, also generic.app/shell/worklist-guard-codex.pyis the canonical Codex guard, but uses a different provider suffix pattern.~/.bram/codex-worklist-guard.pyis the installed Codex hook and does announce Codex.That makes the architecture harder to read. The policy and state are provider-neutral, but these scripts are provider-specific hook adapters and should say so in their names.
The directory split adds another layer of confusion:
app/__shell/is mostly the browser-served shell asset namespace (/__shell/...), but it also contains Claude provider hook sources.app/shell/is mostly unserved shell/support material, but it contains Codex provider hook sources.That means provider hook ownership is split across two similarly named directories for reasons unrelated to provider behavior.
After
Move provider hook adapter sources into a dedicated provider-hook directory, then rename and document them so provider identity is explicit and uniform.
Target canonical layout:
app/provider-hooks/claude-worklist-guard.pyapp/provider-hooks/claude-permission-menu-hook.pyapp/provider-hooks/codex-worklist-guard.pyapp/provider-hooks/codex-permission-menu-hook.pyTarget installed/runtime layout:
.claude/hooks/claude-worklist-guard.py.claude/hooks/claude-permission-menu-hook.py~/.bram/codex-worklist-guard.py~/.bram/codex-permission-menu-hook.pyKeep directory meanings clean:
app/__shell/remains for served shell/runtime assets such ashelpers.jsandconventions.md.app/shell/must either be justified or removed. Keep it only if every remaining file is shell-launch support and the docs say that plainly:claude-code-shellrcandclaude-code-profile.ps1configure the shell process used to launch Claude Code, andcodex-startup-instructions.mdis startup text injected into Codex sessions. If those files are better classified as provider assets during implementation, move them too and deleteapp/shell/.app/provider-hooks/.Update all setup/build/runtime references together:
src-tauri/build.rshook sync.src-tauri/src/lib.rssetup constants, installed-copy checks, stale/drift detection, registration command strings, diagnostics, and tests..claude/settings.jsonregistration in this source repo.Migration/compatibility:
.claude/hooks/worklist-guard.pyinstalls should be treated as legacy and replaced or removed by Setup whenclaude-worklist-guard.pyis installed..claude/hooks/permission-menu-hook.pyinstalls should be treated as legacy and replaced or removed by Setup whenclaude-permission-menu-hook.pyis installed, unless Claude has a hard filename constraint. If there is a constraint, document it next to the registration code.app/shell/worklist-guard-codex.pyandapp/shell/codex-permission-menu-hook.pyreferences should move toapp/provider-hooks/; any migration tolerance should be documented if old names remain accepted temporarily.worklist-guard.py.Verification should cover:
.claude/hooks/claude-worklist-guard.pyfromapp/provider-hooks/claude-worklist-guard.py.~/.bram/codex-worklist-guard.py.worklist-guard.pyreferences except in explicit legacy/migration notes.~/sample-target-appand verify the generated/installed artifacts there use the new Claude hook names, Codex hook names, and registration paths without leaving stale generic hook registrations behind.