sessionoverride

Documentation

Overview

Package sessionoverride loads and merges per-session-cwd configuration overrides from `.tars/settings.json` (team-shared) and `.tars/settings.local.json` (per-user, gitignore-recommended).

Only an explicit allow-list of fields is honoured — anything else is dropped with a diagnostic so a malicious or accidental local file cannot rebind credentials, register hooks, or otherwise widen the trust boundary.

Index

• Variables
• func AllPaths() []string
• func Load(cwd string) (shared, local *Override, diagnostics []Diagnostic, err error)
• func WriteLocalToolConfig(cwd string, config session.SessionToolConfig) error
• type Diagnostic
• type EffectiveConfig
  • func Merge(base session.SessionToolConfig, basePrompt string, shared, local *Override) (EffectiveConfig, map[string]Source)
• type LocalScaffoldResult
  • func ScaffoldLocal(cwd string, force bool) (LocalScaffoldResult, error)
• type MCPServerExtra
• type Override
• type Resolution
• type Service
  • func NewService(store *session.Store) *Service
  • func (s *Service) Invalidate(sessionID string)
  • func (s *Service) Resolve(sessionID string) (Resolution, bool, error)
• type Severity
• type Source

Variables

var AllowedToolConfigFields = map[string]struct{}{
	"tools_enabled":      {},
	"tools_custom":       {},
	"tools_disabled":     {},
	"tools_allow_groups": {},
	"tools_deny_groups":  {},
	"skills_enabled":     {},
	"skills_custom":      {},
	"commands_enabled":   {},
	"commands_custom":    {},
	"mcp_enabled":        {},
	"mcp_custom":         {},
}

AllowedToolConfigFields enumerates the JSON keys honoured inside the `tool_config` object. Mirrors session.SessionToolConfig. `skills_disabled` is intentionally absent for now — Phase 4 (skill registry) will add it once the consumer side knows what to do with the list.

var AllowedTopLevelFields = map[string]struct{}{
	"tool_config":         {},
	"prompt_override":     {},
	"mcp_servers_extra":   {},
	"model_tier_override": {},
}

AllowedTopLevelFields enumerates JSON keys honoured at the top level of a settings override file. Anything outside this set is dropped with a diagnostic.

var BlockedTopLevelFields = map[string]struct{}{
	"llm_providers":  {},
	"api_key":        {},
	"auth":           {},
	"auth_token":     {},
	"hooks":          {},
	"server_command": {},
}

BlockedTopLevelFields enumerates JSON keys that, if present, generate a SeverityError diagnostic instead of the more neutral SeverityWarn used for unknown keys. These are fields known to be sensitive (credentials, authority widening) and must never be silently ignored.

Functions

func AllPaths

func AllPaths() []string

AllPaths enumerates every leaf override path the merger tracks in its sources map. Phase 6's UI uses these to render badges per item.

func Load

func Load(cwd string) (shared, local *Override, diagnostics []Diagnostic, err error)

Load reads session-cwd override files (`<cwd>/.tars/settings.json` and `<cwd>/.tars/settings.local.json`) if they exist. A missing file is not an error — both return values are nil in that case. JSON parse failures abort the load with a descriptive error; schema violations (blocked or unknown fields) are returned as diagnostics with the offending field dropped from the parsed Override.

func WriteLocalToolConfig

func WriteLocalToolConfig(cwd string, config session.SessionToolConfig) error

WriteLocalToolConfig updates only the tool_config object in <cwd>/.tars/settings.local.json, preserving other local override fields.

Types

type Diagnostic

type Diagnostic struct {
	Path     string   `json:"path"`     // dotted JSON path; e.g. "llm_providers"
	Severity Severity `json:"severity"` // "warn" | "error"
	Message  string   `json:"message"`  // human-readable explanation
	File     string   `json:"file"`     // absolute path to the file that produced it
}

Diagnostic describes a single issue noticed while loading a settings override file. Diagnostics never fail the load — they are surfaced to the operator via API + logs so they can fix the file.

type EffectiveConfig

type EffectiveConfig struct {
	ToolConfig        session.SessionToolConfig `json:"tool_config"`
	PromptOverride    string                    `json:"prompt_override"`
	MCPServersExtra   []MCPServerExtra          `json:"mcp_servers_extra,omitempty"`
	ModelTierOverride string                    `json:"model_tier_override,omitempty"`
}

EffectiveConfig is the merger output: a flattened, fully-resolved view of what the chat turn / skill registry / etc. should use.

func Merge

