fix(tools): never drop the sub-agent 🔑 notice — wrap every return through one helper

The "🔑 Your agent_id is: ..." notice is the only signal a freshly
allocated sub-agent has for learning its own ID. It used to be emitted
inline by:

  - GetCurrentLocation success path (line ~192)
  - InvokeExpression case "success" branch (only when startupNotice was set)
  - StartConsole new + reuse paths

Every other return path forgot to add it. Sub-agents could lose their
allocated ID forever if their first call landed on:

  - GetCurrentLocation with no ready pipe — delegated to StartConsole
    with the already-allocated agent_id, so the inner ResolveAgentId
    saw isNewlyAllocated=false and the inner success path stayed silent.
  - InvokeExpression cases "timeout", "Completed" (cached), "error" —
    branches built their own response and never appended the notice.
  - InvokeExpression busy auto-route — recurses with is_subagent:false,
    inner stays silent, outer''s busyResponse never adds the notice.
  - Any drift bail / var1 enforcement / pipe-error early return.

Fix: add a single PrependAgentIdNoticeIfNew helper and a per-method
local Wrap function, then route every return through Wrap. The helper
is a no-op when isNewlyAllocated=false, so the common path
(is_subagent=false or already-known agent_id) is unchanged. Inline
🔑 emissions removed from the three legacy sites so we don''t
double-up.

Trade-off: the notice now appears at the very top of the response
instead of being interleaved with the startupNotice block. AI parses
the same text either way; emit-from-one-place is what makes future
branches automatically correct.

4 unit tests added: success-path notice (regression guard),
error-path notice (the previously-broken case), default-agent silence,
provided-agent-id silence.

