/**
 * claude-settings-scope — Non-destructive scoping of Claude Code settings.
 *
 * Why this exists
 *
 *   The Claude Agent SDK loads `.claude/settings.json` from the working
 *   directory whenever `settingSources: ['project']` is set (we need that
 *   for `.claude/skills/` to be discovered). Anything that file declares
 *   under `env` is then injected into the spawned `claude-code` subprocess,
 *   overriding whatever env we explicitly passed to the SDK.
 *
 *   For users who keep a `.claude/settings.json` checked into their repo
 *   with `ANTHROPIC_BASE_URL` (LiteLLM, corporate proxy, custom gateway,
 *   Claude Pro/Max OAuth, etc.) — i.e. the *typical* Claude Code user on
 *   any team larger than one — that overrides the wizard's Amplitude LLM
 *   gateway URL and the wizard can no longer authenticate. The previous
 *   recovery flow (`SettingsOverrideScreen`) "fixed" this by moving the
 *   user's checked-in `.claude/settings.json` to `.wizard-backup` and
 *   running without it. That was destructive (any non-graceful exit lost
 *   the file) AND hostile (it asked permission to disturb a config the
 *   user had deliberately set up for their tooling).
 *
 * What this module does instead
 *
 *   The SDK's settings precedence is: `local` > `project` > `user`. We
 *   write our wizard-managed env override into `.claude/settings.local.json`
 *   — the *machine-local, gitignored* settings layer — and add `'local'`
 *   to `settingSources`. Local wins, the wizard reaches its gateway, and
 *   the user's checked-in `.claude/settings.json` is untouched on disk
 *   for the entire run.
 *
 *   We also preserve any pre-existing `.claude/settings.local.json` the
 *   user might already have (uncommon for projects, but possible), by
 *   loading it, deep-merging our `env` keys into its existing `env`, and
 *   restoring the original content on exit. If no file existed, we delete
 *   ours on exit. Both paths register as a wizard cleanup so they fire on
 *   any termination (success, cancel, crash).
 *
 *   Result: zero user prompts, zero data-loss risk, and the wizard works
 *   for every Claude Code user — including the ones who route through a
 *   custom gateway.
 */
/** Tracks what we wrote and how to undo it. */
export interface ScopedSettingsHandle {
    /** Absolute path to `.claude/settings.local.json` we wrote to. */
    filePath: string;
    /** Restore the file (or delete if it didn't exist) to its pre-wizard state. */
    restore: () => void;
}
/**
 * Write `.claude/settings.local.json` with the wizard's env override merged
 * into any pre-existing content, and return a `restore()` callback that
 * undoes the write.
 *
 *   - If the file did NOT exist before, restore() deletes it (and the
 *     `.claude/` dir if we created it and it's now empty).
 *   - If the file DID exist, restore() rewrites the original raw bytes.
 *     We use raw bytes (not re-serialized JSON) so we preserve user
 *     formatting / comments / whitespace exactly.
 *
 * Returns null when there's nothing to scope — in which case the caller
 * should NOT add `'local'` to `settingSources` (no point loading an empty
 * layer).
 *
 * No-throw contract: any IO failure here is logged and surfaces as a
 * null return so the wizard falls back to the previous behavior (the
 * subprocess will use whatever the project settings.json says, which
 * the gateway will reject — the user gets the standard auth-error path
 * rather than a worse mid-run failure).
 */
export declare function applyScopedSettings(workingDirectory: string): ScopedSettingsHandle | null;
