settings

type AgentPromptRejection struct {
	Field  string
	Value  string
	Reason string
}

type BackendConfig struct {
	Type   string          `json:"type"`
	Config json.RawMessage `json:"config,omitempty"`
}

type CheckpointRemoteConfig struct {
	Provider string // e.g., "github"
	Repo     string // e.g., "org/checkpoints-repo"
}

type CheckpointsConfig struct {
	Primary BackendConfig   `json:"primary"`
	Mirrors []BackendConfig `json:"mirrors,omitempty"`
}

type ClonePreferences struct {
	ReviewProfiles       map[string]ReviewProfileConfig `json:"review_profiles,omitempty"`
	ReviewDefaultProfile string                         `json:"review_default_profile,omitempty"`

	// Deprecated: legacy pre-profile review settings. Kept so old preference
	// files parse. New review setup writes ReviewProfiles instead, while
	// `entire review` may read Review as a fallback when profiles are absent.
	Review         map[string]ReviewConfig `json:"review,omitempty"`
	ReviewFixAgent string                  `json:"review_fix_agent,omitempty"`

	// ReviewMigrationDismissed records that the user declined the one-shot
	// migration of review keys from project settings to clone-local prefs.
	// Once true, `entire review` stops prompting on every invocation; the
	// user can re-enable by editing this file or deleting the key.
	ReviewMigrationDismissed bool `json:"review_migration_dismissed,omitempty"`

	// CheckpointRemoteClaimDeclined records the `provider:repo` the user
	// declined when `entire enable` offered to claim a refused
	// checkpoint_remote, so the confirm prompt is asked once per store
	// instead of on every run. Only the prompt is one-shot: the line saying
	// the store is being ignored still prints every time, because that is
	// the condition the user has to be able to discover.
	//
	// The declined value rather than a bool, because a repo that later
	// configures a DIFFERENT store is a new question. Clone preferences
	// rather than settings.local.json, so declining once covers every
	// worktree of the clone and so a committed file can never suppress the
	// prompt.
	CheckpointRemoteClaimDeclined string `json:"checkpoint_remote_claim_declined,omitempty"`

	// TrailsEnabled caches whether trails are enabled for this repository on the
	// API. Pointer shape distinguishes "unknown/not refreshed yet" (nil) from a
	// definitive false. This is clone-local and not committed so hook-time agent
	// context injection can avoid network/auth work on the prompt path.
	TrailsEnabled *bool `json:"trails_enabled,omitempty"`

	// Freshness and scope for TrailsEnabled.
	TrailsEnabledCheckedAt *time.Time `json:"trails_enabled_checked_at,omitempty"`
	TrailsEnabledRepoKey   string     `json:"trails_enabled_repo_key,omitempty"`
	TrailsEnabledAPIBase   string     `json:"trails_enabled_api_base,omitempty"`
	TrailsEnabledAuthKey   string     `json:"trails_enabled_auth_key,omitempty"`

	// Agent-help refresh failures use a separate, short-lived backoff. Keeping
	// this out of TrailsEnabled ensures a transient help-command failure cannot
	// suppress SessionStart's authoritative enablement probe or context injection.
	TrailsAgentHelpRefreshFailedAt *time.Time `json:"trails_agent_help_refresh_failed_at,omitempty"`
	TrailsAgentHelpFailureRepoKey  string     `json:"trails_agent_help_failure_repo_key,omitempty"`
	TrailsAgentHelpFailureAPIBase  string     `json:"trails_agent_help_failure_api_base,omitempty"`
	TrailsAgentHelpFailureAuthKey  string     `json:"trails_agent_help_failure_auth_key,omitempty"`
}

