Host support: Amp — native plugin factory, explicit skill registration, and skill-scoped MCP

[ScriptedAlchemy]

Current disposition — native adapter still required

P2 feature expansion. Reconciled against main b5cf7575e0bcfa6da23e12d2c5628146bdbe5cb1 after #721, #723 and #727. Those PRs deliver portable-client compatibility records, not an Amp adapter. #723 deliberately removed Amp from that table because the owner scoped this issue to a native implementation. Do not add a none-tier Amp record and mark this delivered.

The original research was documentation-only. Subsequent non-account CLI/type validation is recorded in the pinned-contract evidence. It used @ampcode/cli@0.0.1788739286-gf348fe and @ampcode/plugin@0.0.0-20260907001852-gf348fed. This reconciliation reviewed code, discussion and official documentation; it did not rerun those probes.

Owner's verification decision: no Amp account is available. Authenticated model/session execution remains unverified, not unsupported and not a mandatory prerequisite to delivering the documented/type-checked adapter. Do not invent authentication success, a standalone plugin validator, or a completed native tool journey.

Authoritative references

• Plugin loading and native factories
• Generated PluginAPI
• Skills, discovery and MCP-in-skill
• MCP settings and authorization
• AGENTS.md
• CLI configuration
• Detailed subsequent implementation notes

Keep the exact native package versions/revisions associated with each assertion. Live documentation is a source to verify, not an unversioned compatibility guarantee.

Already established; do not repeat as pending research

• Directory plugins expose index.js/index.ts with a default factory receiving PluginAPI; optional description is a bounded static string. Helpers must not become additional public entries.
• Project and user plugin locations and project/system/personal/workspace precedence are documented. User paths must honor the configured XDG location, not only a hard-coded home path.
• Each bundled skill requires explicit registerSkill with a plugin-relative directory and matching frontmatter/directory name. A standalone skills installation is a different, smaller distribution path.
• Skill MCP uses a flat server map, not an mcpServers wrapper. Frontmatter wins over a sibling mcp.json; direct/CLI configuration can override a same-named skill server.
• Pinned type validation covered native callback result unions. The recorded Symbol.observable declaration/skipLibCheck caveat and named-handler inference constraint must remain visible in the test evidence.

Correction to the later discussion

The later shorthand that servers load only while a skill is active is too strong. The official skills documentation, rechecked during reconciliation, says MCP connections are established during skill discovery; activation controls visibility of skill-only tools. Do not promise lazy server-process creation from hidden tools. Preserve the original research's distinction and test actual process lifetime when an authenticated environment is available.

Likewise, a data-only registration entry may be emitted without bundling native Amp packages, but that does not exempt authored executable handlers or shared runtime code from the existing compiler/evidence policy. @ampcode/plugin is a types-only dependency in the recorded factory shape; the host supplies the API argument. Do not weaken standalone self-containment or build a second compiler.

Remaining implementation

• Add the scoped native adapter/capability record and registry wiring using existing application/projection/artifact contracts.
• Emit one exact native entry with explicit registration for each selected skill. Keep shared authored content once in the composite where the host contract permits it.
• Define the actual emitted package root and native placement consistently; do not leave an unexplained nested amp-plugin/ copy or derive paths from the caller's cwd.
• Lower canonical events to supported native callbacks/results. Preserve the distinction between observation, permission, input transformation, synthesized output and requesting another agent turn. A framework no-op must not become automatic permission or continuation.
• Emit only intentionally bound skill-scoped MCP servers with the native flat shape and documented precedence. Do not register every application server on every skill implicitly.
• Preserve native trust, disabled state, existing settings and owned-file replacement/removal. No automatic publication of personal/workspace repositories.
• Distinguish unsupported native events from unverified live execution; do not invent session.end semantics or treat process shutdown as a native event.
• Keep standalone content-only usage free of unnecessary workers, Flight/state machinery and fake MCP services.

Acceptance and closure

Use the pinned real PluginAPI for generated-entry type tests, the existing compiler/manifest/evidence tests, and deterministic contract fixtures for callback outputs, registered paths, precedence, cancellation and cleanup. An unrelated helper entry must not run; each intended registration occurs once. Test relocation and selected/unselected components without broadening AB4106 globally.

