Add external event hooks for quota and provider state changes

[jychp]

Closes #2000.

What

Optional, opt-in hooks that run a user-configured command when a quota or provider event fires. CodexBar detects the event and runs the command; it does not switch providers, restart apps, or store keys.

Events: quota_low (with a per-rule usage threshold), quota_reached, quota_reset, provider_unavailable, provider_recovered, refresh_failed.

How

• Config lives in the shared config.json under a top-level hooks block, so the app and CLI share it. Off by default.
• Detection reuses the existing transition points (quota warnings, session depletion, reset detection, status changes, fetch failures), so this is mostly wiring, not a new engine.
• Execution reuses SubprocessRunner: direct exec (no shell), timeout with SIGTERM then SIGKILL, absolute-path validation. Dispatch is fire-and-forget so it never blocks the menu refresh.
• Surfaces: a Hooks settings pane and codexbar hooks list | enable | disable | test.

Security boundary

• The hook process gets a minimal environment: an allowlist of general vars (PATH, HOME, USER, SHELL, locale, TMPDIR) plus the event's CODEXBAR_* values. CodexBar's own environment is not inherited, so a provider key living in env cannot reach a hook.
• No secrets in the payload; the account field is omitted when "hide personal info" is on.
• Failure logs are redacted: only the event and a coarse reason (exit code, timeout, not found), never the command's stderr.
• Only the events that can repeat every refresh (provider_unavailable, refresh_failed) are rate limited. Quota events dedupe upstream, so they are not throttled.

Payload

Env vars (CODEXBAR_EVENT, CODEXBAR_PROVIDER, CODEXBAR_USAGE_PERCENT, CODEXBAR_RESET_AT, ...) plus a JSON payload on stdin.

Proof

Real CLI run against an isolated config (CODEXBAR_CONFIG), hook script pointed at a logger:

$ codexbar hooks list
Hooks: enabled
[on] quota_reached provider=codex: /path/to/hook.sh switch codex openai

$ codexbar hooks test quota_reached --provider codex
ran /path/to/hook.sh: OK — ok

# recorded by the hook (environment + stdin JSON):
env: quota_reached codex usage=0.95 window=session
stdin: {"event":"quota_reached","provider":"codex","timestamp":"2026-07-09T04:42:17Z","usagePercent":0.95,"window":"session"}

The env-allowlist test also confirms a secret in the base environment (ANTHROPIC_API_KEY) does not reach the child, while PATH does.

Tests

Unit coverage for rule matching, threshold gating, payload encoding, rate-limit classification, the environment allowlist, and the runner (exec + missing executable). Localization catalogs updated for the new UI strings. swift build, make lint, and the hooks and localization suites are green.

Notes

