Follow up Amp upstream updates: Plugin API (hooks via .amp/plugins/*.ts)

[dyoshikawa]

Summary

Amp shipped a Plugin API (part of the "Neo" rebuild) that is the event-reaction surface rulesync models as hooks for other tools, but hooks is unsupported for amp. (Amp's rules/mcp/skills/permissions surfaces are current — see #1788 / #1739; this is the remaining gap. Custom commands were intentionally removed upstream and correctly remain unsupported.)

Recent Releases

• "Neo" rebuild incl. Plugin API (2026-05-06): https://ampcode.com/news/neo
• Plugin API reference: https://ampcode.com/manual/plugin-api

Gaps

• hooks — Amp Plugin API unmapped (unsupported). Amp plugins are TypeScript files in .amp/plugins/*.ts (project) and ~/.config/amp/plugins/*.ts (global) that subscribe to lifecycle/hook events via amp.on(...): session.start, tool.call, tool.result, agent.start, agent.end — the same role rulesync's hooks feature fills for other tools (e.g. Claude Code's PreToolUse/PostToolUse). The legacy Toolbox surface (AMP_TOOLBOX, .amp/toolbox) is now deprecated in favor of plugins. rulesync has no src/features/hooks/amp-hooks.ts; amp --features hooks prints "does not support the feature 'hooks'. Skipping."

Proposed Follow-up

• Evaluate a hooks adapter for Amp targeting .amp/plugins/*.ts (project) and ~/.config/amp/plugins/*.ts (global), mapping rulesync hook events onto amp.on(...) (tool.call → pre-tool, tool.result → post-tool, agent.start/agent.end → session lifecycle). Caveat: Amp plugins are arbitrary TypeScript code rather than declarative command/matcher entries, so this is a generation-shape decision (emit a TS plugin wrapper) rather than JSON config — worth a design discussion before implementing.

References

• https://ampcode.com/manual/plugin-api — .amp/plugins/*.ts, amp.on(...) event set, Toolbox deprecation.
• https://ampcode.com/news/neo — Plugin API announcement (2026-05-06).

[dyoshikawa]

Triaged — leaving open pending a maintainer design decision.

Verified (still a real gap). Amp's Plugin API is confirmed current: plugins are TypeScript files in .amp/plugins/*.ts (project) / ~/.config/amp/plugins/*.ts (global) that subscribe via amp.on(event, handler) over session.start, tool.call, tool.result, agent.start, agent.end (https://ampcode.com/manual/plugin-api, https://ampcode.com/news/neo). rulesync has no src/features/hooks/amp-hooks.ts, so amp --features hooks skips.

Why this is not auto-implementable yet — generation-shape decision. Every existing rulesync hooks adapter emits declarative config (event + matcher + shell command, e.g. Claude Code's JSON PreToolUse/PostToolUse). Amp's surface is fundamentally different: plugins are arbitrary, imperative TypeScript code, and request events like tool.call require the handler to return a typed ToolCallResult (allow / reject / modify / synthesize). Mapping rulesync's declarative hook entries onto an emitted .amp/plugins/rulesync.ts wrapper would introduce a brand-new codegen pattern (rulesync emitting executable TS) that no other feature/tool uses.

Decision needed from a maintainer before implementation:

1. Is emitting executable TypeScript (a .amp/plugins/*.ts wrapper that shells out per amp.on event) acceptable as a rulesync output shape, or should Amp hooks stay unsupported until a declarative plugin surface exists?
2. If yes, the event mapping (tool.call→pre-tool, tool.result→post-tool, agent.start/agent.end→session lifecycle) and how to represent ToolCallResult semantics from rulesync's command-only hook model.

Leaving open and labeled for that design discussion rather than forcing an implementation.

[dyoshikawa]

Disposition (2026-06-24): keeping this open as a deliberate tracker per maintainer decision. Amp's hook surface is the Plugin API - arbitrary, imperative TypeScript files in .amp/plugins/*.ts that subscribe via amp.on(event, handler) and return typed ToolCallResult values. Every existing rulesync hooks adapter emits declarative config (event + matcher + shell command); emitting executable TypeScript would introduce a brand-new codegen pattern no other feature/tool uses, which does not fit rulesync's declarative model. Leaving Amp hooks unsupported and tracked here until a declarative plugin surface exists.

[dyoshikawa]

Upstream update (re-check on 2026-06-25)

Newly found releases / changes

Two additional Amp surfaces surfaced in this re-check that aren't covered by this issue (which tracks the Plugin API / hooks) or by #1739 / #1788:

• Code Review Checks — a declarative, file-based surface: markdown files with frontmatter (name, description, severity-default, tools) in .agents/checks/ (project) or ~/.config/amp/checks/ (global); each check spawns a review subagent. Source: https://ampcode.com/manual ("Checks"), https://ampcode.com/news/liberating-code-review. This is structurally similar to rules/skills (markdown + frontmatter, project/global scope) but maps to no existing rulesync feature dimension — flag for product consideration rather than an immediate adapter.
• amp.skills.path config key — a colon/semicolon-separated list that relocates skill roots. amp-skill.ts hardcodes .agents/skills/ (project) and .config/agents/skills/ (global) and does not honor amp.skills.path, so import/export against a customized root would miss skills. Source: https://ampcode.com/manual ("Skills"). Low priority (default paths are correct).

Additional or changed gaps

• amp.mcpPermissions was the subject of Follow up Amp upstream updates: native Agent Skills, skill-bundled MCP mcp.json, and amp.mcpPermissions #1739 (closed) — re-confirmed still documented at https://ampcode.com/manual; no change.
• The Plugin-API hooks gap tracked here remains accurate: commands/subagents/hooks are now expressed exclusively as executable TypeScript plugin code (.amp/plugins/*.ts), with the legacy markdown custom-commands surface removed on 2026-01-29 (https://ampcode.com/news/slashing-custom-commands). rulesync already covers the skills replacement.

References

• https://ampcode.com/manual — Checks, amp.skills.path, amp.mcpPermissions (current manual).
• https://ampcode.com/news/liberating-code-review — Code Review Checks (.agents/checks/).
• https://ampcode.com/news/slashing-custom-commands — markdown custom commands removed (2026-01-29).

[dyoshikawa]

Processed in a batch autonomous pass — one factual correction to the recorded disposition, which may change the calculus:

The 2026-06-24 disposition defers this because "emitting executable TypeScript would introduce a brand-new codegen pattern no other feature/tool uses." That premise is inaccurate: rulesync already emits executable JavaScript plugins for hooks — the OpenCode and Kilo hooks adapters generate .opencode/plugins/rulesync-hooks.js / .kilo/plugins/rulesync-hooks.js via src/features/hooks/opencode-style-generator.ts, wrapping each declarative hook entry (event + matcher + shell command) in generated plugin code with escaped command/matcher embedding. So the codegen pattern exists and is battle-tested; an Amp adapter would be a TypeScript-flavored sibling of that generator, not a new precedent.

What still genuinely needs a design call before implementation (hence leaving this open rather than resolving it autonomously):

1. Request-event semantics. Amp's tool.call handler returns a typed ToolCallResult (allow / reject / modify / synthesize). rulesync's command-only hook model would need a convention — e.g. exit code 0 → allow, non-zero → reject with stderr as the message (mirroring Claude Code's exit-code-2 convention) — and events where that mapping is too lossy could be limited to fire-and-forget observation (tool.result, session.start, agent.start/agent.end).
2. Event mapping: preToolUse → tool.call (with the matcher tested against the tool name), postToolUse → tool.result, sessionStart → session.start, subagentStart/subagentStop → agent.start/agent.end.
3. Scopes: .amp/plugins/rulesync-hooks.ts (project) and ~/.config/amp/plugins/rulesync-hooks.ts (global), isDeletable like the opencode/kilo plugin outputs.

If the opencode/kilo precedent settles question 1's acceptability, this becomes an implementable follow-up in a future pass.

[dyoshikawa]

Re-validated in a batch autonomous pass (2026-07-16). Status update:

• The Code Review Checks side-surface flagged in the 2026-06-25 re-check comment is now shipped: PR feat: support Amp code review checks (.agents/checks/*.md) #2295 added a first-class checks feature emitting .agents/checks/*.md (project) and ~/.config/amp/checks/*.md (global), closing Follow up Amp upstream updates: code review checks (.agents/checks/*.md) #2206.
• The Plugin-API hooks gap tracked here is unchanged, and the recorded disposition stands: the opencode/kilo precedent (src/features/hooks/opencode-style-generator.ts emitting executable JS plugins) settles the codegen-shape concern, but the remaining design call — whether the exit-code convention (0 → allow, non-zero → reject with stderr) is an acceptable mapping for Amp's typed ToolCallResult on tool.call, or whether request events should be observation-only — is a maintainer decision this autonomous pass does not make. Leaving open for that call; once decided, the implementation is a TypeScript-flavored sibling of the opencode/kilo generator.