Java: enable tool metadata for @copilotTool + compat constructor

Address Java SME feedback so annotation-based tools reach parity with the
programmatic API and existing constructor call sites keep compiling.

- ToolDefinition: add a backward-compatible 7-arg constructor delegating to
  the canonical 8-arg with metadata=null.
- CopilotTool: add metadata() plus nested MetadataEntry/MetadataValue/
  MetadataFlag annotations (@target({})) with a shallow bool|str|flag-map
  representation, documenting the programmatic API for richer values.
- CopilotToolProcessor: generate the metadata constructor argument
  (Map.<String, Object>of(...) with an explicit type witness) instead of a
  hardcoded null; null when no metadata is present.
- Tests: processor generation cases (nested flags, absent, combined flags),
  ToolDefinition 7-arg/.metadata(...) copy/flag-chaining cases, and a
  fromObject metadata assertion; extend the SimpleTools fixture pair to emit
  a safeForTelemetry metadata map.
- ADR-005: update the generated snippet to the 8-arg shape and document the
  @copilotTool(metadata = ...) syntax and emitted shape.

Note: mvn verify / spotless:apply not run locally (no JDK/Maven in the dev
environment); relies on PR CI.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: bf2bf0dd-ec9f-42f5-a6e1-4f2a9e562d5f

Author: belaltaher8

java/docs/adr/adr-005-tool-definition.md

