Skip to content

[Bug]: External settings.json rewriters (e.g. CC Switch provider switching) silently wipe Orca's managed Claude hooks — agent progress stalls until the next Orca restart #16771

Open

Description

@allanpk716

Operating system

Windows 10 Pro 10.0.19045

Orca version

1.4.190

Details

Short summary: any external tool that rewrites ~/.claude/settings.json as a whole (provider switchers like CC Switch being the big one) silently wipes Orca's managed Claude hooks, because Orca only (re)installs them at startup — so Claude agent progress in the sidebar/dashboard goes stale indefinitely, until the next Orca restart.

What happened:

Claude agent progress stopped showing (Codex sessions kept reporting fine). Investigation on my machine:

  • ~/.claude/settings.json had no hooks key at all — the 12 managed entries were gone.
  • %APPDATA%/orca/agent-hooks/last-status.json contained only codex entries; zero claude entries — the whole chain after the missing hooks (env vars → claude-hook.cmd → local endpoint) was healthy, the first link was simply absent.
  • Orca 1.4.190 had auto-updated and restarted at 08:53. A CC Switch snapshot of settings.json taken at 10:46 already showed no hooks — i.e. they were wiped within that window, and were never re-installed even though Orca ran all day.

Root cause on the other side (CC Switch sync_claude_live()): on every Claude provider switch it writes settings.json as a full-file overwrite from its DB-stored template (write_json_file(&settings_path, &sanitize_claude_settings_for_live(&provider.settings_config))), not a read-merge-write. Any top-level field the template doesn't contain — hooks being the painful one — is dropped on every switch. CC Switch issues #2871 / #4096 / #6879 all describe facets of this same overwrite strategy (it also eats statusLine/permissions managed by others).

Why Codex sessions are unaffected: Codex hooks live in the Orca-managed runtime home, which external config tools don't touch. The asymmetry ("Codex reports, Claude doesn't") is a direct fingerprint of this failure mode and may help other users self-diagnose.

Impact: this isn't specific to CC Switch — anything that rewrites settings.json wholesale (dotfile managers, other switchers, backup restores) triggers it. Given how many people run a provider switcher alongside Claude Code, I'd expect a steady stream of "agent progress not showing" reports that boil down to this.

Suggestions:

  1. Re-reconcile managed hooks more aggressively than startup-only — e.g. when a Claude session is launched in an Orca terminal, or when a session's expected first hook event never arrives, or via a lightweight file watcher on settings.json.
  2. Expose a repair command. src/cli/handlers/agent-hooks.ts exists in the repo, but the shipped CLI rejects it (orca agent-hooks status → "Unknown command"). Even just a read-only status command ("hooks missing / present / which events") would have saved me an afternoon of forensics.
  3. Longer term, [Feature]: Ship the Claude status hooks as a plugin instead of writing to ~/.claude/settings.json #15496 (ship status hooks as a plugin) removes the shared-file contention entirely.

Related: #15496 (the file-ownership discussion), #15548 (invalid StopFailure event — relevant because it makes hand-copying Orca's hooks into the switcher's template a footgun: a new Claude Code skips the entire settings.json over it), #16003, #15791.

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

Metadata

Metadata

Assignees

Labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions