boucle / recipes

"I want to try safety-check without reading my real settings"

Use this before the real audit when you want to see the checker run on your machine without touching your real Claude Code settings. It creates a temporary HOME and a temporary project, runs the bounded summary command there, and removes the empty temporary directories afterward.

Network boundary: this downloads tools/safety-check/check.sh from GitHub raw content, then runs it locally against only the temporary HOME and temporary project created below. It does not upload your Claude Code settings, hook files, shell history, repository contents, or summary output.

Fix path: run the isolated baseline, confirm the setup is unprotected, then run the real project audit

Expected shape:

This does not install hooks and does not prove your real Claude Code setup is safe. It proves the checker can start, the support summary is bounded, and an empty temporary setup is reported as unverified instead of safe. The repository URL line is printed as support context inside the bounded block; it is not evidence that the checker uploaded output.

After the isolated test, run the real audit from the same project root where you start Claude Code:

Full copy-paste guide and cleanup notes: safety-check first test.

"I want to know if my Claude Code setup is safe"

Start with the audit before installing or changing hooks. Run it from the same project root where you launch Claude Code, so user-level and project-level settings are both visible. In a git checkout, move to the repo root first; outside git, stay in the project directory you use for Claude Code.

Fix path: audit, install the essentials, doctor, verify, then restart Claude Code

Trust the hook layer only after verification reports zero FAIL-OPEN results. The verifier sends representative Claude-style PreToolUse payloads to installed PreToolUse hooks; other hook events are inventoried and reported, but skipped for payload verification because they do not receive those tool payloads. It does not execute the dangerous shell or git commands named inside the payloads.

When asking for help, share only the bounded summary block, not raw settings files, hook source, paths, tokens, or private CLAUDE.md rules:

On native Windows, use PowerShell 7 for the native hooks:

After a clean verification, start a fresh Claude Code session from the same root. A running session may still have old hook settings loaded. For a longer walkthrough, use the safety-check quickstart.

"Safety-check failed. What should I fix first?"

Use this after safety-check --verify, safety-check --verify --strict, or native Windows install.ps1 verify reports warnings, skipped checks, missing hooks, invalid settings, or FAIL-OPEN. Treat the output as a repair list, not as a certificate.

Fix path: remove global hook-disabling flags, validate settings, repair hook files, then rerun verification from the same project root

Prioritize anything that can make all hooks disappear or fail open: IS_DEMO, CLAUDE_CODE_SIMPLE, invalid settings.json, no hooks found, no payload checks, missing or non-executable hook files, and any FAIL-OPEN payload result. Do not chase the letter grade until those are fixed.

On native Windows, use PowerShell 7 and the native verifier first. If Git Bash or WSL is available, check --verify --summary-only can also print the bounded summary block used for support.

A useful baseline is Verify: 0 FAIL-OPEN with payload checks actually run and no skipped PreToolUse checks for hooks that enforce your boundary. After repairs pass, start a fresh Claude Code session from the same project root.

Full repair table: safety summary triage. If you need public help, share only the bounded summary from --verify --summary-only plus OS, shell, Claude Code version, where hooks are installed, and what changed recently.

"I edited Claude settings or hook files by hand"

Use this after editing ~/.claude/settings.json, project .claude/settings.json, hook commands, or hook scripts. Also use it after changing the directory where Claude Code starts. One valid hook file is not enough. A malformed sibling entry, stale settings cache, or launch from the wrong root can leave the boundary unverified.

Fix path: snapshot settings, validate both settings files, run doctor, strictly verify payloads, then start a fresh Claude Code session

Strict verification should show that PreToolUse payload checks ran. It should also show no FAIL-OPEN result for hooks that enforce your boundary. Treat the current session as unprotected if the report says no hooks found, no payload checks ran, invalid JSON, missing files, or skipped PreToolUse checks. Skipped non-PreToolUse events remain inventory unless no PreToolUse payload checks ran. Fix the named issue first.

