fix(agent): rewrite deprecated VSCode tool names at Copilot deploy time (#2465)

[Sergio Sisternes (sergio-sisternes-epam)]

fix(agent): rewrite deprecated VSCode tool names at Copilot deploy time (#2465)

TL;DR

apm install --target copilot now silently rewrites the six built-in tool names
that VSCode Copilot renamed to a namespaced format (e.g. askQuestions →
vscode/askQuestions) when deploying *.agent.md files. Packages that still use
the old names stop producing "Tool or toolset has been renamed" IDE warnings
without any changes to their source files.

Note

Closes #2465. Source package files are never modified — the rewrite is applied
only to the deployed copy under .github/agents/.

Problem (WHY)

• apm install --target copilot calls copy_agent() for the github_agent
  format, which is a verbatim copy with link resolution and no frontmatter
  transform. Packages that ship tools: [askQuestions, runInTerminal, fetch, ...]
  deploy those old names to .github/agents/<name>.agent.md unchanged.
• VSCode Copilot migrated to namespaced built-in tool identifiers. The IDE
  reads the tools: frontmatter of every agent file in .github/agents/ and
  flags any entry it no longer recognises with "Tool or toolset has been renamed",
  breaking the perceived quality of generated files immediately after install.
• [!] The six renamed tools cover the most common capability restrictions authors
  use (terminal access, file creation, web fetch, directory listing). Any package
  that restricts scope to those tools is visibly broken on first open.

Why these matter: APM's Portability by manifest principle requires that a
single apm.yml produces correct output across targets. A deploy step that emits
stale identifiers violates the install-quality promise — the user sees warnings in
files APM just wrote.

Approach (WHAT)

#	Fix
1	Add GITHUB_AGENT_TOOL_RENAMES dict — six old → new pairs — as a module-level constant next to KIRO_AGENT_ALLOWED_TOOLS
2	Add _apply_github_agent_tool_renames(content: str) -> str static method — parses frontmatter, renames matching tools: list entries, returns content unchanged on any edge case (no frontmatter, unparseable YAML, no tools key, non-list value)
3	Add _copy_github_agent(source, target) instance method — like copy_agent but calls the rename transform before link resolution
4	Wire a new elif mapping.format_id == "github_agent" branch in integrate_agents_for_target to call _copy_github_agent
5	Fix the deprecated integrate_package_agents copilot path to call _copy_github_agent for consistency

Implementation (HOW)

• src/apm_cli/integration/agent_integrator.py — adds the rename constant,
  transform static method, and _copy_github_agent wrapper. The
  integrate_agents_for_target dispatch block gains one elif before the
  existing else branch; all other format IDs (kiro_agent, codex_agent,
  opencode_agent) are untouched. The deprecated integrate_package_agents
  copilot write call is updated to _copy_github_agent for parity.
• tests/unit/integration/test_agent_integrator.py — new
  TestGithubAgentToolRenames class with 12 tests covering the static helper
  (all six renames, unknown names, edge cases) and both integration paths.
• docs/src/content/docs/producer/author-primitives/instructions-and-agents.md —
  updates the copilot row in the transform table from "verbatim" to the actual
  behaviour; adds a "Common pitfalls" entry pointing authors toward the new
  namespaced names.

Diagrams

Legend: the new _apply_github_agent_tool_renames step (dashed) is inserted between
reading the source and resolving links; all other stages are unchanged.

flowchart LR
    subgraph Source[Package source]
        A["tools: [askQuestions, ...]"]
    end
    subgraph Deploy["Deploy -- github_agent"]
        B["_apply_github_agent_tool_renames()"]:::new
        C["resolve_links()"]
        D["write_text_lf()"]
    end
    subgraph Output[".github/agents/"]
        E["tools: [vscode/askQuestions, ...]"]
    end
    A --> B --> C --> D --> E
    classDef new stroke-dasharray: 5 5;
    class B new;

Loading

Trade-offs

• Deploy-time rewrite, not source-file update. The transform runs on the
  deployed copy only. Authors are not forced to update their package sources, and
  the source file remains the single source of truth. The downside: the adoption
  comparison (which compares source bytes against the deployed file) will never
  find a match for files that needed renaming — each reinstall rewrites the file.
  This is harmless because the file is in managed_files and the overwrite is
  idempotent.
• YAML roundtrip on tools key only. Using load_yaml_str / yaml_to_str for
  the frontmatter may change whitespace or key ordering from the original source.
  An early-return guard (if renamed == [str(t) for t in tools_raw]: return content)
  avoids any roundtrip when no names match, keeping zero-rename files byte-for-byte
  identical to today.
• Non-list tools: values are left unchanged. A string, dict, or null value
  passes through verbatim. This is consistent with how kiro_agent handles
  unexpected shapes and avoids a lossy transformation in ambiguous cases.

Benefits

1. Zero "Tool or toolset has been renamed" warnings immediately after
   apm install --target copilot — no package source changes needed.
2. Backwards-compatible: packages using already-namespaced names (vscode/askQuestions)
   are returned verbatim (the rename map only covers old → new, not new → new).
3. Isolated to the github_agent format path — kiro, codex, opencode, claude, and
   cursor paths are untouched.
4. 12 new regression tests; 81 total in the file, all green.

Validation

uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/
All checks passed!
1608 files already formatted

uv run --extra dev python -m pylint --disable=all --enable=R0801 \
  --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

bash scripts/lint-auth-signals.sh
[+] auth-signal lint clean

pytest tests/unit/integration/test_agent_integrator.py (81 passed)

============================= test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.0.3, pluggy-1.6.0
configfile: pyproject.toml
collected 81 items

tests/unit/integration/test_agent_integrator.py ........................
.........................................................

============================== 81 passed in 0.43s ==============================

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	Run apm install --target copilot with an agent that has old tool names — deployed file uses namespaced names, no IDE warnings	Portability by manifest, DevX	tests/unit/integration/test_agent_integrator.py::TestGithubAgentToolRenames::test_integrate_copilot_target_rewrites_deprecated_tool_names (regression-trap for #2465) tests/unit/integration/test_agent_integrator.py::TestGithubAgentToolRenames::test_all_six_renames_via_full_integration_path	integration
2	All six deprecated names (askQuestions, runInTerminal, getTerminalOutput, createFile, fetch, listDirectory) are renamed	Portability by manifest	tests/unit/integration/test_agent_integrator.py::TestGithubAgentToolRenames::test_all_six_known_renames_are_applied	unit
3	Agents with no tools: key, null tools, or already-namespaced names are deployed byte-for-byte unchanged	DevX, Portability by manifest	test_no_tools_key_returns_content_unchanged test_null_tools_returns_content_unchanged test_already_namespaced_names_pass_through_unchanged	unit
4	Deprecated integrate_package_agents path (legacy callers) also rewrites tool names	DevX	tests/unit/integration/test_agent_integrator.py::TestGithubAgentToolRenames::test_integrate_package_agents_deprecated_path_rewrites_tool_names	integration

How to test

• uv run --extra dev pytest tests/unit/integration/test_agent_integrator.py -v → all 81 tests pass.
• Create an agent file with tools: [askQuestions, runInTerminal, fetch] in a test package; run apm install --target copilot → inspect .github/agents/<name>.agent.md — the deployed file should contain vscode/askQuestions, execute/runInTerminal, web/fetch; the source file should be unchanged.
• Open the deployed file in VS Code with GitHub Copilot extension — no "Tool or toolset has been renamed" warnings should appear in the Problems panel.
• Run apm install --target copilot again (reinstall) → no collision error; the file is rewritten idempotently.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

apm-spec-waiver: deploy-time compat shim -- renames deprecated VSCode built-in tool identifiers to current namespaced form; no new normative APM behaviour, no spec extension

[Copilot]

Pull request overview

This PR updates the Copilot (github_agent) agent deployment path so that apm install --target copilot rewrites deprecated VS Code Copilot built-in tool names (e.g., askQuestions) to their namespaced equivalents (e.g., vscode/askQuestions) when writing the deployed .github/agents/*.agent.md copy, preventing IDE rename warnings without modifying package sources.

Changes:

• Added a GITHUB_AGENT_TOOL_RENAMES mapping and a frontmatter rewrite helper to rename deprecated tools: entries during github_agent deployment.
• Introduced a dedicated _copy_github_agent() copy path and wired it into both the modern target-driven integration path and the deprecated legacy entry point.
• Added unit + integration regression tests for the rename behavior, and updated docs to reflect the non-verbatim Copilot deploy transform.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/apm_cli/integration/agent_integrator.py	Implements deploy-time YAML frontmatter tool rename transform and routes Copilot deployment through it.
tests/unit/integration/test_agent_integrator.py	Adds coverage ensuring deprecated tool names are rewritten (and non-matching cases remain unchanged).
docs/src/content/docs/producer/author-primitives/instructions-and-agents.md	Documents Copilot deploy-time tool renames and recommends authoring with namespaced tool identifiers.

[Daniel Meppiel (danielmeppiel)]

APM Review Panel: ship_now

Clean community contribution that advances portability-by-manifest with no security concerns; ship with two lightweight follow-ups for diagnostic parity and docs scannability.

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

All nine panelists converged on a positive read of this PR. Supply-chain security found zero concerns -- the transform is a hardcoded, network-free string map with safe YAML parsing and symlink guards already in place. Test-coverage-expert confirmed all behavioral changes carry regression-trap tests (81 passing), flagging only a single non-string-tools-list edge-case branch as untested at nit severity. The python-architect's PA-1 (copy_agent body duplication) and the cli-logging/devx-ux convergence on CL-1/DX-1 (silent rewrite with no diagnostic) are the two substantive themes worth addressing post-merge.

The CL-1/DX-1 convergence is the strongest signal: both the CLI-logging expert and the DevX-UX expert independently flagged that every other agent transform emits at least a verbose-level diagnostic when it mutates content, and this new path does not. That is a pattern break. I side with shipping now because the fail-closed design (unparseable frontmatter passes through unchanged) means the silent path is safe, but a fast follow-up adding a single verbose-level info line per rewritten file is warranted to maintain diagnostic consistency. PA-1 (refactoring copy_agent to accept a pre_transform hook) is architecturally correct but not urgent -- the duplication surface is small and the risk of a missed security check is theoretical today.

From a positioning standpoint, the oss-growth-hacker's story angle is right: this is a quiet, high-trust win -- 'apm install --target copilot silently fixes deprecated tool names so your IDE stays warning-free.' The CHANGELOG entry should lead with the user-facing benefit, not the internal refactor. The doc-writer's DW-2 (listing old names alongside new in the pitfall entry) is a genuine discoverability improvement that costs one sentence. This is a community PR from sergio-sisternes-epam; merging promptly with clear follow-up issues reinforces contributor trust.

Aligned with: Portability by manifest (the transform ensures agent files authored with old VSCode tool names deploy correctly to GitHub Copilot targets without manual editing); DevX (fail-closed design is correct -- follow-up diagnostic restores consistency).

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	1	2	Well-scoped, idiomatic addition that follows existing AgentIntegrator patterns; no architectural faults.
CLI Logging Expert	0	1	1	Silent rename is defensible but a verbose-only diagnostic would align with how every other agent transform communicates mutations.
DevX UX Expert	0	1	2	Silent rewrite is the right default but a single info line per affected file would help users understand why deployed output differs from source.
Supply Chain Security Expert	0	0	0	No supply-chain security concerns: hardcoded network-free string mapping with safe YAML parsing and symlink guards.
OSS Growth Hacker	0	0	2	Clean DX friction removal; docs update solid but CHANGELOG entry and release narrative could mine portability-by-manifest story harder.
Doc Writer	0	2	2	Documentation changes are accurate and well-placed; table cell is verbose, pitfall omits old names that would help authors recognise the issue.
Test Coverage Expert	0	0	1	All behavioral changes have targeted regression-trap tests; one minor edge-case branch (non-string tool entries) lacks a dedicated test.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 4 follow-ups

1. [CLI Logging Expert + DevX UX Expert] Add verbose-level diagnostic when tool names are rewritten -- Two independent panelists converged: every other agent transform emits feedback on mutation. Diagnostic parity prevents user confusion when deployed output differs from source.
2. [Doc Writer] List old tool names alongside new names in the pitfall entry -- A reader debugging existing source with deprecated names cannot confirm which are rewritten without cross-referencing code. One sentence fix.
3. [Python Architect] Refactor copy_agent to accept optional pre_transform to eliminate _copy_github_agent body duplication -- If copy_agent gains a security check later, _copy_github_agent silently misses it. Low urgency but architecturally correct.
4. [OSS Growth Hacker] Ensure CHANGELOG entry frames this as user-facing benefit, not internal refactor -- Reinforces portability-by-manifest positioning in the release narrative.

Architecture

classDiagram
    direction LR
    class BaseIntegrator {
        <<Abstract>>
        +find_files_by_glob()
        +check_collision()
        +sync_remove_files()
    }
    class AgentIntegrator {
        <<ConcreteIntegrator>>
        +integrate_agents_for_target()
        +integrate_package_agents()
        +copy_agent(source, target) int
        +_copy_github_agent(source, target) int
        +_apply_github_agent_tool_renames(content) str
        +_write_codex_agent(source, target)
        +_warn_opencode_frontmatter()
        +_validate_kiro_tools()
        -_FRONTMATTER_RE Pattern
    }
    class GITHUB_AGENT_TOOL_RENAMES {
        <<Constant>>
        +dict 6 entries
    }
    class IntegrationResult {
        <<ValueObject>>
        +files_integrated int
        +files_skipped int
        +links_resolved int
    }
    BaseIntegrator <|-- AgentIntegrator
    AgentIntegrator ..> IntegrationResult : returns
    AgentIntegrator ..> GITHUB_AGENT_TOOL_RENAMES : reads
    class AgentIntegrator:::touched
    class GITHUB_AGENT_TOOL_RENAMES:::touched
    classDef touched fill:#fff3b0,stroke:#d47600

Loading

flowchart TD
    A["apm install / integrate_agents_for_target"] --> B{"mapping.format_id?"}
    B -->|kiro_agent| C["_validate_kiro_tools"]
    C --> D["copy_agent"]
    B -->|codex_agent| E["_write_codex_agent MD-to-TOML transform"]
    B -->|github_agent| F["_copy_github_agent"]
    F --> G["_apply_github_agent_tool_renames YAML roundtrip on frontmatter tools"]
    G --> H["resolve_links"]
    H --> I["write_text_lf"]
    B -->|opencode_agent| J["_warn_opencode_frontmatter"]
    J --> D
    B -->|else| D
    D --> K["resolve_links"]
    K --> L["write_text_lf"]
    style F fill:#fff3b0,stroke:#d47600
    style G fill:#fff3b0,stroke:#d47600

Loading

Recommendation

All panelists aligned, no blocking findings, no security concerns, full test coverage on behavioral changes, and CI green. Community contributor PR -- merge promptly and file follow-up issues for diagnostic parity (FU-1) and docs old-name listing (FU-2).

---

Full per-persona findings

Python Architect

• [recommended] _copy_github_agent duplicates copy_agent body instead of composing it. If copy_agent ever gains a security check (e.g. file-size limit), _copy_github_agent silently misses it.
  Suggested: Refactor copy_agent to accept optional pre_transform: Callable[[str], str] | None = None parameter applied between read and resolve_links.
• [nit] GITHUB_AGENT_TOOL_RENAMES should be immutable (MappingProxyType) -- KIRO_AGENT_ALLOWED_TOOLS is a frozenset; consistency suggests wrapping with MappingProxyType.
• [nit] Legacy integrate_package_agents path parity -- both modern and deprecated paths confirmed to call _copy_github_agent. Good.

CLI Logging Expert

• [recommended] Emit a verbose-level diagnostic when tool names are rewritten -- every other agent transform emits a diagnostic on mutation. Breaking the pattern.
  Suggested: In _copy_github_agent, after rename, emit diagnostics.info naming file and count of renames (shown only in --verbose).
• [nit] _copy_github_agent lacks diagnostics and package_name parameters -- unlike every other per-format helper.

DevX UX Expert

• [recommended] Silent tool rename leaves users confused when source != deployed -- no progress/info message emitted when deprecated names are rewritten. Every other install transform emits at least one info line.
  Suggested: Emit a single _rich_info per file when content changed.
• [nit] Docs table Transform cell is verbose (12 words where others are 1-4).
• [nit] The fetch -> web/fetch rename is an exact match on a common word; docs should note this is exact-match only.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

• [nit] Docs pitfall entry buries user-facing benefit under implementation detail -- lead with 'APM handles this for you'.
• [nit] Deploy-target table update accurate but misses story beat -- shorten for scannability.

Auth Expert -- inactive

PR touches agent_integrator.py for deploy-time YAML tool-name rewriting; no auth surfaces changed.

Doc Writer

• [recommended] Table cell is verbose and hard to scan (12 words in a Transform column where all others are 1-4 words).
  Suggested: Shorten to 'tool names rewritten; otherwise verbatim'.
• [recommended] Pitfall entry lists new names but not old names -- a reader debugging existing source cannot confirm which old names are rewritten without cross-referencing code.
  Suggested: Add parenthetical '(askQuestions, runInTerminal, getTerminalOutput, createFile, fetch, listDirectory)' after 'the six known old names'.
• [nit] Pitfall bold label is slightly awkward ('Old unnamespaced VSCode built-in') -- shorten to 'Deprecated VSCode built-in tool names'.
• [nit] Source attribution could add constant name for discoverability (GITHUB_AGENT_TOOL_RENAMES).

Test Coverage Expert

• [nit] Non-string tools list entries branch untested -- _apply_github_agent_tool_renames has isinstance(t, str) guard passing non-string entries through unchanged; no dedicated test for mapping or sequence entries.
  Suggested: Add one parametrized test case with a mapping entry in the tools list.

Performance Expert -- inactive

O(n) tools YAML parse per agent file at deploy time with O(1) rename map lookup and early-return guard for zero-match case; not a hot-path change.

_{This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.}

[Daniel Meppiel (danielmeppiel)]

Thank you for the original work on this fix. To land it promptly we have opened a superseding PR (#2519) under microsoft/apm that preserves your authorship via commit trailers and resolves the follow-ups surfaced by the apm-review-panel pass.

Closing this PR in favor of #2519. Your contribution is credited on every cherry-picked commit; the superseding PR's body links back here. Please do raise concerns on the superseding PR if the changes diverge from your intent -- we want your sign-off too.

[Daniel Meppiel (danielmeppiel)]

Closing in favor of superseding PR #2519 which includes the panel follow-ups and merge-queue compatibility fix.