feat(policy): a typed behavior-policy layer

memcode behaved one way for everyone. Where a user might reasonably want a
say — which model explores, whether plans get reviewed and by whom, what a
session starts on — the answer was a hardcoded constant or a scattered
config field.

The delegated pin proved the shape but solved exactly one decision point,
and the obvious next step (explore_model, plan_review_model,
advisor_model, startup_model, theme_mode) is a bag of special cases. This
generalises it into one primitive: typed policy on named targets.

    natural-language instruction
        -> policy tool
        -> typed policy store
        -> scope resolution
        -> runtime decision point: policy.Resolve("agent.explore")

The rule the package exists to enforce, stated in its doc comment and
enforced by a guard test:

    Policy chooses behavior. The model may not synthesize policy.

"Always review plans with grok" is a settings write. "Review this plan
with kimi" is an override on that plan. A model deciding a plan looks hard
enough to warrant a stronger model is neither, and is forbidden — that is
the automatic routing this codebase deleted, and it does not come back
through a settings API.

v1 is UNCONDITIONAL. Every policy fires every time; nothing inspects or
classifies a task. The representation leaves room for conditions later,
but there is no condition field and no evaluator, because task
classification is exactly where hidden routing regrows.

Inheritance is DECLARED, not special-cased: a schema names a Parent, and
agent.explore -> agent.delegated -> the primary pin falls out of that. A
future agent.research or plan.scout declares a parent and needs no
resolution code of its own. The shipped "unset delegated means inherit
your own model" behavior is now schema (InheritsPrimaryModel) rather than
a second hand-written chain.

Invocation overrides belong to the OPERATION, not to a store. "Review
this plan with kimi" lives on the plan controller and is cleared at every
transition that begins or ends a plan — there is no global
consume-on-next-use state that could leak into an unrelated later
operation. A test asserts it does not survive its plan.

fallback_models is narrow on purpose: models to try when the chosen one
cannot be REACHED, under the same provider/transport semantics the
catalog's declared chain already uses. Nothing consults it because a
result looked weak. Capability gaps still refuse rather than substitute.

Seven targets, chosen so this is provably about behavior and not models:
agent.delegated, agent.explore (+ concurrency, replacing the hardcoded
maxReaders), plan.review, plan.advisor, startup.model, ui.theme,
session.effort. Modes are three-valued enums (off/offer/always) rather
than a bool plus a nil model, so "never review", "offer review" and
"always review with X" are each expressible.

Policy is kept completely separate from internal/prefs, in both
directions. That system infers standing preferences from repeated signals
and injects advisory prose; this one is explicit, immediate and
programmatic. A guard test asserts prefs has no import of policy: an
inferred pattern must never rewire which model runs.

Storage is two plain JSON files (.memcode/policy.json and the user-level
equivalent), deliberately outside config.json, so a target can be listed,
diffed and reset as a unit — "reset how explore agents behave" deletes one
object. `/policy` and the tool's `show` report every effective value and
which scope it came from, because per-field resolution across four layers
is only comprehensible if the source is visible.

The wire budget for tool defs is raised 31KB -> 32KB. The policy tool's
description was trimmed twice first; what remains is the guardrail
sentence, which is the last thing that should be cut for bytes.

Author: timothyerwin

cmd/explore.go

@@ -6,6 +6,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/memcode-ai/memcode/internal/explore"
+	"github.com/memcode-ai/memcode/internal/policy"
 	"github.com/memcode-ai/memcode/internal/provider"
 )
 
@@ -33,7 +34,12 @@ Requires MEMCODE_API_TOKEN (from the environment or a gitignored .env at the rep
 		defer st.Close()
 		model := provider.EffectiveModel(cfg.Models.Coder)
 
-		return explore.Run(ctx, st, runner, cfg.Root, model, question, userOut())
+		// Explore's model and its concurrency are both agent.explore policy.
+		pol := sessionPolicy(cfg.Root, model).Resolve(policy.AgentExplore)
+		if m := pol.Model("model"); m != "" {
+			model = m
+		}
+		return explore.Run(ctx, st, runner, cfg.Root, model, question, pol.Int("concurrency"), userOut())
 	},
 }
 

cmd/interactive.go

