{"id":51708640,"url":"https://github.com/88plug/recover-from-false-positive","last_synced_at":"2026-07-20T13:03:05.450Z","repository":{"id":364890414,"uuid":"1269616446","full_name":"88plug/recover-from-false-positive","owner":"88plug","description":"Recover Claude Code sessions after an Anthropic API output-classifier false positive. JSON-aware .jsonl log surgeon: removes the triggering message + refusal turn, re-stitches the parentUuid chain so the session resumes cleanly, cleans old sessions, installs a per-repo CLAUDE.md framing guard.","archived":false,"fork":false,"pushed_at":"2026-07-17T16:59:57.000Z","size":192,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-17T18:27:15.737Z","etag":null,"topics":["agent-skills","ai","ai-coding","anthropic","automation","claude","claude-code","claude-code-plugin","claude-skills","cli","coding-agent","data-recovery","debugging","developer-tools","json-repair","logging","productivity","session-management","usage-policy"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/88plug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T23:44:58.000Z","updated_at":"2026-07-17T17:00:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/88plug/recover-from-false-positive","commit_stats":null,"previous_names":["88plug/recover-from-false-positive"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/88plug/recover-from-false-positive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Frecover-from-false-positive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Frecover-from-false-positive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Frecover-from-false-positive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Frecover-from-false-positive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/88plug","download_url":"https://codeload.github.com/88plug/recover-from-false-positive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/88plug%2Frecover-from-false-positive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35686949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","ai-coding","anthropic","automation","claude","claude-code","claude-code-plugin","claude-skills","cli","coding-agent","data-recovery","debugging","developer-tools","json-repair","logging","productivity","session-management","usage-policy"],"created_at":"2026-07-16T19:00:21.316Z","updated_at":"2026-07-20T13:03:05.445Z","avatar_url":"https://github.com/88plug.png","language":"Python","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Recover From False Positive\n\n**Claude Code session recovery for Anthropic API output-classifier false positives — JSON-aware `.jsonl` log repair, parentUuid re-stitch, and CLAUDE.md framing guards.**\n\n[![plugin-validate](https://github.com/88plug/recover-from-false-positive/actions/workflows/plugin-validate.yml/badge.svg)](https://github.com/88plug/recover-from-false-positive/actions/workflows/plugin-validate.yml)\n[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue?style=flat)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-online-2ea44f?style=flat)](https://88plug.github.io/recover-from-false-positive/)\n[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-8A2BE2?style=flat)](https://github.com/88plug/claude-code-plugins)\n[![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/88plug/recover-from-false-positive)\n\n\u003c/div\u003e\n\nRecover Claude Code sessions after an Anthropic API content-filter false positive — the hard failure *\"appears to violate our Usage Policy\"* / *\"cyber-related safeguards\"* that kills a turn mid-generation on dense-but-legitimate engineering. This Claude Code plugin is a JSON-aware `.jsonl` log surgeon for session management: it removes the triggering message and refusal turn, re-stitches the `parentUuid` chain so `claude --resume` works, cleans accumulated refusals across old sessions, and installs a per-repo `CLAUDE.md` framing guard so coding agents and LLM workflows stop re-tripping.\n\nBuilt for developers whose AI agents hit the classifier on legitimate work — mining/PoW software, supply-chain/sigstore tooling, payment automation, chaos/infra-ops, security infra — not for bypassing policy on real abuse.\n\n## Install\n\n### Claude Code\n\n```text\n/plugin marketplace add 88plug/claude-code-plugins\n/plugin install recover-from-false-positive@88plug\n```\n\n### Grok Build\n\n```text\ngrok plugin marketplace add 88plug/claude-code-plugins\ngrok plugin install recover-from-false-positive@88plug --trust\n```\n\n\n## Quickstart\n\nThe skill auto-triggers when Usage-Policy / cyber-safeguards error text appears in the conversation. To run the log surgeon yourself:\n\n```bash\n# Fix ONLY the session that just fired (removes trigger + refusal,\n# re-stitches the chain, backs up first). Resume cleanly afterward.\npython3 ${CLAUDE_PLUGIN_ROOT}/skills/recover-from-false-positive/scripts/scrub_refusals.py --fix-active\n```\n\n\u003e [!NOTE]\n\u003e Detect-only by default. The script makes a backup tarball before writing and\n\u003e refuses any change that would add a dangling `parentUuid`.\n\n## Features\n\n| Feature | What you get |\n| --- | --- |\n| Active session recovery | Remove only the trigger message + refusal; resume as if neither happened |\n| Machine-wide cleanup | Dry-run then `--apply` to scrub accumulated refusal turns; chain-safe |\n| Recurrence guard | Classify the trigger; install a `CLAUDE.md` framing section naming real files and vocab |\n| Hands-free hooks | Detect on `StopFailure`, inject recovery on next prompt, frame every subagent |\n| JSON-aware repair | Re-stitch `uuid` / `parentUuid` — never a blind `sed` delete |\n\n## What it does\n\n- **Fix the active session** — removes only the triggering message + refusal turn from the session that just fired, so it resumes cleanly.\n- **Clean old sessions** — dry-run, then `--apply` to remove accumulated refusal turns machine-wide. Chain-safe; old sessions stay resumable.\n- **Prevent recurrence** — classifies the trigger and installs a `## Cyber-safeguard false positives — READ FIRST` guard in the right `CLAUDE.md`, naming the actual trigger files and vocabulary.\n\n## How the automatic pipeline works\n\nBundled hooks make recovery and prevention hands-free:\n\n- **`StopFailure` → detect** — when a turn dies on the classifier, a pure-Python hook reads the live transcript, extracts trigger vocabulary, pre-classifies it (project-only vs cross-project), and writes `~/.claude/.fp-state.json`. No model generation, so it cannot re-trip.\n- **`UserPromptSubmit` → recover** — on your next prompt, if that state file exists, recovery steps (repair the log, classify with edgar-morin, update the right `CLAUDE.md`) are injected and the state is consumed. Always injects a short neutral generation guideline.\n- **`SubagentStart` → frame** — every subagent gets the neutral guideline so spawned prompts do not trip; `Explore`/`Plan` also get full `CLAUDE.md` re-injected (they skip it by default).\n\n## Why not `sed -i '/violate/d'`\n\nClaude Code `.jsonl` logs are a linked list — every turn carries a `uuid` and a `parentUuid` pointing at the previous turn. Deleting a line with `sed` orphans the next turn (its `parentUuid` points at a uuid that no longer exists), which breaks `claude --resume`. This script **re-stitches** the chain — rewiring each orphan's `parentUuid` up to the removed turn's parent — *before* dropping lines. That is real json-repair / data-recovery for session debugging, not a text filter.\n\n## Clean all old sessions\n\n```bash\n# dry-run first; confirm delta=0 for every file, then apply\npython3 ${CLAUDE_PLUGIN_ROOT}/skills/recover-from-false-positive/scripts/scrub_refusals.py\npython3 ${CLAUDE_PLUGIN_ROOT}/skills/recover-from-false-positive/scripts/scrub_refusals.py --apply\n```\n\n## What it bundles\n\n- A **skill** (`recover-from-false-positive`) with `scripts/scrub_refusals.py` — the chain-re-stitching log surgeon — and `references/prevention.md`, per-repo `CLAUDE.md` guard templates (supply-chain/sigstore, mining/PoW, BTCPay/Lightning, chaos/infra-ops).\n- Four **hooks** (`hooks/hooks.json`): `detect-false-positive.py` (StopFailure), `inject-recovery-context.sh` (UserPromptSubmit), `inject-subagent-framing.sh` and `inject-claudemd-into-subagents.sh` (SubagentStart).\n\n\u003e [!NOTE]\n\u003e Hooks run automatically once the plugin is enabled (Claude Code lists them in the install panel). They are read-only except for `~/.claude/.fp-state.json`, which the detect hook writes and the recovery hook consumes. The `edgar-morin`/`start_complex_reasoning` classification step expects that reasoning tool; without it, fall back to the skill's manual classification matrix.\n\n## Recovery and the auto-fallback limitation\n\n\u003e [!IMPORTANT]\n\u003e Claude Code has **no in-place auto-fallback to another model** on this error.\n\u003e Its only refusal auto-fallback is hardwired Fable 5 → Opus; `fallbackModel`\n\u003e covers availability errors (overload/unavailable) only — not policy refusals;\n\u003e and no hook can switch the active model. A trip ends the turn; the switch is\n\u003e a manual user action.\n\nWhen a turn is blocked, the un-stick path is:\n\n1. This plugin's detect hook repairs the poisoned log so `--resume` stays safe.\n2. Run **`/model claude-sonnet-4-6`** and re-send — a same-generation, lower-risk model often clears it.\n3. Or start a **new session** — context saturation is the usual real cause.\n\nFor fully automatic recovery (no manual step), two out-of-band options work — opt in yourself; this plugin does not ship them by default:\n\n- **Local proxy** at `ANTHROPIC_BASE_URL` that retries a refused request on the next model in a fallback chain (e.g. Opus 4.6 → Sonnet 4.6), transparent to the CLI and before the transcript is poisoned. Best for interactive use.\n- **Headless loop** for autonomous runs: wrap `claude -p … --output-format json`, detect `result.is_error` / the Usage-Policy string, and relaunch with `--model claude-sonnet-4-6` (loop-guarded to avoid runaway relaunches).\n\n## Docs\n\nFull workflow, trigger domains, and troubleshooting: [recover-from-false-positive docs](https://88plug.github.io/recover-from-false-positive/).\n\n## License\n\n[FSL-1.1-ALv2](LICENSE) — Functional Source License, converts to Apache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F88plug%2Frecover-from-false-positive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F88plug%2Frecover-from-false-positive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F88plug%2Frecover-from-false-positive/lists"}