# Plugin-scope agent-author omits `tools:` and all Claude-only fields from `.apm/agents/*.agent.md`

This ADR is a narrower, downstream consequence discovered while designing issue #89's
implementation under ADR-0015's broader direction (Microsoft APM replaces hand-authored
plugin/marketplace authoring). It does not restate ADR-0015's rationale — see that ADR for
the parent decision.

## Context

APM's agent primitive (`.apm/agents/<name>.agent.md`) has no per-target integrator in
`apm compile` — confirmed via APM's own Python source (`integration/targets.py` and related
files, cited in `plugins/kyberforge/docs/research/docs/microsoft-apm/agent-primitive-schema.md`).
Compilation does a naive verbatim copy of the whole frontmatter and body to both the Claude
Code and Copilot CLI targets. This is unlike:

- The **skill** primitive, which is also a straight copy (confirmed in the same research doc)
  but has no field semantics to conflict — `SKILL.md`'s content is target-agnostic already.
- The **prompt**, **instructions**, and **hooks** primitives, which each get real per-target
  reconstruction through a dedicated integrator (field allowlisting, key renaming, dropped-field
  warnings).

Because the agent primitive ships the same frontmatter unchanged to both harnesses, two
concrete incompatibilities surface:

1. **`tools:`** — Claude Code expects a space-separated tool-name string; Copilot CLI expects a
   list drawn from its own alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`). A
   value correct for one harness is wrong for the other.
2. **Claude-only knobs with no Copilot equivalent** — `isolation`, `maxTurns`, `effort`,
   `memory`, `permissionMode`. Writing any of these means Copilot's copy carries frontmatter
   keys it doesn't recognize at all. Whether Copilot's agent loader ignores unknown keys or
   errors on them is unconfirmed by research.

## Decision

At **plugin scope only** (destination package has an `apm.yml` at its root — an APM producer
package compiled via `apm compile`), `.apm/agents/<name>.agent.md` carries only `name`,
`description`, `model`, and the prose body. No `tools:` field, no Claude-only fields, at all.

Absent `tools:` means inherit-all-tools on both harnesses — the one value that is never wrong
on either target, unlike a present, harness-specific value that is guaranteed wrong on at least
one of them.

`agent-audit`, at plugin scope, is intended to flag — as a **SUGGESTION**, not a FAIL, since
this is an upstream schema limitation rather than an authoring mistake — any agent whose
description or body implies a need for tool restriction or a Claude-only behavior the
frontmatter can no longer express. This would give visibility into the gap without pretending
the schema can do something it can't. **Not yet implemented**: `check_apm_agent_file()` in
`validate.sh` currently validates only the field allowlist, `name`, `description`, and
body-emptiness/length — it has no heuristic for this case. Tracked as follow-up work.

### Scope boundary

This decision applies to **plugin-scope `agent-author` only**. Project scope (`.claude/agents/`
+ `.github/agents/`) and user scope (`~/.claude/agents/` + `~/.copilot/agents/`) are not APM
packages — neither goes through `apm compile` — so both keep today's dual-file Claude+Copilot
pair model exactly as ADR-0005 and ADR-0008 already describe. Those two ADRs remain fully
authoritative for project and user scope; only their plugin-scope clauses are affected by this
ADR (see the update notes appended to each).

## Considered options

**Pick one harness's vocabulary and accept breakage on the other (rejected).** E.g. always
write Claude's space-separated `tools:` string. Rejected because it ships a value that is
silently wrong (or possibly a hard error) on Copilot, and which harness "wins" would be an
arbitrary, undocumented asymmetry.

**Same as above, but `agent-audit` flags the cross-harness breakage as a tracked finding
(rejected).** Rejected for the same core reason — it still ships a wrong value to a real
harness. Tracking the breakage doesn't prevent it, and the chosen decision already gets
equivalent visibility (a SUGGESTION finding) without ever shipping the wrong value in the first
place.

## Consequences

- Every plugin-scope APM agent loses per-agent tool restriction and any Claude-only capability
  (isolation, maxTurns, effort, memory, permissionMode) until APM ships a real per-target
  integrator for the agent primitive. This is a known, accepted regression, not an oversight.
- **ADR-0005 is partially superseded** — its plugin-scope clause ("directory containing
  `plugin.json` is plugin scope → both files land in `<root>/agents/`") no longer applies.
  Plugin scope is now "directory containing `apm.yml` → single vendor-neutral file lands in
  `<root>/.apm/agents/`." Project and user scope, and the rest of ADR-0005, are unaffected.
- **ADR-0008 is partially superseded** — its counterpart-derivation/pair-validation mechanism
  no longer applies at plugin scope; `agent-audit` takes the single file directly there. Project
  and user scope, where a real pair still exists, are unaffected.
- **ADR-0009 is not superseded.** The mechanism it established — `agent-audit` reading field
  lists from `references/field-inventory.md` rather than hardcoding them, with a `source_keys`
  provenance chain — survives and is reused. Only the *content shape* changes for plugin scope:
  `field-inventory.md` shifts from two side-by-side CC-only/Copilot-only blocklists to one
  vendor-neutral allowlist (`name`/`description`/`model`/`source_keys` — the last for provenance
  tracking, validated separately by `validate-provenance.sh` against `sources.md`, not a
  provider-specific field) for plugin-scope agents, while
  continuing to serve its original two-blocklist role for project/user-scope validation.