@@ -10,6 +10,7 @@ import (
 	"github.com/memcode-ai/memcode/internal/agent/runtime"
 	"github.com/memcode-ai/memcode/internal/config"
 	"github.com/memcode-ai/memcode/internal/llm"
+	"github.com/memcode-ai/memcode/internal/policy"
 	"github.com/memcode-ai/memcode/internal/provider"
 	"github.com/memcode-ai/memcode/internal/update"
 	"github.com/memcode-ai/memcode/internal/vxui"
@@ -79,12 +80,7 @@ func runInteractive(ctx context.Context, mode permissions.Mode, modeExplicit boo
 		// place that chain lives.
 		pin, win := config.ResolvePin(cfg, "")
 		sess.SetPin(pin, win)
-		// Delegated work (sub-agents, scouts, plan research) runs on the
-		// delegated pin. Unset means inherit the primary, so by default every
-		// worker stays on the model the user chose.
-		if dp, dw := config.ResolveDelegatedPin(cfg, "", pin, win); dp != pin {
-			sess.SetDelegatedPin(dp, dw)
-		}
+		sess.SetPolicy(sessionPolicy(cfg.Root, pin))
 	}
 	sess.SetServingDefault(cfg.ServingDefault) // cached cheap-lane model → banner/footer show it at once (refreshed by the /models fetch)
 	if chrome {
@@ -124,3 +120,15 @@ func runInteractive(ctx context.Context, mode permissions.Mode, modeExplicit boo
 	}
 	return runErr
 }
+
+// sessionPolicy loads the user's behavior policy for this session: the two
+// persisted layers plus the primary pin a model chain ends at. One call at the
+// cmd boundary; every decision point then resolves its own target.
+func sessionPolicy(root, primary string) *policy.Resolver {
+	return &policy.Resolver{
+		Session:   policy.Set{},
+		Workspace: policy.Load(policy.WorkspacePath(root)),
+		User:      policy.Load(policy.UserPath()),
+		Primary:   primary,
+	}
+}

cmd/plan.go

@@ -33,9 +33,7 @@ Requires MEMCODE_API_TOKEN (from the environment or a gitignored .env at the rep
 		pin, win := config.ResolvePin(cfg, "")
 		sess := runtime.New(st, runner, cfg.Root, pin, permissions.ModeAsk, userOut())
 		sess.SetPin(pin, win)
-		if dp, dw := config.ResolveDelegatedPin(cfg, "", pin, win); dp != pin {
-			sess.SetDelegatedPin(dp, dw)
-		}
+		sess.SetPolicy(sessionPolicy(cfg.Root, pin))
 
 		_, err = sess.RunPlan(ctx, strings.Join(args, " "))
 		return err

cmd/run.go

@@ -146,9 +146,7 @@ for local gateway development. Never store keys in .memcode.`,
 			modelFlag, _ := cmd.Flags().GetString("model")
 			pin, win := config.ResolvePin(cfg, modelFlag)
 			sess.SetPin(pin, win)
-			if dp, dw := config.ResolveDelegatedPin(cfg, "", pin, win); dp != pin {
-				sess.SetDelegatedPin(dp, dw) // sub-agents/scouts; unset = inherit
-			}
+			sess.SetPolicy(sessionPolicy(cfg.Root, pin))
 			// The header must name the model that will actually serve. It used
 			// to print a config/provider default, which under Automatic was a
 			// guess and is now simply wrong.

internal/agent/plan/plan.go

@@ -103,6 +103,11 @@ type Controller struct {
 	reflectRounds int // extra research rounds the reflection gate triggered
 
 	savedModel string // model to restore when leaving plan mode
+	// policyOverride holds per-OPERATION policy for the plan in flight, e.g.
+	// "review this plan with kimi". It belongs to this plan and is dropped when
+	// the plan ends — there is deliberately no stored "consume on next use"
+	// state that could leak into an unrelated later operation.
+	policyOverride map[string]map[string]any
 
 	// lastPlan is the pinned apply contract: the most recently PRESENTED
 	// plan-shaped synthesis. Preferred over any "last rendered text" at
@@ -145,6 +150,7 @@ func WithTask(task string) Opt { return func(c *Controller) { c.task = task } }
 func (c *Controller) Enter(currentModel string, opts ...Opt) Effects {
 	c.mu.Lock()
 	defer c.mu.Unlock()
+	c.policyOverride = nil // per-operation policy never outlives its operation
 	if c.phase != Idle {
 		return Effects{}
 	}
@@ -166,6 +172,38 @@ func (c *Controller) Enter(currentModel string, opts ...Opt) Effects {
 	return eff
 }
 
+// SetPolicyOverride attaches policy to the plan currently in flight. Scoped to
+// this operation only; Enter and the terminal transitions clear it.
+func (c *Controller) SetPolicyOverride(target string, fields map[string]any) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.policyOverride == nil {
+		c.policyOverride = map[string]map[string]any{}
+	}
+	dst := c.policyOverride[target]
+	if dst == nil {
+		dst = map[string]any{}
+		c.policyOverride[target] = dst
+	}
+	for k, v := range fields {
+		dst[k] = v
+	}
+}
+
+// PolicyOverride reports the per-operation policy for a target, nil when none.
+func (c *Controller) PolicyOverride(target string) map[string]any {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	out := map[string]any{}
+	for k, v := range c.policyOverride[target] {
+		out[k] = v
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
 // BeginTurn is the per-turn reset: a presented plan goes back to Researching at
 // the top of the next plan-mode turn, so an interrupted turn (Ctrl-C on a
 // clarifying question) never leaves a stale "Plan ready" selector armed with
@@ -234,6 +272,7 @@ func (c *Controller) NotePlanTurn(hasOutput bool) Effects {
 func (c *Controller) Approve(lastTextFallback string) (Effects, ApproveOutcome) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
+	c.policyOverride = nil // per-operation policy never outlives its operation
 	if !c.phase.Planning() {
 		return Effects{}, ApproveOutcome{}
 	}
@@ -262,6 +301,7 @@ func (c *Controller) Approve(lastTextFallback string) (Effects, ApproveOutcome)
 func (c *Controller) Cancel() Effects {
 	c.mu.Lock()
 	defer c.mu.Unlock()
+	c.policyOverride = nil // per-operation policy never outlives its operation
 	if !c.phase.Planning() {
 		return Effects{}
 	}

internal/agent/runtime/agent.go

@@ -5,6 +5,7 @@ import (
 	"io"
 
 	"github.com/memcode-ai/memcode/internal/llm"
+	"github.com/memcode-ai/memcode/internal/policy"
 	"github.com/memcode-ai/memcode/internal/wire"
 )
 
@@ -43,20 +44,30 @@ type AgentResult struct {
 // Task primitive: the caller (the LLM via a tool, or plan mode) blocks until the sub-agent
 // finishes, then acts on the result.
 func (s *Session) spawnAgent(ctx context.Context, spec AgentSpec) (AgentResult, error) {
-	// Every delegated worker — agent-tool tasks, explore scouts, plan-mode
-	// research — runs on the DELEGATED pin. Unset means inherit the primary, so
-	// the default is "the model you chose runs everything" and a split only
-	// happens because someone asked for one.
+	// Which model a delegated worker runs on is POLICY, resolved at this
+	// decision point. Read-only explorers resolve agent.explore, which declares
+	// agent.delegated as its parent, which ends at the session's own model — so
+	// the default is still "everything runs on the model you chose", and a
+	// split exists only because someone asked for one.
 	//
-	// This is a pin, not a decision: nothing here inspects the task to pick a
-	// model, and the agent tool has no model parameter to override it with.
-	model, runner := s.model, s.runner.Fork()
-	if s.delegatedPin != "" {
-		model, runner = s.delegatedPin, s.runner.ForkWithModel(s.delegatedPin)
+	// Nothing here inspects the task. The target is chosen by the worker's
+	// PURPOSE, which the caller already fixed, and the agent tool has no model
+	// parameter to override it with.
+	target := policy.AgentDelegated
+	if spec.Purpose == llm.Explore {
+		target = policy.AgentExplore
+	}
+	model := s.policy.Resolve(target).Model("model")
+	runner := s.runner.Fork()
+	if model != "" && model != s.pin {
+		runner = s.runner.ForkWithModel(model)
+	}
+	if model == "" {
+		model = s.model
 	}
 
 	sub := New(s.store, runner, s.root, model, s.effectiveMode(), io.Discard)
-	sub.delegatedPin, sub.delegatedWindow = s.delegatedPin, s.delegatedWindow // a worker's own workers too
+	sub.policy, sub.pin = s.policy, s.pin // a worker's own workers resolve the same way
 	if spec.Purpose != "" {
 		sub.purpose = spec.Purpose
 	} else {

internal/agent/runtime/delegated_test.go

@@ -325,8 +325,8 @@ func (s *Session) dispatch(ctx context.Context, u wire.Block) toolResult {
 		return s.recallPlanTool(ctx, u.Input)
 	case tools.PreferenceSignal:
 		return s.preferenceSignalTool(ctx, u.Input)
-	case tools.ModelPreference:
-		return s.modelPreferenceTool(ctx, u.Input)
+	case tools.UserPolicy:
+		return s.policyTool(ctx, u.Input)
 	case tools.BrowserNavigate:
 		return s.browserNavigateTool(ctx, u.Input)
 	case tools.BrowserClick: