agent-config

Agent Config

agent-config maps verified Agent Host capabilities and user-confirmed profile tiers to a right-sized execution topology, model, and effort. It provides native support for primary coding-agent harnesses (Codex, Claude Code, Antigravity, DSH, OpenCode, ZCode, Cursor, Grok Build, Hermes, Pi) with safe generic/manual fallback for others. It has no required companion capability, no external Skill, and no external service requirements.

When to use

• Before complex multi-agent or partitioned work where topology, model tier, or effort matters.
• Explicit setup intent (agent-config setup) to configure or reconfigure host models and tiers.
• When invoked or offered by light-implement or ask-light.

Inputs

• Bounded task, SPEC, or ticket graph.
• Evidenced host capabilities and confirmed profile (via companion MCP or session input).

The script entry scripts/agent_config.py takes canonical Host and Profile evidence; missing, stale or mismatched evidence returns NEED_INPUT. Flags and rules: host-evidence-schema.md.

Setup Gate

• Explicit setup: If invoked with setup intent (agent-config setup), run setup mode to prepare or repair the runtime environment and Profile (see references/setup.md). Setup never plans execution for the current task.
• Normal invocation: agent-config is the only mode that plans execution topology and routing for current work. Check setup status via companion get_setup_status; health rules are in companion-contract.md. If companion is missing/stale, offer setup or continue plan-only. If Profile is missing or stale, offer setup or continue session-local where safely possible. Never silently enter setup, auto-install MCP tools, or mutate host files.

Output Contract: AgentConfigResult

agent-config yields a canonical AgentConfigResult envelope:

• readiness: READY | NEED_INPUT | NEED_PROJECT_TICKETS | BLOCKED | UNSUPPORTED (authoritative execution-readiness; redundant status removed).
• mode: persisted | session-local | plan-only
• setup_state: companion (ready | missing | stale), profile (persisted | session-local | missing).
• handoff: "project-tickets" | "setup" | "light-implement" | null
• execution_config: ExecutionConfig | null (strictly present when readiness === "READY"; strictly null for all non-ready states).

Core flow

1. Setup check: Verify a confirmed profile via a healthy companion or session input. Never guess single-model without a profile.
2. Inspect host: Read active models, supported effort values, and concurrency limits.
3. Determine task shape: Classify as single-pass or decomposed (never by word count).
4. Decomposition gate: If decomposed and formal tickets do not exist, emit readiness: NEED_PROJECT_TICKETS, handoff: "project-tickets", execution_config: null, and return the ticketing recommendation to the caller.
5. Difficulty & tier: For multi-model, map work difficulty (routine..critical) to user-confirmed profile tiers (routine, standard, high, review). When the difficulty or reasoning need is not stated, the script may ask a typed decision source (see Optional capabilities).
6. Resolve effort: Resolve abstract policies (e.g. highest-supported) strictly to verified host-supported strings (e.g. high), never emitting unverified literal max.
7. Select execution mode:
   • Case A (Fixed Single-model + Single-pass): Direct execution in main session, single model, resolved effort, no fake roles.
   • Case B (Fixed Single-model + Decomposed, P0): Controller main session coordinates fresh worker contexts, same model, actual effort.
   • Case C (Tiered Multi-model + Single-pass): User-configured tier mapped from task difficulty, minimal topology.
   • Case D (Tiered Multi-model + Decomposed, P0): Ticket difficulty mapped to user profile tiers, resolved effort, Controller integration.
8. Emit plan & apply: Output plan conforming to references/plan-schema.md and AgentConfigResult. Host config mutations require preview approval (preview_configuration → user approval → apply_configuration → validate_configuration).

Invariants

• No intelligence guessing: Never infer model strength from names or metadata; model tiers are strictly user-confirmed.
• Single-model is first-class: Single-model is a peer topology, not a degraded fallback. Case B and Case D are both P0 paths.
• No silent mutation: No automatic package installations, background daemons, or host file edits without explicit consent.
• Anti-wordcount rule: Semantic complexity and dependencies determine task shape, never prose length.

Handoff

• Return AgentConfigResult to the caller; handoff names a recommendation, not permission to start another Skill.
• An already active light-implement caller may resume its authorized bounded item when readiness === "READY".
• For standalone invocation, recommend explicit $light-implement when ready or $project-tickets when tickets are needed, then stop. Starting either user-invoked stage requires explicit user approval for that exact target and verified host transition support; otherwise show its exact invocation.
• Code review converges via review-loop; final acceptance belongs to project-review.

Optional capabilities

• Complexity or reasoning need is not stated → the task profiler asks through the light-decide script path; when you judge without the script, call light-decide with question ids agent-config/task-complexity or agent-config/reasoning-need. It asks only within the project's Decision data: limit (no line means on-device), applies an answer only when the user's policy file calibrates that question, and applies a downgrade only when the score sits clearly inside the lower bin. Unavailable or uncalibrated → keep the deterministic profile. A judgment never confirms a Profile or changes Host configuration.

References

• references/setup.md — Setup questionnaire and tier binding flow
• references/routing.md — 4 peer execution modes and topology selection
• references/task-assessment.md — Task shape and difficulty criteria
• references/companion-contract.md — Companion MCP tool protocol (8 tools)
• references/harness-support.md — Primary coding-agent harnesses (10 native adapters) and generic fallback
• references/profile-schema.md — Host-scoped profile schema
• references/plan-schema.md — Execution plan format and review semantics
• references/host-evidence-schema.md — Host evidence schema v2
• references/provider-adapter-contract.md — Adapter boundaries and preview-apply