Sub-agent profiles and models

Each editable sub-agent profile owns its model policy. It can use one exact provider/model assignment or Inherit from parent, which follows the effective provider and model of the parent chat. The sub-agent still does not inherit the parent mode, instructions, or tools.

Configure a profile

Open Settings → Sub Agents, then edit a built-in or custom profile. You can change its routing description, instructions, tools, model, optional reasoning effort, skill discovery, and enabled state. Built-in profiles are permanent; complete custom profiles can also be added and deleted. Plugin definitions are read-only, although you can enable or disable them.

The model dropdown starts with Inherit from parent, followed by the currently available Kodik catalog, Ollama models, and configured Custom Provider models. Kodik stores the selected policy explicitly:

Provider	Stored reference
Parent chat	"inherit"
Kodik cloud	{ "provider": "kodik", "modelId": "<exact-id>" }
Ollama	{ "provider": "ollama", "modelId": "<exact-id>" }
Custom Provider	{ "provider": "custom-provider", "providerId": "<provider-id>", "modelId": "<exact-id>" }

Reasoning effort is an optional, independent profile override. With Inherit from parent, Settings offers the efforts supported by the current parent model; a saved effort must also be supported by the effective parent model in the chat where the sub-agent runs.

Availability checks

Settings continuously compares configured profiles with the current Kodik model catalog, Ollama endpoint, Custom Providers, model reasoning capabilities, and tool support. An unavailable assignment gets an error indicator beside the profile and is omitted from each parent mode’s usable catalog until repaired.

If an explicitly assigned model disappears after a turn starts, launching that profile fails visibly in chat and directs you to Settings → Sub Agents. Kodik does not silently switch an exact assignment. A profile saved as Inherit from parent deliberately resolves the current parent provider/model for each chat; it is unavailable when that parent model cannot run the profile. Orchestrator startup itself fails when no enabled profile has an available compatible model.

An Ollama model stays local and does not consume Kodik credits. Cost and privacy characteristics for a Custom Provider depend on that provider’s configuration.

JSON configuration

The Settings editor writes versioned JSON. User edits live in ~/.kodik/sub-agents.json; an optional .kodik/sub-agents.json in the workspace completely replaces that user layer.

{
  "version": 1,
  "maxConcurrentWorkers": 4,
  "overrides": {
    "researcher": {
      "model": "inherit"
    },
    "implementer": {
      "description": "Use for small, fully specified product changes.",
      "model": {
        "provider": "ollama",
        "modelId": "qwen3-coder:30b"
      },
      "reasoningEffort": "high",
      "tools": ["read_file", "rg", "edit_file", "shell", "browser"]
    }
  },
  "profiles": [
    {
      "id": "custom:release-auditor",
      "name": "Release Auditor",
      "description": "Use before release to validate packaging and migration evidence.",
      "instructions": "Inspect the assigned release surface and report reproducible evidence.",
      "model": {
        "provider": "kodik",
        "modelId": "openrouter-openai-gpt-5.6-luna"
      },
      "tools": ["read_file", "rg", "shell"],
      "enabled": true
    }
  ]
}

maxConcurrentWorkers is an optional integer from 1 to 16 and defaults to 4. overrides are sparse: omitted fields continue to come from the current source or plugin profile. Entries in profiles are complete custom profiles and use ids in the custom:<slug> namespace. Settings validates unknown fields, duplicate ids, unavailable models, unsupported reasoning effort, parent-owned tools, and file or field size limits.

The Settings editor uses atomic writes and detects outside changes so one editor does not silently overwrite another. No secrets or provider keys are stored in this file.

For the delegation lifecycle and durable reports, see Sub-agents.