opencode-magi 0.6.1 → 0.7.0

package/README.md

@@ -78,7 +78,7 @@ Add the following content to the configuration file.
     }
   },
   "review": {
-    "agents": [
+    "reviewers": [
       { "ref": "account-1" },
       { "ref": "account-2" },
       { "ref": "account-3" }
@@ -87,7 +87,7 @@ Add the following content to the configuration file.
 }
 ```
 
-After refs are expanded, `review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique.
+After `refs` are expanded, `review.reviewers[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique.
 
 #### Set project config
 
@@ -133,7 +133,7 @@ Add the following content to the configuration file.
     }
   },
   "review": {
-    "agents": [
+    "reviewers": [
       { "ref": "account-1" },
       { "ref": "account-2" },
       { "ref": "account-3" }
@@ -143,8 +143,7 @@ Add the following content to the configuration file.
     "editor": { "ref": "account-4" }
   },
   "triage": {
-    "account": "account-5",
-    "agents": [
+    "voters": [
       { "ref": "account-1" },
       { "ref": "account-2" },
       { "ref": "account-3" }
@@ -155,7 +154,18 @@ Add the following content to the configuration file.
 
 Entries with `ref` are expanded from `agents.refs`. Fields set alongside `ref` override fields from the preset.
 
-After refs are expanded, `review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique. `merge.editor.account` is used by `/magi:merge` to push fixes, close PRs, and merge PRs.
+`model` can be a single `provider/model` string, a single object with `id` and `options`, or an ordered candidate array. Candidate arrays are resolved during validation against OpenCode's model catalog; the first available model is selected. Put provider-specific options on model objects, not on the agent role.
+
+```json
+{
+  "model": {
+    "id": "openai/gpt-5.1",
+    "options": { "reasoningEffort": "high" }
+  }
+}
+```
+
+After `refs` are expanded, `review.reviewers[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique. `merge.editor.account` is used by `/magi:merge` to push fixes, close PRs, and merge PRs.
 
 #### Validate config
 

package/dist/config/resolve.js

@@ -33,6 +33,12 @@ export function triageAgentKey(agent, index) {
 export function validateReviewerId(id) {
     return ID_PATTERN.test(id);
 }
+function normalizedModel(model) {
+    if (typeof model !== "string") {
+        throw new Error("model must be normalized before resolving agents");
+    }
+    return model;
+}
 function clonePermissionValue(value) {
     return typeof value === "string" ? value : { ...value };
 }
@@ -86,25 +92,29 @@ export function resolveAgents(config) {
         editor: editor
             ? {
                 ...editor,
+                model: normalizedModel(editor.model),
                 permission: resolveEditorPermission(agents, editor),
             }
             : undefined,
-        reviewers: (config.review?.agents ?? []).map((reviewer, index) => ({
+        reviewers: (config.review?.reviewers ?? []).map((reviewer, index) => ({
             ...reviewer,
             key: reviewerKey(reviewer, index),
             index,
+            model: normalizedModel(reviewer.model),
             permission: resolveReviewerPermission(agents, reviewer),
         })),
-        triage: (config.triage?.agents ?? []).map((agent, index) => ({
+        triage: (config.triage?.voters ?? []).map((agent, index) => ({
             ...agent,
             key: triageAgentKey(agent, index),
             index,
+            model: normalizedModel(agent.model),
             permission: resolveTriageAgentPermission(agents, agent),
         })),
         triageCreator: creator
             ? {
                 ...creator,
                 account: creator.account ?? "",
+                model: normalizedModel(creator.model),
                 permission: resolveTriageCreatorPermission(agents, creator),
             }
             : undefined,

package/dist/config/validate.js

@@ -4,7 +4,7 @@ import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import schema from "../../schema.json" with { type: "json" };
-import { resolveAgents, validateReviewerId } from "./resolve";
+import { resolveAgents, reviewerKey, triageAgentKey, validateReviewerId, } from "./resolve";
 const RESERVED_REVIEWER_KEYS = new Set(["editor", "orchestrator", "system"]);
 const PERMISSION_ACTIONS = new Set(["allow", "ask", "deny"]);
 const AJV = new Ajv2020({ allErrors: true, strict: false });
@@ -27,7 +27,6 @@ const REVIEWER_KEYS = new Set([
     "account",
     "id",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -35,7 +34,6 @@ const EDITOR_KEYS = new Set([
     "account",
     "author",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -43,7 +41,6 @@ const TRIAGE_AGENT_KEYS = new Set([
     "account",
     "id",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -51,20 +48,19 @@ const TRIAGE_CREATOR_KEYS = new Set([
     "account",
     "author",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
 const AUTHOR_KEYS = new Set(["email", "name"]);
 const GITHUB_KEYS = new Set(["apiRetryAttempts", "host", "owner", "repo"]);
 const REVIEW_KEYS = new Set([
-    "agents",
     "automation",
     "checks",
     "concurrency",
     "merge",
     "output",
     "prompts",
+    "reviewers",
     "safety",
     "worktree",
 ]);
@@ -76,7 +72,6 @@ const MERGE_KEYS = new Set([
     "prompts",
 ]);
 const TRIAGE_KEYS = new Set([
-    "agents",
     "automation",
     "categories",
     "concurrency",
@@ -85,6 +80,7 @@ const TRIAGE_KEYS = new Set([
     "prompts",
     "reporter",
     "safety",
+    "voters",
     "worktree",
 ]);
 const REVIEW_MERGE_KEYS = new Set([
@@ -145,6 +141,7 @@ const TRIAGE_PROMPT_KEYS = new Set([
     "existingPr",
     "reconsider",
 ]);
+const MODEL_CANDIDATE_KEYS = new Set(["id", "options"]);
 function githubHost(config) {
     return config.github?.host ?? "github.com";
 }
@@ -190,14 +187,14 @@ function expandAgentRefs(config, errors) {
     const refsValue = isPlainObject(agents) ? agents.refs : undefined;
     const refsInvalid = refsValue != null && !isPlainObject(refsValue);
     const refs = isPlainObject(refsValue) ? refsValue : undefined;
-    if (Array.isArray(magiConfig.review?.agents)) {
-        magiConfig.review.agents = magiConfig.review.agents.map((agent, index) => expandAgentRefUse(agent, `review.agents[${index}]`, refs, refsInvalid, errors));
+    if (Array.isArray(magiConfig.review?.reviewers)) {
+        magiConfig.review.reviewers = magiConfig.review.reviewers.map((agent, index) => expandAgentRefUse(agent, `review.reviewers[${index}]`, refs, refsInvalid, errors));
     }
     if (isPlainObject(magiConfig.merge?.editor)) {
         magiConfig.merge.editor = expandAgentRefUse(magiConfig.merge.editor, "merge.editor", refs, refsInvalid, errors);
     }
-    if (Array.isArray(magiConfig.triage?.agents)) {
-        magiConfig.triage.agents = magiConfig.triage.agents.map((agent, index) => expandAgentRefUse(agent, `triage.agents[${index}]`, refs, refsInvalid, errors));
+    if (Array.isArray(magiConfig.triage?.voters)) {
+        magiConfig.triage.voters = magiConfig.triage.voters.map((agent, index) => expandAgentRefUse(agent, `triage.voters[${index}]`, refs, refsInvalid, errors));
     }
     if (isPlainObject(magiConfig.triage?.creator)) {
         magiConfig.triage.creator = expandAgentRefUse(magiConfig.triage.creator, "triage.creator", refs, refsInvalid, errors);
@@ -275,26 +272,97 @@ function validatePermissionConfig(permission, path, errors) {
         }
     }
 }
-function validateModel(model, path, errors, catalog) {
-    if (!model)
-        return;
+function modelValidationError(model, path, catalog) {
     const slash = model.indexOf("/");
-    if (slash <= 0 || slash === model.length - 1) {
-        errors.push(`${path} must be a full OpenCode model ID in provider/model form`);
-        return;
-    }
+    if (slash <= 0 || slash === model.length - 1)
+        return `${path} must be a full OpenCode model ID in provider/model form`;
     if (!catalog)
-        return;
+        return undefined;
     const providerId = model.slice(0, slash);
     const modelId = model.slice(slash + 1);
     const models = catalog[providerId];
-    if (!models) {
-        errors.push(`${path} uses unknown OpenCode provider: ${providerId}`);
+    if (!models)
+        return `${path} uses unknown OpenCode provider: ${providerId}`;
+    if (!models.includes(modelId))
+        return `${path} uses unknown OpenCode model: ${model}`;
+    return undefined;
+}
+function validateModelId(model, path, errors, catalog) {
+    const error = modelValidationError(model, path, catalog);
+    if (error) {
+        errors.push(error);
+        return false;
+    }
+    return true;
+}
+function readModelCandidate(value, path, errors) {
+    if (typeof value === "string")
+        return { id: value };
+    if (!isPlainObject(value)) {
+        errors.push(`${path} must be a string or an object`);
+        return undefined;
+    }
+    validateKnownKeys(value, path, MODEL_CANDIDATE_KEYS, errors);
+    if (typeof value.id !== "string") {
+        errors.push(`${path}.id must be a string`);
+        return undefined;
+    }
+    if (value.options != null && !isPlainObject(value.options)) {
+        errors.push(`${path}.options must be an object`);
+        return undefined;
+    }
+    return { id: value.id, options: value.options };
+}
+function validateAndNormalizeModel(target, path, errors, catalog) {
+    const model = target.model;
+    if (typeof model === "string") {
+        validateModelId(model, path, errors, catalog);
+        return;
+    }
+    if (isPlainObject(model)) {
+        const candidate = readModelCandidate(model, path, errors);
+        if (candidate &&
+            validateModelId(candidate.id, `${path}.id`, errors, catalog)) {
+            target.model = candidate.id;
+            if (candidate.options)
+                target.options = candidate.options;
+            else
+                delete target.options;
+        }
+        return;
+    }
+    if (!Array.isArray(model)) {
+        if (model != null)
+            errors.push(`${path} must be a string, an object, or an array`);
+        return;
+    }
+    if (!model.length) {
+        errors.push(`${path} must contain at least one model candidate`);
+        return;
+    }
+    if (!catalog) {
+        errors.push(`${path} requires an OpenCode model catalog`);
         return;
     }
-    if (!models.includes(modelId)) {
-        errors.push(`${path} uses unknown OpenCode model: ${model}`);
+    const candidateErrors = [];
+    for (const [index, value] of model.entries()) {
+        const candidatePath = `${path}[${index}]`;
+        const candidate = readModelCandidate(value, candidatePath, errors);
+        if (!candidate)
+            continue;
+        const idPath = isPlainObject(value) ? `${candidatePath}.id` : candidatePath;
+        const error = modelValidationError(candidate.id, idPath, catalog);
+        if (!error) {
+            target.model = candidate.id;
+            if (candidate.options)
+                target.options = candidate.options;
+            else
+                delete target.options;
+            return;
+        }
+        candidateErrors.push(error);
     }
+    errors.push(`${path} must contain at least one usable OpenCode model candidate${candidateErrors.length ? ` (${candidateErrors.join("; ")})` : ""}`);
 }
 function validateReviewerList(reviewers, path, errors, catalog) {
     if (reviewers == null)
@@ -315,14 +383,11 @@ function validateReviewerList(reviewers, path, errors, catalog) {
         validateKnownKeys(reviewer, `${path}[${index}]`, REVIEWER_KEYS, errors);
         if (!reviewer.model)
             errors.push(`${path}[${index}].model is required`);
-        validateString(reviewer.model, `${path}[${index}].model`, errors);
-        validateModel(reviewer.model, `${path}[${index}].model`, errors, catalog);
+        validateAndNormalizeModel(reviewer, `${path}[${index}].model`, errors, catalog);
         if (!reviewer.account)
             errors.push(`${path}[${index}].account is required`);
         validateString(reviewer.account, `${path}[${index}].account`, errors);
         validateString(reviewer.persona, `${path}[${index}].persona`, errors);
-        if (reviewer.options != null && !isPlainObject(reviewer.options))
-            errors.push(`${path}[${index}].options must be an object`);
         validatePermissionConfig(reviewer.permissions, `${path}[${index}].permissions`, errors);
         if (reviewer.id) {
             if (!validateReviewerId(reviewer.id)) {
@@ -334,18 +399,18 @@ function validateReviewerList(reviewers, path, errors, catalog) {
         }
     });
 }
-function validateTriageAgentList(agents, path, errors, catalog) {
-    if (agents == null)
+function validateTriageAgentList(voters, path, errors, catalog) {
+    if (voters == null)
         return;
-    if (!Array.isArray(agents)) {
+    if (!Array.isArray(voters)) {
         errors.push(`${path} must be an array`);
         return;
     }
-    if (agents.length < 3)
-        errors.push(`${path} must contain at least 3 agents`);
-    if (agents.length % 2 === 0)
-        errors.push(`${path} must contain an odd number of agents`);
-    agents.forEach((agent, index) => {
+    if (voters.length < 3)
+        errors.push(`${path} must contain at least 3 voters`);
+    if (voters.length % 2 === 0)
+        errors.push(`${path} must contain an odd number of voters`);
+    voters.forEach((agent, index) => {
         if (!agent || typeof agent !== "object") {
             errors.push(`${path}[${index}] must be an object`);
             return;
@@ -353,14 +418,11 @@ function validateTriageAgentList(agents, path, errors, catalog) {
         validateKnownKeys(agent, `${path}[${index}]`, TRIAGE_AGENT_KEYS, errors);
         if (!agent.model)
             errors.push(`${path}[${index}].model is required`);
-        validateString(agent.model, `${path}[${index}].model`, errors);
-        validateModel(agent.model, `${path}[${index}].model`, errors, catalog);
+        validateAndNormalizeModel(agent, `${path}[${index}].model`, errors, catalog);
         if (!agent.account)
             errors.push(`${path}[${index}].account is required`);
         validateString(agent.account, `${path}[${index}].account`, errors);
         validateString(agent.persona, `${path}[${index}].persona`, errors);
-        if (agent.options != null && !isPlainObject(agent.options))
-            errors.push(`${path}[${index}].options must be an object`);
         validatePermissionConfig(agent.permissions, `${path}[${index}].permissions`, errors);
         if (agent.id) {
             if (!validateReviewerId(agent.id)) {
@@ -406,15 +468,11 @@ function validateEditor(editor, path, errors, catalog) {
     if (!editor.model)
         errors.push(`${path}.model is required`);
     validateKnownKeys(editor, path, EDITOR_KEYS, errors);
-    validateString(editor.model, `${path}.model`, errors);
+    validateAndNormalizeModel(editor, `${path}.model`, errors, catalog);
     validateString(editor.account, `${path}.account`, errors);
     validateString(editor.persona, `${path}.persona`, errors);
-    validateModel(editor.model, `${path}.model`, errors, catalog);
     if (!editor.account)
         errors.push(`${path}.account is required`);
-    if (editor.options != null && !isPlainObject(editor.options)) {
-        errors.push(`${path}.options must be an object`);
-    }
     validatePermissionConfig(editor.permissions, `${path}.permissions`, errors);
     const author = editor.author;
     if (!author || !isPlainObject(author)) {
@@ -450,12 +508,8 @@ function validateTriageCreator(creator, path, errors, catalog) {
     if (!creator.model)
         errors.push(`${path}.model is required`);
     validateString(creator.account, `${path}.account`, errors);
-    validateString(creator.model, `${path}.model`, errors);
+    validateAndNormalizeModel(creator, `${path}.model`, errors, catalog);
     validateString(creator.persona, `${path}.persona`, errors);
-    validateModel(creator.model, `${path}.model`, errors, catalog);
-    if (creator.options != null && !isPlainObject(creator.options)) {
-        errors.push(`${path}.options must be an object`);
-    }
     validatePermissionConfig(creator.permissions, `${path}.permissions`, errors);
     const author = creator.author;
     if (!author || !isPlainObject(author)) {
@@ -680,15 +734,20 @@ function validateTriage(config, errors, options) {
     const creator = triage.creator;
     const reporter = typeof triage.reporter === "string" ? triage.reporter : undefined;
     const safety = triage.safety;
-    if (!triage.agents)
-        errors.push("triage.agents is required");
-    validateTriageAgentList(triage.agents, "triage.agents", errors, options.modelCatalog);
-    if (Array.isArray(triage.agents)) {
-        const resolvedTriageAgents = resolveAgents(config).triage ?? [];
+    if (!triage.voters)
+        errors.push("triage.voters is required");
+    validateTriageAgentList(triage.voters, "triage.voters", errors, options.modelCatalog);
+    if (Array.isArray(triage.voters)) {
+        const resolvedTriageAgents = triage.voters.map((agent, index) => ({
+            account: agent && typeof agent === "object" && typeof agent.account === "string"
+                ? agent.account
+                : "",
+            key: agent && typeof agent === "object" ? triageAgentKey(agent, index) : "",
+        }));
         validateResolvedTriageAgents(resolvedTriageAgents, "triage.resolvedAgents", errors);
         if (reporter != null &&
             !resolvedTriageAgents.some((agent) => agent.key === reporter)) {
-            errors.push(`triage.reporter must match a triage agent key: ${reporter}`);
+            errors.push(`triage.reporter must match a triage voter key: ${reporter}`);
         }
     }
     validateString(triage.reporter, "triage.reporter", errors);
@@ -778,10 +837,10 @@ async function fetchPermissions(config, exec, account) {
     return JSON.parse(raw);
 }
 async function validateWorktreeConfig(config, exec, options, errors) {
-    const agents = resolveAgents(config);
-    const checkEditor = Boolean(agents.editor && (options.requireEditor || options.requireWorktreeConfig));
+    const checkEditor = Boolean(config.merge?.editor &&
+        (options.requireEditor || options.requireWorktreeConfig));
     const checkTriageCreator = Boolean(config.triage?.automation?.create &&
-        agents.triageCreator &&
+        config.triage?.creator &&
         (options.requireTriage || options.requireWorktreeConfig));
     if (!checkEditor && !checkTriageCreator)
         return;
@@ -853,6 +912,9 @@ export async function validateConfig(config, options = {}) {
     const warnings = [];
     if (!config || typeof config !== "object")
         errors.push("config must be an object");
+    if (options.requireModelCatalog && !options.modelCatalog) {
+        errors.push("OpenCode model catalog could not be loaded");
+    }
     expandAgentRefs(config, errors);
     if (config && typeof config === "object")
         validateJsonSchema(config, errors);
@@ -876,11 +938,20 @@ export async function validateConfig(config, options = {}) {
         else {
             validateKnownKeys(config.review, "review", REVIEW_KEYS, errors);
         }
-        if (!config.review.agents)
-            errors.push("review.agents is required");
-        validateReviewerList(config.review.agents, "review.agents", errors, options.modelCatalog);
-        if (Array.isArray(config.review.agents)) {
-            validateResolvedReviewers(resolveAgents(config).reviewers, "review.resolvedAgents", errors);
+        if (!config.review.reviewers)
+            errors.push("review.reviewers is required");
+        validateReviewerList(config.review.reviewers, "review.reviewers", errors, options.modelCatalog);
+        if (Array.isArray(config.review.reviewers)) {
+            validateResolvedReviewers(config.review.reviewers.map((reviewer, index) => ({
+                account: reviewer &&
+                    typeof reviewer === "object" &&
+                    typeof reviewer.account === "string"
+                    ? reviewer.account
+                    : "",
+                key: reviewer && typeof reviewer === "object"
+                    ? reviewerKey(reviewer, index)
+                    : "",
+            })), "review.resolvedReviewers", errors);
         }
     }
     if (options.requireTriage && !config.triage) {

package/dist/index.js

@@ -9,7 +9,7 @@ import { loadConfig, mergeMagiConfig } from "./config/load";
 import { outputBaseDirs } from "./config/output";
 import { worktreeBaseDirs } from "./config/worktree";
 import { resolveRepository } from "./config/resolve";
-import { validateConfig } from "./config/validate";
+import { validateConfig, } from "./config/validate";
 import { withGitHubApiRetry } from "./github/retry";
 import { mapPool } from "./orchestrator/pool";
 import { MagiRunManager } from "./orchestrator/run-manager";
@@ -286,23 +286,6 @@ function parseOptionalIssue(value) {
 function clearFlag(value) {
     return typeof value === "boolean" ? value : undefined;
 }
-function clearToolFlag(value) {
-    if (value === true || value === "true")
-        return true;
-    if (value === "false")
-        return false;
-    return undefined;
-}
-function hasBlankSelector(args) {
-    return !args.runId?.trim() && !args.pr?.trim();
-}
-function hasDefaultedFalseClearFlags(args) {
-    return (hasBlankSelector(args) &&
-        args.branch === "false" &&
-        args.output === "false" &&
-        args.session === "false" &&
-        args.worktree === "false");
-}
 function parseQuestionAnswers(value) {
     const trimmed = value.trim();
     if (!trimmed)
@@ -334,6 +317,9 @@ function issueMarkdownLink(repository, issue) {
     const url = `https://${host}/${repository.github.owner}/${repository.github.repo}/issues/${issue}`;
     return `[#${issue}](${url})`;
 }
+function validationError(validation) {
+    return new Error(JSON.stringify(validation, null, 2));
+}
 function isPlainObject(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -395,7 +381,8 @@ export async function validateMagiConfigFiles(directory, options = {}) {
                 ? withGitHubApiRetry(options.exec, mergedConfig.github?.apiRetryAttempts ?? 3)
                 : undefined,
             modelCatalog: options.modelCatalog,
-            requireGithub: hasProjectConfig && Boolean(mergedConfig.review?.agents),
+            requireGithub: hasProjectConfig && Boolean(mergedConfig.review?.reviewers),
+            requireModelCatalog: true,
             requireWorktreeConfig: true,
         });
         loadedFrom = existing.map((status) => status.path).join(", ");
@@ -447,7 +434,8 @@ export const MagiPlugin = async ({ client, directory }) => {
             .then(extractModelCatalog)
             .catch(() => catalogClient.provider
             ?.list({ query: { directory } })
-            .then(extractModelCatalog));
+            .then(extractModelCatalog))
+            .catch(() => undefined);
         return modelCatalogPromise;
     }
     return {
@@ -492,9 +480,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
                         requireEditor: true,
+                        requireModelCatalog: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startMerge({
@@ -534,9 +523,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         directory,
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
+                        requireModelCatalog: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startReview({
@@ -557,7 +547,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                 },
             }),
             magi_triage: tool({
-                description: "Triage one or more GitHub issues with configured Magi triage agents.",
+                description: "Triage one or more GitHub issues with configured Magi triage voters.",
                 args: {
                     issues: tool.schema.string(),
                     dryRun: tool.schema.boolean().optional(),
@@ -574,12 +564,13 @@ export const MagiPlugin = async ({ client, directory }) => {
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
                         requireEditor: config.triage?.automation?.merge === true,
+                        requireModelCatalog: true,
                         requireReview: config.triage?.automation?.review === true ||
                             config.triage?.automation?.merge === true,
                         requireTriage: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     if (!repository.triage)
                         return JSON.stringify({ errors: ["triage configuration is required"], ok: false }, null, 2);
@@ -692,41 +683,21 @@ export const MagiPlugin = async ({ client, directory }) => {
             }),
             magi_clear: tool({
                 description: "Clear all inactive Magi runs by deleting configured sessions, worktrees, branches, and output artifacts.",
-                args: {
-                    runId: tool.schema.string().optional(),
-                    pr: tool.schema.string().optional(),
-                    issue: tool.schema.string().optional(),
-                    branch: tool.schema.enum(["true", "false"]).optional(),
-                    output: tool.schema.enum(["true", "false"]).optional(),
-                    session: tool.schema.enum(["true", "false"]).optional(),
-                    worktree: tool.schema.enum(["true", "false"]).optional(),
-                },
-                async execute(args) {
+                args: {},
+                async execute() {
                     const loaded = await loadConfig(directory).catch(() => undefined);
                     const clear = loaded?.config.clear;
-                    const useConfiguredDefaults = hasDefaultedFalseClearFlags(args);
                     const options = {
-                        branch: (useConfiguredDefaults
-                            ? undefined
-                            : clearToolFlag(args.branch)) ?? clearFlag(clear?.branch),
-                        output: (useConfiguredDefaults
-                            ? undefined
-                            : clearToolFlag(args.output)) ?? clearFlag(clear?.output),
-                        session: (useConfiguredDefaults
-                            ? undefined
-                            : clearToolFlag(args.session)) ?? clearFlag(clear?.session),
-                        worktree: (useConfiguredDefaults
-                            ? undefined
-                            : clearToolFlag(args.worktree)) ?? clearFlag(clear?.worktree),
+                        branch: clearFlag(clear?.branch),
+                        output: clearFlag(clear?.output),
+                        session: clearFlag(clear?.session),
+                        worktree: clearFlag(clear?.worktree),
                     };
                     return runManager.clear({
                         options,
-                        issue: parseOptionalIssue(args.issue),
                         outputDir: loaded
                             ? outputBaseDirs(directory, loaded.config)
                             : undefined,
-                        pr: parseOptionalPr(args.pr),
-                        runId: args.runId,
                         worktreeDir: loaded
                             ? worktreeBaseDirs(directory, loaded.config)
                             : undefined,

package/dist/orchestrator/run-manager.js

@@ -1616,16 +1616,16 @@ export class MagiRunManager {
             }));
         }
         if (progress.type === "triage_agent_started") {
-            await this.notify(state, `**Triage agent ${progress.voter}** started ${progress.phase} for ${issue}.`);
+            await this.notify(state, `**Triage voter ${progress.voter}** started ${progress.phase} for ${issue}.`);
         }
         if (progress.type === "triage_agent_repair") {
-            await this.notify(state, `**Triage agent ${progress.voter}** started JSON regeneration for ${issue}.`);
+            await this.notify(state, `**Triage voter ${progress.voter}** started JSON regeneration for ${issue}.`);
         }
         if (progress.type === "triage_agent_completed") {
-            await this.notify(state, `**Triage agent ${progress.voter}** completed ${progress.phase} for ${issue}: ${progress.vote}.`);
+            await this.notify(state, `**Triage voter ${progress.voter}** completed ${progress.phase} for ${issue}: ${progress.vote}.`);
         }
         if (progress.type === "triage_agent_failed") {
-            await this.notify(state, `**Triage agent ${progress.voter}** failed ${progress.phase} for ${issue}: ${redactSecrets(progress.error)}`);
+            await this.notify(state, `**Triage voter ${progress.voter}** failed ${progress.phase} for ${issue}: ${redactSecrets(progress.error)}`);
         }
         if (progress.type === "comment_posting") {
             await this.notify(state, `Posting triage comment for ${issue}.`);

package/dist/orchestrator/triage.js

@@ -128,13 +128,14 @@ async function emitTriageModelProgress(input) {
     }
 }
 async function runVote(input) {
-    const prompt = await input.prompt({
-        context: input.context,
-        directory: input.directory,
-        issue: input.issue,
-        repository: input.repository,
-        voter: input.agent,
-    });
+    const prompt = input.promptText ??
+        (await input.prompt({
+            context: input.context,
+            directory: input.directory,
+            issue: input.issue,
+            repository: input.repository,
+            voter: input.agent,
+        }));
     await emitProgress(input.run, {
         phase: input.phase,
         type: "triage_agent_started",
@@ -216,7 +217,7 @@ export function chooseDuplicateOutput(input) {
 async function runDuplicateVote(input) {
     const agents = input.input.repository.agents.triage;
     if (!agents?.length)
-        throw new Error("triage.agents is required");
+        throw new Error("triage.voters is required");
     await emitProgress(input.input, { phase: "duplicate", type: "phase" });
     const outputs = await Promise.all(agents.map((agent) => runVote({
         agent,
@@ -258,9 +259,16 @@ async function runDuplicateVote(input) {
 async function runPhaseVote(input) {
     const agents = input.input.repository.agents.triage;
     if (!agents?.length)
-        throw new Error("triage.agents is required");
+        throw new Error("triage.voters is required");
     await emitProgress(input.input, { phase: input.phase, type: "phase" });
-    const outputs = await Promise.all(agents.map((agent) => runVote({
+    const promptTexts = await Promise.all(agents.map((agent) => input.prompt({
+        context: input.context,
+        directory: input.input.directory,
+        issue: input.input.issue,
+        repository: input.input.repository,
+        voter: agent,
+    })));
+    const outputs = await Promise.all(agents.map((agent, index) => runVote({
         agent,
         client: input.input.client,
         context: input.context,
@@ -269,6 +277,7 @@ async function runPhaseVote(input) {
         parse: input.parse,
         phase: input.phase,
         prompt: input.prompt,
+        promptText: promptTexts[index],
         repository: input.input.repository,
         run: input.input,
         schemaName: input.schemaName,
@@ -285,7 +294,16 @@ async function runPhaseVote(input) {
         voter: agents[index].key,
     })));
     await writeJson(join(input.outputDir, `${input.phase}-majority.json`), majority);
-    return { outputs, vote: majority.vote };
+    return {
+        outputs,
+        reason: chooseDecisionReason({
+            outputs,
+            threshold: majority.threshold,
+            vote: majority.vote,
+            voters: majority.vote ? majority.voters[majority.vote] : undefined,
+        }),
+        vote: majority.vote,
+    };
 }
 async function relationshipScan(input, issue) {
     const [comments, relatedPullRequests, duplicateCandidates] = await Promise.all([
@@ -507,7 +525,7 @@ async function runReconsiderationVote(input) {
 function triageReporter(repository, issue) {
     const agents = repository.agents.triage ?? [];
     if (!agents.length)
-        throw new Error("triage.agents is required");
+        throw new Error("triage.voters is required");
     const configured = repository.triage?.reporter;
     const reporter = configured
         ? agents.find((agent) => agent.key === configured)
@@ -518,26 +536,46 @@ function triageReporter(repository, issue) {
 }
 function decisionCommentBody(input) {
     const reason = input.reason?.trim();
-    const result = JSON.stringify(input.result);
     return reason
-        ? `Magi triage decision: ${result}\n\nReason: ${reason}`
-        : `Magi triage decision: ${result}\n\nAction: ${input.action}`;
+        ? reason
+        : decisionCommentFallback({ action: input.action, result: input.result });
+}
+function decisionCommentFallback(input) {
+    if (input.result.disposition === "accepted") {
+        const category = input.result.category
+            ? `${input.result.category} issue`
+            : "issue";
+        return input.action === "PR"
+            ? `Magi accepted this ${category} and will prepare an implementation pull request.`
+            : `Magi accepted this ${category}.`;
+    }
+    if (input.result.disposition === "rejected") {
+        const category = input.result.category
+            ? `${input.result.category} issue`
+            : "issue";
+        return `Magi does not plan to act on this ${category}.`;
+    }
+    if (input.result.disposition === "duplicate") {
+        return "Magi marked this issue as a duplicate.";
+    }
+    return "Magi completed triage for this issue.";
 }
 function agentForKey(repository, key) {
     const agent = repository.agents.triage?.find((item) => item.key === key);
     if (!agent)
-        throw new Error(`Unknown triage agent: ${key}`);
+        throw new Error(`Unknown triage voter: ${key}`);
     return agent;
 }
 function askOutputs(outputs) {
     return (outputs ?? []).filter((output) => output.vote === "ASK");
 }
 function chooseDecisionReason(input) {
-    return (input.outputs?.find((output) => output.voter === input.reporter.key &&
-        output.vote === input.vote &&
-        output.reason)?.reason ??
-        input.outputs?.find((output) => output.vote === input.vote)?.reason ??
-        input.outputs?.find((output) => output.voter === input.reporter.key)?.reason);
+    if (!input.vote)
+        return undefined;
+    const canonicalVoter = input.voters?.[input.threshold - 1];
+    const canonicalReason = input.outputs?.find((output) => output.voter === canonicalVoter && output.vote === input.vote);
+    return (canonicalReason?.reason ??
+        input.outputs?.find((output) => output.vote === input.vote)?.reason);
 }
 async function postMarkedIssueComment(input) {
     const posted = await postIssueComment(input.exec, input.repository, input.issue, input.account, input.body);
@@ -867,7 +905,7 @@ export async function runTriage(input) {
         throw new Error("triage configuration is required");
     const agents = input.repository.agents.triage;
     if (!agents?.length)
-        throw new Error("triage.agents is required");
+        throw new Error("triage.voters is required");
     const runId = input.runId ?? `run-${Date.now().toString(36)}`;
     const outputDir = issueRunOutputDir({
         config: input.config,
@@ -985,12 +1023,7 @@ export async function runTriage(input) {
                 input,
                 outputDir,
             });
-            const reporter = triageReporter(input.repository, issue.number);
-            commentReason = chooseDecisionReason({
-                outputs: reconsideration.outputs,
-                reporter,
-                vote: reconsideration.vote ?? "ASK",
-            });
+            commentReason = reconsideration.reason;
             result =
                 reconsideration.vote === "YES"
                     ? { category: previous.category, disposition: "accepted" }
@@ -1034,11 +1067,7 @@ export async function runTriage(input) {
                     postComment: true,
                 };
                 return finishWithResult({
-                    commentReason: chooseDecisionReason({
-                        outputs: existingPr.outputs,
-                        reporter: triageReporter(input.repository, issue.number),
-                        vote: "RELATED_PR_HANDLES_ISSUE",
-                    }),
+                    commentReason: existingPr.reason,
                     context,
                     input,
                     issue,
@@ -1119,12 +1148,7 @@ export async function runTriage(input) {
                 schemaName: "triage acceptance",
                 votes: BINARY_VOTES,
             });
-            const reporter = triageReporter(input.repository, issue.number);
-            commentReason = chooseDecisionReason({
-                outputs: acceptance.outputs,
-                reporter,
-                vote: acceptance.vote ?? "ASK",
-            });
+            commentReason = acceptance.reason;
             result =
                 acceptance.vote === "YES"
                     ? { category, disposition: "accepted" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-magi",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Multi-agent PR review and merge orchestration plugin for OpenCode.",
   "license": "MIT",
   "author": "Hirotomo Yamada <hirotomo.yamada@avap.co.jp>",

package/schema.json

@@ -60,8 +60,7 @@
       "additionalProperties": false,
       "properties": {
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "author": {
           "type": "object",
@@ -83,8 +82,7 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "permissions": { "$ref": "#/$defs/permissions" },
         "persona": { "type": "string" }
@@ -97,8 +95,7 @@
       "additionalProperties": false,
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "author": {
           "type": "object",
@@ -121,9 +118,8 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
         "permissions": { "$ref": "#/$defs/permissions" },
         "persona": { "type": "string" }
       }
@@ -136,8 +132,7 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "account": { "type": "string", "minLength": 1 },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "author": {
           "type": "object",
           "required": ["name", "email"],
@@ -151,6 +146,31 @@
         "persona": { "type": "string" }
       }
     },
+    "modelConfig": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "$ref": "#/$defs/modelCandidate" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/$defs/modelCandidate" }
+            ]
+          }
+        }
+      ]
+    },
+    "modelCandidate": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "options": { "type": "object", "additionalProperties": true }
+      }
+    },
     "automation": {
       "type": "object",
       "additionalProperties": false,
@@ -297,7 +317,7 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "agents": {
+        "reviewers": {
           "type": "array",
           "minItems": 3,
           "items": { "$ref": "#/$defs/reviewer" }
@@ -332,7 +352,7 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "agents": {
+        "voters": {
           "type": "array",
           "minItems": 3,
           "items": { "$ref": "#/$defs/triageAgent" }