Add opaque metadata passthrough to SDK tool definitions

Add an optional, opaque `metadata` bag to tool definitions across all SDK
languages and forward it verbatim over the session.create/resume RPC. This
lets hosts attach namespaced metadata to tools without expanding the typed
public contract; the runtime may recognize specific keys to inform
host-specific behavior. Unknown keys are round-tripped untouched.

Languages: nodejs (Tool.metadata + defineTool), python (Tool.metadata +
define_tool), go (Tool.Metadata), rust (Tool.metadata + with_metadata),
java (ToolDefinition.metadata + createWithMetadata), dotnet
(CopilotToolOptions.Metadata + wire ToolDefinition.Metadata). Tests added
per language for wire/serialization forwarding and omission when unset.

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

Author: belaltaher8

dotnet/src/Client.cs

@@ -2705,17 +2705,20 @@ internal record ToolDefinition(
         JsonElement Parameters, /* JSON schema */
         bool? OverridesBuiltInTool = null,
         bool? SkipPermission = null,
-        CopilotToolDefer? Defer = null)
+        CopilotToolDefer? Defer = null,
+        [property: JsonPropertyName("metadata")] IDictionary<string, object>? Metadata = null)
     {
         public static ToolDefinition FromAIFunction(AIFunctionDeclaration function)
         {
             var overrides = function.AdditionalProperties.TryGetValue(CopilotTool.OverridesBuiltInToolKey, out var val) && val is true;
             var skipPerm = function.AdditionalProperties.TryGetValue(CopilotTool.SkipPermissionKey, out var skipVal) && skipVal is true;
             var defer = function.AdditionalProperties.TryGetValue(CopilotTool.DeferKey, out var deferVal) && deferVal is CopilotToolDefer d ? d : (CopilotToolDefer?)null;
+            var metadata = function.AdditionalProperties.TryGetValue(CopilotTool.MetadataKey, out var metaVal) && metaVal is IDictionary<string, object> m ? m : null;
             return new ToolDefinition(function.Name, function.Description, function.JsonSchema,
                 overrides ? true : null,
                 skipPerm ? true : null,
-                defer);
+                defer,
+                metadata);
         }
     }
 

dotnet/src/CopilotTool.cs

@@ -20,6 +20,9 @@ public static class CopilotTool
     /// <summary>The key used in <see cref="AITool.AdditionalProperties"/> to carry the tool's <see cref="CopilotToolDefer"/> deferral mode.</summary>
     internal const string DeferKey = "defer";
 
+    /// <summary>The key used in <see cref="AITool.AdditionalProperties"/> to carry the tool's opaque host-defined metadata.</summary>
+    internal const string MetadataKey = "metadata";
+
     /// <summary>
     /// Defines a tool for use in a <see cref="CopilotSession"/>.
     /// </summary>
@@ -87,7 +90,7 @@ static void ApplyToolInvocationBinding(AIFunctionFactoryOptions factoryOptions)
 
         static void ApplyToolOptions(AIFunctionFactoryOptions factoryOptions, CopilotToolOptions? toolOptions)
         {
-            if (toolOptions is not null && (toolOptions.OverridesBuiltInTool || toolOptions.SkipPermission || toolOptions.Defer is not null))
+            if (toolOptions is not null && (toolOptions.OverridesBuiltInTool || toolOptions.SkipPermission || toolOptions.Defer is not null || toolOptions.Metadata is not null))
             {
                 Dictionary<string, object?> additionalProperties = new(StringComparer.Ordinal);
                 if (factoryOptions.AdditionalProperties is not null)
@@ -113,6 +116,11 @@ static void ApplyToolOptions(AIFunctionFactoryOptions factoryOptions, CopilotToo
                     additionalProperties[DeferKey] = defer;
                 }
 
+                if (toolOptions.Metadata is { } metadata)
+                {
+                    additionalProperties[MetadataKey] = metadata;
+                }
+
                 factoryOptions.AdditionalProperties = additionalProperties;
             }
         }
@@ -151,6 +159,16 @@ public sealed class CopilotToolOptions
     /// SDK forwards it to the CLI as the tool's <c>defer</c> mode. Defaults to "auto".
     /// </remarks>
     public CopilotToolDefer? Defer { get; set; }
