Skip to content

Make provider hook adapter names and directories explicit #217

Description

@judell

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions