🤖 feat: user-defined agents (unify modes + subagents)

[ThomasK33]

Unifies modes (Plan/Exec/Compact) and subagents (explore/exec presets) into user-defined Agent Definitions.

Key points:

• Agent definitions are discovered from ~/.mux/agents/*.md and <projectRoot>/.mux/agents/*.md (project overrides global overrides built-in).
• YAML frontmatter is parsed + validated; markdown body becomes the agent prompt (layered with mux’s prelude).
• New unified agentAiDefaults config (with back-compat for legacy modeAiDefaults / subagentAiDefaults).
• System message composition now supports Agent: <agentId> scoped sections in AGENTS.md (and keeps Mode: scoping working).
• The task tool now supports agentId (with subagent_type as a legacy alias).

Docs/tests:

• New docs for Agent Definitions and Agent-scoped instruction sections.
• Unit coverage for agent scoping + tool policy resolution.

CI/stability fixes included:

• Make mux api --help runnable in the bundled ESM CLI output (define require via createRequire).
• Make default worktree srcBaseDir respect MUX_ROOT during E2E runs (special-case ~/.mux / ~/.cmux tilde expansion).
• E2E harness hardening: per-test MUX_ROOT isolation + sanity check + updated UI helpers for the Agent selector combobox.
• Avoid git signing hangs in smoke tests and E2E demo repos (commit.gpgSign=false).
• Stabilize OpenAI image integration tests and Storybook play tests (narrower queries / more reliable vision model).

---

📋 Implementation Plan

Plan: User-defined Agents (unify Modes + Subagents)

Goal

Unify modes (Plan/Exec/Compact) and subagents (explore/exec presets) into a single, extensible concept: Agent Definitions.

Users can define new “modes” and “subagents” via Markdown files discovered from:

• ~/.mux/agents/*.md
• <projectRoot>/.mux/agents/*.md

Each file’s Markdown body becomes the agent’s system prompt (layered with mux’s base prelude), and its YAML frontmatter is strongly typed and parsed/validated on discovery.

Additionally, consolidate model + thinking defaults so modes and subagents share one configuration pipeline (frontmatter defaults → config overrides → workspace overrides → inheritance).

---

Recommended approach (v1): “Agent Definitions” registry + unified AI defaults

Net LoC estimate (product code): ~1,200–1,700

1) Define the on-disk format + schema

1.1 File layout + precedence

• Discover *.md files (non-recursive):
  1. Project-local: <projectRoot>/.mux/agents/*.md
  2. Global: ~/.mux/agents/*.md
  3. Built-ins (shipped in code)
• Collision rule: project-local overrides global overrides built-in by agentId.
• agentId is the filename without extension (e.g., plan.md → agentId="plan").

1.2 YAML frontmatter schema (strongly typed)

Create AgentDefinitionFrontmatterSchema (Zod) + TS types.

Proposed schema (v1):

---
name: Plan                # required, UI label
description: Create a plan before coding

# Visibility / availability
ui:
  selectable: true         # shows in main-agent UI selector
subagent:
  runnable: false          # allowed as task subagent

# AI defaults (baseline; can be overridden by config.json)
ai:
  modelString: openai:gpt-5.2
  thinkingLevel: medium

# Tool restrictions (simple + predictable)
# - base picks the baseline tool set (plan|exec|compact)
# - tools optionally *narrow* that set using exactly one strategy
policy:
  base: plan               # plan|exec|compact (default: exec)
  tools:
    deny: ["file_edit_insert", "file_edit_replace_string"]
    # OR:
    # only: ["web_fetch", "agent_skill_read"]
---

Notes:

• agentId is derived from the filename (strip .md); there is no id field in frontmatter.
• policy.base keeps compatibility with existing “mode-based” behavior (tool defaults + UX expectations).
• policy.tools is optional. If present, it must specify exactly one of:
  • deny: allow the base tool set except these tools
  • only: deny the base tool set except these tools
• Tool names are validated against the tool registry; unknown names warn + ignore.
• All policies are further restricted by runtime “hard-denies” (e.g., subagents can’t re-enable recursive task spawning).

1.3 Parsing rules

Mirror agent skills parsing patterns:

• Enforce a max file size (same ballpark as skills).
• Parse YAML frontmatter + markdown body.
• Derive agentId from the filename (strip .md).
• On invalid file: skip it and surface a non-fatal diagnostic (logs + optional UI warning).

---

2) Implement discovery + reading (Node)

Create an agentDefinitionsService analogous to agentSkillsService.

Deliverables:

• discoverAgentDefinitions({ projectRoot }) → list of index entries (id/name/description/flags + ai defaults + policy metadata).
• readAgentDefinition({ projectRoot, agentId }) → returns the validated frontmatter + markdown body.
• Cache results by (projectRoot, mtime) to avoid re-reading on every message; add a cheap invalidation strategy:
  • recompute if any discovered file’s mtime changes OR if the directory listing changes.

---

3) Unify “modeAiDefaults” + “subagentAiDefaults” into one config model

3.1 New config field

Add a single field to global config (backed by Zod + TS types):

• agentAiDefaults: Record<string, { modelString?: string; thinkingLevel?: ThinkingLevel }>

3.2 Back-compat migration

On config load:

• If agentAiDefaults is missing, synthesize it from existing:
  • modeAiDefaults[plan|exec|compact] → agentAiDefaults[plan|exec|compact]
  • subagentAiDefaults[type] → agentAiDefaults[type]

On config save:

• Write agentAiDefaults.
• Either:
  • keep writing legacy keys for one release (lowest risk), or
  • stop writing legacy keys but keep reading them (medium risk).

---

4) Apply Agent Definitions to system prompt construction

4.1 Main agent

Update buildSystemMessage to incorporate the selected agentId:

• Always include mux prelude.
• Inject the agent definition markdown body as a dedicated “Agent Prompt” block.
• Keep AGENTS.md layering (global + project-local).

4.2 Extend instruction scoping in AGENTS.md

Add support for a new scoped heading:

• Agent: <agentId>

Rules:

• For backward compat, keep Mode: plan|exec|compact working.
• When building system prompt:
  • apply Agent: <agentId> sections
  • apply Mode: <policy.base> sections
  • apply Model: sections (unchanged)
  • apply Tool: sections (unchanged)

---

5) Make tool policies agent-driven (with subagent safety)

5.1 Policy resolution algorithm

Implement a single policy resolver:

1. Start from policy.base:

• plan → existing plan tool policy
• exec → existing exec tool policy
• compact → existing compact policy

2. Optionally apply policy.tools (exactly one):

• deny: remove tools from the base set
• only: keep only these tools from the base set

3. Apply runtime “hard-denies”:

• If running as a subagent, forcibly deny:
  • task (no recursion)
  • propose_plan (main-agent only)
  • any other tools we consider unsafe for child agents (explicit list)

5.2 Enforce in both frontend + backend

• Frontend: use resolved policy to hide/disable UI affordances.
• Backend: treat frontend state as advisory; enforce server-side before tool execution.

---

6) Unify AI defaults + overrides resolution for agents

Target resolution order (single algorithm used everywhere):

Explicit call args (e.g. /compact -m)                 [highest]
→ Workspace override for agentId (if supported)
→ Global config override: config.agentAiDefaults[agentId]
→ AgentDefinition frontmatter defaults (ai.*)
→ Inherit from parent context (subagents only)
→ Sticky last-used workspace values (main agent only)
→ System fallback model/thinking

6.1 Workspace overrides

Generalize the existing “per-mode workspace override” to “per-agent workspace override”:

• Workspace metadata: aiSettingsByAgentId: Record<string, AiSettings>
• Local cache key: workspaceAiSettingsByAgentId:${workspaceId}

When user changes model/thinking while agentId=X, persist overrides under that agentId.

6.2 Replace WorkspaceModeAISync with WorkspaceAgentAISync

• Drive “effective model/thinking” from (workspaceId, agentId).
• Continue writing to legacy “active model/thinking” keys as a compatibility bridge until consumers are migrated.

---

7) UI changes

7.1 Replace ModeSelector with AgentSelector

• New UI selector lists AgentDefinition entries where ui.selectable: true.
• Persist the chosen agentId (global or per-project).
• Keep an ergonomic keybind:
  • TOGGLE_MODE becomes “toggle between last two selected UI agents”.

7.2 Settings: single “Agents” defaults editor

Replace the split “Mode defaults” and “Subagent defaults” views with one:

• Lists discovered agents, grouped:
  • UI-selectable agents
  • subagent-runnable agents
  • hidden/internal agents (optional)
• For each agent, show a read-only “Policy” summary (to keep tool permissions understandable):
  • base policy (policy.base)
  • tool filter (deny or only)
  • effective tools preview (computed list; show both main-agent and subagent variants after hard-denies)
• For each agent, allow configuring:
  • modelString (inherit / override)
  • thinkingLevel (inherit / override)

---

8) Subagents: switch from presets to agentId

8.1 Tool + API shape

Evolve the task tool schema:

• New: task({ agentId: string, prompt: string, ... })
• Keep accepting subagent_type as an alias for 1–2 releases (mapped to agentId).

8.2 Backend behavior

• Validate requested agentId exists and subagent.runnable: true.
• Build subagent system prompt from that agent definition.
• Apply tool policy resolver with “subagent hard-denies”.
• Apply unified AI defaults resolution (with parent inheritance when agent/config/frontmatter doesn’t specify).

---

9) Telemetry + timing

Current telemetry expects a small fixed mode union in some places.

• Add agentId: string to relevant telemetry events.
• Keep mode as the derived policy.base for backward compat and dashboards.
• Update sessionTimingService schema so custom agentIds don’t crash timing aggregation.

---

10) Tests / validation

Unit tests (fast):

• AgentDefinition parsing:
  • valid frontmatter + body
  • invalid YAML / missing fields
  • agentId derived from filename (strip .md)
• Discovery precedence:
  • project overrides global overrides built-in
• Tool policy merge:
  • base policy + deny list
  • base policy + only list
  • subagent hard-deny always wins
• AI defaults resolution:
  • config override beats frontmatter
  • workspace override beats config

Integration tests (targeted):

• System message includes the agent definition body + Agent: scoped AGENTS.md sections.
• Task creation uses agentId and enforces hard-denies.

---

11) Documentation

Add/extend user docs so this feature is discoverable and predictable:

• New docs page (e.g. docs/agents.mdx):
  • What an “Agent Definition” is (unifies modes + subagents)
  • Discovery paths + precedence (<project>/.mux/agents/*.md overrides ~/.mux/agents/*.md)
  • File format (frontmatter schema + markdown body semantics)
  • Examples for:
    • a UI-selectable agent (Plan-like)
    • a subagent-runnable definition (Explore-like)
  • Tool policy semantics:
    • policy.base
    • tools.deny vs tools.only
    • subagent hard-denies (cannot be re-enabled)
  • AI defaults resolution order (frontmatter defaults vs config overrides vs workspace overrides vs inheritance)
• Update docs/instruction-files.mdx:
  • Document new Agent: <agentId> scoped sections
  • Clarify interaction with existing Mode: scoping (derived from policy.base)
• Add docs navigation entry (docs.json) for the new page.

---

Alternatives (not recommended for v1)

Option B: Only add custom subagents (keep modes fixed)

Net LoC (product): ~400–700

• Keep Plan/Exec modes as-is.
• Add ~/.mux/agents/*.md only for subagent presets.
• Continue using modeAiDefaults for modes; unify only subagent side.

Pros: much smaller surface area.
Cons: does not deliver “custom modes” and does not unify defaults/UI.

Option C: Agent Definitions replace mode-based tool policy entirely

Net LoC (product): ~2,000–3,000

• Remove AgentMode/UIMode assumptions.
• Tool policy becomes fully data-driven (no plan/exec base).

Pros: cleanest long-term architecture.
Cons: high risk; lots of knock-on refactors.

---

Generated with mux • Model: openai:gpt-5.2 • Thinking: xhigh

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

@codex review

Addressed the "Apply per-agent defaults when syncing model/thinking" thread.

• Added a cached agentAiDefaults localStorage key (populated from config + kept in sync from Settings)
• WorkspaceModeAISync now prefers per-agent workspace overrides, then per-agent defaults (config + agent frontmatter), then legacy per-mode defaults
• Model/thinking updates now also write workspace AI settings under the current agentId so overrides stick when switching agents

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

@codex review

Addressed your note about custom agents clobbering base mode overrides:

• When updating model/thinking with a non-plan/exec agent active, we now write only the per-agent entry in the per-workspace cache.
• Backend updateModeAISettings is now only invoked when the active agent matches the base mode.

This prevents a reviewer agent (base=exec) from overwriting exec-mode overrides.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

@codex review

Addressed the backend persistence clobber:

• WorkspaceService.maybePersistAISettingsFromOptions now skips persisting plan/exec AI settings when options.agentId is present and doesn’t match the base options.mode.
• Added unit coverage in workspaceService.test.ts.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".