type EntireSettings struct {

	// Enabled indicates whether Entire is active. When false, CLI commands
	// show a disabled message and hooks exit silently. Defaults to true.
	Enabled bool `json:"enabled"`

	// Deprecated: no longer used, and deliberately not read anywhere — not even
	// merged from an override (see mergeScalarFields). Kept so the strict loader
	// (DisallowUnknownFields) still accepts a "local_dev" key in settings files
	// written before it was removed.
	//
	// It let a tracked settings file decide that hooks run repo content; see
	// agent.LegacyLocalDevHookScript for the full rationale. Do not reintroduce a
	// setting that influences hook command generation.
	LocalDev bool `json:"local_dev,omitempty"`

	// LogLevel sets the logging verbosity (debug, info, warn, error).
	// Can be overridden by ENTIRE_LOG_LEVEL environment variable.
	// Defaults to "info".
	LogLevel string `json:"log_level,omitempty"`

	// StrategyOptions contains strategy-specific configuration
	StrategyOptions map[string]any `json:"strategy_options,omitempty"`

	// AbsoluteGitHookPath embeds the full binary path in git hooks instead of
	// bare "entire". This is needed for GUI git clients (Xcode, Tower, etc.)
	// that don't source shell profiles and can't find "entire" on PATH.
	AbsoluteGitHookPath bool `json:"absolute_git_hook_path,omitempty"`

	// Telemetry controls anonymous usage analytics.
	// nil = not asked yet (show prompt), true = opted in, false = opted out
	Telemetry *bool `json:"telemetry,omitempty"`

	// Redaction configures PII redaction behavior for transcripts and metadata.
	Redaction *RedactionSettings `json:"redaction,omitempty"`

	// ReviewProfiles maps profile names (e.g. "general", "security") to
	// named review setups. `entire review` runs one profile: its canonical task
	// is fanned out to the configured agents, then an optional master agent
	// consolidates the worker reports.
	ReviewProfiles map[string]ReviewProfileConfig `json:"review_profiles,omitempty"`

	// ReviewDefaultProfile is the profile used by `entire review` when no
	// profile is supplied. If empty, `general` is used when present, otherwise
	// the single configured profile is used.
	ReviewDefaultProfile string `json:"review_default_profile,omitempty"`

	// Deprecated: legacy pre-profile review settings. Kept so old config files
	// still parse. `entire review` reads this only as a compatibility fallback
	// when no review_profiles are configured, exposing it as the general profile.
	Review map[string]ReviewConfig `json:"review,omitempty"`

	// ReviewFixAgent is a legacy saved fix-agent preference. The `entire review
	// --fix` flow has been removed; this field is retained only so older
	// settings/preferences files still parse. It is no longer read by
	// `entire review`.
	ReviewFixAgent string `json:"review_fix_agent,omitempty"`

	// Deprecated: `entire investigate` moved to the entire-investigate plugin,
	// which owns its configuration in .entire/investigate.local.json. This
	// field is no longer read by anything.
	//
	// It is kept, and kept as a raw message, so the strict loader
	// (DisallowUnknownFields) still accepts an "investigate" key left behind in
	// an existing settings file. Dropping it outright would make settings
	// unloadable — and so the whole CLI unusable — in every repository that
	// still has one. Same reasoning as LocalDev above. Do not reintroduce a
	// typed struct here: the plugin parses its own file.
	//
	// Any well-formed JSON value is accepted and none of it is interpreted.
	// That is the whole contract — the shape of an old investigate block is
	// not this CLI's business any more, and validating it would re-couple the
	// two. Well-formed is not a promise this field makes, it is one the
	// decoder has already kept: a json.RawMessage is only ever populated by a
	// decoder that scanned the value to find its end, so malformed content
	// fails the surrounding settings parse long before it reaches here.
	Investigate json.RawMessage `json:"investigate,omitempty"`

	// CommitLinking controls how commits are linked to agent sessions.
	// "always" = auto-link without prompting, "prompt" = ask on each commit.
	// Defaults to "prompt" (preserves existing user behavior).
	CommitLinking string `json:"commit_linking,omitempty"`

	// ExternalAgents enables discovery and registration of external agent
	// plugins (entire-agent-* binaries on $PATH). Defaults to false.
	//
	// Discovery executes what it finds, so Load() honors a true value only
	// when it is developer-owned — set in an untracked
	// .entire/settings.local.json — and resets it to false otherwise. See
	// enforceExternalAgentsTrust. Readers that obtain settings by any route
	// other than Load() (LoadFromFile, LoadFromBytes) get the ungated value
	// and must not scan $PATH on it.
	ExternalAgents bool `json:"external_agents,omitempty"`

	// AllowSymlinkedAgentDirs lists worktree-relative agent config directories
	// (".claude", ".codex/…") whose symlinks Entire may follow instead of
	// refusing. Defaults to empty, which is the strict behaviour.
	//
	// A list rather than a boolean, on purpose: a flag would disable the whole
	// class, where naming a path is the user saying which arrangement is theirs.
	// Entries are checked against the directories actually derivable from the
	// agents' hook-config paths, so `.entire` and `.git/hooks` cannot be
	// spelled here at all.
	//
	// Following a link means writing where it points, so Load() honors this only
	// from an untracked .entire/settings.local.json, the same gate as
	// ExternalAgents. See enforceSymlinkedAgentDirsTrust and
	// agent.SetVouchedSymlinkedDirs.
	AllowSymlinkedAgentDirs []string `json:"allow_symlinked_agent_dirs,omitempty"`

	// SummaryGeneration stores provider preferences for explain --generate.
	// This is separate from strategy_options.summarize, which controls
	// checkpoint auto-summarize behavior.
	SummaryGeneration *SummaryGenerationSettings `json:"summary_generation,omitempty"`

	// Vercel indicates that the repository uses Vercel and the metadata branch
	// should include a vercel.json that disables deployments for Entire branches.
	Vercel bool `json:"vercel,omitempty"`

	// SummaryTimeoutSeconds is an optional hard deadline (in seconds) for
	// `entire explain --generate` summary generation. Zero or negative means
	// "unset" -- falls back to the per-run --summary-timeout-seconds flag
	// (if set) or the package default (5 minutes). Raise for very large
	// transcripts; lower (e.g. 30) for fast-fail in CI.
	SummaryTimeoutSeconds int `json:"summary_timeout_seconds,omitempty"`

	// SignCheckpointCommits controls whether checkpoint commits are signed.
	// nil/true = sign (default), false = skip signing.
	SignCheckpointCommits *bool `json:"sign_checkpoint_commits,omitempty"`

	// Checkpoints selects checkpoint storage backends (a primary plus optional
	// write-only mirrors). checkpoint.Open consumes it via the lenient
	// LoadCheckpointsConfig loader; the field also lives here so the strict
	// settings loader (DisallowUnknownFields) accepts a "checkpoints" key.
	Checkpoints *CheckpointsConfig `json:"checkpoints,omitempty"`

	// Deprecated: no longer used. Exists to tolerate old settings files
	// that still contain "strategy": "auto-commit" or similar.
	Strategy string `json:"strategy,omitempty"`
	// contains filtered or unexported fields
}

type OPFSettings struct {
	Enabled    bool            `json:"enabled,omitempty"`
	Categories map[string]bool `json:"categories,omitempty"`

	// Command is executed, so Load() honors it only when it is
	// developer-owned — set in an untracked .entire/settings.local.json — and
	// resets it to "" otherwise. See enforceOPFCommandTrust. Readers that
	// obtain settings by any route other than Load() (LoadFromFile,
	// LoadFromBytes) get the ungated value and must not pass it to exec.
	Command        string `json:"command,omitempty"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`

	// PromptDefault controls whether the pre-push hook asks the user
	// before running OPF. "" (default) and "ask" both surface the
	// interactive prompt; "never" skips OPF and pushes regex-only content;
	// "always" runs without asking. ENTIRE_OPF=yes|no on the push
	// invocation overrides this setting per-push.
	PromptDefault string `json:"prompt_default,omitempty"`
	// contains filtered or unexported fields
}

type PIISettings struct {
	Enabled        bool              `json:"enabled"`
	Email          *bool             `json:"email,omitempty"`
	Phone          *bool             `json:"phone,omitempty"`
	Address        *bool             `json:"address,omitempty"`
	CustomPatterns map[string]string `json:"custom_patterns,omitempty"`
}

type RedactionSettings struct {
	PII *PIISettings `json:"pii,omitempty"`

	// CustomRedactions is a label → RE2 regex map for user-defined patterns
	// to scrub from transcripts. Use it for internal credential shapes the
	// bundled detectors don't know about, project codenames, or any other
	// string pattern you don't want stored. Each match is replaced with the
	// bare "REDACTED" token used by the built-in secret layers, not the
	// "[REDACTED_<LABEL>]" token used by PII. Failed regex compilations are
	// logged via slog.Warn and the rule is skipped.
	CustomRedactions map[string]string `json:"custom_redactions,omitempty"`

	// OpenAIPrivacyFilter is the optional 8th redaction layer (opt-in).
	// See docs/security-and-privacy.md.
	OpenAIPrivacyFilter *OPFSettings `json:"openai_privacy_filter,omitempty"`

	// ExternalizeImages opts into lifting inline base64 images out of transcripts
	// into the checkpoint's assets/ store (off by default). Restore re-injects
	// them regardless of this flag.
	ExternalizeImages bool `json:"externalize_images,omitempty"`

	// Betterleaks toggles the betterleaks scanner engine (layer 2 of the
	// redaction stack). Omitted, or present with `enabled` omitted, means
	// enabled. Honored from the committed settings file only; ignored in
	// settings.local.json.
	Betterleaks *ScannerSettings `json:"betterleaks,omitempty"`

	// Goredact toggles the goredact scanner engine. Omitted, or present
	// with `enabled` omitted, means disabled. Same committed-file-only rule.
	Goredact *ScannerSettings `json:"goredact,omitempty"`
}