Report separately: documentation evidence, type/fixture proof, non-account CLI operations actually executed, and authenticated cases not executed. Honor the accepted no-account limitation; do not leave the implementation indefinitely blocked on credentials or call a fake-host test native execution.

Update English/Chinese setup and reference output from the existing shared metadata paths. Reuse #651/#652 conformance rather than another client catalog. Local CLI, hosted settings and Orbs have different authorities; do not claim uniform filesystem access.

Non-goals

No agent loop, provider/model management, cloud deployment service, domain database, account provisioning, automatic approval, broad self-containment exception, or reimplementation of the already-landed portable-client records.

[ScriptedAlchemy]

Owner decision recorded: no Amp account, so live model/session execution is unverified, not unsupported. The native contract is now pinned from official sources, and the non-account validation the decision authorizes has been run.

Pinned contract (2026-09-07)

Plugin shape — https://ampcode.com/docs/customize/plugins:

• "A single-file plugin is a .ts or .js file directly inside a plugin location. A directory plugin uses <name>/index.ts or <name>/index.js. If both entry files exist, Amp uses index.ts."
• "Every plugin entry file exports a default function. Amp passes a PluginAPI object to that function."
• Locations and precedence: .amp/plugins/ (project), $XDG_CONFIG_HOME/amp/plugins/ or ~/.config/amp/plugins/ (system), then personal and workspace repositories; "the precedence order is project, system, personal, then workspace".
• Skills: "Amp does not scan the skills/ directory automatically, so the plugin must register each skill when it loads", with await amp.registerSkill({ path: 'skills/<name>' }); "The path is relative to the plugin directory and must name a directory that contains SKILL.md. The skill's frontmatter name must match its directory name", listed as <plugin>:<skill>. "Single-file plugins cannot register skills."
• description named export: "must be a static string literal of at most 300 characters" (@ampcode/plugin doc comment).

Skill-scoped MCP — https://ampcode.com/docs/customize/skills:

• "A skill can define MCP servers in a sibling mcp.json file or in the mcpServers field of its SKILL.md frontmatter. If both are present, Amp uses mcpServers and ignores mcp.json."
• The document is a flat map of server name to config, not an mcpServers wrapper: local command, args?, env?; remote url, headers?; common includeTools?.
• "Amp hides tools from a server defined only by a skill until the skill is loaded. If a server with the same name is also supplied by a CLI flag or direct configuration, that source takes precedence."

Events — @ampcode/plugin@0.0.0-20260907001852-gf348fed PluginEventMap: session.start (fire-and-forget), and the request events tool.call, tool.result, agent.start, agent.end. ToolCallResult is allow | reject-and-continue{message} | modify{input} | synthesize{result:{output,exitCode?}} | error{message}; ToolResultResult is a done | error | cancelled status with optional output/error, or void; AgentEndResult is { action: 'continue', userMessage } or void.

Non-account validation run

• @ampcode/cli@0.0.1788739286-gf348fe and @ampcode/plugin@0.0.0-20260907001852-gf348fed installed into a disposable consumer; the native binary was completed with the package's own install.cjs.
• amp --help, amp plugins --help, amp skill add --help — first-party, no auth. skill add documents its source as "owner/repo[/path], Git URL, or local path", with --global installing to ~/.config/agents/skills/.
• amp plugins list → Error: failed to load global plugins. Unable to connect to https://ampcode.com/.; amp skills list --json and amp skill add ./skills/review → No API key found. Starting login flow.... Account-dependent, therefore unverified.
• A generated-shape entry (export const description, default async function (amp: PluginAPI), registerSkill, and amp.on handlers returning allow/reject-and-continue/modify/synthesize plus the tool.result status mapping) typechecks clean against the pinned PluginAPI with strict: true.
• Two constraints found by that typecheck, both load-bearing for the generator:
  1. The pinned index.d.ts references Symbol.observable, which no TypeScript lib declares, so the entry is typechecked with skipLibCheck: true (or the symbol is declared).
  2. A handler extracted into a named helper typed with PluginEventContext<'tool.call'> breaks amp.on's inference (TS2345); handlers must be registered inline or typed through PluginEventMap.
• plugins: reload and plugins: list are interactive command-palette actions and no standalone plugin validator exists, so none is invented.

Scope change for the records PR

#711 is a native-adapter issue, so the Amp row has been removed from the portable client table in #723 (portable-client-records-b, 9f38233d97): recording Amp as a none-tier reader of the emitted artifact would contradict this decision. The adapter implementation — an amp target, an index.js entry exporting only default and description, registerSkill per emitted skill, event registration mapped to the result unions above, skill-scoped mcp.json in Amp's flat shape with its documented precedence, and capability rows marking live execution unverified — is the remaining work and is tracked here.

[ScriptedAlchemy]

Pinned native contract, and what remains to build

The non-account validation described in the previous comment settles the contract
this adapter must emit. Recording it here so the implementation is a mechanical
step and nothing about it is inferred later:

Entry. One index.js at the plugin root, default-exporting an async
function of the PluginAPI value Amp passes in, plus an optional
description string export. No other export is read, so helpers stay private.
The entry imports nothing at run time — @ampcode/plugin is a types-only
package and the API arrives as an argument — so the emitted entry is
self-contained by construction and needs no compilation step or externals.

Skills. Nothing is discovered: each skill is registered explicitly with
await amp.registerSkill({ path: 'skills/<name>' }), relative to the plugin
root, and the SKILL.md frontmatter name must equal the directory name.

Skill-scoped MCP. skills/<name>/mcp.json is a flat server map (no
mcpServers wrapper): { "<server>": { "command", "args", "env" } | { "url", "headers" } }, with optional includeTools. Servers load only while that skill
is active, and a server of the same name from the user's own Amp config wins.

Events. amp.on('<event>', handler) with inline handlers; the callback
result is the projection surface (allow, reject-and-continue, modify,
synthesize for tool.call; an output/status object for tool.result;
continue with a user message for agent.end). Typechecked against the pinned
@ampcode/plugin types; a handler passed as a named function loses the generic
narrowing, so the emitted handlers must be inline.

Install. The plugin directory is copied to .amp/plugins/<name>/ (project)
or ~/.config/amp/plugins/<name>/ (user) and listed by amp plugins list.

Remaining work is the adapter itself — an amp-<version>.json capability table,
the projection that emits the entry, the registered skill tree, and the
skill-scoped MCP documents, registry wiring, discovery/precedence tests, and the
en/zh reference rows. Every row it records is spec- and type-proven by the run
above; live tool-call execution stays recorded as unverified, since it needs an
account this environment does not have.

[ScriptedAlchemy]

Follow-up #740 is merged. Standalone Amp event workers now live beside their generated wrappers inside .amp/plugins/<name>/hooks/; relocation, manifest/compile evidence, receipt-owned install/replace/uninstall, and hostless Workbench lookup are covered by regression tests.

[ScriptedAlchemy]

Optional native Amp qualification (owner can run on macOS/account)

The adapter is merged and spec/type/install-qualified; this checklist records the remaining real-host dogfood without blocking the implementation:

1. Record amp --version, macOS version, and Agent Bundle commit/preview.
2. Build a fixture with one Amp plugin tool, one bundled skill, one tool.call deny/modify path, one tool.result replacement, and one skill-scoped MCP server.
3. Install through Agent Bundle into the project .amp/plugins/<plugin>/; run amp plugins list and amp skills list --json; confirm one plugin entry and one qualified skill.
4. In Amp, run plugins: reload; invoke the tool and record the real allow/deny/modify/result behavior. Activate the skill and confirm only its declared MCP tools appear; a same-named direct user MCP server must win.
5. Open two overlapping threads, reload once, and confirm no duplicate registration/resource leak. Uninstall with Agent Bundle and confirm only receipt-owned files disappear.
6. Attach redacted command output/screenshots here, including any discrepancy. Do not grant global permissions or publish personal/workspace repositories for this proof.

Live activation remains unqualified, not unsupported, until this evidence is attached.