apt-mcp-agent-setup 3.2.7 → 3.3.1

package/src/templates/apt-runtime.md

@@ -4,10 +4,10 @@
 2. Call `route_request` for a new request or changed intent, including target package/stack and explicit skills. Load the selected specialist and companion skills with `skill_load`. Do not read the complete trigger catalog into the model context.
 3. Read-only questions, reviews and running existing tests do not require a code-change pipeline. Before executable changes, inspect `pipeline_status` and bind `pipeline_start` or `pipeline_use` with canonical task/run identity and an explicit workspace.
 4. Small changes use scope, fix/check and review. Features use clarification only where needed, a plan with acceptance criteria, implementation, verification, review and acceptance. Bug fixes start with diagnosis and regression coverage. Do not require three questions, a PRD or external issues when the task is already clear.
-5. Use `pipeline_next` to reserve work before dispatch. Delegate useful independent research and reviews to native host subagents, with at most four active actors including the coordinator. Only one writer per workspace. Workers must not start/reset/rebind the parent pipeline.
+5. Use `pipeline_next` to reserve work before dispatch. Use its pinned `nativeDispatch` fields only where the native tool supports them. Codex model overrides use a fresh brief with `fork_turns:"none"` and the exact `nativeTaskName`; a follow-up cannot change an existing worker's model. Include APT attempt, actor and session markers in the brief. Delegate useful independent research and reviews to native host subagents, with at most four active actors including the coordinator. Only one writer per workspace. Workers must not start/reset/rebind the parent pipeline.
 6. Pin a quality plan for new executable runs: stable criteria, expected outcomes, concrete check IDs, target platforms and required review roles. Use `pipeline_verify` with a supported test report and named assertions, then `pipeline_checkpoint` with the current evidence IDs. Exit code, build, screenshot or a free-form summary cannot prove functional acceptance. Missing required checks keep the run unaccepted.
-7. Record separate technical and Product/UX review verdicts when the work affects a user flow. Review staged, unstaged and relevant untracked changes. Keep finding IDs open across reviews until a current fix or reasoned dismissal is confirmed by a reviewer. High-risk work needs a host-observed independent technical reviewer; actor names and self-reported models do not prove independence. Rerun checks after affected changes. Review-only requests produce findings, not unsolicited edits or MR comments.
-8. Stop after ten repair/check attempts per work item or three repeated outcomes without progress. Preserve budgets and blocked/paused states across resume. User interruption always wins over continuation hooks.
+7. Record separate technical and Product/UX review verdicts when the work affects a user flow. Review staged, unstaged and relevant untracked changes. Keep finding IDs open across reviews until a current fix or reasoned dismissal is confirmed by a reviewer. The native reviewer records its own structured verdict with `pipeline_checkpoint(action="review")`; nested work items use `spec`/`quality`, while run-level review uses `technical`/`product`. High-risk work needs host proof of the reviewer and verdict authorship; actor names, worker receipts alone and self-reported models do not prove it. Rerun checks after affected changes. Review-only requests produce findings, not unsolicited edits or MR comments.
+8. `pipeline_verify(kind="review")` cannot satisfy a review gate and is rejected before command execution. Use the `requiredReview` returned by `pipeline_next`, then record a structured review on the reserved attempt. Stop after ten repair/check attempts per work item or three repeated outcomes without progress. Preserve budgets and blocked/paused states across resume. User interruption always wins over continuation hooks.
 9. Native tool enforcement and automatic continuation depend on observed host capability. If unavailable, use sequential execution and state that limitation. Never claim independent review without an independent reviewer.
 10. Keep prose short and clear, reuse existing code, and load only current-step references. Strong caveman style is opt-in. Publishing, merging and external communication require authorization for those actions.
 

package/src/templates/mcp-tools.md

@@ -4,17 +4,19 @@
 
 For Figma and Stitch tool names and authentication, read `docs/agents/design-config.md` when working on design tasks.
 
-- Bootstrap: `session_bootstrap(sessionId, contextEpoch, host, capabilities)` identifies this context and reports resumable work. Pass native model capability and account scope only when the host supplies them.
+- Bootstrap: `session_bootstrap(sessionId, contextEpoch, host, capabilities)` identifies this context and reports resumable work. When the native tool schema is visible, describe `capabilities.nativeDispatch` with its tool, selection mode, model/effort field names, fork modes and requestable model IDs. This coordinator declaration permits a request, but is not a host-observed model receipt. An absent capability field means unknown, not a permanent denial.
 - Route: `route_request(sessionId, requestId, prompt, target, stack, explicitSkills)` returns the workflow, specialist, review roles, platform verification requirements and phase-specific skills. Load current-step skills with `skill_load` and agent/workflow content with `context_load` for each new worker or context epoch.