On native Windows, use PowerShell 7 and verify the native hook set:

After a clean check, start a fresh Claude Code session from the same root. Running sessions can keep old settings or permission state in memory even when the files on disk are correct. If the edit was only a hook test, keep the backup until the fresh session proves the boundary still works.

If verification fails, use the failed verification recipe and triage table before reinstalling repeatedly.

"I want to try the hooks without keeping them installed"

Use this when you are on a borrowed machine, a client repo, a CI runner, or any place where the hook boundary should be tested and then removed. The trial still edits user-level Claude Code settings while it is active, so snapshot first and verify both installation and cleanup.

Fix path: back up settings, install the smallest useful set, doctor, verify, optionally run one fresh Claude Code session, uninstall, then rerun the audit

If the trial is only a configuration check, do not start Claude Code between install and uninstall. If you want to test behavior in Claude Code itself, start a fresh session from the same root after strict verification, run one bounded task, then uninstall before leaving the machine or handing the repo back.

After uninstall, the summary should no longer claim a verified hook boundary. A result such as Verify: not run, no hooks found, or 0 payload checks is expected after cleanup. That means the trial hooks are gone; it does not mean the current setup is protected.

Run backup list first, inspect the available snapshots, and restore the named backup you intend to use. Use bare restore only when the most recent backup is the exact snapshot you want back.

On native Windows, use the same shape with PowerShell 7 and the native verifier:

For a no-install dry run before touching real settings, use the temporary first test. It uses a temporary HOME and does not prove your real setup is safe.

"I am on Windows and do not want Git Bash or WSL"

Use this path for native PowerShell hooks. It installs and verifies the recommended .ps1 hook baseline from PowerShell 7 (pwsh) without bash or jq. Use install.ps1 all when you want all seven standalone hooks. Run from the same project root where you start Claude Code so project-level settings are visible.

Fix path: use PowerShell 7, install the recommended native hooks, doctor, verify, then start a fresh Claude Code session

After a clean verification, start a fresh Claude Code session from that same root. A running session may still have old hook settings loaded.

Use native verification to prove the PowerShell hooks installed under Claude Code settings block representative payloads. Use Git Bash or WSL only when you need the broader bash-based safety-check report with the bounded copy/paste summary:

For a temporary Windows trial, snapshot settings first and verify cleanup after removal:

Native Windows verification is narrower than the full bash safety-check audit. It proves the native PowerShell hooks it checks; it does not prove every developer's global settings, WSL settings, Git Bash path, or checked-in bash hooks are protected.

"Claude ignores my CLAUDE.md rules"