@@ -181,14 +181,45 @@ final class MyTools$$CopilotToolMeta {
                     Phase phase = invocation.getArgumentsAs(Phase.class);
                     return CompletableFuture.completedFuture(
                         instance.setCurrentPhase(phase));
-                }, null, null, null)
+                }, null, null, null, null)
         );
     }
 }
 ```
 
+The trailing constructor arguments are `overridesBuiltInTool`, `skipPermission`, `defer`, and `metadata` — all `null` here because none were set on the annotation.
+
 At runtime, `ToolDefinition.fromObject(myTools)` loads the generated `$$CopilotToolMeta` class — zero reflection, zero dependency on `-parameters`.
 
+### Host-defined metadata
+
+`@CopilotTool` also accepts an opaque `metadata` bag via nested annotations. Because annotation members can't express arbitrary maps, the representation is deliberately shallow: each entry maps a namespaced key to a boolean, a string, or a one-level map of named boolean flags.
+
+```java
+@CopilotTool(
+    value = "Reports phase",
+    metadata = {
+        @CopilotTool.MetadataEntry(
+            key = "github.com/copilot:safeForTelemetry",
+            value = @CopilotTool.MetadataValue(flags = {
+                @CopilotTool.MetadataFlag(name = "name", value = true),
+                @CopilotTool.MetadataFlag(name = "inputsNames", value = false)
+            }))
+    })
+public String reportPhase(@CopilotToolParam("Phase") String phase) {
+    return phase;
+}
+```
+
+The processor emits this as the `metadata` constructor argument:
+
+```java
+Map.<String, Object>of("github.com/copilot:safeForTelemetry",
+        Map.of("name", true, "inputsNames", false))
+```
+
+For richer values (numbers, arrays, deeper nesting), use the programmatic `ToolDefinition.createWithMetadata(...)` / `ToolDefinition.metadata(...)` API instead.
+
 ### Compile-time validation
 
 Because the processor has full access to the source AST, it can emit compile errors for:

java/src/main/java/com/github/copilot/rpc/ToolDefinition.java

@@ -89,6 +89,36 @@ public record ToolDefinition(@JsonProperty("name") String name, @JsonProperty("d
         @JsonProperty("skipPermission") Boolean skipPermission, @JsonProperty("defer") ToolDefer defer,
         @JsonProperty("metadata") Map<String, Object> metadata) {
 
+    /**
+     * Backward-compatible constructor without the {@code metadata} component.
+     * <p>
+     * Delegates to the canonical constructor with {@code metadata} set to
+     * {@code null}. Retained so existing direct constructor call sites (including
+     * previously-generated {@code $$CopilotToolMeta} classes) keep compiling after
+     * {@code metadata} was added.
+     *
+     * @param name
+     *            the unique name of the tool
+     * @param description
+     *            a description of what the tool does
+     * @param parameters
+     *            the JSON Schema for the tool's parameters
+     * @param handler
+     *            the handler function to execute when invoked
+     * @param overridesBuiltInTool
+     *            whether this tool overrides a built-in tool; {@code null} for the
+     *            default
+     * @param skipPermission
+     *            whether the tool may run without a permission check; {@code null}
+     *            for the default
+     * @param defer
+     *            the deferral mode; {@code null} lets the runtime decide
+     */
+    public ToolDefinition(String name, String description, Object parameters, ToolHandler handler,
+            Boolean overridesBuiltInTool, Boolean skipPermission, ToolDefer defer) {
+        this(name, description, parameters, handler, overridesBuiltInTool, skipPermission, defer, null);
+    }
+
     /**
      * Creates a tool definition with a JSON schema for parameters.
      * <p>

java/src/main/java/com/github/copilot/tool/CopilotTool.java

@@ -50,4 +50,79 @@
 
     /** Defer configuration for this tool. */
     ToolDefer defer() default ToolDefer.NONE;
+
+    /**
+     * Opaque, host-defined metadata for this tool. Keys are namespaced and not
+     * part of the stable public API; specific keys may be recognized to inform
+     * host-specific behavior.
+     *
+     * <p>
+     * Because annotation members cannot express arbitrary maps, this uses a
+     * deliberately shallow representation: each {@link MetadataEntry} maps a
+     * string key to a single {@link MetadataValue} that is either a boolean, a
+     * string, or a one-level map of named boolean {@link MetadataFlag flags}.
+     * Numbers, arrays, and deeper nesting are not supported here; use the
+     * programmatic {@code ToolDefinition.createWithMetadata(...)} /
+     * {@code ToolDefinition.metadata(...)} API for richer values.
+     *
+     * <p>
+     * Example emitted shape:
+     *
+     * <pre>
+     * Map.of("github.com/copilot:safeForTelemetry",
+     *        Map.of("name", true, "inputsNames", false))
+     * </pre>
+     */
+    MetadataEntry[] metadata() default {};
+
+    /**
+     * A single metadata key/value pair. Used only as a member value of
+     * {@link CopilotTool#metadata()}.
+     */
+    @Documented
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target({})
+    @interface MetadataEntry {
+
+        /** The namespaced metadata key. */
+        String key();
+
+        /** The value associated with {@link #key()}. */
+        MetadataValue value();
+    }
+
+    /**
+     * A metadata value. Exactly one representation is intended per value: a map
+     * of named boolean {@link #flags()} (when non-empty), otherwise a
+     * {@link #str()} (when non-empty), otherwise a {@link #bool()}.
+     */
+    @Documented
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target({})
+    @interface MetadataValue {
+
+        /** Scalar boolean value. Used when {@link #flags()} and {@link #str()} are unset. */
+        boolean bool() default false;
+
+        /** Scalar string value. Used when {@link #flags()} is empty and this is non-empty. */
+        String str() default "";
+
+        /** Object-like value: a one-level map of named boolean flags. Takes precedence when non-empty. */
+        MetadataFlag[] flags() default {};
+    }
+
+    /**
+     * A single named boolean flag within a {@link MetadataValue#flags()} map.
+     */
+    @Documented
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target({})
+    @interface MetadataFlag {
+
+        /** The flag name (map key). */
+        String name();
+
+        /** The flag value. */
+        boolean value();
+    }
 }

java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java

@@ -277,10 +277,47 @@ private void writeToolDefinition(PrintWriter out, ExecutableElement method) {
         out.println("                " + overridesArg + ",");
         out.println("                " + skipPermArg + ",");
         out.println("                " + deferArg + ",");
-        out.println("                null");
+        out.println("                " + metadataSource(annotation));
         out.print("            )");
     }
 
+    /**
+     * Converts the {@code @CopilotTool(metadata = ...)} entries into a Java source
+     * literal. Returns {@code "null"} when no metadata is present, otherwise a
+     * {@code Map.<String, Object>of(...)} expression.
+     */
+    private String metadataSource(CopilotTool annotation) {
+        CopilotTool.MetadataEntry[] entries = annotation.metadata();
+        if (entries.length == 0) {
+            return "null";
+        }
+        List<String> parts = new ArrayList<>();
+        for (CopilotTool.MetadataEntry entry : entries) {
+            parts.add("\"" + escapeJava(entry.key()) + "\", " + metadataValueSource(entry.value()));
+        }
+        return "Map.<String, Object>of(" + String.join(", ", parts) + ")";
+    }
+
+    /**
+     * Converts a single {@link CopilotTool.MetadataValue} into a Java source
+     * literal. A non-empty {@code flags} map takes precedence, then a non-empty
+     * {@code str}, otherwise the {@code bool} scalar.
+     */
+    private String metadataValueSource(CopilotTool.MetadataValue value) {
+        CopilotTool.MetadataFlag[] flags = value.flags();
+        if (flags.length > 0) {
+            List<String> flagParts = new ArrayList<>();
+            for (CopilotTool.MetadataFlag flag : flags) {
+                flagParts.add("\"" + escapeJava(flag.name()) + "\", " + flag.value());
+            }
+            return "Map.of(" + String.join(", ", flagParts) + ")";
+        }
+        if (!value.str().isEmpty()) {
+            return "\"" + escapeJava(value.str()) + "\"";
+        }
+        return String.valueOf(value.bool());
+    }
+
     private String generateSchemaWithParamMetadata(List<? extends VariableElement> parameters) {
         List<? extends VariableElement> schemaParameters = getSchemaParameters(parameters);
 

java/src/test/java/com/github/copilot/ToolDefinitionTest.java

@@ -82,4 +82,50 @@ void testMetadataOmittedWhenNull() throws Exception {
 
         assertFalse(json.has("metadata"));
     }
+
+    @Test
+    void testSevenArgConstructorLeavesMetadataNull() throws Exception {
+        ToolDefinition tool = new ToolDefinition("my_tool", "A tool", schema(),
+                invocation -> CompletableFuture.completedFuture("ok"), null, null, null);
+
+        assertNull(tool.metadata());
+
+        ObjectNode json = (ObjectNode) MAPPER.readTree(MAPPER.writeValueAsString(tool));
+
+        assertFalse(json.has("metadata"));
+    }
+
+    @Test
+    void testMetadataCopyMethodSerializes() throws Exception {
+        Map<String, Object> metadata = Map.of("github.com/copilot:safeForTelemetry",
+                Map.of("name", true, "inputsNames", false));
+        ToolDefinition tool = ToolDefinition
+                .create("my_tool", "A tool", schema(), invocation -> CompletableFuture.completedFuture("ok"))
+                .metadata(metadata);
+
+        assertEquals(metadata, tool.metadata());
+
+        ObjectNode json = (ObjectNode) MAPPER.readTree(MAPPER.writeValueAsString(tool));
+
+        assertTrue(json.get("metadata").has("github.com/copilot:safeForTelemetry"));
+    }
+
+    @Test
+    void testChainingFlagsPreservesMetadata() throws Exception {
+        Map<String, Object> metadata = Map.of("github.com/copilot:safeForTelemetry", Map.of("name", true));
+
+        ToolDefinition metadataFirst = ToolDefinition
+                .create("my_tool", "A tool", schema(), invocation -> CompletableFuture.completedFuture("ok"))
+                .metadata(metadata).overridesBuiltInTool(true).skipPermission(true).defer(ToolDefer.NEVER);
+
+        ToolDefinition flagsFirst = ToolDefinition
+                .create("my_tool", "A tool", schema(), invocation -> CompletableFuture.completedFuture("ok"))
+                .overridesBuiltInTool(true).skipPermission(true).defer(ToolDefer.NEVER).metadata(metadata);
+
+        assertEquals(metadata, metadataFirst.metadata());
+        assertEquals(metadata, flagsFirst.metadata());
+        assertEquals(Boolean.TRUE, flagsFirst.overridesBuiltInTool());
+        assertEquals(Boolean.TRUE, flagsFirst.skipPermission());
+        assertEquals(ToolDefer.NEVER, flagsFirst.defer());
+    }
 }

java/src/test/java/com/github/copilot/rpc/ToolDefinitionFromObjectTest.java

@@ -92,6 +92,21 @@ void fromObject_handlerInvocation() throws Exception {
         assertEquals("Hello, Alice!", result);
     }
 
+    @Test
+    void fromObject_toolMetadata() {
+        var tools = ToolDefinition.fromObject(new SimpleTools());
+
+        var withMetadata = findTool(tools, "greet_user");
+        assertNotNull(withMetadata);
+        assertNotNull(withMetadata.metadata());
+        assertEquals(Map.of("github.com/copilot:safeForTelemetry", Map.of("name", true, "inputsNames", false)),
+                withMetadata.metadata());
+
+        var withoutMetadata = findTool(tools, "add_numbers");
+        assertNotNull(withoutMetadata);
+        assertNull(withoutMetadata.metadata());
+    }
+
     // ── Test 2: Handler return type patterns ────────────────────────────────────
 
     @Test

java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools$$CopilotToolMeta.java

@@ -30,7 +30,8 @@ public List<ToolDefinition> definitions(SimpleTools instance, ObjectMapper mappe
                     Map<String, Object> args = invocation.getArguments();
                     String name = (String) args.get("name");
                     return CompletableFuture.completedFuture(instance.greetUser(name));
-                }, null, null, null, null),
+                }, null, null, null, Map.<String, Object>of("github.com/copilot:safeForTelemetry",
+                        Map.of("name", true, "inputsNames", false))),
                 new ToolDefinition("add_numbers", "Adds two numbers together",
                         Map.of("type", "object", "properties",
                                 Map.ofEntries(

java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools.java

@@ -12,7 +12,10 @@
  */
 public class SimpleTools {
 
-    @CopilotTool("Greets a user by name")
+    @CopilotTool(value = "Greets a user by name", metadata = {
+            @CopilotTool.MetadataEntry(key = "github.com/copilot:safeForTelemetry", value = @CopilotTool.MetadataValue(flags = {
+                    @CopilotTool.MetadataFlag(name = "name", value = true),
+                    @CopilotTool.MetadataFlag(name = "inputsNames", value = false) })) })
     public String greetUser(@CopilotToolParam(value = "The user's name", required = true) String name) {
         return "Hello, " + name + "!";
     }

java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java

@@ -212,6 +212,86 @@ public String doSomething(@CopilotToolParam("Input") String input) {
                 "Expected completedFuture wrapping for String return, got:\n" + generated);
     }
 
+    @Test
+    void generatesMetadata_withNestedFlags() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class MetaTools {
+                    @CopilotTool(value = "Reports phase", metadata = {
+                        @CopilotTool.MetadataEntry(
+                            key = "github.com/copilot:safeForTelemetry",
+                            value = @CopilotTool.MetadataValue(flags = {
+                                @CopilotTool.MetadataFlag(name = "name", value = true),
+                                @CopilotTool.MetadataFlag(name = "inputsNames", value = false)
+                            }))
+                    })
+                    public String reportPhase(@CopilotToolParam("Phase") String phase) {
+                        return phase;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.MetaTools", source)));
+        assertNoErrors(result);
+        String generated = result.getGeneratedSource("test.MetaTools$$CopilotToolMeta");
+        assertTrue(generated.contains("Map.<String, Object>of(\"github.com/copilot:safeForTelemetry\""),
+                "Expected typed metadata map, got:\n" + generated);
+        assertTrue(generated.contains("Map.of(\"name\", true, \"inputsNames\", false)"),
+                "Expected nested flag map, got:\n" + generated);
+    }
+
+    @Test
+    void generatesNullMetadata_whenAbsent() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class PlainTools {
+                    @CopilotTool("Plain tool")
+                    public String doSomething(@CopilotToolParam("Input") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.PlainTools", source)));
+        assertNoErrors(result);
+        String generated = result.getGeneratedSource("test.PlainTools$$CopilotToolMeta");
+        assertFalse(generated.contains("Map.<String, Object>of("),
+                "Expected no metadata map for a tool without metadata, got:\n" + generated);
+    }
+
+    @Test
+    void generatesMetadata_alongsideOtherFlags() {
+        String source = """
+                package test;
+                import com.github.copilot.tool.CopilotTool;
+                import com.github.copilot.rpc.ToolDefer;
+                import com.github.copilot.tool.CopilotToolParam;
+                public class ComboTools {
+                    @CopilotTool(value = "Combo", name = "combo", overridesBuiltInTool = true,
+                        skipPermission = true, defer = ToolDefer.NEVER,
+                        metadata = {
+                            @CopilotTool.MetadataEntry(key = "k",
+                                value = @CopilotTool.MetadataValue(bool = true))
+                        })
+                    public String doSomething(@CopilotToolParam("Input") String input) {
+                        return input;
+                    }
+                }
+                """;
+
+        CompilationResult result = compileWithProcessor(List.of(inMemorySource("test.ComboTools", source)));
+        assertNoErrors(result);
+        String generated = result.getGeneratedSource("test.ComboTools$$CopilotToolMeta");
+        assertTrue(generated.contains("Boolean.TRUE"), "Expected overrides/skip flags, got:\n" + generated);
+        assertTrue(generated.contains("ToolDefer.NEVER"), "Expected defer, got:\n" + generated);
+        assertTrue(generated.contains("Map.<String, Object>of(\"k\", true)"),
+                "Expected scalar bool metadata, got:\n" + generated);
+    }
+
     @Test
     void generatesCorrectCode_forVoidReturnType() {
         String source = """