type ReviewConfig struct {
	// Agent is the underlying agent registry key for this worker. Empty means
	// the profile map key is the agent name. Set this when the map key is an
	// alias such as "claude-sonnet" or "claude-opus".
	Agent string `json:"agent,omitempty"`

	// Model is an optional model hint passed to the agent CLI for this worker.
	// Empty means use the agent's own default.
	Model string `json:"model,omitempty"`

	// Skills is the list of slash-prefixed skill invocations configured
	// for this agent. May be empty for prompt/model-driven workers (e.g. Pi),
	// in which case the profile task plus Prompt drive the review.
	Skills []string `json:"skills,omitempty"`

	// Prompt, when non-empty, carries saved agent-specific instructions. It is
	// appended after the profile task (and after any Skills); it is not a
	// verbatim replacement for the whole review prompt.
	//
	// The instructions reach agents spawned with approval checks disabled, so
	// Load() honors this field only from a developer-owned layer (clone-local
	// preferences, or an untracked .entire/settings.local.json) and resets it
	// to "" otherwise. See enforceAgentPromptTrust. Readers that obtain
	// settings by any route other than Load() (LoadFromFile, LoadFromBytes)
	// get the ungated value and must not hand it to an agent.
	Prompt string `json:"prompt,omitempty"`
}

type ReviewProfileConfig struct {
	// Task is the canonical instruction every reviewer agent receives, so it
	// gets the same provenance gate as ReviewConfig.Prompt: Load() honors it
	// only from a developer-owned layer and resets it to "" otherwise, at
	// which point review falls back to its built-in task text for
	// conventional profile names. See enforceAgentPromptTrust.
	Task   string                  `json:"task,omitempty"`
	Agents map[string]ReviewConfig `json:"agents,omitempty"`
	// Judge is the single agent (plus optional model) that consolidates the
	// reviewers' reports into the final verdict. It is optional: a
	// one-reviewer profile needs no judge (the lone report is the result),
	// and a multi-reviewer profile with no judge set falls back to an
	// auto-selected reviewer that can write a verdict.
	Judge *ReviewConfig `json:"judge,omitempty"`
	// Output selects where the final review verdict is delivered: "local"
	// (printed and saved to the local review manifest — the default) or
	// "trail" (additionally posted to the branch's trail as a finding via
	// the data API). Empty means local.
	Output string `json:"output,omitempty"`
}

type ScannerSettings struct {
	Enabled *bool `json:"enabled,omitempty"`
}

type SummaryGenerationSettings struct {
	// Provider is the selected summary provider agent name
	// (for example "claude-code", "codex", or "pi").
	Provider string `json:"provider,omitempty"`

	// Model is an optional model hint passed to the selected provider.
	Model string `json:"model,omitempty"`
}