Build clean. xunit: net8 162/162, net9 275/275 (+4 from this change).
Note: Unit/Proxy/** is net9-only by csproj convention because the
Proxy project itself is net9-only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: yotsuda

PowerShell.MCP.Proxy/Tools/PowerShellTools.cs

@@ -110,6 +110,20 @@ private static (string agentId, bool isNewlyAllocated, string? error) ResolveAge
         return ("default", false, null);
     }
 
+    /// <summary>
+    /// Prepends the 🔑 agent_id notice to a tool response when a new sub-agent
+    /// ID was just allocated. No-op for the common case (isNewlyAllocated=false),
+    /// so this can be applied unconditionally to every return path of a tool method.
+    /// Centralizing the emit here is what guarantees the notice can't be dropped by
+    /// timeout / cached-completed / error / busy-route / drift-bail / auto-start
+    /// branches the way it was when each branch had to remember to add it.
+    /// </summary>
+    private static string PrependAgentIdNoticeIfNew(string body, bool isNewlyAllocated, string agentId)
+    {
+        if (!isNewlyAllocated) return body;
+        return $"🔑 Your agent_id is: {agentId} — pass this in all subsequent tool calls.\n\n{body}";
+    }
+
     [McpServerTool]
     [Description("Retrieves the current location and all available drives (providers) from the PowerShell session. Returns current_location and other_drive_locations array. Call this when you need to understand the current PowerShell context, as users may change location during the session. When executing multiple invoke_expression commands in succession, calling once at the beginning is sufficient.")]
     public static async Task<string> GetCurrentLocation(
@@ -122,17 +136,24 @@ public static async Task<string> GetCurrentLocation(
         CancellationToken cancellationToken = default)
     {
         var (agentId, isNewlyAllocated, error) = ResolveAgentId(is_subagent, agent_id);
+        // Wrap every return so the 🔑 notice can never be dropped on a sub-agent's
+        // first call regardless of which branch builds the response.
+        string Wrap(string r) => PrependAgentIdNoticeIfNew(r, isNewlyAllocated, agentId);
         if (error != null)
-            return error;
+            return Wrap(error);
 
         // Find a ready pipe
         var (readyPipeName, consoleSwitched, closedConsoleMessages, allPipesStatusInfo, _) = await FindReadyPipeAsync(pipeDiscoveryService, agentId, cancellationToken);
 
         if (readyPipeName == null)
         {
-            // No ready pipe - auto-start (StartConsole includes busy info collection)
+            // No ready pipe - auto-start (StartConsole includes busy info collection).
+            // Pass is_subagent: false because the sub-agent ID was already allocated
+            // here; if we passed it as true the inner StartConsole would skip its own
+            // ResolveAgentId allocation but our Wrap would still add the notice. Either
+            // shape works; passing false makes the inner call's intent explicit.
             Console.Error.WriteLine($"[INFO] No ready PowerShell console found, auto-starting... Reason: {allPipesStatusInfo}");
-            return await StartConsole(powerShellService, pipeDiscoveryService, agent_id: agentId, is_subagent: is_subagent, cancellationToken: cancellationToken);
+            return Wrap(await StartConsole(powerShellService, pipeDiscoveryService, agent_id: agentId, is_subagent: false, cancellationToken: cancellationToken));
         }
 
         try
@@ -168,18 +189,13 @@ public static async Task<string> GetCurrentLocation(
             {
                 response.Append(completedOutputs);
             }
-            if (isNewlyAllocated)
-            {
-                response.AppendLine($"🔑 Your agent_id is: {agentId} — pass this in all subsequent tool calls.");
-                response.AppendLine();
-            }
             response.Append(result);
-            return response.ToString();
+            return Wrap(response.ToString());
         }
         catch (Exception ex)
         {
             Console.Error.WriteLine($"[ERROR] GetCurrentLocation failed: {ex.Message}");
-            return $"Failed to get current location: {ex.Message}\n\nPlease try again. A new console will be started automatically if needed.";
+            return Wrap($"Failed to get current location: {ex.Message}\n\nPlease try again. A new console will be started automatically if needed.");
         }
     }
 
@@ -248,8 +264,11 @@ public static async Task<string> InvokeExpression(
         }
 
         var (agentId, isNewlyAllocated, resolveError) = ResolveAgentId(is_subagent, agent_id);
+        // Wrap every return so the 🔑 notice can never be dropped on a sub-agent's
+        // first call regardless of which branch builds the response.
+        string Wrap(string r) => PrependAgentIdNoticeIfNew(r, isNewlyAllocated, agentId);
         if (resolveError != null)
-            return resolveError;
+            return Wrap(resolveError);
 
         var sessionManager = ConsoleSessionManager.Instance;
         // Find a ready pipe
@@ -283,7 +302,7 @@ public static async Task<string> InvokeExpression(
             var (success, locationResult) = await StartConsoleInternal(powerShellService, agentId, null, autoStartLocation, cancellationToken);
             if (!success)
             {
-                return locationResult; // Error message
+                return Wrap(locationResult); // Error message
             }
 
             // Pick up the freshly-spawned pipe so the rest of this call
@@ -292,7 +311,7 @@ public static async Task<string> InvokeExpression(
             readyPipeName = sessionManager.GetActivePipeName(agentId);
             if (readyPipeName == null)
             {
-                return "Failed to acquire newly-started console pipe.";
+                return Wrap("Failed to acquire newly-started console pipe.");
             }
 
             await SetConsoleTitleAsync(powerShellService, readyPipeName, cancellationToken);
@@ -324,7 +343,7 @@ public static async Task<string> InvokeExpression(
         var var1Error = PipelineHelper.CheckVar1Enforcement(pipeline, var1, var2);
         if (var1Error != null)
         {
-            return var1Error;
+            return Wrap(var1Error);
         }
 
         // Cwd drift detection: if the user typed `cd` in the visible console
@@ -360,7 +379,7 @@ public static async Task<string> InvokeExpression(
             }
             bailResponse.AppendLine($"ℹ️ User changed cwd in console {driftConsoleName} from '{drift.Value.AiCwd}' to '{drift.Value.LiveCwd}'.");
             bailResponse.AppendLine($"Pipeline NOT executed. Re-issue to run at '{drift.Value.LiveCwd}', or prepend `Set-Location -LiteralPath '{drift.Value.AiCwd.Replace("'", "''")}';` to revert.");
-            return bailResponse.ToString();
+            return Wrap(bailResponse.ToString());
         }
 
         // Execute the command
@@ -418,7 +437,7 @@ public static async Task<string> InvokeExpression(
                                     var (startSuccess, startError) = await StartConsoleInternal(powerShellService, agentId, null, startLoc, cancellationToken);
                                     if (!startSuccess)
                                     {
-                                        return startError;
+                                        return Wrap(startError);
                                     }
 
                                     // Set console window title
@@ -465,7 +484,7 @@ public static async Task<string> InvokeExpression(
                                     busyResponse.AppendLine($"ℹ️ Auto-routed to {newConsoleName} at {startLoc} (source console busy with {jsonResponse.Reason}). Pipeline executed automatically — no re-send needed.");
                                     busyResponse.AppendLine();
                                     busyResponse.Append(retryResult);
-                                    return busyResponse.ToString();
+                                    return Wrap(busyResponse.ToString());
                                 }
                                 break;
 
@@ -522,7 +541,7 @@ public static async Task<string> InvokeExpression(
                                     timeoutResponse.AppendLine();
                                     timeoutResponse.AppendLine(scopeWarning);
                                 }
-                                return timeoutResponse.ToString();
+                                return Wrap(timeoutResponse.ToString());
 
                             case PipeStatus.Completed:
                                 // Snapshot AI-intended cwd from the cached completion.
@@ -589,10 +608,10 @@ public static async Task<string> InvokeExpression(
                                 {
                                     cachedResponse.Append("Result cached. Will be returned on next tool call.");
                                 }
-                                return cachedResponse.ToString();
+                                return Wrap(cachedResponse.ToString());
 
                             case "error":
-                                return jsonResponse.Message ?? $"Error from PowerShell.MCP module: {jsonResponse.Error}";
+                                return Wrap(jsonResponse.Message ?? $"Error from PowerShell.MCP module: {jsonResponse.Error}");
 
                             case "success":
                                 // Snapshot AI-intended cwd at successful completion. This
@@ -632,10 +651,6 @@ public static async Task<string> InvokeExpression(
                                 if (!string.IsNullOrEmpty(startupNotice))
                                 {
                                     successResponse.AppendLine(startupNotice);
-                                    if (isNewlyAllocated)
-                                    {
-                                        successResponse.AppendLine($"🔑 Your agent_id is: {agentId} — pass this in all subsequent tool calls.");
-                                    }
                                     successResponse.AppendLine();
                                 }
                                 if (completedOutput.Length > 0)
@@ -670,7 +685,7 @@ public static async Task<string> InvokeExpression(
                                 //     successResponse.AppendLine();
                                 //     successResponse.AppendLine(jsonHint);
                                 // }
-                                return successResponse.ToString();
+                                return Wrap(successResponse.ToString());
                         }
                     }
                 }
@@ -681,7 +696,7 @@ public static async Task<string> InvokeExpression(
             }
 
             // Fallback: return result as-is (shouldn't happen with new DLL)
-            return result;
+            return Wrap(result);
         }
         catch (Exception ex)
         {
@@ -692,7 +707,7 @@ public static async Task<string> InvokeExpression(
             var otherClosed = pipeDiscoveryService.DetectClosedConsoles(agentId);
             var closedMessages = new List<string> { $"  - ⚠ Console {consoleName} was closed" };
             closedMessages.AddRange(otherClosed);
-            return $"Command execution failed: {ex.Message}\n{string.Join("\n", closedMessages)}\nPlease try again. A new console will be started automatically if needed.";
+            return Wrap($"Command execution failed: {ex.Message}\n{string.Join("\n", closedMessages)}\nPlease try again. A new console will be started automatically if needed.");
         }
     }
 
@@ -909,8 +924,11 @@ public static async Task<string> StartConsole(
         CancellationToken cancellationToken = default)
     {
         var (agentId, isNewlyAllocated, resolveError) = ResolveAgentId(is_subagent, agent_id);
+        // Wrap every return so the 🔑 notice can never be dropped on a sub-agent's
+        // first call regardless of which branch builds the response.
+        string Wrap(string r) => PrependAgentIdNoticeIfNew(r, isNewlyAllocated, agentId);
         if (resolveError != null)
-            return resolveError;
+            return Wrap(resolveError);
 
         var forceNew = !string.IsNullOrEmpty(reason);
 
@@ -969,13 +987,9 @@ await powerShellService.ExecuteSilentAsync(
                     reuseResponse.Append(reuseCompletedOutput);
                 }
                 reuseResponse.AppendLine("ℹ️ Did not launch a new console. An existing standby console is available and will be reused. To force a new console, provide the reason parameter.");
-                if (isNewlyAllocated)
-                {
-                    reuseResponse.AppendLine($"🔑 Your agent_id is: {agentId} — pass this in all subsequent tool calls.");
-                }
                 reuseResponse.AppendLine();
                 reuseResponse.Append(reuseLocationResult);
-                return reuseResponse.ToString();
+                return Wrap(reuseResponse.ToString());
             }
             // No standby console found, fall through to create a new one
         }
@@ -985,7 +999,7 @@ await powerShellService.ExecuteSilentAsync(
         var (success, startResult) = await StartConsoleInternal(powerShellService, agentId, startupCommands, resolvedPath, cancellationToken);
         if (!success)
         {
-            return startResult; // Error message
+            return Wrap(startResult); // Error message
         }
 
         // Set console window title
@@ -1015,13 +1029,9 @@ await powerShellService.ExecuteSilentAsync(
             response.AppendLine();
         }
         response.AppendLine("PowerShell console started successfully with PowerShell.MCP module imported.");
-        if (isNewlyAllocated)
-        {
-            response.AppendLine($"🔑 Your agent_id is: {agentId} — pass this in all subsequent tool calls.");
-        }
         response.AppendLine();
         response.Append(startResult);
-        return response.ToString();
+        return Wrap(response.ToString());
     }
 
     /// <summary>

Tests/Unit/Proxy/PowerShellToolsTests.cs

@@ -135,6 +135,109 @@ public async Task GetCurrentLocation_PipeError_ReturnsErrorMessage()
         Assert.Contains("Pipe communication failed", result);
     }
 
+    [Fact]
+    public async Task GetCurrentLocation_SubAgentNewAllocation_ReadyPipe_EmitsAgentIdNotice()
+    {
+        // Sub-agent's first call must include the 🔑 agent_id notice in the response
+        // so the AI knows which ID to pass to subsequent tool calls. Success-path
+        // regression guard.
+        _mockPipeDiscoveryService
+            .Setup(s => s.FindReadyPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>(), It.IsAny<bool>()))
+            .ReturnsAsync(new PipeDiscoveryResult(TestPipeName, false, new List<string>(), null));
+
+        _mockPowerShellService
+            .Setup(s => s.GetCurrentLocationFromPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync("Location [FileSystem]: C:\\test");
+
+        _mockPipeDiscoveryService
+            .Setup(s => s.CollectAllCachedOutputsAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new CachedOutputResult("", ""));
+
+        var result = await PowerShellTools.GetCurrentLocation(
+            _mockPowerShellService.Object,
+            _mockPipeDiscoveryService.Object,
+            agent_id: null,
+            is_subagent: true);
+
+        Assert.Contains("🔑 Your agent_id is:", result);
+    }
+
+    [Fact]
+    public async Task GetCurrentLocation_SubAgentNewAllocation_PipeError_StillEmitsAgentIdNotice()
+    {
+        // Regression: previously the error / timeout / cached-completed branches did
+        // not emit 🔑. A sub-agent that hit any of those on its first call lost its
+        // allocated ID forever. The wrap-every-return refactor closes that hole.
+        _mockPipeDiscoveryService
+            .Setup(s => s.FindReadyPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>(), It.IsAny<bool>()))
+            .ReturnsAsync(new PipeDiscoveryResult(TestPipeName, false, new List<string>(), null));
+
+        _mockPowerShellService
+            .Setup(s => s.GetCurrentLocationFromPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ThrowsAsync(new InvalidOperationException("Pipe communication failed"));
+
+        var result = await PowerShellTools.GetCurrentLocation(
+            _mockPowerShellService.Object,
+            _mockPipeDiscoveryService.Object,
+            agent_id: null,
+            is_subagent: true);
+
+        Assert.Contains("🔑 Your agent_id is:", result);
+        Assert.Contains("Failed to get current location", result);
+    }
+
+    [Fact]
+    public async Task GetCurrentLocation_DefaultAgent_DoesNotEmitAgentIdNotice()
+    {
+        // Non-sub-agent (default) calls must NOT carry the 🔑 notice — it would just
+        // be noise. Verifies the wrap helper is a no-op when isNewlyAllocated=false.
+        _mockPipeDiscoveryService
+            .Setup(s => s.FindReadyPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>(), It.IsAny<bool>()))
+            .ReturnsAsync(new PipeDiscoveryResult(TestPipeName, false, new List<string>(), null));
+
+        _mockPowerShellService
+            .Setup(s => s.GetCurrentLocationFromPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync("Location [FileSystem]: C:\\test");
+
+        _mockPipeDiscoveryService
+            .Setup(s => s.CollectAllCachedOutputsAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new CachedOutputResult("", ""));
+
+        var result = await PowerShellTools.GetCurrentLocation(
+            _mockPowerShellService.Object,
+            _mockPipeDiscoveryService.Object);
+
+        Assert.DoesNotContain("🔑", result);
+    }
+
+    [Fact]
+    public async Task GetCurrentLocation_ProvidedAgentId_DoesNotEmitAgentIdNotice()
+    {
+        // When the AI passes back a previously-issued agent_id, no allocation happens
+        // so the 🔑 notice would be a duplicate. Must stay silent.
+        _mockPipeDiscoveryService
+            .Setup(s => s.FindReadyPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>(), It.IsAny<bool>()))
+            .ReturnsAsync(new PipeDiscoveryResult(TestPipeName, false, new List<string>(), null));
+
+        _mockPowerShellService
+            .Setup(s => s.GetCurrentLocationFromPipeAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync("Location [FileSystem]: C:\\test");
+
+        _mockPipeDiscoveryService
+            .Setup(s => s.CollectAllCachedOutputsAsync(It.IsAny<string>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new CachedOutputResult("", ""));
+
+        // Use a valid sa-* shaped ID so IsValidAgentId returns true
+        var validSubAgentId = ConsoleSessionManager.Instance.AllocateSubAgentId();
+        var result = await PowerShellTools.GetCurrentLocation(
+            _mockPowerShellService.Object,
+            _mockPipeDiscoveryService.Object,
+            agent_id: validSubAgentId,
+            is_subagent: true);
+
+        Assert.DoesNotContain("🔑", result);
+    }
+
     [Fact]
     public async Task GetCurrentLocation_ConsoleSwitched_SetsWindowTitle()
     {