Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@ reasoning behind a change are published separately as **Lunos Notes**.

### Added

- **Choose which model each subagent uses.** `agent.<type>.model` now accepts `"inherit"` and
`"small"` as well as `provider/model`. The new `subagent.model` sets a default for every
subagent, and `subagent.dynamic` lets the main agent pick a model per task, from a list you allow.
Subagent models are checked against the residency policy before they start. An inherited model
keeps the main agent's reasoning variant; before this, the variant was dropped whenever a model
was configured.
- **Skills can restrict the agent's tools** with `allowed-tools` in `SKILL.md`, in Claude Code's
format. The restriction applies from when the skill loads to the end of the turn, through the
permission system. Hook scripts now receive `LUNOS_AGENT` and `LUNOS_SKILL`. `research-mode`
Expand Down
1 change: 1 addition & 0 deletions docs/deployment/self-hosted.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,7 @@ With that in place:
- **Every outbound model call is recorded** to a local audit log with timestamp, provider, jurisdiction and destination host. Blocked attempts are recorded too. The log never contains request contents.
- **Providers whose region cannot be verified are denied,** including ones that _could_ be EU (Azure, AWS Bedrock, Google Vertex). Their region is a choice made in your cloud account, which the software cannot inspect — so permitting them automatically would let an unverified US-region resource pass a policy claiming to enforce EU residency. You may opt in explicitly once you have verified the region.
- **Providers with no recorded jurisdiction are always denied.**
- **Subagents are checked too.** A subagent's model is checked against the policy before the subagent starts. If you assign models to subagents, keep them on EU providers with per-type settings: for example `"agent": { "explore": { "model": "small" } }`, where `small_model` is also an EU provider. See "Choosing models for subagents" in the agents documentation.

Full reference, including the audit log format and how to opt into configurable providers: [Data residency controls](../data-residency.md).