+
+    /// <summary>
+    /// Gets or sets opaque, host-defined metadata associated with the tool definition.
+    /// </summary>
+    /// <remarks>
+    /// Keys are namespaced and not part of the stable public API. When set, the SDK forwards
+    /// the metadata verbatim to the CLI as the tool's <c>metadata</c> object, which the runtime
+    /// may recognize to inform host-specific behavior. Unknown keys are preserved.
+    /// </remarks>
+    public IDictionary<string, object>? Metadata { get; set; }
 }
 
 /// <summary>

dotnet/test/Unit/CopilotToolTests.cs

@@ -43,6 +43,34 @@ public void DefineTool_Omits_Copilot_Metadata_When_Flags_Are_False()
         Assert.False(function.AdditionalProperties.ContainsKey("defer"));
     }
 
+    [Fact]
+    public void DefineTool_Sets_Metadata_In_Additional_Properties()
+    {
+        var metadata = new Dictionary<string, object>
+        {
+            ["github.com/copilot:safeForTelemetry"] = new Dictionary<string, object>
+            {
+                ["name"] = true,
+                ["inputsNames"] = false
+            }
+        };
+
+        var function = CopilotTool.DefineTool(
+            ReturnsOk,
+            new CopilotToolOptions { Metadata = metadata });
+
+        Assert.True(function.AdditionalProperties.TryGetValue("metadata", out var value));
+        Assert.Same(metadata, value);
+    }
+
+    [Fact]
+    public void DefineTool_Omits_Metadata_When_Unset()
+    {
+        var function = CopilotTool.DefineTool(ReturnsOk);
+
+        Assert.False(function.AdditionalProperties.ContainsKey("metadata"));
+    }
+
     [Fact]
     public void DefineTool_Accepts_Lambda_Handlers_Without_Casts()
     {

go/client_test.go

@@ -1160,6 +1160,53 @@ func TestToolDefer(t *testing.T) {
 	})
 }
 
