feat: expand parity workflows and harden agent runtime

Author: Telli

README.md

@@ -74,8 +74,14 @@ Built-in REPL slash commands include `/help`, `/status`, `/doctor`, `/session`,
 Parity-oriented commands now include:
 
 - `models` / `/models`
+- `usage` / `/usage`
+- `cost` / `/cost`
+- `stats` / `/stats`
 - `connect` / `/connect`
+- `hooks` / `/hooks`
+- `skills` / `/skills`
 - `agents` / `/agents`
+- `todo` / `/todo`
 - `share` / `/share`
 - `unshare` / `/unshare`
 - `compact` / `/compact`
@@ -162,7 +168,7 @@ dotnet test SharpClawCode.sln --filter "FullyQualifiedName~ParityScenarioTests"
 | `--session <id>` | Reuse a specific SharpClaw session id for prompt execution |
 | `--agent <id>` | Select the active agent for prompt execution |
 
-Subcommands include `prompt`, `repl`, `doctor`, `status`, `session`, `models`, `connect`, `agents`, `share`, `unshare`, `compact`, `serve`, `commands`, `mcp`, `plugins`, `acp`, `bridge`, and `version`.
+Subcommands include `prompt`, `repl`, `doctor`, `status`, `session`, `models`, `usage`, `cost`, `stats`, `connect`, `hooks`, `skills`, `agents`, `todo`, `share`, `unshare`, `compact`, `serve`, `commands`, `mcp`, `plugins`, `acp`, `bridge`, and `version`.
 
 ## Documentation Map
 
@@ -218,7 +224,8 @@ All options are validated at startup via `IValidateOptions` implementations.
 ## Current Scope
 
 - The shared tooling layer is permission-aware across the runtime.
-- The current runtime includes multi-turn provider-backed tool execution with durable conversation history.
+- The current runtime includes multi-turn provider-backed tool execution with durable conversation history and session-backed prompt replay.
+- Agent-driven tool calls flow through the same approval and allowlist enforcement path used by direct tool execution, including caller-aware interactive approval behavior.
 - Operational commands support stable JSON output via `--output-format json`, which makes them useful in scripts and automation.
 - The embedded server exposes local JSON and SSE endpoints for prompts, sessions, sharing, status, and doctor flows.
 

docs/architecture.md

@@ -40,7 +40,7 @@ Test projects: **UnitTests**, **IntegrationTests**, **MockProvider**, **ParityHa
 4. **`SharpClawAgentBase`** delegates to **`AgentFrameworkBridge.RunAsync`**, which drives **`ProviderBackedAgentKernel`** (streaming `IModelProvider`, auth checks, **`ProviderExecutionException`** on hard failures).
 5. Turn completion updates session, checkpoints as implemented in **`ConversationRuntime`**, publishes events via **`IRuntimeEventPublisher`**.
 
-**Note:** `AgentRunContext` carries **`IToolExecutor`**, but the current **`AgentFrameworkBridge`** path does not attach SharpClaw tools to the Microsoft Agent Framework chat loop; **`AgentRunResult.ToolResults`** is empty in that bridge. Tools are still fully usable via **`IToolExecutor`** (tests and parity harness call it directly).
+**Note:** `AgentRunContext` carries **`IToolExecutor`**, and the current **`AgentFrameworkBridge`** path advertises the resolved tool set to the provider, executes tool calls through the permission-aware executor, and records tool results in the agent run result. Prompt references and tool approvals respect the caller's normalized interactivity mode.
 
 ### Operational commands
 

docs/runtime.md

@@ -31,7 +31,7 @@ The agent stack is described in [agents.md](agents.md).
 
 ## Context assembly
 
-**`PromptContextAssembler`** pulls workspace/session-aware data (skills registry, memory hooks, git context as wired today) into the prompt path before the agent runs.
+**`PromptContextAssembler`** pulls workspace/session-aware data (skills registry, todo state, memory hooks, git context as wired today) into the prompt path before the agent runs.
 
 It also includes a compact diagnostics summary from **`IWorkspaceDiagnosticsService`**, which currently surfaces configured diagnostics sources and build-derived findings for .NET workspaces.
 
@@ -73,7 +73,9 @@ The parity layer adds several runtime-owned services:
 - **`IAgentCatalogService`** — overlays configured specialist agents on top of built-in agents
 - **`IConversationCompactionService`** — creates durable session summaries stored in session metadata
 - **`IShareSessionService`** — creates and removes self-hosted share snapshots
-- **`IHookDispatcher`** — executes configured hook processes for turn/tool/share/server events
+- **`IHookDispatcher`** — executes configured hook processes for turn/tool/share/server events and exposes hook inspection/testing
+- **`ITodoService`** — persists session and workspace todo items under session metadata and `.sharpclaw/tasks.json`
+- **`IWorkspaceInsightsService`** — reconstructs durable usage, cost, and execution stats from persisted event logs
 
 These services are intentionally small and runtime-owned rather than separate orchestration subsystems.
 

src/SharpClaw.Code.Acp/AcpStdioHost.cs