• Rebased onto current main so PR Fix visual settings refresh #1996 (visual settings refresh) is included; nothing from it is reverted.
• Quota hooks are decoupled from notification preferences: detection runs when either notifications or a matching hook rule is enabled, and only the notification post is gated on the notification settings. Users without a configured quota hook see byte-identical behavior.
• Editing hook rules does not trigger a provider refresh: hook writes go through updateConfig(affectsBackgroundWork: false), so the config persists and the pane re-renders without scheduling a background refresh (reuses main's refresh-isolation mechanism).
• quota_low hooks are driven by each rule's own usage threshold (crossed upward), independently of the notification thresholds and preferences. A rule without a threshold falls back to the provider's notification thresholds. Crossing selection lives in QuotaLowHookThreshold.crossedRules (Core) and is unit-tested.

Non-goals

No provider switching, no editing other tools' config, no app restarts, no storing keys, no vendor fallback chains, no running commands from remote config.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 9, 2026, 11:47 AM ET / 15:47 UTC.

Summary
Adds optional external hook rules in shared config, a Hooks settings pane, codexbar hooks CLI commands, event emission for quota/provider transitions, a subprocess-backed hook runner, localization, and tests.

Reproducibility: not applicable. as a bug reproduction: this is a new feature PR. The contributor supplied a terminal transcript for codexbar hooks test against an isolated config, and the source/tests show the intended code paths.

Review metrics: 2 noteworthy metrics.

• Changed surface: 34 files, +1544/-52. The PR spans core config, command execution, app event emission, settings UI, CLI, localization, and tests, so it needs broad maintainer review even with no current findings.
• Hook CLI surface: 4 subcommands added. list, enable, disable, and test become user-facing controls for the new command-execution feature.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #2000
Summary: This PR is the candidate implementation for the open same-author feature request; the merged visual-settings PR is adjacent because this branch preserves its refresh-isolation behavior.

Members:

• canonical: Feature request: run an external command on quota/provider events #2000 - The PR body closes this open feature request and implements its proposed external hooks mechanism.
• adjacent_distinct: Fix visual settings refresh #1996 - That merged PR owns display-only refresh isolation; this PR references and preserves that behavior but solves a different feature request.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Get maintainer approval for the local command-execution hook surface before merge.

Risk before merge

• [P1] Merging creates a new local command-execution surface and persisted hooks config contract; the code is guarded, but only maintainers can decide whether that belongs in CodexBar core.
• [P1] The feature is intentionally opt-in and direct-exec, but user-configured commands still execute on quota/provider state changes, so reviewer focus should stay on the security boundary and upgrade expectations.

Maintainer options:

1. Accept the guarded execution boundary (recommended)
   Land the PR if maintainers are comfortable owning opt-in local command hooks with absolute paths, direct exec, minimal environment, redacted logs, and disabled-by-default config.
2. Require a narrower hook surface
   Ask for a smaller event/config/UI scope before merge if the full command-execution feature is too broad for the first core version.
3. Pause the feature
   Leave the PR open or close it after maintainer comment if external command hooks should not be part of CodexBar core.

Next step before merge

• No automated repair is pending; the remaining action is maintainer product/security review of whether this new core hook surface should ship.

Maintainer decision needed

• Question: Should CodexBar core accept an opt-in local external-command hook surface for quota and provider events, including shared config, settings UI, and CLI controls?
• Rationale: The current implementation has no concrete line-level defect from this review, but adding local command execution and a persistent config contract is a product/security boundary that automation should not approve on maintainers' behalf.
• Likely owner: steipete — The decision spans CodexBar product scope, config persistence, CLI behavior, and security posture, all areas where recent main history points to steipete.
• Options:
  • Accept guarded core hooks (recommended): Merge after maintainer review if CodexBar should own this opt-in command-execution surface with the current direct-exec and redaction constraints.
  • Narrow before merge: Ask for a smaller hook contract, such as CLI-only or fewer events, before accepting the new surface.
  • Decline core surface: Keep external reactions on existing codexbar serve or user automation paths if local hooks are outside core scope.

Security
Cleared: No concrete security defect was found in the current diff; the remaining concern is maintainer acceptance of the new opt-in command-execution boundary.

Review details

Best possible solution:

Have a maintainer explicitly approve, narrow, or decline the guarded core hook surface before merging; once accepted, keep the current direct-exec, minimal-environment, redacted-payload design.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a new feature PR. The contributor supplied a terminal transcript for codexbar hooks test against an isolated config, and the source/tests show the intended code paths.

Is this the best way to solve the issue?

Unclear until maintainer direction is confirmed. If core hooks are accepted, the implementation is a reasonably narrow solution because it reuses SubprocessRunner, keeps hooks off by default, avoids shell execution, and adds focused tests.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c2d0cd1a1ff7.

Label changes

Label changes:

• add merge-risk: 🚨 security-boundary: Merging enables user-configured local processes to run in response to provider/quota events, which green tests cannot fully settle as a product/security boundary.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes a terminal transcript from a real codexbar hooks test run against isolated config, including hook-captured environment and stdin JSON; contributors should continue redacting private values in any future proof.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A generic event-hook mechanism could cover several automation requests without CodexBar owning provider switching or vendor-specific workflows.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes a terminal transcript from a real codexbar hooks test run against isolated config, including hook-captured environment and stdin JSON; contributors should continue redacting private values in any future proof.

Label justifications:

• P2: This is a normal-priority feature PR with focused tests and proof, but it needs maintainer review because it adds a security-sensitive integration surface.
• merge-risk: 🚨 security-boundary: Merging enables user-configured local processes to run in response to provider/quota events, which green tests cannot fully settle as a product/security boundary.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A generic event-hook mechanism could cover several automation requests without CodexBar owning provider switching or vendor-specific workflows.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes a terminal transcript from a real codexbar hooks test run against isolated config, including hook-captured environment and stdin JSON; contributors should continue redacting private values in any future proof.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes a terminal transcript from a real codexbar hooks test run against isolated config, including hook-captured environment and stdin JSON; contributors should continue redacting private values in any future proof.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was found and read fully; its guidance on focused SwiftPM validation, avoiding live credential probes, and treating command execution/security-sensitive behavior carefully was applied. (AGENTS.md:1, c2d0cd1a1ff7)
• Not already on main: Current main has no HookEventType, HooksConfig, codexbar hooks, or hook event strings, so the central feature is not already implemented. (c2d0cd1a1ff7)
• New config contract: The PR adds optional top-level hooks state to CodexBarConfig and preserves it through normalization, creating a new persisted user configuration surface. (Sources/CodexBarCore/Config/CodexBarConfig.swift:8, 24d4e96594d0)
• Hook execution boundary: HookRunner filters the environment to a narrow allowlist plus event variables, writes JSON to stdin, calls SubprocessRunner directly, and redacts failure logging to coarse reasons. (Sources/CodexBarCore/Hooks/HookRunner.swift:13, 24d4e96594d0)
• Previous threshold and redaction blockers addressed: The current head drives quota_low by per-rule upward crossings and maps refresh failures to coarse statuses instead of forwarding raw error descriptions. (Sources/CodexBar/UsageStore+Hooks.swift:134, 24d4e96594d0)
• Focused tests cover security and matching behavior: The PR adds hook tests for matching, threshold crossing, payloads, rate limiting, runner execution, missing executables, and base-environment secret exclusion, plus refresh-failure redaction tests. (TestsLinux/HooksTests.swift:69, 24d4e96594d0)

Likely related people:

• steipete: Git history shows Peter Steinberger owns much of the current config persistence, CLI dispatch, quota-warning, and subprocess baseline that this feature extends. (role: recent area contributor; confidence: high; commits: a83a83fa4131, b76c34014cc0, 8106e7d3cc31; files: Sources/CodexBar/SettingsStore+ConfigPersistence.swift, Sources/CodexBarCLI/CLIEntry.swift, Sources/CodexBarCore/Host/Process/SubprocessRunner.swift)
• Zihao-Qi: Authored the recently merged visual settings refresh work that this PR explicitly rebased over and preserved via updateConfig(affectsBackgroundWork:). (role: recent adjacent contributor; confidence: medium; commits: 5c6e6f99847d; files: Sources/CodexBar/SettingsStore+ConfigPersistence.swift, Sources/CodexBar/UsageStore.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (7 earlier review cycles)

• reviewed 2026-07-09T04:30:13.587Z sha b1a5c65 :: needs real behavior proof before merge. :: [P1] Pass hooks a minimal environment | [P1] Preserve display-only refresh isolation | [P2] Do not globally rate-limit quota threshold hooks | [P3] Restore the unrelated changelog entry
• reviewed 2026-07-09T04:45:46.506Z sha d7130ae :: needs real behavior proof before merge. :: [P2] Decouple quota hooks from notification preferences | [P2] Avoid refreshing providers when editing hooks
• reviewed 2026-07-09T04:50:51.049Z sha d7130ae :: found issues before merge. :: [P2] Decouple quota hooks from notification preferences | [P2] Avoid refreshing providers when editing hooks
• reviewed 2026-07-09T05:12:46.593Z sha fa11d2d :: found issues before merge. :: [P2] Honor quota_low hook thresholds
• reviewed 2026-07-09T05:19:11.718Z sha fa11d2d :: needs changes before merge. :: [P2] Honor quota_low hook thresholds
• reviewed 2026-07-09T15:05:24.002Z sha 247bcb7 :: needs maintainer review before merge. :: none
• reviewed 2026-07-09T15:16:59.372Z sha 247bcb7 :: found issues before merge. :: [P2] Send hooks a coarse refresh failure status

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1a5c65eaa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Emit quota hooks independently of notifications

This quota_reached hook is only reached after the sessionQuotaNotificationsEnabled guard above, so users who disable macOS session quota notifications but enable hooks will never receive external depletion events even on a real transition. Hooks have their own enable switch/config, so the hook emission should be tied to the quota transition rather than the notification preference; the same coupling affects quota_low through quotaWarningNotificationsEnabled.

Useful? React with 👍 / 👎.

[jychp]

@clawsweeper re-review

Pushed d7130ae addressing the review:

• Minimal hook environment (allowlist + CODEXBAR_* only), so provider keys in env can't reach a hook.
• Rate-limit only provider_unavailable / refresh_failed; quota events dedupe upstream (fixes the quota_low multi-threshold suppression).
• Redacted failure logs (coarse reason, never stderr).
• Rebased onto current main, so Fix visual settings refresh #1996 is included and nothing is reverted.
• Added real-behavior proof (codexbar hooks test output + stdin JSON) to the PR description.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[jychp]

@clawsweeper re-review

Pushed fa11d2d addressing the remaining P2 items:

• Quota hooks decoupled from notification preferences (detection runs when notifications OR a matching hook rule is enabled; only the notification post is gated on the notification setting). Gated on hasQuotaHookRule, so behavior is unchanged for users without a quota hook.
• Editing hook rules no longer triggers a provider refresh: hook writes bump a separate hooksRevision instead of configRevision, preserving the Fix visual settings refresh #1996 refresh isolation.

Quota/notification transition suites and hooks tests are green.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[jychp]

@clawsweeper re-review

Pushed 247bcb7 fixing the remaining P2 (quota_low threshold contract):

• quota_low hooks now run on a dedicated path and fire when usage crosses each rule's own threshold upward, independent of the notification thresholds. A thresholdless rule falls back to the provider's notification thresholds.
• The notification path reverted to notification-only; hooks no longer piggyback on notification-threshold crossings.
• Crossing selection extracted to QuotaLowHookThreshold.crossedRules (Core) with focused unit tests: own-threshold crossing, thresholdless fallback, and selecting only the newly-crossed rule (no re-fire of lower thresholds).

All hooks + quota/notification transition suites green; make lint clean.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[jychp]

@clawsweeper re-review

Pushed 24d4e96 addressing the remaining P2 (refresh_failed payload redaction):

• refresh_failed hooks now receive a coarse, non-secret status (timeout / offline / network_error / auth_required / cancelled / error) derived from the error type and NSURLError code only, via refreshFailureHookStatus. The raw error.localizedDescription is no longer forwarded to hooks.
• Added a test asserting URL errors map to categories and that a body-bearing provider error never leaks its description into the status.

Also merged current main (resolved the background-work config conflict by adopting updateConfig(affectsBackgroundWork:) and dropping the parallel hooksRevision). make lint clean; hooks + quota/notification/localization suites green.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.