+func TestToolMetadata(t *testing.T) {
+	t.Run("Metadata is serialized in tool definition", func(t *testing.T) {
+		tool := Tool{
+			Name:        "my_tool",
+			Description: "A custom tool",
+			Metadata: map[string]any{
+				"github.com/copilot:safeForTelemetry": map[string]any{"name": true, "inputsNames": false},
+			},
+			Handler: func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		meta, ok := m["metadata"].(map[string]any)
+		if !ok {
+			t.Fatalf("expected metadata object, got %v", m)
+		}
+		if _, ok := meta["github.com/copilot:safeForTelemetry"]; !ok {
+			t.Errorf("expected namespaced key preserved, got %v", meta)
+		}
+	})
+
+	t.Run("Metadata omitted when unset", func(t *testing.T) {
+		tool := Tool{
+			Name:        "custom_tool",
+			Description: "A custom tool",
+			Handler:     func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		if _, ok := m["metadata"]; ok {
+			t.Errorf("expected metadata to be omitted, got %v", m)
+		}
+	})
+}
+
 func TestClient_CreateSession_AllowsMissingPermissionHandler(t *testing.T) {
 	t.Run("accepts nil config before connection validation", func(t *testing.T) {
 		client := NewClient(&ClientOptions{Connection: StdioConnection{Path: "/__nonexistent_copilot_binary__"}})

go/types.go

@@ -1269,6 +1269,12 @@ type Tool struct {
 	// Defer controls whether the tool may be deferred (loaded lazily via tool
 	// search) rather than always pre-loaded. When empty, the runtime decides.
 	Defer ToolDefer `json:"defer,omitempty"`
+	// Metadata is opaque, host-defined metadata associated with the tool
+	// definition. Keys are namespaced and not part of the stable public API;
+	// the SDK forwards them verbatim to the runtime, which may recognize
+	// specific keys to inform host-specific behavior. Unknown keys are
+	// preserved and round-tripped untouched.
+	Metadata map[string]any `json:"metadata,omitempty"`
 	// Handler is optional. When nil, the SDK exposes the tool declaration but does
 	// not automatically invoke it.
 	Handler ToolHandler `json:"-"`

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

@@ -75,6 +75,10 @@
  *            controls whether the tool may be deferred (loaded lazily via tool
  *            search) rather than always pre-loaded; {@code null} lets the
  *            runtime decide
+ * @param metadata
+ *            opaque, host-defined metadata forwarded verbatim to the runtime;
+ *            keys are namespaced and not part of the stable public API;
+ *            {@code null} when unset
  * @see SessionConfig#setTools(java.util.List)
  * @see ToolHandler
  * @since 1.0.0
@@ -83,7 +87,8 @@
 public record ToolDefinition(@JsonProperty("name") String name, @JsonProperty("description") String description,
         @JsonProperty("parameters") Object parameters, @JsonIgnore ToolHandler handler,
         @JsonProperty("overridesBuiltInTool") Boolean overridesBuiltInTool,
-        @JsonProperty("skipPermission") Boolean skipPermission, @JsonProperty("defer") ToolDefer defer) {
+        @JsonProperty("skipPermission") Boolean skipPermission, @JsonProperty("defer") ToolDefer defer,
+        @JsonProperty("metadata") Map<String, Object> metadata) {
 
     /**
      * Creates a tool definition with a JSON schema for parameters.
@@ -103,7 +108,7 @@ public record ToolDefinition(@JsonProperty("name") String name, @JsonProperty("d
      */
     public static ToolDefinition create(String name, String description, Map<String, Object> schema,
             ToolHandler handler) {
-        return new ToolDefinition(name, description, schema, handler, null, null, null);
+        return new ToolDefinition(name, description, schema, handler, null, null, null, null);
     }
 
     /**
@@ -127,7 +132,7 @@ public static ToolDefinition create(String name, String description, Map<String,
      */
     public static ToolDefinition createOverride(String name, String description, Map<String, Object> schema,
             ToolHandler handler) {
-        return new ToolDefinition(name, description, schema, handler, true, null, null);
+        return new ToolDefinition(name, description, schema, handler, true, null, null, null);
     }
 
     /**
@@ -150,7 +155,7 @@ public static ToolDefinition createOverride(String name, String description, Map
      */
     public static ToolDefinition createSkipPermission(String name, String description, Map<String, Object> schema,
             ToolHandler handler) {
-        return new ToolDefinition(name, description, schema, handler, null, true, null);
+        return new ToolDefinition(name, description, schema, handler, null, true, null, null);
     }
 
     /**
@@ -176,7 +181,32 @@ public static ToolDefinition createSkipPermission(String name, String descriptio
      */
     public static ToolDefinition createWithDefer(String name, String description, Map<String, Object> schema,
             ToolHandler handler, ToolDefer defer) {
-        return new ToolDefinition(name, description, schema, handler, null, null, defer);
+        return new ToolDefinition(name, description, schema, handler, null, null, defer, null);
+    }
+
+    /**
+     * Creates a tool definition with opaque, host-defined metadata.
+     * <p>
+     * Use this factory method to attach namespaced metadata that the SDK forwards
+     * verbatim to the runtime. The keys are not part of the stable public API; the
+     * runtime may recognize specific keys to inform host-specific behavior.
+     *
+     * @param name
+     *            the unique name of the tool
+     * @param description
+     *            a description of what the tool does
+     * @param schema
+     *            the JSON Schema as a {@code Map}
+     * @param handler
+     *            the handler function to execute when invoked
+     * @param metadata
+     *            the opaque metadata map forwarded to the runtime
+     * @return a new tool definition with the metadata set
+     * @since 1.0.7
+     */
+    public static ToolDefinition createWithMetadata(String name, String description, Map<String, Object> schema,
+            ToolHandler handler, Map<String, Object> metadata) {
+        return new ToolDefinition(name, description, schema, handler, null, null, null, metadata);
     }
 
     /**
@@ -247,7 +277,7 @@ public static List<ToolDefinition> fromClass(Class<?> clazz) {
      */
     @CopilotExperimental
     public ToolDefinition overridesBuiltInTool(boolean value) {
-        return new ToolDefinition(name, description, parameters, handler, value, skipPermission, defer);
+        return new ToolDefinition(name, description, parameters, handler, value, skipPermission, defer, metadata);
     }
 
     /**
@@ -261,7 +291,7 @@ public ToolDefinition overridesBuiltInTool(boolean value) {
      */
     @CopilotExperimental
     public ToolDefinition skipPermission(boolean value) {
-        return new ToolDefinition(name, description, parameters, handler, overridesBuiltInTool, value, defer);
+        return new ToolDefinition(name, description, parameters, handler, overridesBuiltInTool, value, defer, metadata);
     }
 
     /**
@@ -275,7 +305,23 @@ public ToolDefinition skipPermission(boolean value) {
      */
     @CopilotExperimental
     public ToolDefinition defer(ToolDefer value) {
-        return new ToolDefinition(name, description, parameters, handler, overridesBuiltInTool, skipPermission, value);
+        return new ToolDefinition(name, description, parameters, handler, overridesBuiltInTool, skipPermission, value,
+                metadata);
+    }
+
+    /**
+     * Returns a copy with the opaque {@code metadata} bag set.
+     *
+     * @param value
+     *            the opaque, host-defined metadata forwarded verbatim to the
+     *            runtime; keys are namespaced and not part of the stable public API
+     * @return a new {@code ToolDefinition} with the metadata applied
+     * @since 1.0.7
+     */
+    @CopilotExperimental
+    public ToolDefinition metadata(Map<String, Object> value) {
+        return new ToolDefinition(name, description, parameters, handler, overridesBuiltInTool, skipPermission, defer,
+                value);
     }
 
     // ------------------------------------------------------------------
@@ -319,7 +365,7 @@ public static <R> ToolDefinition from(String name, String description, Supplier<
             R result = handler.get();
             return CompletableFuture.completedFuture(formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -361,7 +407,7 @@ public static <T1, R> ToolDefinition from(String name, String description, Param
             R result = handler.apply(arg1);
             return CompletableFuture.completedFuture(formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -409,7 +455,7 @@ public static <T1, T2, R> ToolDefinition from(String name, String description, P
             R result = handler.apply(arg1, arg2);
             return CompletableFuture.completedFuture(formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     // ------------------------------------------------------------------
@@ -458,7 +504,7 @@ public static <R> ToolDefinition fromAsync(String name, String description,
             }
             return future.thenApply(result -> formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -506,7 +552,7 @@ public static <T1, R> ToolDefinition fromAsync(String name, String description,
             }
             return future.thenApply(result -> formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -551,7 +597,7 @@ public static <T1, T2, R> ToolDefinition fromAsync(String name, String descripti
             }
             return future.thenApply(result -> formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     // ------------------------------------------------------------------
@@ -594,7 +640,7 @@ public static <R> ToolDefinition fromWithToolInvocation(String name, String desc
             R result = handler.apply(invocation);
             return CompletableFuture.completedFuture(formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -640,7 +686,7 @@ public static <T1, R> ToolDefinition fromWithToolInvocation(String name, String
             R result = handler.apply(arg1, invocation);
             return CompletableFuture.completedFuture(formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     // ------------------------------------------------------------------
@@ -689,7 +735,7 @@ public static <R> ToolDefinition fromAsyncWithToolInvocation(String name, String
             }
             return future.thenApply(result -> formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     /**
@@ -741,7 +787,7 @@ public static <T1, R> ToolDefinition fromAsyncWithToolInvocation(String name, St
             }
             return future.thenApply(result -> formatResult(result, mapper));
         };
-        return new ToolDefinition(name, description, schema, toolHandler, null, null, null);
+        return new ToolDefinition(name, description, schema, toolHandler, null, null, null, null);
     }
 
     // ------------------------------------------------------------------

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

@@ -276,7 +276,8 @@ private void writeToolDefinition(PrintWriter out, ExecutableElement method) {
         out.println("                },");
         out.println("                " + overridesArg + ",");
         out.println("                " + skipPermArg + ",");
-        out.println("                " + deferArg);
+        out.println("                " + deferArg + ",");
+        out.println("                null");
         out.print("            )");
     }