feat(#1689): per-plan agent_hint executor routing (#3417)

* feat(#1689): per-plan agent_hint executor routing

Option A per-plan specialist routing: a plan with an `agent_hint:` frontmatter field is dispatched to that subagent instead of gsd-executor when it resolves on the active runtime; absent/unresolved/disabled falls back to gsd-executor (byte-identical). Default-on via workflow.agent_hint_routing.

- src/phase.cts: parse agent_hint into the plan-index JSON (plan_json.agent_hint)
- agent-install-check.cts: resolveAgentHint() reuses getAgentsDir + runtime filename variants; probes project + global agent dirs; fails closed; rejects path-traversing names
- gsd-tools.cjs: 'resolve-agent' query route (fail-closed to gsd-executor; --raw/--json)
- execute-phase.md: lean per-plan reference + {EXECUTOR_TYPE} placeholder (host stays under the ADR-857 Phase 6 byte ceiling)
- execute-phase/steps/per-plan-executor-routing.md: resolution logic (Agent()-based dispatch; advisory on orchestrator-worktree)
- config: workflow.agent_hint_routing (validKey, default-on via SCHEMA_DEFAULTS, boolean validator)
- docs (CONFIGURATION.md, plan-md.md), changeset, tests/agent-hint-routing-1689.test.cjs (17 tests)

* chore(#1689): backfill changeset PR number (#3417)

* chore(#1689): regenerate install-tree fixtures for new workflow fragment

* chore(#1689): ack deliberate execute-phase.md growth (agent_hint routing)

* test(#1689): SPAWN contract allows parameterized subagent_type placeholder

agent-frontmatter's spawn-type checks scanned subagent_type="..." as a
concrete agent name. execute-phase now uses subagent_type="{EXECUTOR_TYPE}"
(a runtime placeholder resolved via resolve-agent, default gsd-executor).
Skip {TOKEN} placeholders in both the known-type and <available_agent_types>
checks; execute-phase still lists the built-in roster incl. gsd-executor.

* fix(#1689): CI conformance for the routing fragment

- per-plan-executor-routing.md: add the canonical runtime-launcher preamble to
  its gsd_run block (runtime-launcher-parity #373), matching sibling step fragments.
- agent-install-check.cts: drop a literal ~/.claude/agents path from the
  resolveAgentHint JSDoc so it does not leak into the compiled engine .cjs
  (cline install leak guard).

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-13 23:10:52 -04:00
committed by GitHub
parent 470389f3a2
commit 7976b1ca0d
34 changed files with 504 additions and 23 deletions

View File

@@ -594,6 +594,8 @@ interface RawPlan {
hasSummary: boolean;
/** #2830: true iff this plan's own SUMMARY declares `status: halted` (a designed stop). */
halted: boolean;
/** #1689: optional per-plan specialist executor hint (frontmatter `agent_hint:`). null when unset. */
agentHint: string | null;
}
/**
@@ -814,6 +816,18 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
}
// #1689: optional per-plan specialist executor hint. Read verbatim here; the
// orchestrator resolves it against the active runtime's agent dir at dispatch
// time (execute-phase.md -> `gsd_run query resolve-agent`), falling back to
// gsd-executor when the field is unset or the named agent does not resolve.
let agentHint: string | null = null;
const fmAgentHint = fm['agent_hint'];
if (fmAgentHint !== undefined) {
// eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
const hintStr = String(fmAgentHint).trim();
agentHint = hintStr !== '' ? hintStr : null;
}
const hasSummary = !unsummarizedPlanFiles.has(planFile);
// #2830: a plan can have a SUMMARY (hasSummary=true) and still be halted —
@@ -833,6 +847,7 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
autonomous,
objective: extractObjective(content) || (fm['objective'] as string | null) || null,
filesModified,
agentHint,
taskCount,
hasSummary,
halted,
@@ -935,6 +950,7 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
autonomous: rawPlan.autonomous,
objective: rawPlan.objective,
files_modified: rawPlan.filesModified,
agent_hint: rawPlan.agentHint,
task_count: rawPlan.taskCount,
has_summary: rawPlan.hasSummary,
// #2830: additive fields — halted is this plan's OWN status; blocked_by