diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/ContextStore.java b/agentscope-core/src/main/java/io/agentscope/core/tool/ContextStore.java
index 72b3213941..d77986ed2c 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/ContextStore.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/ContextStore.java
@@ -18,16 +18,17 @@
 /**
  * Storage layer abstraction for tool execution context.
  *
- * <p>This interface defines the storage contract for context objects. It supports two retrieval
+ * <p>This interface defines the storage contract for context objects. It supports three retrieval
  * modes:
  * <ol>
  *   <li><b>By type only</b>: {@code get(Class<T>)} - suitable for singleton scenarios</li>
  *   <li><b>By key + type</b>: {@code get(String, Class<T>)} - suitable for multi-instance
- *       scenarios</li>
+ *       scenarios requiring type safety</li>
  * </ol>
  *
- * <p>This design allows handling both simple cases (one UserContext) and complex cases
- * (multiple UserContext instances for different users).
+ * <p>This design allows handling both simple cases (one UserContext), complex cases
+ * (multiple UserContext instances for different users), and dynamic attributes (like a simple
+ * string tenantId).
  *
  * <p>Implementations can be:
  * <ul>
@@ -43,6 +44,9 @@
  * // Multiple instances of same type
  * UserContext admin = store.get("admin", UserContext.class);
  * UserContext guest = store.get("guest", UserContext.class);
+ *
+ * // Dynamic property by key only
+ * Object tenantId = store.get("tenantId");
  * }</pre>
  *
  * @see ToolExecutionContext
@@ -73,6 +77,19 @@ public interface ContextStore {
      */
     <T> T get(String key, Class<T> type);
 
+    /**
+     * Retrieves an object by key without requiring the caller to know its registered type.
+     *
+     * <p>This is useful when the key is the public contract and the runtime type may be any
+     * application object.
+     *
+     * @param key The key identifying the specific instance
+     * @return The object instance, or null if not found
+     */
+    default Object get(String key) {
+        return null;
+    }
+
     /**
      * Retrieves an object by type only (without key).
      *
@@ -105,6 +122,16 @@ public interface ContextStore {
      */
     boolean contains(String key, Class<?> type);
 
+    /**
+     * Checks whether an object with the specified key exists regardless of type.
+     *
+     * @param key The key identifying the instance
+     * @return true if any object exists with this key, false otherwise
+     */
+    default boolean contains(String key) {
+        return get(key) != null;
+    }
+
     /**
      * Checks whether any object of the specified type exists (regardless of key).
      *
diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/DefaultContextStore.java b/agentscope-core/src/main/java/io/agentscope/core/tool/DefaultContextStore.java
index 80d60193e9..259dfb866f 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/DefaultContextStore.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/DefaultContextStore.java
@@ -33,6 +33,9 @@ class DefaultContextStore implements ContextStore {
     // Two-level map: Class -> (Key -> Object)
     private final Map<Class<?>, Map<String, Object>> objectMap;
 
+    // Direct key index for type-agnostic lookup
+    private final Map<String, Object> keyMap;
+
     private DefaultContextStore(Builder builder) {
         if (builder.objectMap != null) {
             Map<Class<?>, Map<String, Object>> copy = new HashMap<>();
@@ -45,6 +48,10 @@ private DefaultContextStore(Builder builder) {
         } else {
             this.objectMap = Collections.emptyMap();
         }
+        this.keyMap =
+                builder.keyMap != null
+                        ? Collections.unmodifiableMap(new HashMap<>(builder.keyMap))
+                        : Collections.emptyMap();
     }
 
     /**
@@ -70,6 +77,17 @@ public <T> T get(String key, Class<T> type) {
         return null;
     }
 
+    /**
+     * Retrieves an object by key regardless of its registered runtime type.
+     *
+     * @param key The key identifying the instance
+     * @return The object instance, or null if not found
+     */
+    @Override
+    public Object get(String key) {
+        return keyMap.get(key);
+    }
+
     /**
      * Retrieves an object by type only (singleton case).
      *
@@ -98,6 +116,17 @@ public boolean contains(String key, Class<?> type) {
         return keyMap != null && keyMap.containsKey(key);
     }
 
+    /**
+     * Checks whether an object with the specified key exists regardless of its registered type.
+     *
+     * @param key The key identifying the instance
+     * @return true if the object exists, false otherwise
+     */
+    @Override
+    public boolean contains(String key) {
+        return keyMap.containsKey(key);
+    }
+
     /**
      * Checks whether any object of the specified type exists.
      *
@@ -146,22 +175,23 @@ public boolean equals(Object o) {
         if (this == o) return true;
         if (o == null || getClass() != o.getClass()) return false;
         DefaultContextStore that = (DefaultContextStore) o;
-        return Objects.equals(objectMap, that.objectMap);
+        return Objects.equals(objectMap, that.objectMap) && Objects.equals(keyMap, that.keyMap);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(objectMap);
+        return Objects.hash(objectMap, keyMap);
     }
 
     @Override
     public String toString() {
-        return "DefaultContextStore{" + "objectMap=" + objectMap + '}';
+        return "DefaultContextStore{" + "objectMap=" + objectMap + ", keyMap=" + keyMap + '}';
     }
 
     /** Builder for DefaultContextStore. */
     public static class Builder {
         private Map<Class<?>, Map<String, Object>> objectMap;
+        private Map<String, Object> keyMap;
 
         private Builder() {}
 
@@ -243,9 +273,14 @@ public <T> Builder register(String key, Class<T> type, T object) {
             if (this.objectMap == null) {
                 this.objectMap = new HashMap<>();
             }
-
             Map<String, Object> keyMap = this.objectMap.computeIfAbsent(type, k -> new HashMap<>());
             keyMap.put(key, object);
+
+            if (this.keyMap == null) {
+                this.keyMap = new HashMap<>();
+            }
+            this.keyMap.put(key, object);
+
             return this;
         }
 
diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutionContext.java b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutionContext.java
index d860f9c2cb..3b1f3a5f0f 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutionContext.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/ToolExecutionContext.java
@@ -75,6 +75,22 @@ public <T> T get(String key, Class<T> type) {
         return null;
     }
 
+    /**
+     * Retrieves an object by key without requiring the caller to know its registered type.
+     *
+     * @param key The key identifying the instance
+     * @return The object instance, or null if not found
+     */
+    public Object get(String key) {
+        for (ContextStore store : stores) {
+            Object obj = store.get(key);
+            if (obj != null) {
+                return obj;
+            }
+        }
+        return null;
+    }
+
     /**
      * Retrieves an object by type only (for singleton scenarios).
      *
@@ -109,6 +125,21 @@ public boolean contains(String key, Class<?> type) {
         return false;
     }
 
+    /**
+     * Checks whether an object with the specified key exists in any store, regardless of type.
+     *
+     * @param key The key identifying the instance
+     * @return true if any store contains the object, false otherwise
+     */
+    public boolean contains(String key) {
+        for (ContextStore store : stores) {
+            if (store.contains(key)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /**
      * Checks whether an object of the specified type exists in any store (regardless of key).
      *
diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentConfig.java b/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentConfig.java
index 66b3792fac..fcf89ef3d3 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentConfig.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentConfig.java
@@ -19,6 +19,15 @@
 import io.agentscope.core.session.InMemorySession;
 import io.agentscope.core.session.JsonSession;
 import io.agentscope.core.session.Session;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 
 /**
  * Configuration for sub-agent registration.
@@ -27,14 +36,34 @@
  * supports smart defaults that derive tool name and description from the agent itself.
  *
  * <p>Sub-agents operate in conversation mode, supporting multi-turn dialogue with session
- * management. The tool exposes two parameters:
+ * management. The tool exposes the following built-in parameters:
  *
  * <ul>
  *   <li>{@code message} - Required. The message to send to the agent.
- *   <li>{@code conversation_id} - Optional. Omit to start a new conversation, provide to continue
+ *   <li>{@code session_id} - Optional. Omit to start a new conversation, provide to continue
  *       an existing one.
  * </ul>
  *
+ * <p>Users can also define additional parameters to be passed to the sub-agent. The framework
+ * strictly separates these into two categories for security:
+ *
+ * <ul>
+ *   <li><b>Custom Parameters:</b> Added via {@link Builder#addParameter}. These are exposed to the
+ *       LLM in the tool schema, allowing the LLM to infer and generate values based on the
+ *       conversation. Required custom parameters are also placed in the JSON Schema {@code
+ *       required} array, so they must be present in the tool call input before the tool is
+ *       executed.
+ *   <li><b>System Parameters:</b> Added via {@link Builder#addSystemParameter}. These are strictly
+ *       injected by the system via {@code ToolExecutionContext}. They are completely transparent
+ *       (invisible) to the LLM, preventing prompt injection. Use system parameters for sensitive
+ *       values or for values that should be supplied only by backend context.
+ * </ul>
+ *
+ * <p>A parameter name can belong to only one category. If the same value is useful both as a
+ * model-visible business hint and as a backend override, declare it as a custom parameter and let
+ * {@code ToolExecutionContext} override the LLM-provided value at runtime. If the value is
+ * security-sensitive, declare it as a system parameter instead.
+ *
  * <p><b>Default Behavior:</b>
  *
  * <ul>
@@ -50,11 +79,12 @@
  * // Minimal configuration - uses all defaults
  * SubAgentConfig config = SubAgentConfig.defaults();
  *
- * // Custom configuration with persistent session
+ * // Custom configuration with persistent session and custom parameters
  * SubAgentConfig config = SubAgentConfig.builder()
  *     .toolName("ask_expert")
  *     .description("Ask the expert a question")
  *     .session(new JsonSession(Path.of("sessions")))
+ *     .addParameter("userId", "string", "The user ID", true)
  *     .build();
  * }</pre>
  */
@@ -65,6 +95,10 @@ public class SubAgentConfig {
     private final boolean forwardEvents;
     private final StreamOptions streamOptions;
     private final Session session;
+    private final Map<String, Map<String, Object>> customParameters;
+    private final List<String> requiredCustomParameters;
+    private final Set<String> systemParameters;
+    private static final Set<String> RESERVED_PARAMETER_NAMES = Set.of("message", "session_id");
 
     private SubAgentConfig(Builder builder) {
         this.toolName = builder.toolName;
@@ -72,6 +106,11 @@ private SubAgentConfig(Builder builder) {
         this.forwardEvents = builder.forwardEvents;
         this.streamOptions = builder.streamOptions;
         this.session = builder.session != null ? builder.session : new InMemorySession();
+        this.customParameters = copyCustomParameters(builder.customParameters);
+        this.requiredCustomParameters =
+                Collections.unmodifiableList(new ArrayList<>(builder.requiredCustomParameters));
+        this.systemParameters =
+                Collections.unmodifiableSet(new LinkedHashSet<>(builder.systemParameters));
     }
 
     /**
@@ -148,6 +187,126 @@ public Session getSession() {
         return session;
     }
 
+    /**
+     * Gets the custom parameters defined for the sub-agent tool.
+     *
+     * <p>The returned map and nested JSON-schema containers are immutable defensive copies of the
+     * builder input.
+     *
+     * @return A map of parameter names to their JSON schema definitions
+     */
+    public Map<String, Map<String, Object>> getCustomParameters() {
+        return customParameters;
+    }
+
+    /**
+     * Gets the list of required custom parameter names.
+     *
+     * <p>These names are used to populate the generated JSON Schema {@code required} array for
+     * model-visible custom parameters. They are validated by the tool executor before
+     * {@code ToolExecutionContext} is merged into the tool call; use {@link Builder#addSystemParameter}
+     * for context-only required values.
+     *
+     * @return A list containing the names of required parameters
+     */
+    public List<String> getRequiredCustomParameters() {
+        return requiredCustomParameters;
+    }
+
+    /**
+     * Gets the system parameters defined for the sub-agent tool.
+     *
+     * <p>System parameters are injected transparently via ToolExecutionContext and are NOT exposed
+     * to the LLM in the JSON schema.
+     *
+     * @return A set containing the names of system parameters
+     */
+    public Set<String> getSystemParameters() {
+        return systemParameters;
+    }
+
+    /**
+     * Creates an immutable defensive copy of the custom parameter schema map.
+     *
+     * <p>Custom parameter schemas are JSON-Schema-like trees supplied by users through
+     * {@link Builder#addParameter(String, Map, boolean)}. They can contain nested maps and lists
+     * such as {@code properties}, {@code items}, {@code enum}, and {@code required}. Because a
+     * {@link SubAgentConfig} instance is treated as immutable after {@link Builder#build()}, this
+     * method recursively copies and freezes JSON-style containers so later mutations to the builder
+     * or to caller-owned schema objects cannot change the generated tool schema.
+     *
+     * <p>The copy intentionally handles JSON-style values only: {@link Map}, {@link List},
+     * {@link Set}, scalar values, and {@code null}. Nested map keys must be strings because JSON
+     * object keys are strings. Sets are copied as immutable lists to preserve stable JSON array
+     * semantics when schemas are serialized.
+     *
+     * @param source The custom parameter definitions keyed by parameter name
+     * @return An immutable copy of the custom parameter definitions
+     * @throws IllegalArgumentException If a parameter name is null or a nested schema map contains
+     *     a non-string key
+     * @throws NullPointerException If any parameter schema map is null
+     */
+    private static Map<String, Map<String, Object>> copyCustomParameters(
+            Map<String, Map<String, Object>> source) {
+        if (source == null || source.isEmpty()) {
+            return Collections.emptyMap();
+        }
+
+        Map<String, Map<String, Object>> copy = new LinkedHashMap<>();
+        for (Map.Entry<String, Map<String, Object>> entry : source.entrySet()) {
+            if (entry.getKey() == null) {
+                throw new IllegalArgumentException("Parameter name cannot be null.");
+            }
+            copy.put(entry.getKey(), immutableSchemaMap(entry.getValue()));
+        }
+        return Collections.unmodifiableMap(copy);
+    }
+
+    private static Map<String, Object> immutableSchemaMap(Map<String, Object> source) {
+        Objects.requireNonNull(source, "Parameter schema cannot be null.");
+
+        Map<String, Object> copy = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> entry : source.entrySet()) {
+            if (entry.getKey() == null) {
+                throw new IllegalArgumentException("Parameter schema key cannot be null.");
+            }
+            copy.put(entry.getKey(), immutableJsonValue(entry.getValue()));
+        }
+        return Collections.unmodifiableMap(copy);
+    }
+
+    private static Object immutableJsonValue(Object value) {
+        if (value instanceof Map<?, ?> mapValue) {
+            Map<String, Object> copy = new LinkedHashMap<>();
+            for (Map.Entry<?, ?> entry : mapValue.entrySet()) {
+                if (!(entry.getKey() instanceof String key)) {
+                    throw new IllegalArgumentException(
+                            "JSON schema object keys must be strings: " + entry.getKey());
+                }
+                copy.put(key, immutableJsonValue(entry.getValue()));
+            }
+            return Collections.unmodifiableMap(copy);
+        }
+
+        if (value instanceof List<?> listValue) {
+            List<Object> copy = new ArrayList<>(listValue.size());
+            for (Object item : listValue) {
+                copy.add(immutableJsonValue(item));
+            }
+            return Collections.unmodifiableList(copy);
+        }
+
+        if (value instanceof Set<?> setValue) {
+            List<Object> copy = new ArrayList<>(setValue.size());
+            for (Object item : setValue) {
+                copy.add(immutableJsonValue(item));
+            }
+            return Collections.unmodifiableList(copy);
+        }
+
+        return value;
+    }
+
     /** Builder for SubAgentConfig. */
     public static class Builder {
         private String toolName;
@@ -155,6 +314,9 @@ public static class Builder {
         private boolean forwardEvents = true;
         private StreamOptions streamOptions;
         private Session session;
+        private Map<String, Map<String, Object>> customParameters = new HashMap<>();
+        private List<String> requiredCustomParameters = new ArrayList<>();
+        private Set<String> systemParameters = new LinkedHashSet<>();
 
         private Builder() {}
 
@@ -229,6 +391,124 @@ public Builder session(Session session) {
             return this;
         }
 
+        /**
+         * Adds a simple custom parameter to the tool's JSON schema.
+         *
+         * <p>This is a convenience method for adding basic parameters. For complex schemas (e.g.,
+         * enums, arrays), use {@link #addParameter(String, Map, boolean)}.
+         *
+         * <p>If {@code required} is true, the parameter is included in the generated JSON Schema
+         * {@code required} array. That means the LLM/tool caller must provide it in the tool input;
+         * backend context can override the provided value, but it cannot satisfy this
+         * pre-execution schema requirement by itself.
+         *
+         * @param name The name of the parameter
+         * @param type The type of the parameter (e.g., "string", "integer")
+         * @param description The description of the parameter
+         * @param required true if the parameter is required, false otherwise
+         * @return This builder
+         */
+        public Builder addParameter(
+                String name, String type, String description, boolean required) {
+            Map<String, Object> prop = new HashMap<>();
+            prop.put("type", type);
+            prop.put("description", description);
+            return addParameter(name, prop, required);
+        }
+
+        /**
+         * Adds a custom parameter with a fully defined JSON schema.
+         *
+         * <p>This method allows for advanced JSON schema features like enums, nested objects, or
+         * arrays, enabling precise control over how the language model understands the parameter.
+         *
+         * <p>Custom parameters are model-visible. When {@code required} is true, the parameter is
+         * also model-required via JSON Schema validation before the tool is invoked. The backend can
+         * still provide a same-name value through {@code ToolExecutionContext}; that value overrides
+         * the LLM input at runtime, but the tool call must still include the required field to pass
+         * schema validation. Use {@link #addSystemParameter(String)} for values that should be
+         * supplied only by backend context.
+         *
+         * @param name The name of the parameter
+         * @param schema The JSON schema map definition for the parameter
+         * @param required true if the parameter must be generated in the tool input, false
+         *     otherwise
+         * @return This builder
+         * @throws IllegalArgumentException If the {@code name} is null, empty, reserved, already
+         *     declared as a system parameter, or if {@code schema} is empty.
+         * @throws NullPointerException If {@code schema} is null.
+         */
+        public Builder addParameter(String name, Map<String, Object> schema, boolean required) {
+            String normalizedName = normalizeParameterName(name, "Parameter");
+            Objects.requireNonNull(schema, "Parameter schema cannot be null.");
+            if (schema.isEmpty()) {
+                throw new IllegalArgumentException("Parameter schema cannot be empty.");
+            }
+
+            if (systemParameters.contains(normalizedName)) {
+                throw new IllegalArgumentException(
+                        "Cannot declare parameter '"
+                                + normalizedName
+                                + "' as both custom and system parameter.");
+            }
+
+            this.customParameters.put(normalizedName, new HashMap<>(schema));
+            if (required) {
+                if (!this.requiredCustomParameters.contains(normalizedName)) {
+                    this.requiredCustomParameters.add(normalizedName);
+                }
+            } else {
+                this.requiredCustomParameters.remove(normalizedName);
+            }
+            return this;
+        }
+
+        /**
+         * Adds a system parameter (e.g., userId) to be injected securely.
+         *
+         * <p>Unlike custom parameters, system parameters are completely invisible to the
+         * language model and will NOT be included in the generated JSON schema. They are
+         * extracted strictly from the {@link io.agentscope.core.tool.ToolExecutionContext}
+         * at runtime, preventing prompt injection attacks and LLM hallucination.
+         *
+         * <p>Use this for security-sensitive values, such as authenticated user IDs or tenant IDs,
+         * and for values that must be supplied by backend context rather than by the LLM. System
+         * parameter names cannot also be declared as custom parameters.
+         *
+         * @param name The name of the system parameter
+         * @return This builder
+         * @throws IllegalArgumentException If the {@code name} is null, empty, reserved, or already
+         * declared as a custom parameter.
+         */
+        public Builder addSystemParameter(String name) {
+            String normalizedName = normalizeParameterName(name, "System parameter");
+
+            if (customParameters.containsKey(normalizedName)) {
+                throw new IllegalArgumentException(
+                        "Cannot declare parameter '"
+                                + normalizedName
+                                + "' as both custom and system parameter.");
+            }
+
+            this.systemParameters.add(normalizedName);
+            return this;
+        }
+
+        private String normalizeParameterName(String name, String label) {
+            if (name == null || name.trim().isEmpty()) {
+                throw new IllegalArgumentException(label + " name cannot be null or empty.");
+            }
+
+            String normalizedName = name.trim();
+            if (RESERVED_PARAMETER_NAMES.contains(normalizedName)) {
+                throw new IllegalArgumentException(
+                        "Cannot use reserved parameter name: '"
+                                + normalizedName
+                                + "'. This is a built-in parameter.");
+            }
+            return normalizedName;
+        }
+
         /**
          * Builds the configuration.
          *
diff --git a/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentTool.java b/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentTool.java
index 068e44c658..8d08c5bb0a 100644
--- a/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentTool.java
+++ b/agentscope-core/src/main/java/io/agentscope/core/tool/subagent/SubAgentTool.java
@@ -27,12 +27,16 @@
 import io.agentscope.core.tool.AgentTool;
 import io.agentscope.core.tool.ToolCallParam;
 import io.agentscope.core.tool.ToolEmitter;
+import io.agentscope.core.tool.ToolExecutionContext;
 import io.agentscope.core.util.JsonUtils;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Set;
 import java.util.UUID;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -47,13 +51,26 @@
  * <p>Thread safety is ensured by using {@link SubAgentProvider} to create a fresh agent instance
  * for each new session.
  *
- * <p>The tool exposes two parameters:
+ * <p>By default, the tool exposes two core parameters:
  *
  * <ul>
  *   <li>{@code session_id} - Optional. Omit to start a new session, provide to continue an
  *       existing one.
  *   <li>{@code message} - Required. The message to send to the agent.
  * </ul>
+ *
+ * <p>Additionally, the tool supports two categories of external parameters defined in
+ * {@link SubAgentConfig}:
+ * <ul>
+ *   <li><b>System Parameters:</b> Extracted strictly from {@link ToolExecutionContext}. These are
+ *       invisible to the LLM and completely tamper-proof.
+ *   <li><b>Custom Parameters:</b> Exposed to the LLM in the JSON schema. If marked as required,
+ *       the LLM MUST provide a value, and the framework will validate its presence BEFORE execution.
+ *       While {@link ToolExecutionContext} can forcefully override the LLM's value at runtime,
+ *       it cannot bypass the initial schema validation. <em>Rule of thumb: If the LLM should
+ *       infer it, use Custom Parameters; if the LLM shouldn't know about it, use System Parameters.</em>
+ * </ul>
+ * Both types of parameters are securely injected into the sub-agent's message {@code metadata}.
  */
 public class SubAgentTool implements AgentTool {
 
@@ -116,6 +133,11 @@ public Mono<ToolResultBlock> callAsync(ToolCallParam param) {
      * <ul>
      *   <li>Session ID generation for new conversations
      *   <li>Agent state loading for continued sessions
+     *   <li>Extraction of external parameters with strict priority:
+     *       {@link ToolExecutionContext} (highest) &gt; LLM input (lowest). For required custom
+     *       parameters, this override occurs after schema validation has already required the LLM
+     *       tool call to contain the field.
+     *   <li>Secure injection of custom parameters into the message metadata
      *   <li>Message execution (streaming or non-streaming based on config)
      *   <li>Agent state persistence after execution
      * </ul>
@@ -142,6 +164,45 @@ private Mono<ToolResultBlock> executeConversation(ToolCallParam param) {
                             return Mono.just(ToolResultBlock.error("Message is required"));
                         }
 
+                        // Extract external parameters
+                        Map<String, Object> finalMetadata = new HashMap<>();
+                        ToolExecutionContext context = param.getContext();
+
+                        // 1. Extract system parameters (Securely injected, invisible to LLM)
+                        Set<String> declaredSystemParams = config.getSystemParameters();
+                        if (declaredSystemParams != null && !declaredSystemParams.isEmpty()) {
+                            for (String paramName : declaredSystemParams) {
+                                Object ctxValue = extractFromContext(context, paramName);
+                                if (ctxValue != null) {
+                                    finalMetadata.put(paramName, ctxValue);
+                                } else {
+                                    logger.warn(
+                                            "System parameter '{}' was declared but not provided in"
+                                                    + " ToolExecutionContext",
+                                            paramName);
+                                }
+                            }
+                        }
+
+                        // 2. Extract custom parameters. These are visible in the JSON Schema.
+                        // Required custom parameters are validated by ToolExecutor before this
+                        // method runs; context only overrides the value selected by the LLM.
+                        Map<String, Map<String, Object>> declaredCustomParams =
+                                config.getCustomParameters();
+                        if (declaredCustomParams != null && !declaredCustomParams.isEmpty()) {
+                            for (String paramName : declaredCustomParams.keySet()) {
+                                Object ctxValue = extractFromContext(context, paramName);
+                                if (ctxValue != null) {
+                                    finalMetadata.put(paramName, ctxValue);
+                                    continue;
+                                }
+
+                                if (input.containsKey(paramName) && input.get(paramName) != null) {
+                                    finalMetadata.put(paramName, input.get(paramName));
+                                }
+                            }
+                        }
+
                         // Create agent for this session
                         final String finalSessionId = sessionId;
                         Agent agent = agentProvider.provide();
@@ -156,6 +217,7 @@ private Mono<ToolResultBlock> executeConversation(ToolCallParam param) {
                                 Msg.builder()
                                         .role(MsgRole.USER)
                                         .content(TextBlock.builder().text(message).build())
+                                        .metadata(finalMetadata)
                                         .build();
 
                         logger.debug(
@@ -190,6 +252,45 @@ private Mono<ToolResultBlock> executeConversation(ToolCallParam param) {
                 });
     }
 
+    /**
+     * Extracts a value from the ToolExecutionContext by parameter key.
+     *
+     * @param context   The execution context
+     * @param paramName The name of the parameter to extract
+     * @return The extracted value, or null if not found
+     */
+    private Object extractFromContext(ToolExecutionContext context, String paramName) {
+        if (context == null) {
+            return null;
+        }
+
+        Object ctxValue = context.get(paramName);
+        if (ctxValue != null) {
+            return ctxValue;
+        }
+
+        ctxValue = context.get(paramName, String.class);
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, Integer.class);
+        }
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, Boolean.class);
+        }
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, Double.class);
+        }
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, Map.class);
+        }
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, List.class);
+        }
+        if (ctxValue == null) {
+            ctxValue = context.get(paramName, Object.class);
+        }
+        return ctxValue;
+    }
+
     /**
      * Loads agent state from the session storage.
      *
@@ -350,13 +451,19 @@ private ToolResultBlock buildResult(Msg response, String sessionId) {
     /**
      * Builds the JSON schema for tool parameters.
      *
-     * <p>Creates a schema with two properties:
+     * <p>Creates a schema with two core properties:
      *
      * <ul>
      *   <li>{@code session_id} - Optional string for continuing existing conversations
      *   <li>{@code message} - Required string containing the message to send
      * </ul>
      *
+     * <p>If custom parameters are defined in the configuration, they are merged into the properties
+     * map, and required custom parameters are added to the JSON Schema {@code required} array. This
+     * intentionally keeps required custom parameters model-visible and pre-validated. Use system
+     * parameters for context-only required values. The schema strictly disables {@code
+     * additionalProperties}.
+     *
      * @return A map representing the JSON schema for tool parameters
      */
     private Map<String, Object> buildSchema() {
@@ -381,8 +488,22 @@ private Map<String, Object> buildSchema() {
         messageProp.put("description", "Message to send to the agent");
         properties.put(PARAM_MESSAGE, messageProp);
 
+        // Custom parameters
+        Map<String, Map<String, Object>> customParams = config.getCustomParameters();
+        if (customParams != null && !customParams.isEmpty()) {
+            properties.putAll(customParams);
+        }
+
         schema.put("properties", properties);
-        schema.put("required", List.of(PARAM_MESSAGE));
+        schema.put("additionalProperties", false);
+
+        // Prevent duplicate elements from appearing in the required array
+        Set<String> requiredFields = new LinkedHashSet<>();
+        requiredFields.add(PARAM_MESSAGE);
+        if (config.getRequiredCustomParameters() != null) {
+            requiredFields.addAll(config.getRequiredCustomParameters());
+        }
+        schema.put("required", new ArrayList<>(requiredFields));
 
         return schema;
     }
diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentConfigTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentConfigTest.java
index 15b5ab7ab9..ccba8b77e1 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentConfigTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentConfigTest.java
@@ -16,15 +16,21 @@
 package io.agentscope.core.tool.subagent;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import io.agentscope.core.agent.EventType;
 import io.agentscope.core.agent.StreamOptions;
 import io.agentscope.core.session.InMemorySession;
 import io.agentscope.core.session.Session;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
@@ -156,6 +162,179 @@ void testDefaultSessionWhenNotSpecified() {
             assertInstanceOf(InMemorySession.class, config.getSession());
         }
 
+        @Test
+        @DisplayName("Should throw exception when adding reserved parameter name")
+        void testAddReservedParameterThrowsException() {
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addParameter("message", "string", "Invalid param", true),
+                    "Should throw IllegalArgumentException for reserved 'message'");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addParameter("session_id", "string", "Invalid param", false),
+                    "Should throw IllegalArgumentException for reserved 'session_id'");
+        }
+
+        @Test
+        @DisplayName("Should throw exception when parameter name is empty")
+        void testAddEmptyParameterNameThrowsException() {
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addParameter("", "string", "Invalid param", true));
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addParameter(null, "string", "Invalid param", true));
+        }
+
+        @Test
+        @DisplayName("Should build config with simple custom parameter")
+        void testSimpleCustomParameter() {
+            SubAgentConfig config =
+                    SubAgentConfig.builder()
+                            .addParameter("userId", "string", "The user ID", true)
+                            .build();
+
+            assertNotNull(config.getCustomParameters());
+            assertEquals(1, config.getCustomParameters().size());
+
+            Map<String, Object> paramConfig = config.getCustomParameters().get("userId");
+            assertNotNull(paramConfig);
+            assertEquals("string", paramConfig.get("type"));
+            assertEquals("The user ID", paramConfig.get("description"));
+
+            assertNotNull(config.getRequiredCustomParameters());
+            assertTrue(config.getRequiredCustomParameters().contains("userId"));
+        }
+
+        @Test
+        @DisplayName("Should build config with schema custom parameter")
+        void testSchemaCustomParameter() {
+            Map<String, Object> enumSchema = new HashMap<>();
+            List<String> enumValues = new ArrayList<>(List.of("admin", "user"));
+            enumSchema.put("type", "string");
+            enumSchema.put("enum", enumValues);
+            enumSchema.put("description", "The user role");
+
+            SubAgentConfig config =
+                    SubAgentConfig.builder().addParameter("role", enumSchema, false).build();
+            enumValues.add("owner");
+            enumSchema.put("description", "Mutated description");
+
+            assertNotNull(config.getCustomParameters());
+            assertEquals(1, config.getCustomParameters().size());
+
+            Map<String, Object> paramConfig = config.getCustomParameters().get("role");
+            assertNotNull(paramConfig);
+            assertEquals("string", paramConfig.get("type"));
+            assertEquals("The user role", paramConfig.get("description"));
+            assertTrue(paramConfig.containsKey("enum"));
+            assertEquals(List.of("admin", "user"), paramConfig.get("enum"));
+
+            assertNotNull(config.getRequiredCustomParameters());
+            assertFalse(config.getRequiredCustomParameters().contains("role"));
+        }
+
+        @Test
+        @DisplayName("Should expose immutable custom parameter schemas")
+        @SuppressWarnings("unchecked")
+        void testCustomParameterSchemaIsImmutable() {
+            Map<String, Object> schema = new HashMap<>();
+            schema.put("type", "object");
+            schema.put("properties", Map.of("mode", Map.of("type", "string")));
+
+            SubAgentConfig config =
+                    SubAgentConfig.builder().addParameter("options", schema, false).build();
+
+            Map<String, Object> parameterSchema = config.getCustomParameters().get("options");
+            assertThrows(
+                    UnsupportedOperationException.class,
+                    () -> parameterSchema.put("description", "mutated"));
+
+            Map<String, Object> properties =
+                    (Map<String, Object>) parameterSchema.get("properties");
+            assertThrows(
+                    UnsupportedOperationException.class,
+                    () -> properties.put("extra", Map.of("type", "string")));
+        }
+
+        @Test
+        @DisplayName("Should throw exception when custom parameter schema is null or empty")
+        void testAddNullOrEmptyParameterSchemaThrowsException() {
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+
+            assertThrows(
+                    NullPointerException.class,
+                    () -> builder.addParameter("missingSchema", null, true));
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addParameter("emptySchema", Map.of(), true));
+        }
+
+        @Test
+        @DisplayName("Should reject non-string keys in nested custom parameter schemas")
+        void testRejectNonStringSchemaKeys() {
+            Map<Object, Object> nested = new HashMap<>();
+            nested.put(1, Map.of("type", "string"));
+
+            Map<String, Object> schema = new HashMap<>();
+            schema.put("type", "object");
+            schema.put("properties", nested);
+
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+            builder.addParameter("options", schema, false);
+
+            assertThrows(IllegalArgumentException.class, builder::build);
+        }
+
+        @Test
+        @DisplayName("Should reject parameter declared as both custom and system")
+        void testRejectCustomAndSystemParameterConflict() {
+            SubAgentConfig.Builder customFirst = SubAgentConfig.builder();
+            customFirst.addParameter("userId", "string", "User ID", true);
+
+            assertThrows(
+                    IllegalArgumentException.class, () -> customFirst.addSystemParameter("userId"));
+
+            SubAgentConfig.Builder systemFirst = SubAgentConfig.builder();
+            systemFirst.addSystemParameter("tenantId");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> systemFirst.addParameter("tenantId", "string", "Tenant ID", true));
+        }
+
+        @Test
+        @DisplayName("Should throw exception when adding reserved system parameter name")
+        void testAddReservedSystemParameterThrowsException() {
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addSystemParameter("message"),
+                    "Should throw IllegalArgumentException for reserved 'message'");
+
+            assertThrows(
+                    IllegalArgumentException.class,
+                    () -> builder.addSystemParameter("session_id"),
+                    "Should throw IllegalArgumentException for reserved 'session_id'");
+        }
+
+        @Test
+        @DisplayName("Should throw exception when system parameter name is empty")
+        void testAddEmptySystemParameterNameThrowsException() {
+            SubAgentConfig.Builder builder = SubAgentConfig.builder();
+
+            assertThrows(IllegalArgumentException.class, () -> builder.addSystemParameter(""));
+
+            assertThrows(IllegalArgumentException.class, () -> builder.addSystemParameter(null));
+        }
+
         @Test
         @DisplayName("Builder should be chainable")
         void testBuilderChaining() {
@@ -168,10 +347,28 @@ void testBuilderChaining() {
                             .forwardEvents(true)
                             .streamOptions(null)
                             .session(new InMemorySession())
+                            .addParameter("param", Map.of("type", "string"), true)
+                            .addSystemParameter("sysParam")
                             .build();
 
             assertNotNull(config);
         }
+
+        @Test
+        @DisplayName(
+                "Multiple builds from same builder should keep parameter snapshots independent")
+        void testMultipleBuildsKeepParameterSnapshotsIndependent() {
+            SubAgentConfig.Builder builder =
+                    SubAgentConfig.builder().addParameter("first", "string", "First", true);
+
+            SubAgentConfig config1 = builder.build();
+            builder.addParameter("second", "string", "Second", true);
+            SubAgentConfig config2 = builder.build();
+
+            assertTrue(config1.getCustomParameters().containsKey("first"));
+            assertFalse(config1.getCustomParameters().containsKey("second"));
+            assertTrue(config2.getCustomParameters().containsKey("second"));
+        }
     }
 
     @Nested