CLAUDE.md instructions are text appended to the context window. The model reads them and usually follows them, but nothing prevents deviation. As context grows, rule-following degrades. This is documented behavior (#37599, #38065, #40425).

Fix: enforce-hooks

Tag rules in CLAUDE.md with @enforced, then install the dynamic enforce hook. It re-reads CLAUDE.md on every tool call and blocks covered violations at the tool-call level. Verify the hook after install, run the runtime smoke test, and use OS-level controls for anything outside tool calls.

Install boundary: this downloads tools/enforce/install.sh and tools/enforce/enforce-hooks.py from GitHub raw content, then runs them locally in the current project. It may create CLAUDE.md, install .claude/hooks/enforce-hooks.py, update project .claude/settings.json, and add armor rules for the generated hook files. It does not upload CLAUDE.md, settings, hook files, shell history, repository contents, or audit output.

For audit-only sessions, use the read-only audit recipe, which includes setup, strict verification, smoke testing, fresh-session guidance, and removal steps.

Also helps: fewer rules placed more prominently, shorter sessions, and accepting that CLAUDE.md is guidance while hooks are enforcement.

"I need Claude to inspect the repo, not change it"

Use this when Claude Code should review, test, and report without writing files, mutating data, restarting services, or committing. A prompt that says "do not edit" is guidance. The enforced rule below blocks covered tool calls before they execute.

This is read-only for the audited Claude Code session after the hook is installed. Setting up the boundary intentionally edits project files first: you add an @enforced rule to CLAUDE.md and register a project-level hook in .claude/settings.json. Use a disposable branch or worktree when the main checkout must stay untouched, and keep the timestamped settings backup until the audit is done.

Fix path: add an enforced read-only rule, install the dynamic hook, verify, smoke test, then start a fresh session

After verification, start a fresh Claude Code session from the same project root and use a narrow prompt such as: Audit this repository. Do not edit files, run migrations, restart services, or commit. Report findings only.

To leave read-only mode, remove or rename the Read-only mode @enforced section, then verify from the same project root. Plugin mode reads CLAUDE.md dynamically, so the read-only rule stops applying on the next tool call after the section is gone.

If you also want to remove the hook registration, restore the settings snapshot only when you want .claude/settings.json returned to its pre-audit state, or remove enforce-pretooluse.sh from Claude Code's hooks UI. Then run the checks again. A strict audit should fail if the read-only section still exists without an active hook, or if restored settings contain broken hook references.

If there was no pre-audit settings file, remove only the temporary enforce hook entry and generated plugin files. Keep .claude/settings.json if it contains other project settings.

This is not a sandbox. Hooks cover Claude Code tool calls, not every way a process can affect a system. For production data or secrets, combine this with OS permissions, backups, containers, or a disposable clone. Full copy-paste guide: read-only audit mode.

"Claude deleted/overwrote my files"

Users have lost 87GB of personal data, had 30+ files destroyed, and seen explicit "don't touch" instructions ignored. The permission system has known bypass patterns (#38119).

Fix: file-guard

Protects files matching patterns you define in .file-guard. In default write-protect mode it blocks Edit, Write, MultiEdit, NotebookEdit, and modifying Bash commands for matching paths. Put patterns under a [deny] section when Claude must not read, search, list, or reference those paths at all. Works on absolute and relative paths.

Also: bash-guard blocks rm -rf /, rm -rf ~, and recursive deletion of system paths, even inside compound commands and pipes.

"Claude ran a dangerous command"

Claude can run sudo, drop databases, delete Docker volumes, expose credentials via env/printenv, or modify cloud infrastructure. The built-in permission system sometimes approves these in bypass mode (#39981).

Fix: bash-guard

Blocks dangerous Bash commands before execution. Catches compound commands (cd /tmp && rm -rf /), pipes, subshells, and common evasion patterns. Covered by hundreds of bash tests, with additional PowerShell coverage when pwsh is available.

Blocked categories: recursive deletion, sudo, Docker/container commands, database drops, credential exposure, cloud infrastructure (aws/gcloud/az destructive operations), chmod 777, disk operations.

"Claude force-pushed / reset my branch / deleted commits"

Claude can run git push --force, git reset --hard, git checkout ., git clean -f, or push --delete. It can also bypass pre-commit hooks with --no-verify (#40117).

Fix: git-safe + branch-guard

git-safe blocks force pushes, hard resets, checkout ., clean -f, push --delete, and --no-verify. branch-guard prevents commits directly to main/master/production.

"Claude is about to commit or push code that may contain secrets"

A Claude Code session can bulk-stage files, commit plaintext credentials, and push before a product guardrail or PostToolUse logger can stop the side effect (#89273). Hook verification proves representative hooks answered their payloads; it does not prove the current staged content or remote destination is safe.

Fix path: inspect staged content, run an external secret scanner, verify the remote, then approve the exact commit or push

Also run the secret scanner your project already trusts, such as a pre-commit hook, CI scanner, gitleaks, trufflehog, or the host's built-in secret scanning. Keep that scanner outside Claude Code's hook layer so a broken Claude hook is not the only line of defense.

Approve only an exact action after those checks: commit message, branch, remote, and whether push is allowed. Avoid broad git add . and unattended commit/push tasks in auto-mode sessions that can touch credential files, generated config, logs, transcripts, or environment dumps.

If a secret may already have been committed or pushed, do not paste the value into chat or public issues. Stop, revoke or rotate the credential through the provider, preserve the commit SHA and affected path for private incident handling, and assume the value is exposed even if the branch is later force-pushed away.

Related known limitation: git commits can leak plaintext credentials before any built-in guard reacts.

"Nested Claude calls used API credits instead of my subscription"

Use this before letting Claude Code launch nested claude -p subprocesses from Bash, cron, launchd, CI, or an autonomous loop. A shell alias that unsets ANTHROPIC_API_KEY for manual commands does not protect noninteractive Bash subprocesses. If the parent Claude Code environment exports the key, assistant-launched subprocesses can inherit it and use API-key billing instead of subscription/OAuth auth.

Fix path: start Claude Code with billing-sensitive API keys unset, verify the warning is gone, then block or wrap nested claude -p calls before autonomous work

If the summary still reports ANTHROPIC_API_KEY is set, fix the shell, terminal profile, launchd environment, CI secret injection, or wrapper that starts Claude Code. Then start a fresh Claude Code process from that clean environment. Do not trust an already-running session to forget inherited environment variables.

If you intentionally use API-key auth for some workflows, keep it in a separate shell profile or a real wrapper executable that unsets billing-sensitive credentials before subscription/OAuth sessions can spawn nested Claude calls. An interactive alias is not enough because aliases do not expand in noninteractive Bash tool shells.

For unattended sessions, add an explicit policy around nested Claude invocations: either block claude -p with a PreToolUse Bash rule, or require a wrapper command whose source you can inspect and whose behavior is verified before the session starts. Record the intended auth path in your handoff when the next action is autonomous work, a commit, or a push.

Related known limitation: exported ANTHROPIC_API_KEY can override subscription auth in Bash-spawned Claude subprocesses.

"My hook blocks Write/Edit. Does it also block shell writes?"

Claude Code can route file changes through Bash, heredocs, sed, scripts, or PowerShell instead of the dedicated Write, Edit, MultiEdit, and NotebookEdit tools. A hook that only matches dedicated file tools will not see those shell operations. Use this canary before trusting protected-file policy in auto-mode, bypass mode, CI, or unattended sessions.

Fix path: protect the file pattern, install both file and shell guards, verify the installed hooks, then dry-run one structured write payload and one Bash write payload

The last two commands send synthetic Claude-style payloads to the hook. They do not create or modify .env. The structured Write case uses an absolute path because relative Write/Edit payloads can be ambiguous; the Bash case checks that a shell redirection targeting the same protected path is blocked too.

A passing canary proves only those payload shapes against the hook command loaded from your current filesystem. Before relying on it, start a fresh Claude Code session from the same project root and keep an external fallback for secrets, generated credentials, or client data.

Related known limitation: permission modes can steer Edit and Write work through shell commands.

"Claude re-reads the same files and wastes tokens"

Claude often reads the same file multiple times in a session, each time consuming tokens for content already in context.

Fix: read-once

Tracks file reads and blocks redundant re-reads within a session. Allows re-reads when the file has changed on disk. Typical savings: 20-40% fewer tokens per session.

Note: if you need to Edit a file, read-once allows the re-read. It only blocks reads where the file content hasn't changed.

"Claude bypasses a denied tool by using a different tool"

When Bash(rm) is denied, Claude may use Python os.remove() instead (#39459). When a pre-commit hook blocks a commit, Claude may use --no-verify (#40117). The tool is blocked but the goal is not.

Partial fix: bash-guard + enforce-hooks

bash-guard catches common equivalences (blocks rm in both shell and Python patterns). enforce-hooks can define broader rules that span multiple tools. But goal-level enforcement is a known limitation of the hook architecture: hooks gate tool calls, not intentions.

For critical paths, combine hooks with OS-level controls (file permissions, network policy, containerization). See the full searchable list of known gaps.

"I wrote a hook and want to test it before Claude Code runs it"

Use this when a custom or third-party hook needs a repeatable dry run. The harness feeds synthetic Claude-style PreToolUse payloads to the hook command and reports whether it allows, denies, errors, or crashes. It does not require a live Claude Code session.

Fix path: download the test harness, run one allow and one deny case, then keep the command in CI for hook changes

For non-Bash tools, set the tool name and payload fields explicitly:

When a hook has more than a few cases, commit a small JSONL fixture and run it in batch mode. Each line is one case with tool, input, expect, and label:

A passing dry run proves only the hook command's stdin behavior for those payloads. Before relying on the boundary, also verify the hook is registered in the settings file Claude Code will load, use a command-type hook for enforcement, start a fresh session, and run safety-check --verify --strict from the same project root.

For ready-made examples, see test-hook examples and the README test-hook section.

"I need to prove what Claude Code actually did"

Use this after an unattended session, a confusing change, or a disputed agent claim. session-log records every Claude Code tool call to daily JSONL files, then the repository's tools/session-log/report.sh helper summarizes calls, errors, files touched, commands run, and multi-day trends.

Fix path: install the PostToolUse logger, start a fresh session, then inspect the report before trusting claims

The raw logs live at ~/.claude/session-logs/YYYY-MM-DD.jsonl. They are local audit records, so review them before sharing. Paths, commands, and file names may reveal private project structure or secrets in command arguments.

When Claude says "I pushed", "I ran tests", or "I only read files", check the log for the actual tool call and, for Bash, its recorded exit code. A claimed action without a matching log entry should be treated as unverified.

For commit or push work, also inspect the staged diff and the exact remote target before approval. Hook verification can show that local guardrails responded to representative payloads; it does not prove the current staged content is safe to publish.

On native Windows, install and verify the PowerShell hook with PowerShell 7. The native hook writes the same JSONL format, but the report helper is a Bash script in the repository, so use Git Bash or WSL for the summary report if needed.

The audit trail begins after installation and a fresh Claude Code session. It cannot reconstruct earlier sessions, and it records tool calls rather than model reasoning. Full documentation: session-log.

"I need help without leaking private settings"

Do not paste raw Claude Code settings, hook commands, hook stderr, transcripts, screenshots, or private CLAUDE.md rules into a public issue. The support path is to run the verifier from the affected project root and share only the bounded summary block.

Fix path: rerun from the project root, print the public summary, then add short environment context

Command boundary: this downloads tools/safety-check/check.sh from GitHub raw content, then runs it locally on your current project and Claude Code settings. The checker does not upload settings.json, hook files, shell history, repository contents, session logs, or safety summary output.

Post the output from --- Safety Summary (copy/paste) --- through --- End Safety Summary ---, plus only these short fields:

For failures after a Claude Code update, say whether you captured the pre-update version and bounded summary from the update checklist. Do not paste both full command outputs; the key distinction is whether the new strict result is a regression from a known baseline or the first verified result for an already-untrusted setup.

For MCP-related failures, include only visible server names and connection state from claude mcp list, plus whether a fresh session can run one harmless read-only call against each critical server. Do not paste claude mcp get output for HTTP servers into public reports; headers, URLs, and command arguments can expose bearer tokens, private hosts, or local paths. A clean hook summary proves local hooks responded to representative payloads, not that a remote MCP server kept the same tool surface or instructions.

If the next action is commit, push, or public report, say whether the staged diff and destination have been reviewed separately. The safety summary is support evidence for the hook boundary, not approval to publish repository contents, logs, settings, or secrets.

If native PowerShell verification is the only available path, copy the final count line and any WARN or SKIP lines instead of the startup hook table:

If someone asks for raw files, build a temporary reproduction with throwaway settings first. The safe support evidence guide and safe support examples show what is safe to paste and what to redact.

"I want CI to fail when repo hooks stop blocking"

Use this when a repository commits Claude Code hook settings or hook scripts and you want pull requests to prove that boundary still works. CI can verify checked-in project hooks. It cannot prove every developer's global ~/.claude/settings.json is safe.

Network boundary: the workflow downloads tools/safety-check/check.sh from GitHub raw content, then runs it locally on the checked-out repository and a temporary CI home directory. The checker does not upload settings.json, hook files, shell history, repository contents, or safety summary output. Treat CI logs as the only publication surface, because hook commands can print paths or stderr.

Fix path: commit repo-local settings and hook scripts, require the checked-in settings file, isolate HOME, run strict safety-check from the repository root, and skip only the optional Claude Code version probe

The test -f .claude/settings.json line fails early when the repository policy file is absent. The temporary HOME prevents a self-hosted runner's global Claude Code settings from making the job pass when the checked-out repository has no working hook layer.

For a runnable sample, commit a minimal hook such as hooks/block-dangerous-bash.sh that reads the hook JSON from stdin and exits 2 for destructive commands:

The cleanup uses rmdir instead of recursive deletion. If a hook, shell startup file, or unexpected tool writes into the temporary home, the path is left in the CI log for inspection.

Do not treat install.sh recommended in CI as proof that repo-local policy is protected. That installs user-level hooks under the runner's temporary HOME. It is useful as an installer smoke test, but it does not prove the checked-out .claude/settings.json or repository hook files protect developers.

For native PowerShell hook scripts, use a runner where both bash and pwsh are available so safety-check --verify --strict can execute the checked-in .ps1 commands. Do not use install.ps1 verify as proof for repo-local hooks; it verifies Boucle hooks installed under the CI user's home directory.

Use an explicit command such as pwsh -NoProfile -File ./hooks/block-dangerous-bash.ps1 in checked-in settings, and commit the PowerShell hook script beside it:

Full workflow examples and expected failure modes: scripted safety-check checks.

"I need to leave a PR or incident handoff"

Use this when a teammate, reviewer, or incident owner needs to know exactly what hook boundary was checked. Keep the note short: root, command, result, residual warnings, and the trigger for the next recheck.

Fix path: run the bounded summary, paste the handoff record, and mark whether a fresh Claude Code session was started

Command boundary: this downloads tools/safety-check/check.sh from GitHub raw content, then runs it locally on your current project and Claude Code settings. The checker does not upload settings.json, hook files, shell history, repository contents, session logs, or safety summary output.

Treat this as a boundary statement, not a certificate. Verify: 0 FAIL-OPEN means representative PreToolUse payload checks did not find a configured PreToolUse hook that failed open; it does not prove every possible path or lifecycle hook event is blocked.

Full template and Windows notes: team handoff reports.

"I am about to let Claude Code work for a while"

Before a long, unattended, or high-trust session, verify the hooks from the exact project root Claude Code will use. This preflight catches missing hook files, stale settings, failed payload checks, direct commits to protected branches, and missing audit logs before the session starts.

Fix path: install the session guard set, verify strictly, snapshot state, then restart Claude Code

The guard set blocks dangerous shell and git commands, protects sensitive files, prevents direct commits to protected branches, prevents losing work when exiting Claude Code worktrees, and writes a JSONL tool-call audit trail. The final git status --short is a human checkpoint: start from a state you can explain, or commit/stash intentionally before turning the session loose.

On native Windows, use PowerShell 7 and the native verifier:

After a clean preflight, start a fresh Claude Code session from that same root. Existing sessions may still have old hook settings loaded. If the session will touch secrets, production data, cloud resources, or customer files, combine hooks with OS permissions, containers, network policy, and backups.

"Claude Code updated. Are my hooks still working?"

Claude Code, IDE integrations, terminal profiles, and settings files can all change the hook boundary. A clean install from last week does not prove the current session is protected.

Fix path: back up settings, upgrade, doctor, then strictly verify from the same project root

Run the update check before trusting Claude Code with destructive commands, repo writes, or autonomous work after a version change. The strict verifier sends representative hook payloads; it does not execute the dangerous shell or git commands named in those payloads.

Before changing anything, record claude --version and a --verify --summary-only result. After the update, compare those notes with the new strict verification so you can tell a new regression from an old unverified setup.

On native Windows, use PowerShell 7 and verify the native hooks:

Keep the backup until the fresh session proves the hook boundary still works. If restore is needed, run backup list first and restore the named snapshot you intend to use. After a clean verification, start a fresh Claude Code session from that same project root. For restore steps and failure triage, use the Claude Code update checklist.

On macOS, add a protected-folder canary if the fresh session was launched from Claude Desktop, an IDE, or another app wrapper and the project lives under Desktop, Documents, Downloads, iCloud Drive, Dropbox, Google Drive, OneDrive, or another CloudStorage path. In that same Claude Code session, ask it to open one byte from a known project file with Bash, then read the same file with the Read tool. Treat EPERM, an empty Read result, or a mismatch where stat works but opening the file fails as a stop signal. Launch Claude Code directly from Terminal, or move the checkout to a non-TCC-protected path, before consequential edits.

"I resumed a session after hooks or settings changed"

Use this when a Claude Code conversation was resumed, left open during a hook install, or kept running while settings.json, settings.local.json, MCP servers, plugins, or permission modes changed. Disk files can be correct while the active session still uses old hook paths, old permission state, or a different mode.

Fix path: verify from disk, start a fresh session from the verified root, then run one harmless canary in that fresh session

First prove the files on disk are healthy from the exact project root Claude Code should use:

If strict verification reports missing hooks, skipped boundary checks, no payload checks, or FAIL-OPEN, repair that before continuing. If disk verification is clean, do not treat a resumed or long-running session as automatically refreshed. Start a new Claude Code process from the same root and keep the old session read-only until the fresh one proves the current boundary.

In the fresh session, run a harmless canary that must pass through the same boundary you care about. For example, ask Claude Code to report the current working directory, then ask it to attempt a known-safe dry run or a blocked test command that your installed guard is expected to deny. The point is not to run destructive work; it is to prove the fresh session loaded the hook and permission state you just verified on disk.

On native Windows, use PowerShell 7 and the native verifier before opening the fresh session:

Treat these as recheck triggers: resumed conversation, compacted session, changed launch directory, edited .claude/settings.local.json, hook install or restore, plugin or MCP update, IDE extension update, or any unexpected permission prompt after a clean install.

Related limitations: bypassPermissions not restored on session resume and settings.local.json permission-state desync.

"An MCP server or plugin changed. Is it still the same tool?"

Use this after adding, updating, reconnecting, or approving an MCP server, Claude connector, marketplace plugin, or plugin channel. MCP tool names, schemas, descriptions, server URLs, and prompt metadata are part of the trust boundary. A hook verifier proves local hooks still execute; it does not prove a remote server kept the same tool surface.

Fix path: record the visible server list, rerun hook verification, start a fresh session, then test one harmless read-only tool per critical server

Before changing the server, connector, plugin, or channel, capture a bounded baseline. Do not paste claude mcp get output into public logs for HTTP servers that may store secrets in headers.

After the change, run the strict local hook recheck from the same project root and terminal profile. If hooks disappeared, payload checks did not run, or any boundary hook reports FAIL-OPEN, stop before using the changed MCP surface for credential reads, shell execution, repository writes, network actions, or external publication.

On native Windows, use PowerShell 7 for the same baseline and verifier:

Start a fresh Claude Code session from the same root after the check. In that fresh session, compare the visible MCP server list with the baseline and run one harmless read-only call for each critical server before trusting write-capable tools. Treat a new tool, missing tool, changed description, changed schema, unexpected URL, failed read-only probe, or connector crossing from read/draft behavior into send/delete/publish behavior as a renewed approval event.

Related limitations: runtime-gated MCP metadata poisoning, remote MCP connectors gaining write tools, and MCP hook ask/deny enforcement gaps.