-- Models: `model_list(sessionId, offset, limit, query)` reports inventory source, account scope, coverage and eligibility. CLI metadata is reference only. Use the model decision from `pipeline_next`; compare requested and host-observed model receipts after dispatch.
+- Models: `model_list(sessionId, offset, limit, query)` reports advertised, requestable and eligible models with source, account scope and coverage. CLI and Codex local cache entries are reference only. Use the pinned `nativeDispatch` from `pipeline_next`; compare its selector with the actual spawn arguments, then keep the host-reported worker model separate. An `inherit` selector or a model chosen in the IDE does not confirm a child model.
 - Start: `pipeline_start(pipeline, task, workspace, acceptanceCriteria, scope, qualityPlan, productImpact, sessionId)` creates a versioned run. Bootstrap the session in the intended workspace first. `workspace` is a schema-valid object, such as `{mode:"current",confirmed:true}`; a string or an unbound global server cannot create a run. On Antigravity, use the workspace MCP alias. New executable runs require at least one acceptance criterion string that exactly matches `qualityPlan.criteria[].expectedOutcome`. The plan uses `criteria: [{id, expectedOutcome, source, checkIds}]`, `checks: [{id, criterionIds, format, testIds, required}]`, and `reviews: [{id, required}]`. A recent user-facing web or mobile route requires its platform check and Product review. Use `pipeline_use(task, runId)` to resume the same run.
-- Execute: `pipeline_next(task, runId, sessionId, role, requestId)` reserves an attempt. Include its APT attempt markers in the native worker brief. Native host agents perform the work; the coordinator controls transitions and continues through ready parts of an approved feature without asking for approval after each internal step. Resource and quota waits remain resumable.
-- Verify: `pipeline_verify` records authorized argv execution under the run workspace. For functional acceptance, pass `checkId`, supported `reportFormat` and named test IDs in the pinned plan. Zero, skipped or unreadable tests and unrelated successful commands remain unverified. `pipeline_checkpoint` records the latest review verdict per stage and persistent finding IDs through `action=review`; resolution needs current evidence and later reviewer confirmation. A direct start without a bound route needs Technical `impactAssessment` before acceptance. User-flow impact requires Product review and platform checks. Missing required platform checks leave the run unaccepted.
+- Execute: `pipeline_next(task, runId, sessionId, role, requestId)` reserves an attempt. Pass its exact `nativeTaskName`, model/tier, reasoning effort and fork mode to the native tool where that tool supports them. Codex model overrides require `fork_turns:"none"`; put `APT_ATTEMPT_ID`, `APT_ACTOR_ID` and `APT_SESSION_ID` in the fresh worker brief. A `followup_task` keeps the existing worker's model; dispatch a new worker when a new model is required. The coordinator controls transitions. Resource and quota waits remain resumable.
+- Verify: `pipeline_verify` records authorized argv execution under the run workspace. For functional acceptance, pass `checkId`, supported `reportFormat` and named test IDs in the pinned plan. Zero, skipped or unreadable tests and unrelated successful commands remain unverified. `pipeline_verify(kind="review")` is rejected before running a command. Read `pipeline_next.requiredReview`: nested work items require `spec`/`quality`, while run-level gates require `technical`/`product`. The reserved reviewer records its own structured verdict with `pipeline_checkpoint(action="review")`; resolution of a persistent finding needs current evidence and later reviewer confirmation. A direct start without a bound route needs Technical `impactAssessment` before acceptance. User-flow impact requires Product review and platform checks. Missing required platform checks leave the run unaccepted.
 - Inspect: `pipeline_status` reports current criterion/check status, open findings, reviewer provenance and pending creation intents without binding sessions. `pipeline_reset(task, runId, sessionId, confirm:true, target:"creation")` abandons a matching unfinished intent while preserving its file. The default `target:"run"` cancels a run without deleting history. `pipeline_prepare_merge` only prepares a report.
 - Read-only questions, review and existing test execution do not require a mutation pipeline. Scope-limited changes use the short pipeline; increased risk adds required checks.
 - MCP gates cover proxied calls. Native tool gates and continuation require observed host hooks. Plan Mode and user interruption take precedence.
 - Codegraph failures permit file-search fallback. The proxy refreshes the review graph before impact analysis; it must report failure rather than use stale results.
-- `mcp_agent_health` reports process, initialization and functional readiness separately. `npx apt-mcp-agent-setup doctor` performs read-only configuration inspection.
+- `mcp_agent_health` reports process, initialization and functional readiness separately. `npx apt-mcp-agent-setup doctor` performs read-only configuration inspection.
+- Backend catalogs are available without starting child processes. A tool call starts only its target backend. Pass `backend` to `mcp_agent_health` when a live probe is required.
+- Use `npx apt-mcp-agent-setup mcp registrations --json` to inspect workspace aliases and `mcp cleanup --dry-run` before reviewing legacy validation aliases. Cleanup requires a reviewed plan and preserves a backup.
 - Browser work uses the lazy `browser-local` backend when the preset has it. Pass `aptTask` and `aptWorker` on browser calls. Use snapshot and console evidence. A page load or screenshot alone is not a feature check. After an uncertain browser action, inspect state before retrying and never replay a side-effecting call automatically.
 - `presentation_prepare` returns pinned PPT Master commands for the document-artifact pipeline. It does not execute commands or overwrite a source deck. Preserve unselected slides and report `visual-unverified` when no renderer and visual review are available.
 - `aso_import` reads workspace-relative CSV/XLSX exports. Preserve nulls and source metadata. It is export intake, not a live Sensor Tower connection; do not call unregistered market-data tool names.