@@ -208,6 +405,30 @@ void testGetSessionNeverNull() {
             SubAgentConfig configWithNullSession = SubAgentConfig.builder().session(null).build();
             assertNotNull(configWithNullSession.getSession());
         }
+
+        @Test
+        @DisplayName("getCustomParameters() should return empty map when not set")
+        void testGetCustomParametersEmpty() {
+            SubAgentConfig config = SubAgentConfig.builder().build();
+            assertNotNull(config.getCustomParameters());
+            assertTrue(config.getCustomParameters().isEmpty());
+        }
+
+        @Test
+        @DisplayName("getRequiredCustomParameters() should return empty list when not set")
+        void testGetRequiredCustomParametersEmpty() {
+            SubAgentConfig config = SubAgentConfig.builder().build();
+            assertNotNull(config.getRequiredCustomParameters());
+            assertTrue(config.getRequiredCustomParameters().isEmpty());
+        }
+
+        @Test
+        @DisplayName("getSystemParameters() should return empty set when not set")
+        void testGetSystemParametersEmpty() {
+            SubAgentConfig config = SubAgentConfig.builder().build();
+            assertNotNull(config.getSystemParameters());
+            assertTrue(config.getSystemParameters().isEmpty());
+        }
     }
 
     @Nested
diff --git a/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentToolTest.java b/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentToolTest.java
index 198e046307..1f373f8ae0 100644
--- a/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentToolTest.java
+++ b/agentscope-core/src/test/java/io/agentscope/core/tool/subagent/SubAgentToolTest.java
@@ -18,6 +18,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
@@ -36,6 +37,7 @@
 import io.agentscope.core.message.ToolUseBlock;
 import io.agentscope.core.tool.ToolCallParam;
 import io.agentscope.core.tool.ToolEmitter;
