Skills: allow fork skills to override the model

[dgageot]

Summary

Allow fork skills (context: fork) to override the model used while running as a sub-agent, via a new model: field in SKILL.md frontmatter. Useful when a skill is best handled by a faster, cheaper, or more specialised model than the parent agent's default — e.g. a powerful reasoning model for refactors, or a fast model for routine bookkeeping.

---
name: bump-go-dependencies
description: Update Go module dependencies one by one
context: fork
model: openai/gpt-4o-mini
---

The model value accepts the same forms as the rest of the agent config: a named model from the config, an inline provider/model reference, or a comma-separated alloy. It is ignored for non-fork skills (which don't run as a sub-session).

Behaviour

• Override is applied for the duration of the sub-session and the agent's previous model is restored when the skill completes.
• If the model reference cannot be resolved (unknown name, missing credentials, runtime not configured for model switching, …) the skill falls back to the agent's currently-active model and a warning is logged.
• If the user switches the model via the TUI model picker while a fork skill is running, their choice is preserved — the deferred restore detects the concurrent change and is a no-op.

Implementation notes

The save/restore around the sub-session uses pointer-identity compare-and-swap on the agent's atomic.Pointer[[]provider.Provider]:

• Agent.SetModelOverride(...) now returns a ModelOverrideSnapshot of the value just stored.
• LocalRuntime.WithAgentModel(ctx, name, ref) (restore func(), err error) is the canonical entry point: it captures prev, applies the override, and returns a restore closure that CAS-swaps prev back only if the override has not been mutated since.
• The post-apply snapshot is captured atomically with the store (returned by SetModelOverride), so there is no race window where a concurrent SetModelOverride could be misattributed to the skill's scope.
• The returned restore func is always non-nil — on error it is a no-op closure — so callers can defer restore() unconditionally.

Files

• pkg/skills/skills.go — Skill.Model field + frontmatter parsing
• pkg/agent/agent.go — ModelOverrideSnapshot, SnapshotModelOverride, RestoreModelOverride; SetModelOverride returns the snapshot of the stored value
• pkg/runtime/model_switcher.go — WithAgentModel helper + setAgentModelInternal threading the snapshot through every branch
• pkg/runtime/skill_runner.go — apply/restore around the sub-session
• docs/features/skills/index.md — new model field documented + example

Tests

Race-detector unit tests cover:

• frontmatter parsing for both named-model and provider/model forms
• Agent.SetModelOverride returning a snapshot of the stored pointer (not load-after-store)
• Snapshot/RestoreModelOverride happy path, restore-to-pre-existing-override, concurrent-change-preserved, concurrent-clear-preserved
• WithAgentModel for: agent-not-found, nil model switcher, invalid ref, apply+restore, idempotent restore, concurrent change preserved

Validated with go build, go vet, golangci-lint (0 issues), and the full mise test suite under -race.

Commits

The branch is structured so every commit is independently reviewable:

1. feat(skills): allow fork skills to override the model — adds the field and the simplest possible apply/restore
2. refactor(runtime): reuse SetAgentModel for skill model overrides — drops a duplicated resolution helper
3. fix(skills): preserve concurrent model picks via CAS restore — introduces the snapshot/CAS-restore primitive
4. refactor(runtime): introduce WithAgentModel, drop dead ModelOverrides — single-call helper, removes dead API
5. fix(runtime): always-non-nil restore from WithAgentModel + add tests — caller-side ergonomics + coverage
6. fix(runtime): close race window in WithAgentModel snapshot capture — atomically captures the post-apply snapshot inside SetModelOverride

Assisted-By: docker-agent