@@ -190,7 +190,8 @@ private async Task<JsonObject> HandleSessionPromptAsync(
                     WorkingDirectory: workspace,
                     PermissionMode: PermissionMode.WorkspaceWrite,
                     OutputFormat: OutputFormat.Json,
-                    Metadata: new Dictionary<string, string> { ["acp"] = "true" }),
+                    Metadata: new Dictionary<string, string> { ["acp"] = "true" },
+                    IsInteractive: false),
                 cancellationToken)
             .ConfigureAwait(false);
 

src/SharpClaw.Code.Agents/Models/AgentRunContext.cs

@@ -24,6 +24,7 @@ namespace SharpClaw.Code.Agents.Models;
 /// Prior-turn messages assembled from session events. When non-empty these are prepended
 /// to the provider request so the model has multi-turn context.
 /// </param>
+/// <param name="IsInteractive">Whether tool approvals can interact with the caller.</param>
 public sealed record AgentRunContext(
     string SessionId,
     string TurnId,
@@ -38,4 +39,5 @@ public sealed record AgentRunContext(
     DelegatedTaskContract? DelegatedTask = null,
     PrimaryMode PrimaryMode = PrimaryMode.Build,
     IToolMutationRecorder? ToolMutationRecorder = null,
-    IReadOnlyList<ChatMessage>? ConversationHistory = null);
+    IReadOnlyList<ChatMessage>? ConversationHistory = null,
+    bool IsInteractive = true);

src/SharpClaw.Code.Agents/Services/AgentFrameworkBridge.cs

@@ -44,7 +44,7 @@ public async Task<AgentRunResult> RunAsync(AgentFrameworkRequest request, Cancel
             EnvironmentVariables: null,
             AllowedTools: allowedTools,
             AllowDangerousBypass: false,
-            IsInteractive: false,
+            IsInteractive: request.Context.IsInteractive,
             SourceKind: PermissionRequestSourceKind.Runtime,
             SourceName: null,
             TrustedPluginNames: null,
@@ -57,7 +57,7 @@ public async Task<AgentRunResult> RunAsync(AgentFrameworkRequest request, Cancel
             request.Context.WorkingDirectory,
             cancellationToken).ConfigureAwait(false);
 
-        var providerTools = registryTools
+        var providerTools = FilterAdvertisedTools(registryTools, allowedTools)
             .Select(t => new ProviderToolDefinition(t.Name, t.Description, t.InputSchemaJson))
             .ToList();
 
@@ -158,4 +158,16 @@ public async Task<AgentRunResult> RunAsync(AgentFrameworkRequest request, Cancel
             return null;
         }
     }
+
+    private static IEnumerable<ToolDefinition> FilterAdvertisedTools(
+        IReadOnlyList<ToolDefinition> registryTools,
+        IReadOnlyCollection<string>? allowedTools)
+    {
+        if (allowedTools is null || allowedTools.Count == 0)
+        {
+            return registryTools;
+        }
+
+        return registryTools.Where(tool => allowedTools.Contains(tool.Name, StringComparer.OrdinalIgnoreCase));
+    }
 }

src/SharpClaw.Code.Cli/Composition/CliServiceCollectionExtensions.cs

@@ -34,8 +34,14 @@ public static IServiceCollection AddSharpClawCli(this IServiceCollection service
         services.AddSingleton<ICommandHandler, DoctorCommandHandler>();
         services.AddSingleton<ICommandHandler>(serviceProvider => serviceProvider.GetRequiredService<SessionCommandHandler>());
         services.AddSingleton<ICommandHandler, ModelsCommandHandler>();
+        services.AddSingleton<ICommandHandler, UsageCommandHandler>();
+        services.AddSingleton<ICommandHandler, CostCommandHandler>();
+        services.AddSingleton<ICommandHandler, StatsCommandHandler>();
         services.AddSingleton<ICommandHandler, ConnectCommandHandler>();
+        services.AddSingleton<ICommandHandler, HooksCommandHandler>();
+        services.AddSingleton<ICommandHandler, SkillsCommandHandler>();
         services.AddSingleton<ICommandHandler, AgentsCommandHandler>();
+        services.AddSingleton<ICommandHandler, TodoCommandHandler>();
         services.AddSingleton<ICommandHandler, ShareCommandHandler>();
         services.AddSingleton<ICommandHandler, UnshareCommandHandler>();
         services.AddSingleton<ICommandHandler, CompactCommandHandler>();
@@ -52,8 +58,14 @@ public static IServiceCollection AddSharpClawCli(this IServiceCollection service
         services.AddSingleton<ISlashCommandHandler>(serviceProvider => serviceProvider.GetRequiredService<SessionCommandHandler>());
         services.AddSingleton<ISlashCommandHandler, SessionsSlashCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, ModelsCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, UsageCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, CostCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, StatsCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, ConnectCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, HooksCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, SkillsCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, AgentsCommandHandler>();
+        services.AddSingleton<ISlashCommandHandler, TodoCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, ShareCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, UnshareCommandHandler>();
         services.AddSingleton<ISlashCommandHandler, CompactCommandHandler>();

src/SharpClaw.Code.Commands/Handlers/AgentsCommandHandler.cs

@@ -72,7 +72,7 @@ private async Task<int> ExecuteListAsync(CommandExecutionContext context, Cancel
             0,
             context.OutputFormat,
             message,
-            JsonSerializer.Serialize(agents, ProtocolJsonContext.Default.ListAgentCatalogEntry));
+            JsonSerializer.Serialize(agents.ToList(), ProtocolJsonContext.Default.ListAgentCatalogEntry));
         await outputRendererDispatcher.RenderCommandResultAsync(result, context.OutputFormat, cancellationToken).ConfigureAwait(false);
         return 0;
     }