+import io.agentscope.core.tool.ToolExecutionContext;
 import io.agentscope.core.tool.Toolkit;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -44,6 +46,7 @@
 import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
@@ -479,8 +482,237 @@ void testToolNameGenerationTruncation() {
         assertFalse(generatedName.contains("__"));
     }
 
+    @Test
+    @DisplayName("Should generate schema containing custom parameters but NOT system parameters")
+    void testSchemaWithCustomParameters() {
+        Agent mockAgent = createMockAgent("TestAgent", "Test");
+
+        SubAgentConfig config =
+                SubAgentConfig.builder()
+                        .addParameter("userId", "string", "The user ID", true)
+                        .addParameter("tenantId", "string", "The tenant ID", false)
+                        .addSystemParameter("secureSystemToken") // System parameter
+                        .build();
+
+        SubAgentTool tool = new SubAgentTool(() -> mockAgent, config);
+        Map<String, Object> schema = tool.getParameters();
+
+        @SuppressWarnings("unchecked")
+        Map<String, Object> properties = (Map<String, Object>) schema.get("properties");
+
+        // Custom params should exist
+        assertTrue(properties.containsKey("userId"));
+        assertTrue(properties.containsKey("tenantId"));
+        // System params MUST be invisible to LLM schema
+        assertFalse(properties.containsKey("secureSystemToken"));
+
+        @SuppressWarnings("unchecked")
+        List<String> required = (List<String>) schema.get("required");
+        assertTrue(required.contains("message"));
+        assertTrue(required.contains("userId"));
+        assertFalse(required.contains("tenantId"));
+    }
+
+    @Test
+    @DisplayName(
+            "Should extract custom parameters, prioritize Context override, and filter malicious"
+                    + " fields")
+    void testCustomParameterExtractionAndPriority() {
+        Agent mockAgent = createMockAgent("TestAgent", "Test");
+        SubAgentConfig config =
+                SubAgentConfig.builder()
+                        .forwardEvents(false)
+                        .addParameter("injectedUserId", "string", "User ID", true)
+                        .addParameter("tenantId", "string", "Tenant ID", false)
+                        .build();
+        SubAgentTool tool = new SubAgentTool(() -> mockAgent, config);
+
+        Map<String, Object> llmInput = new HashMap<>();
+        llmInput.put("message", "Hello");
+        llmInput.put("injectedUserId", "1001"); // Normal business parameters
+        llmInput.put("tenantId", "FAKE_TENANT_FROM_LLM"); // forge parameters
+        llmInput.put("maliciousField", "hacked"); // Undeclared malicious fields
+
+        ToolExecutionContext systemContext =
+                ToolExecutionContext.builder()
+                        .register("tenantId", "REAL_SYSTEM_TENANT_ID")
+                        .build();
+
+        ToolUseBlock toolUse =
+                ToolUseBlock.builder().id("1").name("call_testagent").input(llmInput).build();
+        tool.callAsync(
+                        ToolCallParam.builder()
+                                .toolUseBlock(toolUse)
+                                .input(llmInput)
+                                .context(systemContext)
+                                .build())
+                .block();
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<Msg>> captor = ArgumentCaptor.forClass(List.class);
+        verify(mockAgent).call(captor.capture());
+        Map<String, Object> metadata = captor.getValue().get(0).getMetadata();
+
+        assertNotNull(metadata);
+        assertEquals("1001", metadata.get("injectedUserId"));
+        assertEquals(
+                "REAL_SYSTEM_TENANT_ID",
+                metadata.get("tenantId"),
+                "System Context MUST override LLM input");
+        assertFalse(metadata.containsKey("maliciousField"));
+        assertFalse(metadata.containsKey("message"));
+    }
+
+    @Test
+    @DisplayName("Should let Context override LLM input for custom parameters of any runtime type")
+    void testCustomParameterContextOverrideForCustomRuntimeType() {
+        Agent mockAgent = createMockAgent("TestAgent", "Test");
+        SubAgentConfig config =
+                SubAgentConfig.builder()
+                        .forwardEvents(false)
+                        .addParameter("tenant", "object", "Tenant context", false)
+                        .build();
+        SubAgentTool tool = new SubAgentTool(() -> mockAgent, config);
+
+        Map<String, Object> llmInput = new HashMap<>();
+        llmInput.put("message", "Hello");
+        llmInput.put("tenant", "FAKE_TENANT_FROM_LLM");
+
+        TenantContext realTenant = new TenantContext("REAL_SYSTEM_TENANT_ID");
+        ToolExecutionContext systemContext =
+                ToolExecutionContext.builder().register("tenant", realTenant).build();
+
+        ToolUseBlock toolUse =
+                ToolUseBlock.builder().id("1").name("call_testagent").input(llmInput).build();
+        tool.callAsync(
+                        ToolCallParam.builder()
+                                .toolUseBlock(toolUse)
+                                .input(llmInput)
+                                .context(systemContext)
+                                .build())
+                .block();
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<Msg>> captor = ArgumentCaptor.forClass(List.class);
+        verify(mockAgent).call(captor.capture());
+        Map<String, Object> metadata = captor.getValue().get(0).getMetadata();
+
+        assertNotNull(metadata);
+        assertSame(realTenant, metadata.get("tenant"));
+    }
+
+    @Test
+    @DisplayName(
+            "Should securely inject system parameters and completely ignore LLM prompt injections")
+    void testSystemParameterSecurityAndInjectionDefense() {
+        Agent mockAgent = createMockAgent("DefenseAgent", "Test prompt injection defense");
+        SubAgentConfig config =
+                SubAgentConfig.builder()
+                        .forwardEvents(false)
+                        .addSystemParameter("authUserId") // System parameters with real context
+                        .addSystemParameter("adminBypassToken") // Forge system parameters by LLM
+                        .build();
+        SubAgentTool tool = new SubAgentTool(() -> mockAgent, config);
+
+        Map<String, Object> llmInput = new HashMap<>();
+        llmInput.put("message", "Hack system");
+        llmInput.put("adminBypassToken", "FORGED_TOKEN");
+
+        ToolExecutionContext systemContext =
+                ToolExecutionContext.builder().register("authUserId", "sys_user_999").build();
+
+        ToolUseBlock toolUse =
+                ToolUseBlock.builder().id("1").name("call_defenseagent").input(llmInput).build();
+        tool.callAsync(
+                        ToolCallParam.builder()
+                                .toolUseBlock(toolUse)
+                                .input(llmInput)
+                                .context(systemContext)
+                                .build())
+                .block();
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<Msg>> captor = ArgumentCaptor.forClass(List.class);
+        verify(mockAgent).call(captor.capture());
+        Map<String, Object> metadata = captor.getValue().get(0).getMetadata();
+
+        assertNotNull(metadata);
+        assertEquals("sys_user_999", metadata.get("authUserId"));
+        assertFalse(
+                metadata.containsKey("adminBypassToken"),
+                "Forged system parameter from LLM MUST be ignored");
+    }
+
+    @Test
+    @DisplayName("Should inject system parameters of any runtime type")
+    void testSystemParameterInjectionForCustomRuntimeType() {
+        Agent mockAgent = createMockAgent("DefenseAgent", "Test custom system context");
+        SubAgentConfig config =
+                SubAgentConfig.builder()
+                        .forwardEvents(false)
+                        .addSystemParameter("authContext")
+                        .build();
+        SubAgentTool tool = new SubAgentTool(() -> mockAgent, config);
+
+        Map<String, Object> llmInput = new HashMap<>();
+        llmInput.put("message", "Use secure context");
+        llmInput.put("authContext", "FORGED_AUTH_CONTEXT");
+
+        AuthContext authContext = new AuthContext("sys_user_999", List.of("read", "write"));
+        ToolExecutionContext systemContext =
+                ToolExecutionContext.builder().register("authContext", authContext).build();
+
+        ToolUseBlock toolUse =
+                ToolUseBlock.builder().id("1").name("call_defenseagent").input(llmInput).build();
+        tool.callAsync(
+                        ToolCallParam.builder()
+                                .toolUseBlock(toolUse)
+                                .input(llmInput)
+                                .context(systemContext)
+                                .build())
+                .block();
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<List<Msg>> captor = ArgumentCaptor.forClass(List.class);
+        verify(mockAgent).call(captor.capture());
+        Map<String, Object> metadata = captor.getValue().get(0).getMetadata();
+
+        assertNotNull(metadata);
+        assertSame(authContext, metadata.get("authContext"));
+    }
+
     // Helper methods
 
