[Java] @CopilotTool ergonomics 4.1: Create @CopilotTool and @Param annotations #1758

Overview

Create the @CopilotTool and @Param annotation classes in the new com.github.copilot.tool package.

Branch: edburns/1682-java-tool-ergonomics on upstream

Prerequisites

Before writing any code, read the entire implementation plan at:
1682-java-tool-ergonomics-prompts-remove-before-merge/dd-3018003-ignorance-reduction-for-implementation-plan.md

Relevant plan sections to carefully re-read

• Section 3.1 — Package placement (Resolution: Option B — new com.github.copilot.tool package)
• Section 3.2 — @CopilotTool annotation design (Resolution: RUNTIME retention, include ToolDefer support)
• Section 3.3 — @Param annotation design (Resolution: support defaultValue() in v1)
• Section 4.1 — Annotations (@CopilotTool, @Param) (the primary task description)

Deliverables

Files to create

1. java/src/main/java/com/github/copilot/tool/CopilotTool.java
2. java/src/main/java/com/github/copilot/tool/Param.java

@CopilotTool specification

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@CopilotExperimental
public @interface CopilotTool {
    /** Tool description (sent to the model). */
    String value();

    /** Tool name. Defaults to method name converted to snake_case. */
    String name() default "";

    /** Whether this tool overrides a built-in tool. */
    boolean overridesBuiltInTool() default false;

    /** Whether to skip permission checks. */
    boolean skipPermission() default false;

    /** Defer configuration for this tool. */
    ToolDefer defer() default ToolDefer.NONE;
}

@Param specification

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface Param {
    /** Parameter description (sent to the model). */
    String value() default "";

    /** Parameter name override. Defaults to the actual parameter name. */
    String name() default "";

    /** Whether this parameter is required. Default true. */
    boolean required() default true;

    /** Optional default value when the argument is omitted. */
    String defaultValue() default "";
}

Module-info update

Add exports com.github.copilot.tool; to java/src/main/java/module-info.java.

Gating tests and criteria

All of the following must pass before this task is considered complete:

1. Compilation gate: mvn clean compile passes with zero errors.
2. Annotation attribute verification test: Write a unit test in java/src/test/java/com/github/copilot/tool/CopilotToolAnnotationTest.java that:
   • Uses reflection to verify @CopilotTool has RUNTIME retention.
   • Verifies @CopilotTool target is ElementType.METHOD.
   • Verifies @CopilotTool is annotated with @CopilotExperimental.
   • Verifies all declared attributes exist with correct default values: name() → "", overridesBuiltInTool() → false, skipPermission() → false, defer() → ToolDefer.NONE.
   • Verifies @Param has RUNTIME retention and ElementType.PARAMETER target.
   • Verifies @Param attributes: value() → "", name() → "", required() → true, defaultValue() → "".
3. Applicability test: In the same test class, create a sample inner class with a method annotated with @CopilotTool and parameters annotated with @Param, and verify via reflection that the annotations are present with expected values.
4. Spotless format check: mvn spotless:check passes.
5. Full test suite: mvn clean verify passes (existing tests are not broken).

Constraints

• ✅✅ YOU MUST run mvn spotless:apply before every commit.

• Do NOT create any processor logic, schema generation, or runtime scanning in this task.

• Do NOT modify any files outside the java/ directory.

• Follow the existing code style (4-space indent, Javadoc on public APIs).

• The ToolDefer enum already exists in com.github.copilot.rpc — import it; do NOT duplicate it.