Standardize repository-backed session configuration keys

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs

@@ -462,7 +462,10 @@ public sealed record SubscribeResult
 ///
 /// After creation, the client should subscribe to the session URI to receive state
 /// updates. The server also broadcasts a `root/sessionAdded` notification to all
-/// clients.</summary>
+/// clients.
+///
+/// Repository preparation MUST finish before `session/ready` or executing turns.
+/// Clients recover the outcome from session state, not progress notifications.</summary>
 public sealed record CreateSessionParams
 {
     /// <summary>Session URI (client-chosen, e.g. `ahp-session:/&lt;uuid&gt;`)</summary>
@@ -490,12 +493,16 @@ public sealed record CreateSessionParams
     /// {@link AgentCapabilities.multipleWorkingDirectories}; a server without that
     /// capability treats only the first entry as the session's working directory
     /// and ignores the rest. Dispatch working-directory actions to change the set
-    /// after the session has started.</summary>
+    /// after the session has started.
+    ///
+    /// A non-empty list and repository intent in `config` are mutually exclusive.
+    /// A repository URI identifies the source, not a working-directory URI; one
+    /// source may produce multiple directories.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<string>? WorkingDirectories { get; init; }
 
-    /// <summary>Agent-specific configuration values collected via `resolveSessionConfig`.
-    /// Keys and values correspond to the schema returned by the server.</summary>
+    /// <summary>Session configuration values collected via `resolveSessionConfig`.
+    /// Keys and values follow the advertised {@link SessionConfigSchema}.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public Dictionary<string, JsonElement>? Config { get; init; }
 
@@ -524,7 +531,10 @@ public sealed record CreateSessionParams
 
 /// <summary>Disposes a session and cleans up server-side resources.
 ///
-/// The server broadcasts a `root/sessionRemoved` notification to all clients.</summary>
+/// The server broadcasts a `root/sessionRemoved` notification to all clients.
+/// Disposal MUST NOT erase a shared checkout or uncommitted user changes.
+/// Repository cleanup remains host-owned; ending a client's wait or subscription
+/// does not grant permission to delete repository data.</summary>
 public sealed record DisposeSessionParams
 {
     /// <summary>Channel URI this command targets.</summary>
@@ -1346,7 +1356,10 @@ public sealed record DisposeTerminalParams
 /// The client calls this command whenever the user changes a significant input
 /// (e.g. picks a working directory, toggles a property). Each response returns
 /// the full current property set (not a delta). The returned `values` contain
-/// server-resolved defaults to pass to `createSession`.</summary>
+/// server-resolved defaults to pass to `createSession`.
+///
+/// This command MUST NOT clone or prepare a repository. Standard repository
+/// inputs and their advertisement requirements are defined by {@link SessionConfigSchema}.</summary>
 public sealed record ResolveSessionConfigParams
 {
     public required string Channel { get; init; }
@@ -1365,7 +1378,7 @@ public sealed record ResolveSessionConfigParams
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? WorkingDirectory { get; init; }
 
-    /// <summary>Current user-filled configuration values</summary>
+    /// <summary>Current user-filled configuration values; see {@link SessionConfigSchema}.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public Dictionary<string, JsonElement>? Config { get; init; }
 }

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Notifications.generated.cs

@@ -117,7 +117,9 @@ public sealed record SessionSummaryChangedParams
 ///   the client then never shows an indicator.
 /// - Like all notifications this is ephemeral and is **not** replayed on
 ///   reconnect. A client that never receives the terminal frame SHOULD expire
-///   the indicator after an idle timeout.</summary>
+///   the indicator after an idle timeout.
+/// - Completion of reported work does not establish session readiness.
+///   Observe session lifecycle state for the durable outcome.</summary>
 public sealed record ProgressParams
 {
     /// <summary>Channel URI this notification belongs to (the root channel).</summary>

clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/State.generated.cs

@@ -1586,7 +1586,10 @@ public sealed class SessionState
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? DefaultChat { get; set; }
 
-    /// <summary>Session configuration schema and current values</summary>
+    /// <summary>Session configuration schema and current values. For repository-backed
+    /// creation, this includes the advertised standard properties and requested
+    /// `repositorySource` and optional `repositoryRevision` values throughout
+    /// `creating`, `ready`, and `failed`, so clients can recover intent from state.</summary>
     [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public SessionConfigState? Config { get; set; }
 
@@ -2007,7 +2010,20 @@ public sealed record SessionConfigPropertySchema
     public bool? SessionMutable { get; init; }
 }
 
-/// <summary>A JSON Schema object describing available session configuration metadata.</summary>
+/// <summary>A JSON Schema object describing available session configuration metadata.
+///
+/// Repository-backed creation uses the standard optional config keys
+/// `repositorySource` (a credential-free repository URI) and
+/// `repositoryRevision` (a branch, tag, or commit). Support is advertised by
+/// `properties.repositorySource`; `properties.repositoryRevision` MUST NOT be
+/// advertised without it. Each advertised property MUST have `type: 'string'`
+/// and MUST NOT have `readOnly: true` or `sessionMutable: true`.
+///
+/// The host MUST NOT accept repository inputs unless their corresponding
+/// properties are advertised. Values travel through `resolveSessionConfig.config`
+/// and `createSession.config`; schema discovery MUST NOT prepare a repository.
+/// Neither key is globally required. Without repository intent, existing
+/// directory/default behavior is unchanged. Other property ids remain host-defined.</summary>
 public sealed record SessionConfigSchema
 {
     /// <summary>JSON Schema: always `'object'`</summary>

clients/go/ahptypes/commands.generated.go

@@ -375,6 +375,9 @@ type SubscribeResult struct {
 // After creation, the client should subscribe to the session URI to receive state
 // updates. The server also broadcasts a `root/sessionAdded` notification to all
 // clients.
+//
+// Repository preparation MUST finish before `session/ready` or executing turns.
+// Clients recover the outcome from session state, not progress notifications.
 type CreateSessionParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -396,9 +399,13 @@ type CreateSessionParams struct {
 	// capability treats only the first entry as the session's working directory
 	// and ignores the rest. Dispatch working-directory actions to change the set
 	// after the session has started.
+	//
+	// A non-empty list and repository intent in `config` are mutually exclusive.
+	// A repository URI identifies the source, not a working-directory URI; one
+	// source may produce multiple directories.
 	WorkingDirectories []URI `json:"workingDirectories,omitempty"`
-	// Agent-specific configuration values collected via `resolveSessionConfig`.
-	// Keys and values correspond to the schema returned by the server.
+	// Session configuration values collected via `resolveSessionConfig`.
+	// Keys and values follow the advertised {@link SessionConfigSchema}.
 	Config map[string]json.RawMessage `json:"config,omitempty"`
 	// Eagerly claim an active client role for the new session.
 	//
@@ -423,6 +430,9 @@ type CreateSessionParams struct {
 // Disposes a session and cleans up server-side resources.
 //
 // The server broadcasts a `root/sessionRemoved` notification to all clients.
+// Disposal MUST NOT erase a shared checkout or uncommitted user changes.
+// Repository cleanup remains host-owned; ending a client's wait or subscription
+// does not grant permission to delete repository data.
 type DisposeSessionParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -1070,6 +1080,9 @@ type DisposeTerminalParams struct {
 // (e.g. picks a working directory, toggles a property). Each response returns
 // the full current property set (not a delta). The returned `values` contain
 // server-resolved defaults to pass to `createSession`.
+//
+// This command MUST NOT clone or prepare a repository. Standard repository
+// inputs and their advertisement requirements are defined by {@link SessionConfigSchema}.
 type ResolveSessionConfigParams struct {
 	// Channel URI this command targets.
 	Channel URI `json:"channel"`
@@ -1080,7 +1093,7 @@ type ResolveSessionConfigParams struct {
 	Provider *string `json:"provider,omitempty"`
 	// Working directory for the session
 	WorkingDirectory *URI `json:"workingDirectory,omitempty"`
-	// Current user-filled configuration values
+	// Current user-filled configuration values; see {@link SessionConfigSchema}.
 	Config map[string]json.RawMessage `json:"config,omitempty"`
 }
 

clients/go/ahptypes/notifications.generated.go

@@ -115,6 +115,8 @@ type SessionSummaryChangedParams struct {
 //   - Like all notifications this is ephemeral and is **not** replayed on
 //     reconnect. A client that never receives the terminal frame SHOULD expire
 //     the indicator after an idle timeout.
+//   - Completion of reported work does not establish session readiness.
+//     Observe session lifecycle state for the durable outcome.
 type ProgressParams struct {
 	// Channel URI this notification belongs to (the root channel).
 	Channel URI `json:"channel"`

clients/go/ahptypes/state.generated.go

@@ -905,7 +905,10 @@ type SessionState struct {
 	// marker — chats remain equal peers at the protocol level. Hosts MAY change
 	// this over the session's lifetime.
 	DefaultChat *URI `json:"defaultChat,omitempty"`
-	// Session configuration schema and current values
+	// Session configuration schema and current values. For repository-backed
+	// creation, this includes the advertised standard properties and requested
+	// `repositorySource` and optional `repositoryRevision` values throughout
+	// `creating`, `ready`, and `failed`, so clients can recover intent from state.
 	Config *SessionConfigState `json:"config,omitempty"`
 	// Top-level customizations active in this session.
 	//
@@ -1365,6 +1368,19 @@ type SessionConfigPropertySchema struct {
 }
 
 // A JSON Schema object describing available session configuration metadata.
+//
+// Repository-backed creation uses the standard optional config keys
+// `repositorySource` (a credential-free repository URI) and
+// `repositoryRevision` (a branch, tag, or commit). Support is advertised by
+// `properties.repositorySource`; `properties.repositoryRevision` MUST NOT be
+// advertised without it. Each advertised property MUST have `type: 'string'`
+// and MUST NOT have `readOnly: true` or `sessionMutable: true`.
+//
+// The host MUST NOT accept repository inputs unless their corresponding
+// properties are advertised. Values travel through `resolveSessionConfig.config`
+// and `createSession.config`; schema discovery MUST NOT prepare a repository.
+// Neither key is globally required. Without repository intent, existing
+// directory/default behavior is unchanged. Other property ids remain host-defined.
 type SessionConfigSchema struct {
 	// JSON Schema: always `'object'`
 	Type string `json:"type"`

clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt

@@ -617,11 +617,15 @@ data class CreateSessionParams(
      * capability treats only the first entry as the session's working directory
      * and ignores the rest. Dispatch working-directory actions to change the set
      * after the session has started.
+     *
+     * A non-empty list and repository intent in `config` are mutually exclusive.
+     * A repository URI identifies the source, not a working-directory URI; one
+     * source may produce multiple directories.
      */
     val workingDirectories: List<String>? = null,
     /**
-     * Agent-specific configuration values collected via `resolveSessionConfig`.
-     * Keys and values correspond to the schema returned by the server.
+     * Session configuration values collected via `resolveSessionConfig`.
+     * Keys and values follow the advertised {@link SessionConfigSchema}.
      */
     val config: Map<String, JsonElement>? = null,
     /**
@@ -1317,7 +1321,7 @@ data class ResolveSessionConfigParams(
      */
     val workingDirectory: String? = null,
     /**
-     * Current user-filled configuration values
+     * Current user-filled configuration values; see {@link SessionConfigSchema}.
      */
     val config: Map<String, JsonElement>? = null
 )

clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt

@@ -1802,7 +1802,10 @@ data class SessionState(
      */
     val defaultChat: String? = null,
     /**
-     * Session configuration schema and current values
+     * Session configuration schema and current values. For repository-backed
+     * creation, this includes the advertised standard properties and requested
+     * `repositorySource` and optional `repositoryRevision` values throughout
+     * `creating`, `ready`, and `failed`, so clients can recover intent from state.
      */
     val config: SessionConfigState? = null,
     /**

clients/rust/crates/ahp-types/src/commands.rs

@@ -558,6 +558,9 @@ pub struct SubscribeResult {
 /// After creation, the client should subscribe to the session URI to receive state
 /// updates. The server also broadcasts a `root/sessionAdded` notification to all
 /// clients.
+///
+/// Repository preparation MUST finish before `session/ready` or executing turns.
+/// Clients recover the outcome from session state, not progress notifications.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CreateSessionParams {
@@ -583,10 +586,14 @@ pub struct CreateSessionParams {
     /// capability treats only the first entry as the session's working directory
     /// and ignores the rest. Dispatch working-directory actions to change the set
     /// after the session has started.
+    ///
+    /// A non-empty list and repository intent in `config` are mutually exclusive.
+    /// A repository URI identifies the source, not a working-directory URI; one
+    /// source may produce multiple directories.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub working_directories: Option<Vec<Uri>>,
-    /// Agent-specific configuration values collected via `resolveSessionConfig`.
-    /// Keys and values correspond to the schema returned by the server.
+    /// Session configuration values collected via `resolveSessionConfig`.
+    /// Keys and values follow the advertised {@link SessionConfigSchema}.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub config: Option<JsonObject>,
     /// Eagerly claim an active client role for the new session.
@@ -614,6 +621,9 @@ pub struct CreateSessionParams {
 /// Disposes a session and cleans up server-side resources.
 ///
 /// The server broadcasts a `root/sessionRemoved` notification to all clients.
+/// Disposal MUST NOT erase a shared checkout or uncommitted user changes.
+/// Repository cleanup remains host-owned; ending a client's wait or subscription
+/// does not grant permission to delete repository data.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DisposeSessionParams {
@@ -1374,6 +1384,9 @@ pub struct DisposeTerminalParams {
 /// (e.g. picks a working directory, toggles a property). Each response returns
 /// the full current property set (not a delta). The returned `values` contain
 /// server-resolved defaults to pass to `createSession`.
+///
+/// This command MUST NOT clone or prepare a repository. Standard repository
+/// inputs and their advertisement requirements are defined by {@link SessionConfigSchema}.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ResolveSessionConfigParams {
@@ -1389,7 +1402,7 @@ pub struct ResolveSessionConfigParams {
     /// Working directory for the session
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub working_directory: Option<Uri>,
-    /// Current user-filled configuration values
+    /// Current user-filled configuration values; see {@link SessionConfigSchema}.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub config: Option<JsonObject>,
 }

clients/rust/crates/ahp-types/src/notifications.rs

@@ -153,6 +153,8 @@ pub struct SessionSummaryChangedParams {
 /// - Like all notifications this is ephemeral and is **not** replayed on
 ///   reconnect. A client that never receives the terminal frame SHOULD expire
 ///   the indicator after an idle timeout.
+/// - Completion of reported work does not establish session readiness.
+///   Observe session lifecycle state for the durable outcome.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ProgressParams {

clients/rust/crates/ahp-types/src/state.rs

@@ -2053,7 +2053,10 @@ pub struct SessionState {
     /// this over the session's lifetime.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub default_chat: Option<Uri>,
-    /// Session configuration schema and current values
+    /// Session configuration schema and current values. For repository-backed
+    /// creation, this includes the advertised standard properties and requested
+    /// `repositorySource` and optional `repositoryRevision` values throughout
+    /// `creating`, `ready`, and `failed`, so clients can recover intent from state.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub config: Option<SessionConfigState>,
     /// Top-level customizations active in this session.
@@ -2464,6 +2467,19 @@ pub struct SessionConfigPropertySchema {
 }
 
 /// A JSON Schema object describing available session configuration metadata.
+///
+/// Repository-backed creation uses the standard optional config keys
+/// `repositorySource` (a credential-free repository URI) and
+/// `repositoryRevision` (a branch, tag, or commit). Support is advertised by
+/// `properties.repositorySource`; `properties.repositoryRevision` MUST NOT be
+/// advertised without it. Each advertised property MUST have `type: 'string'`
+/// and MUST NOT have `readOnly: true` or `sessionMutable: true`.
+///
+/// The host MUST NOT accept repository inputs unless their corresponding
+/// properties are advertised. Values travel through `resolveSessionConfig.config`
+/// and `createSession.config`; schema discovery MUST NOT prepare a repository.
+/// Neither key is globally required. Without repository intent, existing
+/// directory/default behavior is unchanged. Other property ids remain host-defined.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SessionConfigSchema {

clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift

@@ -651,9 +651,13 @@ public struct CreateSessionParams: Codable, Sendable {
     /// capability treats only the first entry as the session's working directory
     /// and ignores the rest. Dispatch working-directory actions to change the set
     /// after the session has started.
+    ///
+    /// A non-empty list and repository intent in `config` are mutually exclusive.
+    /// A repository URI identifies the source, not a working-directory URI; one
+    /// source may produce multiple directories.
     public var workingDirectories: [String]?
-    /// Agent-specific configuration values collected via `resolveSessionConfig`.
-    /// Keys and values correspond to the schema returned by the server.
+    /// Session configuration values collected via `resolveSessionConfig`.
+    /// Keys and values follow the advertised {@link SessionConfigSchema}.
     public var config: [String: AnyCodable]?
     /// Eagerly claim an active client role for the new session.
     ///
@@ -1596,7 +1600,7 @@ public struct ResolveSessionConfigParams: Codable, Sendable {
     public var provider: String?
     /// Working directory for the session
     public var workingDirectory: String?
-    /// Current user-filled configuration values
+    /// Current user-filled configuration values; see {@link SessionConfigSchema}.
     public var config: [String: AnyCodable]?
 
     enum CodingKeys: String, CodingKey {