+    private static class TenantContext {
+        private final String tenantId;
+
+        private TenantContext(String tenantId) {
+            this.tenantId = tenantId;
+        }
+
+        String getTenantId() {
+            return tenantId;
+        }
+    }
+
+    private static class AuthContext {
+        private final String userId;
+        private final List<String> permissions;
+
+        private AuthContext(String userId, List<String> permissions) {
+            this.userId = userId;
+            this.permissions = permissions;
+        }
+
+        String getUserId() {
+            return userId;
+        }
+
+        List<String> getPermissions() {
+            return permissions;
+        }
+    }
+
     private Agent createMockAgent(String name, String description) {
         Agent agent = mock(Agent.class);
         when(agent.getName()).thenReturn(name);
diff --git a/docs/en/multi-agent/subagent.md b/docs/en/multi-agent/subagent.md
index 8c620bc708..da0325facc 100644
--- a/docs/en/multi-agent/subagent.md
+++ b/docs/en/multi-agent/subagent.md
@@ -108,6 +108,86 @@ The example uses **TaskToolsBuilder** to create the **Task** and **TaskOutput**
 
 **Synchronous vs background**: By default, the Task tool runs the sub-agent and returns its reply. If you pass a flag like `run_in_background=true`, the tool returns a `task_id` instead; the orchestrator (or user) can later call **TaskOutput** with that `task_id` to get the result. This requires a **TaskRepository** to store in-flight tasks.
 
+## Passing Custom Context and Parameters
+
+In real-world applications, you may need to pass additional parameters to a sub-agent alongside the `message`. `SubAgentTool` supports two distinct parameter categories:
+
+1. **Custom parameters (model-visible business variables)**: Declared with `addParameter`. They are included in the tool JSON Schema, so the LLM can infer them from the conversation (for example target language or analysis depth).
+2. **System parameters (backend-only security variables)**: Declared with `addSystemParameter`. They are injected from `ToolExecutionContext`, are not included in the tool JSON Schema, and cannot be supplied by the LLM (for example authenticated `userId` or `tenantId`).
+
+### 1. Declare parameters
+First, declare parameters via `SubAgentConfig`. A parameter name can be declared in only one category: use `addParameter` for values the model should see, and `addSystemParameter` for values that must come only from backend context.
+
+```java
+SubAgentConfig config = SubAgentConfig.builder()
+        // Visible to the LLM. Set required=true when the model must provide it in the tool call.
+        .addParameter("analysis_depth",
+                Map.of("type", "string", "enum", List.of("basic", "detailed")),
+                true)
+        // Invisible to the LLM. Must be supplied through ToolExecutionContext.
+        .addSystemParameter("userId")
+        .build();
+
+SubAgentTool tool = new SubAgentTool(agentProvider, config);
+```
+
+### 2. Examples of injection methods
+
+#### Method 1: Custom parameters (LLM dynamic injection)
+Suitable for **business properties**. Variables declared via `addParameter` (such as `analysis_depth`) are rendered into the JSON Schema passed to the LLM.
+When the user says: *"Help me do an extremely deep code review"*, the LLM can infer and generate the following call:
+```json
+{
+  "message": "Review the codebase",
+  "analysis_depth": "detailed" 
+}
+```
+
+If `required=true`, the parameter is also placed in the JSON Schema `required` array. This means the tool call must include the field before `SubAgentTool` is invoked; `ToolExecutor` performs schema validation before context injection. A same-name value in `ToolExecutionContext` can still override the LLM-provided value at runtime, but it does not bypass the pre-execution schema requirement.
+
+Use `required=false` when the LLM may omit a business parameter. Use `addSystemParameter` when the value must be supplied only by backend context.
+
+#### Method 2: System parameters (backend context injection)
+Suitable for **sensitive security properties** (e.g., `userId`). Variables declared via `addSystemParameter` are **completely invisible** to the LLM. The system injects them directly at runtime.
+```java
+// Register the context at the system entry point
+ToolExecutionContext context = ToolExecutionContext.builder()
+        .register("userId", String.class, "user_123") // Explicitly specify the type as String.class
+        .build();
+
+// Pass the context during execution
+ToolCallParam param = ToolCallParam.builder()
+        .toolUseBlock(toolUseBlock)
+        .input(Map.of("message", "Check my order"))
+        .context(context)
+        .build();
+
+tool.callAsync(param).subscribe();
+```
+
+> **🔒 Security and Priority**
+> Because system parameters (such as `userId`) are declared via `addSystemParameter`, they will not appear in the schema sent to the LLM. At runtime, the framework extracts them strictly from `ToolExecutionContext`. Even if a malicious prompt causes the LLM to emit `"userId": "admin"`, the fake value is ignored because `userId` is not a model-visible custom parameter.
+
+> **Required custom vs. system parameters**
+> A required custom parameter is required from the LLM/tool-call input because it is part of the JSON Schema. A system parameter is required from backend context because it is not part of the schema. Do not use a required custom parameter for security-sensitive context-only values.
+
+### 3. Retrieve parameters in the sub-agent
+Regardless of the injection method, the parameters are ultimately and securely mounted in the `metadata` of the input message received by the sub-agent. The extraction method is identical:
+
+```java
+public Mono<Msg> call(List<Msg> messages) {
+    Msg userMsg = messages.get(messages.size() - 1);
+    Map<String, Object> metadata = userMsg.getMetadata();
+    
+    // Retrieve the system-injected security parameter
+    String userId = (String) metadata.get("userId");
+    // Retrieve the LLM-injected business parameter
+    String depth = (String) metadata.get("analysis_depth");
+    
+    // ... execute specific logic based on these parameters ...
+}
+```
+
 ## Example: Tech Due Diligence Assistant
 
 The AgentScope example implements a **Tech Due Diligence Assistant**: one orchestrator that delegates to four sub-agents.
diff --git a/docs/zh/multi-agent/subagent.md b/docs/zh/multi-agent/subagent.md
index fa83a4d31b..e5279b60aa 100644
--- a/docs/zh/multi-agent/subagent.md
+++ b/docs/zh/multi-agent/subagent.md
@@ -108,6 +108,86 @@ TaskToolsBuilder.builder()
 
 **同步与后台**：默认 Task 工具会运行子智能体并返回其回复。若传入类似 `run_in_background=true` 的标志，工具会返回 `task_id`；编排智能体（或用户）之后可用 **TaskOutput** 传入该 `task_id` 获取结果。这需要 **TaskRepository** 存储进行中的任务。
 
+## 传递自定义上下文与参数
+
+在实际业务中，可能需要向子智能体传递除 `message` 之外的额外参数。`SubAgentTool` 支持两类参数：
+
+1. **自定义参数（大模型可见的业务变量）**：通过 `addParameter` 声明，会进入工具 JSON Schema，由大模型根据对话内容推断（如：翻译目标语言、分析深度）。
+2. **系统参数（后端注入的安全变量）**：通过 `addSystemParameter` 声明，由底层系统通过 `ToolExecutionContext` 注入，不会进入工具 JSON Schema，大模型无法提供这类参数（如：已认证的 `userId`、`tenantId`）。
+
+### 1. 声明参数
+首先，通过 `SubAgentConfig` 声明参数。同一个参数名只能属于一类：需要让大模型看到和生成的值使用 `addParameter`；必须仅由后端上下文提供的值使用 `addSystemParameter`。
+
+```java
+SubAgentConfig config = SubAgentConfig.builder()
+        // 大模型可见。required=true 表示大模型必须在工具调用中提供该字段。
+        .addParameter("analysis_depth",
+                Map.of("type", "string", "enum", List.of("basic", "detailed")),
+                true)
+        // 大模型不可见。必须通过 ToolExecutionContext 注入。
+        .addSystemParameter("userId")
+        .build();
+
+SubAgentTool tool = new SubAgentTool(agentProvider, config);
+```
+
+### 2. 两种注入方式示例
+
+#### 方式一：自定义参数（大模型动态注入）
+适用于**业务属性**。通过 `addParameter` 声明的变量（如 `analysis_depth`）会被渲染进传递给大模型的 JSON Schema 中。
+当用户说：*“帮我进行极其深入的代码审查”* 时，大模型可以推断并生成如下调用：
+```json
+{
+  "message": "审查代码库",
+  "analysis_depth": "detailed" 
+}
+```
+
+如果 `required=true`，该参数还会进入 JSON Schema 的 `required` 数组。这意味着工具调用必须在进入 `SubAgentTool` 之前就包含这个字段；`ToolExecutor` 会先做 schema 校验，然后才会合并上下文。`ToolExecutionContext` 中的同名值仍然可以在运行时覆盖大模型提供的值，但它不会绕过这一步预执行 schema 校验。
+
+如果业务参数允许大模型省略，请设置 `required=false`。如果某个值必须只由后端上下文提供，请使用 `addSystemParameter`。
+
+#### 方式二：系统参数（后端上下文注入）
+适用于**敏感安全属性**（如 `userId`）。通过 `addSystemParameter` 声明的变量对大模型**完全隐身**。系统会在运行时直接注入它们。
+```java
+// 在系统入口处注册上下文
+ToolExecutionContext context = ToolExecutionContext.builder()
+        .register("userId", String.class, "user_123") // 明确指定类型为 String.class
+        .build();
+
+// 执行时传入 context
+ToolCallParam param = ToolCallParam.builder()
+        .toolUseBlock(toolUseBlock)
+        .input(Map.of("message", "查一下我的订单"))
+        .context(context)
+        .build();
+
+tool.callAsync(param).subscribe();
+```
+
+> **🔒 安全与优先级**
+> 由于系统参数（如 `userId`）是通过 `addSystemParameter` 声明的，它不会出现在发送给大模型的 schema 中。框架在运行时严格从 `ToolExecutionContext` 中提取它们。即使恶意提示词诱导大模型输出 `"userId": "admin"`，这个假值也会被忽略，因为 `userId` 不是大模型可见的自定义参数。
+
+> **必填自定义参数与系统参数**
+> 必填自定义参数是 JSON Schema 层面的必填字段，要求大模型/工具调用输入提供。系统参数则是后端上下文层面的参数，不属于 JSON Schema。不要把安全敏感、仅由上下文提供的值声明为必填自定义参数。
+
+### 3. 在子智能体中读取参数
+无论参数是通过哪种方式注入的，最终都会被安全地挂载到子智能体输入消息的 `metadata` 中。提取方式完全一致：
+
+```java
+public Mono<Msg> call(List<Msg> messages) {
+    Msg userMsg = messages.get(messages.size() - 1);
+    Map<String, Object> metadata = userMsg.getMetadata();
+    
+    // 获取系统注入的安全参数
+    String userId = (String) metadata.get("userId");
+    // 获取大模型注入的业务参数
+    String depth = (String) metadata.get("analysis_depth");
+    
+    // ... 基于这些参数执行特定逻辑 ...
+}
+```
+
 ## 示例：技术尽调助手
 
 AgentScope 示例实现了一个**技术尽调助手**：一个编排智能体委托给四个子智能体。