src/SharpClaw.Code.Commands/Handlers/ConnectCommandHandler.cs

@@ -110,7 +110,14 @@ private async Task<List<ConnectTargetStatus>> BuildStatusesAsync(string workspac
         {
             var auth = await authFlowService.GetStatusAsync(provider.ProviderName, cancellationToken).ConfigureAwait(false);
             var configuredUrl = config.Document.ConnectLinks?.FirstOrDefault(link => string.Equals(link.Target, provider.ProviderName, StringComparison.OrdinalIgnoreCase))?.Url;
-            results.Add(new ConnectTargetStatus(provider.ProviderName, provider.ProviderName, "provider", auth.IsAuthenticated, configuredUrl));
+            var detail = auth.IsAuthenticated
+                ? string.IsNullOrWhiteSpace(auth.SubjectId)
+                    ? "authenticated"
+                    : $"authenticated as {auth.SubjectId}"
+                : auth.ExpiresAtUtc is { } expiresAt && expiresAt <= DateTimeOffset.UtcNow
+                    ? "authentication expired"
+                    : "not authenticated";
+            results.Add(new ConnectTargetStatus(provider.ProviderName, provider.ProviderName, "provider", auth.IsAuthenticated, configuredUrl, auth.ExpiresAtUtc, detail));
         }
 
         foreach (var link in config.Document.ConnectLinks ?? [])
@@ -120,7 +127,7 @@ private async Task<List<ConnectTargetStatus>> BuildStatusesAsync(string workspac
                 continue;
             }
 
-            results.Add(new ConnectTargetStatus(link.Target, link.DisplayName, "external", false, link.Url));
+            results.Add(new ConnectTargetStatus(link.Target, link.DisplayName, "external", false, link.Url, null, "manual browser flow"));
         }
 
         return results.OrderBy(static item => item.Target, StringComparer.OrdinalIgnoreCase).ToList();

src/SharpClaw.Code.Commands/Handlers/CostCommandHandler.cs

@@ -0,0 +1,57 @@
+using System.CommandLine;
+using System.Globalization;
+using System.Text.Json;
+using SharpClaw.Code.Commands.Models;
+using SharpClaw.Code.Commands.Options;
+using SharpClaw.Code.Protocol.Commands;
+using SharpClaw.Code.Protocol.Serialization;
+using SharpClaw.Code.Runtime.Abstractions;
+
+namespace SharpClaw.Code.Commands;
+
+/// <summary>
+/// Surfaces estimated workspace cost based on persisted usage snapshots.
+/// </summary>
+public sealed class CostCommandHandler(
+    IWorkspaceInsightsService workspaceInsightsService,
+    OutputRendererDispatcher outputRendererDispatcher) : ICommandHandler, ISlashCommandHandler
+{
+    /// <inheritdoc />
+    public string Name => "cost";
+
+    /// <inheritdoc />
+    public string Description => "Shows estimated usage cost for the current workspace.";
+
+    /// <inheritdoc />
+    public string CommandName => Name;
+
+    /// <inheritdoc />
+    public Command BuildCommand(GlobalCliOptions globalOptions)
+    {
+        var command = new Command(Name, Description);
+        command.SetAction((parseResult, cancellationToken) => ExecuteAsync(globalOptions.Resolve(parseResult), cancellationToken));
+        return command;
+    }
+
+    /// <inheritdoc />
+    public Task<int> ExecuteAsync(SlashCommandParseResult command, CommandExecutionContext context, CancellationToken cancellationToken)
+        => ExecuteAsync(context, cancellationToken);
+
+    private async Task<int> ExecuteAsync(CommandExecutionContext context, CancellationToken cancellationToken)
+    {
+        var report = await workspaceInsightsService
+            .BuildCostReportAsync(context.WorkingDirectory, context.SessionId, cancellationToken)
+            .ConfigureAwait(false);
+        var total = report.WorkspaceEstimatedCostUsd.HasValue
+            ? report.WorkspaceEstimatedCostUsd.Value.ToString("0.0000", CultureInfo.InvariantCulture)
+            : "n/a";
+        var result = new CommandResult(
+            true,
+            0,
+            context.OutputFormat,
+            $"Workspace estimated cost: ${total} across {report.Sessions.Count} session(s).",
+            JsonSerializer.Serialize(report, ProtocolJsonContext.Default.WorkspaceCostReport));
+        await outputRendererDispatcher.RenderCommandResultAsync(result, context.OutputFormat, cancellationToken).ConfigureAwait(false);
+        return 0;
+    }
+}