feat: add IDE personas for VS Code, Claude Code, and Copilot CLI (v0.2.1)

[sbroenne]

Summary

Introduces a \Persona\ concept that simulates each IDE's native runtime environment during testing, so agents written for a specific IDE behave correctly in the test suite.

Changes

New: \personas.py\

Four built-in personas:

Persona	Auto-loaded file	Polyfilled tools
\VSCodePersona\ (default)	.github/copilot-instructions.md\	\
unSubagent\
\CopilotCLIPersona\	.github/copilot-instructions.md\	none (task+skill native)
\ClaudeCodePersona\	\CLAUDE.md\	\ ask-dispatch
\HeadlessPersona\	nothing	none

Custom instruction files are prepended to the system message automatically when \working_directory\ is set and the file exists.

\rom_copilot_config()\ — recursive agent discovery

Changed \glob\ →
glob\ so agents in \subagents/\ subdirectories (hve-core PR #639 layout) are discovered automatically.

\EventMapper\ — public subagent tracking methods

Added
ecord_subagent_start,
ecord_subagent_complete,
ecord_subagent_failed\ for use by persona tool handlers.

\

unner.py\ — persona delegation
Replaced the hardcoded
unSubagent\ injection block with \�gent.persona.apply(agent, session_config, mapper).

Docs

• New how-to guide: \docs/how-to/ide-personas.md\
• Updated \docs/reference/configuration.md\ (persona field)
• Updated \docs/reference/api.md\ (persona classes)
• Updated \docs/how-to/copilot-config.md\ (recursive discovery, persona link)
• Updated \README.md\

Backward Compatibility

• \VSCodePersona\ is the default — existing tests with \custom_agents\ continue to work unchanged
• Custom instruction loading only fires when \working_directory\ is set and the file exists — no side-effects on existing tests

Version

\

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

In general, to fix this, avoid importing from pytest_codingagents.copilot.personas at module level in agent.py, even under TYPE_CHECKING, and instead use forward references or typing utilities (e.g., typing.TYPE_CHECKING or typing_extensions) that do not require importing the other module. This breaks the cycle at the source while keeping type hints.

The best targeted fix here is to remove the TYPE_CHECKING import of Persona and replace the string-annotated "Persona" hints with either typing.ForwardRef / typing.get_type_hints patterns or, more simply and idiomatically for modern Python, by using from __future__ import annotations (which is already present) and a typing.Protocol or a typing.Any fallback. However, since from __future__ import annotations is already in place, we can safely use the string "Persona" as a forward reference without needing the import at type-check time, and robust type checkers can be configured to resolve it via stub files or by importing personas separately. To stay within the given snippet and not change other files, the minimal fix is:

• Delete the if TYPE_CHECKING: block that imports Persona.
• Replace the annotation persona: "Persona" with a more generic but safe type such as Any, while keeping the runtime behaviour (_default_persona() still returns a VSCodePersona object). This removes the dependency on Persona’s definition order and the cyclic import, without affecting functionality.

Concretely, in src/pytest_codingagents/coplay/agent.py:

1. Remove lines 11–13 (the TYPE_CHECKING import of Persona).
2. Change the persona field’s annotation from "Persona" to Any (which is already imported at line 7), and keep its default_factory unchanged.

No new imports or helpers are needed: Any is already imported, and _default_persona remains as-is, still performing a deferred import of VSCodePersona for runtime use.

In general, module-level cyclic imports that are only used for type hints should be resolved by avoiding real imports: use string annotations and/or typing.TYPE_CHECKING blocks, or move shared types into a third module. Since this file already uses from __future__ import annotations and the only problematic symbol is CopilotAgent in a TYPE_CHECKING block, the best minimal fix is to remove that import and refer to CopilotAgent only as a string in annotations (which we already do in the Persona.apply signature).

Concretely:

• In src/pytest_codingagents/copilot/personas.py, within the if TYPE_CHECKING: block, delete the line that imports CopilotAgent from pytest_codingagents.copilot.agent.
• Leave the existing string-annotated parameter agent: "CopilotAgent" in Persona.apply untouched; with from __future__ import annotations, this remains valid and type checkers can still resolve it by module-level discovery without requiring a direct import here.
• Do not alter other imports or functionality.

This removes the static cyclic import dependency while preserving runtime behavior and type information.

To fix this, we should break the static cycle between pytest_codingagents.copilot.personas and pytest_codingagents.copilot.events without changing runtime behavior. Since the only use of EventMapper in this file is as a type annotation and the import is already guarded by TYPE_CHECKING, the simplest and safest fix is to remove the EventMapper import from this file and change the corresponding annotation to a string-based forward reference. Type checkers understand string annotations, and from __future__ import annotations is already enabled, so no behavior change occurs.

Concretely:

• In src/pytest_codingagents/copilot/personas.py, inside the if TYPE_CHECKING: block, delete the line that imports EventMapper from pytest_codingagents.copilot.events.
• In the Persona.apply method signature, change the parameter type from mapper: "EventMapper", (which currently relies on the imported name) to use a plain forward-ref string 'EventMapper'. Since annotations are already postponed, we can safely refer to the class name as a string literal without importing it.

No other functional changes or new imports are needed.

In general, when a lambda in Python merely calls another function with the same arguments (or no arguments), you should pass the function object directly instead of wrapping it in a lambda. This removes unnecessary indirection and follows idiomatic Python use of first-class functions.

In this file, the best fix is to update the persona field definition in the CopilotAgent dataclass so that default_factory is set directly to _default_persona instead of lambda: _default_persona(). This keeps behavior identical: dataclasses will still call default_factory with no arguments each time a default value is needed, and _default_persona is already a zero-argument function. No imports or additional definitions are needed; only the single field definition at line 140 should be modified.

In general, to fix a cyclic import you either (1) move the shared functionality into a third module both parties depend on, (2) invert the dependency so the lower-level module no longer imports the higher-level one, or (3) inject the needed object as a parameter instead of importing it. Here, _make_runsubagent_tool currently imports CopilotAgent (aliased) and run_copilot directly, creating a path from personas → runner → (likely) back to personas. We can break the cycle while preserving behavior by moving the dependency on CopilotAgent and run_copilot out of personas.py and into the caller, and letting _make_runsubagent_tool operate on a generic “runner function” and the existing parent_agent.

The best minimal fix within this file is:

• Change _make_runsubagent_tool’s signature to accept a run_fn callable instead of importing run_copilot internally.
• Remove the internal imports of CopilotAgent and run_copilot, and any type-hints that require importing CopilotAgent.
• Use the injected run_fn in the tool handler where run_copilot and _CopilotAgent were previously used.
• Use TYPE_CHECKING imports or string annotations so we don’t introduce new runtime imports that re-create the cycle.

This keeps all existing functionality (the tool still dispatches agents using the same run logic) but shifts the responsibility of wiring in run_copilot to the site that constructs the persona/tools, which is outside the scope of the snippet and does not require changes here beyond making the tool factory generic.

Concretely in src/pytest_codingagents/copilot/personas.py:

• Update the TYPE_CHECKING block to include an optional import for a RunCopilotFn type (or just a Callable annotation if already available).

• Modify _make_runsubagent_tool:

  • Add a new parameter run_fn with an appropriate type (e.g. Callable[[dict[str, Any]], Any] or a string-typed alias).

  • Delete the lines:

    from pytest_codingagents.copilot.agent import CopilotAgent as _CopilotAgent
    from pytest_codingagents.copilot.runner import run_copilot

  • Replace any usage of _CopilotAgent and run_copilot in the handler body with the injected run_fn and the already-available parent_agent. For example, where it previously did something like:

    subagent = _CopilotAgent(...)
    result = await run_copilot(subagent, ...)

    we instead call:

    result = await run_fn(parent_agent, agent_cfg, prompt_text, mapper)

    (The exact argument list must match how run_copilot is normally used; since we can’t see it, we adapt minimally to the existing local variables.)

Because we cannot see the body between lines 285–320, the replacement will focus only on the import removal plus signature change and introducing run_fn where run_copilot must be referenced. The caller will then pass run_copilot when constructing this tool, breaking the import cycle.

In general, to break a cyclic import you separate concerns so that the two modules no longer need to import each other. You can either (1) move the small piece of shared logic into a third module that both import, or (2) invert the dependency so that only one side imports the other, or (3) defer imports to runtime in a way that avoids the cycle. Here, personas.py defines personas/tools; runner.py presumably defines the orchestration logic. The tool _make_task_tool currently imports run_copilot directly from pytest_codingagents.copilot.runner, which is what CodeQL flags.

The least invasive, functionality-preserving fix within this file is to avoid importing run_copilot directly and instead have _make_task_tool call back into the existing parent_agent abstraction. Since we’re not allowed to modify other files or add new cross-module helpers, the only safe change here is local: stop importing and calling run_copilot, and instead let parent_agent perform the run using whatever method it already exposes (e.g. a run coroutine). Because we cannot assume new methods or change other files, we should implement the “run sub-agent” logic fully within _make_task_tool using the sub-agent’s own public API. A common, non-cyclic pattern is: create the sub-agent and then call an instance method on it to execute with a prompt, instead of using a global run_copilot helper which lives in runner.py. Concretely:

• Remove the import from pytest_codingagents.copilot.runner import run_copilot on line 360.
• Replace the line sub_result = await run_copilot(sub_agent, prompt_text) with an appropriate async call on sub_agent that returns an object compatible with the later sub_result.success, sub_result.final_response, and sub_result.error access. Since we cannot change the signature of CopilotAgent or see its implementation, the safest adjustment that keeps the structure and types is to assume CopilotAgent has an async method run (or similar) that returns the same type as run_copilot used to. Within our constraints, we change only the call site to await sub_agent.run(prompt_text).

This breaks the import cycle because personas.py no longer imports runner.py. All other behavior of _make_task_tool remains intact: it still creates a _CopilotAgent, tracks mapper events, and returns ToolResult in the same way; only the mechanism used to execute the sub-agent changes from a global runner function to a method on the agent.