func Merge(base session.SessionToolConfig, basePrompt string, shared, local *Override) (EffectiveConfig, map[string]Source)

Merge folds (base session config + base prompt) with optional shared and local overrides into a single EffectiveConfig and reports, for every trackable path in AllPaths(), which layer last touched it.

Semantics:

• String / scalar fields: replaced by the highest layer that set them.
• Slice fields inside tool_config (tools_enabled, tools_disabled, tools_allow_groups, tools_deny_groups, skills_enabled, commands_enabled, mcp_enabled): union of every layer's values, dedup'd, preserving first-seen order.
• tools_custom, skills_custom, commands_custom, and mcp_custom make that layer's corresponding allowlist replace earlier entries. If the custom flag is explicitly true and the allowlist is omitted, inherited entries are cleared.
• mcp_servers_extra: merged by Name, later layers replacing earlier entries with the same name; new names append.

type LocalScaffoldResult

type LocalScaffoldResult struct {
	CWD               string
	SettingsPath      string
	LocalSettingsPath string
	SkillsDir         string
	CommandsDir       string
	GitignorePath     string
	Created           []string
	Existing          []string
}

func ScaffoldLocal

func ScaffoldLocal(cwd string, force bool) (LocalScaffoldResult, error)

type MCPServerExtra

type MCPServerExtra struct {
	Name    string            `json:"name"`
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

MCPServerExtra is the narrowed schema permitted for an MCP server entry declared in a session-cwd override file. Credentials and arbitrary env passthroughs are intentionally absent; if a project needs those they belong in the user-global config, not in a checked-in override file.

type Override

type Override struct {
	ToolConfig        *session.SessionToolConfig `json:"tool_config,omitempty"`
	PromptOverride    *string                    `json:"prompt_override,omitempty"`
	MCPServersExtra   []MCPServerExtra           `json:"mcp_servers_extra,omitempty"`
	ModelTierOverride *string                    `json:"model_tier_override,omitempty"`

	// Presence records every override path the file explicitly touched.
	// Keys are dotted paths (e.g. "tool_config.tools_enabled"); the loader
	// populates this so the merger knows whether to use this layer's value
	// for that path. Not serialized.
	Presence map[string]bool `json:"-"`
}

Override captures the parsed contents of one settings file (`.tars/settings.json` or `.tars/settings.local.json`). All fields are pointers / nilable so the merger can distinguish "explicitly set to the zero value" from "not set at all".

type Resolution

type Resolution struct {
	SessionID   string            `json:"session_id"`
	Cwd         string            `json:"cwd"`
	Effective   EffectiveConfig   `json:"effective"`
	Sources     map[string]Source `json:"sources"`
	Diagnostics []Diagnostic      `json:"diagnostics,omitempty"`
}

Resolution is the cached output of one Service.Resolve call.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service resolves a session's EffectiveConfig from its base configuration (sessions.json) plus any `.tars/` overrides at the session's active cwd. Results are cached per-session keyed by (cwd, settings.json mtime, settings.local.json mtime); a Resolve call detects file mutations and reloads automatically. Cache entries are also dropped explicitly via Invalidate when the active cwd transitions.

The zero value is not usable; callers must construct via NewService.

func NewService

func NewService(store *session.Store) *Service

NewService constructs a Service backed by the supplied session store. store may be nil for tests that want to manually inject behavior — calls to Resolve will then surface the missing-store error.

func (*Service) Invalidate

func (s *Service) Invalidate(sessionID string)

Invalidate drops any cached resolution for sessionID. Safe to call for a session ID that was never resolved.

func (*Service) Resolve

func (s *Service) Resolve(sessionID string) (Resolution, bool, error)

Resolve returns the up-to-date Resolution for sessionID. Cached values are returned when the active cwd has not changed AND neither settings.json nor settings.local.json has been modified.

type Severity

type Severity string

Severity classifies a Diagnostic.

const (
	SeverityWarn  Severity = "warn"
	SeverityError Severity = "error"
)

type Source

type Source string

Source identifies which layer contributed the effective value of a given configuration field. The layers are ordered base < shared < local; later values win on conflict.

const (
	// SourceBase corresponds to the value persisted on the session itself
	// (sessions.json), or the system default when the session has not yet
	// configured anything.
	SourceBase Source = "base"

	// SourceShared corresponds to `<cwd>/.tars/settings.json` — intended to
	// be checked into the project repo and shared across the team.
	SourceShared Source = "shared"

	// SourceLocal corresponds to `<cwd>/.tars/settings.local.json` — intended
	// to be gitignored and contain personal preferences.
	SourceLocal Source = "local"
)