Expand Down
4 changes: 4 additions & 0 deletions packages/core/src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ import { ConfigPlugin } from "./config/plugin"
import { ConfigProvider } from "./config/provider"
import { ConfigReference } from "./config/reference"
import { ConfigResidency } from "./config/residency"
import { ConfigSubagent } from "./config/subagent"
import { ConfigToolOutput } from "./config/tool-output"
import { ConfigWatcher } from "./config/watcher"
import { ConfigV1 } from "./v1/config/config"
Expand Down Expand Up @@ -109,6 +110,9 @@ export class Info extends Schema.Class<Info>("Config.Info")({
}),
experimental: ConfigExperimental.Experimental.pipe(Schema.optional),
providers: Schema.Record(Schema.String, ConfigProvider.Info).pipe(Schema.optional),
subagent: ConfigSubagent.Info.pipe(Schema.optional).annotate({
description: "How subagents choose their model: inherit, small_model, a fixed model, or per task",
}),
residency: ConfigResidency.Info.pipe(Schema.optional).annotate({
description:
"Data-residency policy restricting which provider jurisdictions this deployment may use, with an audit log of outbound model calls",
Expand Down
28 changes: 28 additions & 0 deletions packages/core/src/config/subagent.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
export * as ConfigSubagent from "./subagent"

import { Schema } from "effect"

/**
* How subagents choose their model (XCOD-82). Declared in both the v1 and v2 config schemas, so
* the live config path keeps it (the XCOD-68 / XCOD-93 lesson).
*/
export const Info = Schema.Struct({
model: Schema.String.pipe(Schema.optional).annotate({
description:
'Default model for every subagent without its own agent.<name>.model: "inherit" (the main agent\'s model, the default), "small" (small_model) or "provider/model"',
}),
variant: Schema.String.pipe(Schema.optional).annotate({
description: 'Reasoning variant for subagents whose model is overridden: "inherit" or a variant name',
}),
dynamic: Schema.Struct({
enabled: Schema.Boolean.pipe(Schema.optional).annotate({
description: "Let the main agent choose a model per task call, from `allow` only",
}),
allow: Schema.Array(Schema.String).pipe(Schema.optional).annotate({
description: 'Models the main agent may choose per task call ("provider/model")',
}),
})
.pipe(Schema.optional)
.annotate({ description: "Per-task model selection by the main agent" }),
}).annotate({ identifier: "SubagentConfig" })
export type Info = Schema.Schema.Type<typeof Info>
4 changes: 4 additions & 0 deletions packages/core/src/v1/config/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import { ConfigServerV1 } from "./server"
import { ConfigSkillsV1 } from "./skills"
import { ConfigHooks } from "../../config/hooks"
import { ConfigResidency } from "../../config/residency"
import { ConfigSubagent } from "../../config/subagent"

export type Layout = ConfigLayoutV1.Layout

Expand Down Expand Up @@ -92,6 +93,9 @@ export const Info = Schema.Struct({
description:
"Default agent to use when none is specified. Must be a primary agent. Falls back to 'build' if not set or if the specified agent is invalid.",
}),
subagent: Schema.optional(ConfigSubagent.Info).annotate({
description: "How subagents choose their model: inherit, small_model, a fixed model, or per task",
}),
subagent_depth: Schema.optional(NonNegativeInt).annotate({
description: "Maximum subagent nesting depth. Defaults to 1, which prevents subagents from launching subagents.",
}),
Expand Down
8 changes: 7 additions & 1 deletion packages/opencode/src/agent/agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ export const Info = Schema.Struct({
}),
),
variant: Schema.optional(Schema.String),
/** Raw `agent.<name>.model` from config: `"inherit"`, `"small"` or `"provider/model"` (XCOD-82). */
modelSpec: Schema.optional(Schema.String),
prompt: Schema.optional(Schema.String),
options: Schema.Record(Schema.String, Schema.Unknown),
steps: Schema.optional(Schema.Finite),
Expand Down Expand Up @@ -420,7 +422,11 @@ const layer = Layer.effect(
options: {},
native: false,
}
if (value.model) item.model = Provider.parseModel(value.model)
if (value.model) {
item.modelSpec = value.model
// "inherit" and "small" are resolved per task call (agent/subagent-model.ts), not here.
if (value.model !== "inherit" && value.model !== "small") item.model = Provider.parseModel(value.model)
}
item.variant = value.variant ?? item.variant
item.prompt = value.prompt ?? item.prompt
item.description = value.description ?? item.description
Expand Down
132 changes: 132 additions & 0 deletions packages/opencode/src/agent/subagent-model.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
export * as SubagentModel from "./subagent-model"

import path from "path"
import { Global } from "@opencode-ai/core/global"
import { Residency } from "@opencode-ai/core/residency"

/**
* Which model a subagent runs on, and which rule chose it (XCOD-82). First match wins:
*
* 1. `per-call`: the main agent's `model` argument, only when `subagent.dynamic.enabled` and the
* model is on `subagent.dynamic.allow`. Anything else is refused, never silently replaced.
* 2. `per-type`: `agent.<subagent_type>.model`.
* 3. `global`: `subagent.model`.
* 4. `inherit`: the main agent's current model. This is the default and matches upstream.
*
* Values: `"inherit"` means the main agent's model, `"small"` means `small_model` (or inherit if
* that isn't set), and `"provider/model"` means that exact model.
*/

export type Rule = "per-call" | "per-type" | "global" | "inherit"

export interface Model {
providerID: string
modelID: string
}

export interface Input {
readonly subagentType: string
/** The main agent's current model and reasoning variant. */
readonly parent: Model & { variant?: string }
readonly perCall?: string
/** Raw `agent.<type>.model` / `agent.<type>.variant` from config. */
readonly typeModel?: string
readonly typeVariant?: string
readonly config: {
readonly small_model?: string
readonly subagent?: {
readonly model?: string
readonly variant?: string
readonly dynamic?: { readonly enabled?: boolean; readonly allow?: readonly string[] }
}
}
}

export interface Resolved {
readonly model: Model
readonly variant: string | undefined
readonly rule: Rule
/** Human-readable name of the rule, e.g. `agent.qa.model` or `subagent.model`. */
readonly source: string
}

export class RefusedError extends Error {
override name = "SubagentModelRefused"
}

function parse(spec: string): Model {
const [providerID, ...rest] = spec.split("/")
return { providerID, modelID: rest.join("/") }
}

function resolveValue(value: string, input: Input): { model: Model; inherited: boolean } {
const parent = { providerID: input.parent.providerID, modelID: input.parent.modelID }
if (value === "inherit") return { model: parent, inherited: true }
if (value === "small") {
if (input.config.small_model) return { model: parse(input.config.small_model), inherited: false }
return { model: parent, inherited: true }
}
return { model: parse(value), inherited: false }
}

/** Models the main agent may pick per call. Empty unless dynamic selection is enabled. */
export function allowed(config: Input["config"], residency?: Residency.Resolved): string[] {
const dynamic = config.subagent?.dynamic
if (!dynamic?.enabled) return []
const list = [...new Set(dynamic.allow ?? [])]
if (!residency) return list
return list.filter((spec) => Residency.evaluate(parse(spec).providerID, residency.policy).allowed)
}

export function resolve(input: Input): Resolved {
const configuredVariant = (explicit?: string) => {
const value = explicit ?? input.config.subagent?.variant
return value === undefined || value === "inherit" ? undefined : value
}
const finish = (value: string, rule: Rule, source: string, explicitVariant?: string): Resolved => {
const { model, inherited } = resolveValue(value, input)
const variant = configuredVariant(explicitVariant)
// An inherited model keeps the main agent's reasoning effort unless a variant is configured.
// An overridden model uses the configured variant, or the model's default.
return { model, variant: variant ?? (inherited ? input.parent.variant : undefined), rule, source }
}

if (input.perCall !== undefined) {
const allow = input.config.subagent?.dynamic?.allow ?? []
if (!input.config.subagent?.dynamic?.enabled)
throw new RefusedError(`Choosing a model per task is disabled. Set "subagent.dynamic.enabled" to allow it.`)
if (!allow.includes(input.perCall))
throw new RefusedError(
`Model "${input.perCall}" is not on subagent.dynamic.allow. Choose one of: ${allow.join(", ") || "(none)"}.`,
)
return finish(input.perCall, "per-call", "task model", input.typeVariant)
}
if (input.typeModel !== undefined)
return finish(input.typeModel, "per-type", `agent.${input.subagentType}.model`, input.typeVariant)
if (input.config.subagent?.model !== undefined)
return finish(input.config.subagent.model, "global", "subagent.model", input.typeVariant)
return finish("inherit", "inherit", "inherit", input.typeVariant)
}

/**
* Check the resolved model against the residency policy before the subagent session starts.
* A denial is written to the residency audit log like any other denied call, and the error
* names the rule that chose the model.
*/
export function checkResidency(resolved: Resolved, residency: Residency.Resolved | undefined) {
if (!residency) return
try {
Residency.enforce({
providerID: resolved.model.providerID,
baseURL: "",
resolved: residency,
defaultAuditPath: path.join(Global.Path.log, "residency-egress.log"),
fetch: undefined,
})
} catch (error) {
if (!(error instanceof Residency.DeniedError)) throw error
throw new RefusedError(
`${resolved.source} → ${resolved.model.providerID}/${resolved.model.modelID} denied by residency policy. ${error.decision.reason}`,
)
}
}
15 changes: 13 additions & 2 deletions packages/opencode/src/tool/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ import { EditTool } from "./edit"
import { GlobTool } from "./glob"
import { GrepTool } from "./grep"
import { ReadTool } from "./read"
import { TaskTool } from "./task"
import { TaskTool, withModelParameter } from "./task"
import { ToolJsonSchema } from "./json-schema"
import { Residency } from "@opencode-ai/core/residency"
import { SubagentModel } from "../agent/subagent-model"
import { Database } from "@opencode-ai/core/database/database"
import { TodoWriteTool } from "./todo"
import { WebFetchTool } from "./webfetch"
Expand Down Expand Up @@ -302,6 +305,10 @@ const layer = Layer.effect(
return true
})

// XCOD-82: allowed per-task models, minus any the residency policy would deny.
const cfg = yield* config.get()
const subagentModels = SubagentModel.allowed(cfg, Residency.resolve(cfg.residency))

const codeModeDescription = filtered.some((tool) => tool.id === "execute")
? yield* describeCodeMode(input)
: undefined
Expand All @@ -316,10 +323,14 @@ const layer = Layer.effect(
jsonSchema: tool.jsonSchema,
}
yield* plugin.trigger("tool.definition", { toolID: tool.id }, output)
const jsonSchema =
const pluginSchema =
output.parameters === tool.parameters || output.jsonSchema !== tool.jsonSchema
? output.jsonSchema
: undefined
const jsonSchema =
tool.id === TaskTool.id && subagentModels.length
? withModelParameter(pluginSchema ?? ToolJsonSchema.fromTool(tool), subagentModels)
: pluginSchema
return {
id: tool.id,
description: [
Expand Down
Loading
Loading