feat: support project hook commands

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-08-26 04:43:56 +02:00 · 2026-03-28 13:23:01 +01:00
parent f459cc7291
commit dff97efd58
10 changed files with 1428 additions and 13 deletions
@@ -0,0 +1,62 @@
+using System.Text.Json.Serialization;
+
+namespace Aryx.AgentHost.Contracts;
+
+internal static class HookTypeNames
+{
+    public const string SessionStart = "sessionStart";
+    public const string SessionEnd = "sessionEnd";
+    public const string UserPromptSubmitted = "userPromptSubmitted";
+    public const string PreToolUse = "preToolUse";
+    public const string PostToolUse = "postToolUse";
+    public const string ErrorOccurred = "errorOccurred";
+}
+
+internal sealed class HookConfigFile
+{
+    public int Version { get; init; }
+    public HookConfigHooks Hooks { get; init; } = new();
+}
+
+internal sealed class HookConfigHooks
+{
+    public IReadOnlyList<HookCommandDefinition>? SessionStart { get; init; }
+    public IReadOnlyList<HookCommandDefinition>? SessionEnd { get; init; }
+    public IReadOnlyList<HookCommandDefinition>? UserPromptSubmitted { get; init; }
+    public IReadOnlyList<HookCommandDefinition>? PreToolUse { get; init; }
+    public IReadOnlyList<HookCommandDefinition>? PostToolUse { get; init; }
+    public IReadOnlyList<HookCommandDefinition>? ErrorOccurred { get; init; }
+}
+
+internal sealed class HookCommandDefinition
+{
+    public string Type { get; init; } = string.Empty;
+    public string? Bash { get; init; }
+
+    [JsonPropertyName("powershell")]
+    public string? PowerShell { get; init; }
+
+    public string? Cwd { get; init; }
+    public IReadOnlyDictionary<string, string>? Env { get; init; }
+    public int? TimeoutSec { get; init; }
+}
+
+internal sealed class ResolvedHookSet
+{
+    public static ResolvedHookSet Empty { get; } = new();
+
+    public IReadOnlyList<HookCommandDefinition> SessionStart { get; init; } = [];
+    public IReadOnlyList<HookCommandDefinition> SessionEnd { get; init; } = [];
+    public IReadOnlyList<HookCommandDefinition> UserPromptSubmitted { get; init; } = [];
+    public IReadOnlyList<HookCommandDefinition> PreToolUse { get; init; } = [];
+    public IReadOnlyList<HookCommandDefinition> PostToolUse { get; init; } = [];
+    public IReadOnlyList<HookCommandDefinition> ErrorOccurred { get; init; } = [];
+
+    public bool IsEmpty =>
+        SessionStart.Count == 0
+        && SessionEnd.Count == 0
+        && UserPromptSubmitted.Count == 0
+        && PreToolUse.Count == 0
+        && PostToolUse.Count == 0
+        && ErrorOccurred.Count == 0;
+}
@@ -30,6 +30,9 @@ internal sealed class CopilotAgentBundle : IAsyncDisposable
        List<IAsyncDisposable> disposables = [];
        List<AIAgent> agents = [];
        CopilotClientOptions clientOptions = CopilotCliPathResolver.CreateClientOptions();
+        ResolvedHookSet configuredHooks = await HookConfigLoader.LoadAsync(command.ProjectPath, cancellationToken)
+            .ConfigureAwait(false);
+        IHookCommandRunner hookCommandRunner = HookCommandRunner.Instance;
        SessionToolingBundle? toolingBundle = command.Tooling is null
            ? null
            : await SessionToolingBundle.CreateAsync(command.Tooling, command.ProjectPath, cancellationToken)
@@ -51,7 +54,9 @@ internal sealed class CopilotAgentBundle : IAsyncDisposable
                agentIndex,
                (request, invocation) => onPermissionRequest(definition, request, invocation),
                (request, invocation) => onUserInputRequest(definition, request, invocation),
-                evt => onSessionEvent?.Invoke(definition, evt));
+                evt => onSessionEvent?.Invoke(definition, evt),
+                configuredHooks,
+                hookCommandRunner);

            ApplySessionTooling(sessionConfig, toolingBundle?.McpServers, toolingBundle?.Tools);

@@ -78,7 +83,9 @@ internal sealed class CopilotAgentBundle : IAsyncDisposable
        int agentIndex,
        PermissionRequestHandler? onPermissionRequest = null,
        UserInputHandler? onUserInputRequest = null,
-        SessionEventHandler? onSessionEvent = null)
+        SessionEventHandler? onSessionEvent = null,
+        ResolvedHookSet? configuredHooks = null,
+        IHookCommandRunner? hookCommandRunner = null)
    {
        // Let the Copilot SDK allocate session IDs. Explicit custom SessionId values currently
        // cause turns to complete without assistant output, even for simple single-agent prompts.
@@ -98,7 +105,7 @@ internal sealed class CopilotAgentBundle : IAsyncDisposable
            WorkingDirectory = command.ProjectPath,
            OnPermissionRequest = onPermissionRequest,
            OnUserInputRequest = onUserInputRequest,
-            Hooks = CopilotSessionHooks.Create(command, definition),
+            Hooks = CopilotSessionHooks.Create(command, definition, configuredHooks, hookCommandRunner),
            OnEvent = onSessionEvent,
            Streaming = true,
            CustomAgents = CreateCustomAgents(definition.Copilot?.CustomAgents),
@@ -1,3 +1,5 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
 using Aryx.AgentHost.Contracts;
 using GitHub.Copilot.SDK;

@@ -7,25 +9,209 @@ internal static class CopilotSessionHooks
 {
    private const string AllowDecision = "allow";
    private const string AskDecision = "ask";
+    private const string DenyDecision = "deny";
+    private static readonly JsonSerializerOptions HookJsonOptions = new(JsonSerializerDefaults.Web)
+    {
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+    };

-    public static SessionHooks Create(RunTurnCommandDto command, PatternAgentDefinitionDto agentDefinition)
+    public static SessionHooks Create(
+        RunTurnCommandDto command,
+        PatternAgentDefinitionDto agentDefinition,
+        ResolvedHookSet? configuredHooks = null,
+        IHookCommandRunner? hookCommandRunner = null)
    {
        ArgumentNullException.ThrowIfNull(command);
        ArgumentNullException.ThrowIfNull(agentDefinition);
+        ResolvedHookSet hooks = configuredHooks ?? ResolvedHookSet.Empty;
+        IHookCommandRunner runner = hookCommandRunner ?? HookCommandRunner.Instance;

        return new SessionHooks
        {
-            OnPreToolUse = (input, _) => Task.FromResult<PreToolUseHookOutput?>(
-                CreatePreToolUseOutput(command, agentDefinition, input)),
-            OnPostToolUse = static (_, _) => Task.FromResult<PostToolUseHookOutput?>(null),
-            OnUserPromptSubmitted = static (_, _) => Task.FromResult<UserPromptSubmittedHookOutput?>(null),
-            OnSessionStart = static (_, _) => Task.FromResult<SessionStartHookOutput?>(null),
-            OnSessionEnd = static (_, _) => Task.FromResult<SessionEndHookOutput?>(null),
-            OnErrorOccurred = static (_, _) => Task.FromResult<ErrorOccurredHookOutput?>(null),
+            OnPreToolUse = (input, _) => CreatePreToolUseOutputAsync(command, agentDefinition, hooks, runner, input),
+            OnPostToolUse = (input, _) => RunPostToolUseHooksAsync(command, hooks, runner, input),
+            OnUserPromptSubmitted = (input, _) => RunUserPromptSubmittedHooksAsync(command, hooks, runner, input),
+            OnSessionStart = (input, _) => RunSessionStartHooksAsync(command, hooks, runner, input),
+            OnSessionEnd = (input, _) => RunSessionEndHooksAsync(command, hooks, runner, input),
+            OnErrorOccurred = (input, _) => RunErrorOccurredHooksAsync(command, hooks, runner, input),
        };
    }

-    private static PreToolUseHookOutput CreatePreToolUseOutput(
+    private static async Task<PreToolUseHookOutput?> CreatePreToolUseOutputAsync(
+        RunTurnCommandDto command,
+        PatternAgentDefinitionDto agentDefinition,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        PreToolUseHookInput input)
+    {
+        if (configuredHooks.PreToolUse.Count > 0)
+        {
+            string payload = SerializeHookInput(new FilePreToolUseHookInput
+            {
+                Timestamp = input.Timestamp,
+                Cwd = input.Cwd,
+                ToolName = input.ToolName,
+                ToolArgs = SerializeHookValue(input.ToolArgs),
+            });
+
+            foreach (HookCommandDefinition hook in configuredHooks.PreToolUse)
+            {
+                string? hookOutput = await hookCommandRunner.RunAsync(
+                        hook,
+                        payload,
+                        command.ProjectPath,
+                        CancellationToken.None)
+                    .ConfigureAwait(false);
+
+                PreToolUseHookOutput? decision = ParsePreToolUseDecision(hookOutput);
+                if (string.Equals(decision?.PermissionDecision, DenyDecision, StringComparison.OrdinalIgnoreCase))
+                {
+                    return decision;
+                }
+            }
+        }
+
+        return CreateApprovalPolicyOutput(command, agentDefinition, input);
+    }
+
+    private static async Task<PostToolUseHookOutput?> RunPostToolUseHooksAsync(
+        RunTurnCommandDto command,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        PostToolUseHookInput input)
+    {
+        await RunConfiguredHooksAsync(
+                configuredHooks.PostToolUse,
+                hookCommandRunner,
+                command.ProjectPath,
+                SerializeHookInput(new FilePostToolUseHookInput
+                {
+                    Timestamp = input.Timestamp,
+                    Cwd = input.Cwd,
+                    ToolName = input.ToolName,
+                    ToolArgs = SerializeHookValue(input.ToolArgs),
+                    ToolResult = input.ToolResult,
+                }))
+            .ConfigureAwait(false);
+
+        return null;
+    }
+
+    private static async Task<UserPromptSubmittedHookOutput?> RunUserPromptSubmittedHooksAsync(
+        RunTurnCommandDto command,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        UserPromptSubmittedHookInput input)
+    {
+        await RunConfiguredHooksAsync(
+                configuredHooks.UserPromptSubmitted,
+                hookCommandRunner,
+                command.ProjectPath,
+                SerializeHookInput(new FileUserPromptSubmittedHookInput
+                {
+                    Timestamp = input.Timestamp,
+                    Cwd = input.Cwd,
+                    Prompt = input.Prompt,
+                }))
+            .ConfigureAwait(false);
+
+        return null;
+    }
+
+    private static async Task<SessionStartHookOutput?> RunSessionStartHooksAsync(
+        RunTurnCommandDto command,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        SessionStartHookInput input)
+    {
+        await RunConfiguredHooksAsync(
+                configuredHooks.SessionStart,
+                hookCommandRunner,
+                command.ProjectPath,
+                SerializeHookInput(new FileSessionStartHookInput
+                {
+                    Timestamp = input.Timestamp,
+                    Cwd = input.Cwd,
+                    Source = input.Source,
+                    InitialPrompt = input.InitialPrompt,
+                }))
+            .ConfigureAwait(false);
+
+        return null;
+    }
+
+    private static async Task<SessionEndHookOutput?> RunSessionEndHooksAsync(
+        RunTurnCommandDto command,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        SessionEndHookInput input)
+    {
+        await RunConfiguredHooksAsync(
+                configuredHooks.SessionEnd,
+                hookCommandRunner,
+                command.ProjectPath,
+                SerializeHookInput(new FileSessionEndHookInput
+                {
+                    Timestamp = input.Timestamp,
+                    Cwd = input.Cwd,
+                    Reason = input.Reason,
+                    FinalMessage = input.FinalMessage,
+                    Error = input.Error,
+                }))
+            .ConfigureAwait(false);
+
+        return null;
+    }
+
+    private static async Task<ErrorOccurredHookOutput?> RunErrorOccurredHooksAsync(
+        RunTurnCommandDto command,
+        ResolvedHookSet configuredHooks,
+        IHookCommandRunner hookCommandRunner,
+        ErrorOccurredHookInput input)
+    {
+        await RunConfiguredHooksAsync(
+                configuredHooks.ErrorOccurred,
+                hookCommandRunner,
+                command.ProjectPath,
+                SerializeHookInput(new FileErrorOccurredHookInput
+                {
+                    Timestamp = input.Timestamp,
+                    Cwd = input.Cwd,
+                    Error = new FileHookError
+                    {
+                        Message = input.Error,
+                        Context = input.ErrorContext,
+                        Recoverable = input.Recoverable,
+                    },
+                }))
+            .ConfigureAwait(false);
+
+        return null;
+    }
+
+    private static async Task RunConfiguredHooksAsync(
+        IReadOnlyList<HookCommandDefinition> hooks,
+        IHookCommandRunner hookCommandRunner,
+        string projectPath,
+        string payload)
+    {
+        if (hooks.Count == 0)
+        {
+            return;
+        }
+
+        foreach (HookCommandDefinition hook in hooks)
+        {
+            await hookCommandRunner.RunAsync(
+                    hook,
+                    payload,
+                    projectPath,
+                    CancellationToken.None)
+                .ConfigureAwait(false);
+        }
+    }
+
+    private static PreToolUseHookOutput CreateApprovalPolicyOutput(
        RunTurnCommandDto command,
        PatternAgentDefinitionDto agentDefinition,
        PreToolUseHookInput input)
@@ -42,6 +228,101 @@ internal static class CopilotSessionHooks
        };
    }

+    private static PreToolUseHookOutput? ParsePreToolUseDecision(string? hookOutput)
+    {
+        if (string.IsNullOrWhiteSpace(hookOutput))
+        {
+            return null;
+        }
+
+        try
+        {
+            FilePreToolUseHookOutput? parsed = JsonSerializer.Deserialize<FilePreToolUseHookOutput>(hookOutput, HookJsonOptions);
+            if (!string.Equals(parsed?.PermissionDecision, DenyDecision, StringComparison.OrdinalIgnoreCase))
+            {
+                return null;
+            }
+
+            return new PreToolUseHookOutput
+            {
+                PermissionDecision = DenyDecision,
+                PermissionDecisionReason = Normalize(parsed?.PermissionDecisionReason),
+            };
+        }
+        catch (JsonException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Ignoring invalid preToolUse hook output: {exception.Message}");
+            return null;
+        }
+    }
+
+    private static string SerializeHookInput<T>(T input)
+        => JsonSerializer.Serialize(input, HookJsonOptions);
+
+    private static string SerializeHookValue(object? value)
+        => JsonSerializer.Serialize(value, HookJsonOptions);
+
    private static string? Normalize(string? value)
        => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+
+    private sealed class FileSessionStartHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public string Source { get; init; } = string.Empty;
+        public string? InitialPrompt { get; init; }
+    }
+
+    private sealed class FileSessionEndHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public string Reason { get; init; } = string.Empty;
+        public string? FinalMessage { get; init; }
+        public string? Error { get; init; }
+    }
+
+    private sealed class FileUserPromptSubmittedHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public string Prompt { get; init; } = string.Empty;
+    }
+
+    private sealed class FilePreToolUseHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public string ToolName { get; init; } = string.Empty;
+        public string ToolArgs { get; init; } = "null";
+    }
+
+    private sealed class FilePostToolUseHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public string ToolName { get; init; } = string.Empty;
+        public string ToolArgs { get; init; } = "null";
+        public object? ToolResult { get; init; }
+    }
+
+    private sealed class FileErrorOccurredHookInput
+    {
+        public long Timestamp { get; init; }
+        public string Cwd { get; init; } = string.Empty;
+        public FileHookError Error { get; init; } = new();
+    }
+
+    private sealed class FileHookError
+    {
+        public string Message { get; init; } = string.Empty;
+        public string Context { get; init; } = string.Empty;
+        public bool Recoverable { get; init; }
+    }
+
+    private sealed class FilePreToolUseHookOutput
+    {
+        public string? PermissionDecision { get; init; }
+        public string? PermissionDecisionReason { get; init; }
+    }
 }
@@ -0,0 +1,220 @@
+using System.ComponentModel;
+using System.Diagnostics;
+using Aryx.AgentHost.Contracts;
+
+namespace Aryx.AgentHost.Services;
+
+internal interface IHookCommandRunner
+{
+    Task<string?> RunAsync(
+        HookCommandDefinition hook,
+        string inputJson,
+        string projectPath,
+        CancellationToken cancellationToken);
+}
+
+internal sealed class HookCommandRunner : IHookCommandRunner
+{
+    private const int DefaultTimeoutSeconds = 30;
+
+    public static HookCommandRunner Instance { get; } = new();
+
+    public async Task<string?> RunAsync(
+        HookCommandDefinition hook,
+        string inputJson,
+        string projectPath,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(hook);
+        ArgumentNullException.ThrowIfNull(inputJson);
+        ArgumentException.ThrowIfNullOrWhiteSpace(projectPath);
+
+        string? commandText = SelectCommandText(hook);
+        if (commandText is null)
+        {
+            Console.Error.WriteLine("[aryx hooks] Skipping hook because no compatible shell command is configured for this platform.");
+            return null;
+        }
+
+        string workingDirectory = ResolveWorkingDirectory(projectPath, hook.Cwd);
+        ProcessStartInfo startInfo = CreateStartInfo(commandText, workingDirectory);
+        ApplyEnvironment(startInfo, hook.Env);
+
+        using Process process = new()
+        {
+            StartInfo = startInfo,
+        };
+
+        try
+        {
+            if (!process.Start())
+            {
+                Console.Error.WriteLine($"[aryx hooks] Failed to start hook command '{commandText}'.");
+                return null;
+            }
+        }
+        catch (Win32Exception exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to start hook command '{commandText}': {exception.Message}");
+            return null;
+        }
+        catch (InvalidOperationException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to start hook command '{commandText}': {exception.Message}");
+            return null;
+        }
+
+        Task<string> stdoutTask = process.StandardOutput.ReadToEndAsync();
+        Task<string> stderrTask = process.StandardError.ReadToEndAsync();
+
+        try
+        {
+            await process.StandardInput.WriteAsync(inputJson).ConfigureAwait(false);
+            await process.StandardInput.FlushAsync().ConfigureAwait(false);
+            process.StandardInput.Close();
+        }
+        catch (IOException exception)
+        {
+            TryKillProcess(process);
+            Console.Error.WriteLine($"[aryx hooks] Failed to write hook input for '{commandText}': {exception.Message}");
+            return null;
+        }
+        catch (ObjectDisposedException exception)
+        {
+            TryKillProcess(process);
+            Console.Error.WriteLine($"[aryx hooks] Failed to write hook input for '{commandText}': {exception.Message}");
+            return null;
+        }
+
+        TimeSpan timeout = TimeSpan.FromSeconds(hook.TimeoutSec ?? DefaultTimeoutSeconds);
+        using CancellationTokenSource timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeoutCts.CancelAfter(timeout);
+
+        try
+        {
+            await process.WaitForExitAsync(timeoutCts.Token).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+        {
+            TryKillProcess(process);
+            await DrainOutputAsync(process, stdoutTask, stderrTask).ConfigureAwait(false);
+            Console.Error.WriteLine($"[aryx hooks] Hook command timed out after {(int)timeout.TotalSeconds} seconds: '{commandText}'.");
+            return null;
+        }
+
+        string stdout = await stdoutTask.ConfigureAwait(false);
+        string stderr = await stderrTask.ConfigureAwait(false);
+        if (process.ExitCode != 0)
+        {
+            string detail = string.IsNullOrWhiteSpace(stderr) ? $"exit code {process.ExitCode}" : stderr.Trim();
+            Console.Error.WriteLine($"[aryx hooks] Hook command failed for '{commandText}': {detail}");
+            return null;
+        }
+
+        return stdout;
+    }
+
+    private static async Task DrainOutputAsync(Process process, Task<string> stdoutTask, Task<string> stderrTask)
+    {
+        try
+        {
+            await process.WaitForExitAsync(CancellationToken.None).ConfigureAwait(false);
+        }
+        catch (InvalidOperationException)
+        {
+            // Process already exited or could not be waited on.
+        }
+
+        await Task.WhenAll(stdoutTask, stderrTask).ConfigureAwait(false);
+    }
+
+    private static ProcessStartInfo CreateStartInfo(string commandText, string workingDirectory)
+    {
+        ProcessStartInfo startInfo = new()
+        {
+            WorkingDirectory = workingDirectory,
+            RedirectStandardInput = true,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+
+        if (OperatingSystem.IsWindows())
+        {
+            startInfo.FileName = "powershell.exe";
+            startInfo.ArgumentList.Add("-NoLogo");
+            startInfo.ArgumentList.Add("-NoProfile");
+            startInfo.ArgumentList.Add("-NonInteractive");
+            startInfo.ArgumentList.Add("-ExecutionPolicy");
+            startInfo.ArgumentList.Add("Bypass");
+            startInfo.ArgumentList.Add("-Command");
+            startInfo.ArgumentList.Add(commandText);
+            return startInfo;
+        }
+
+        startInfo.FileName = "bash";
+        startInfo.ArgumentList.Add("-lc");
+        startInfo.ArgumentList.Add(commandText);
+        return startInfo;
+    }
+
+    private static void ApplyEnvironment(ProcessStartInfo startInfo, IReadOnlyDictionary<string, string>? environment)
+    {
+        if (environment is not { Count: > 0 })
+        {
+            return;
+        }
+
+        foreach ((string key, string value) in environment)
+        {
+            startInfo.Environment[key] = value;
+        }
+    }
+
+    private static string ResolveWorkingDirectory(string projectPath, string? configuredCwd)
+    {
+        if (string.IsNullOrWhiteSpace(configuredCwd))
+        {
+            return Path.GetFullPath(projectPath);
+        }
+
+        string resolved = Path.IsPathRooted(configuredCwd)
+            ? configuredCwd
+            : Path.Combine(projectPath, configuredCwd);
+
+        return Path.GetFullPath(resolved);
+    }
+
+    private static string? SelectCommandText(HookCommandDefinition hook)
+    {
+        if (OperatingSystem.IsWindows())
+        {
+            return NormalizeOptionalString(hook.PowerShell);
+        }
+
+        return NormalizeOptionalString(hook.Bash);
+    }
+
+    private static void TryKillProcess(Process process)
+    {
+        try
+        {
+            if (!process.HasExited)
+            {
+                process.Kill(entireProcessTree: true);
+            }
+        }
+        catch (InvalidOperationException)
+        {
+            // Process already exited.
+        }
+        catch (NotSupportedException)
+        {
+            // The platform does not support process tree termination.
+        }
+    }
+
+    private static string? NormalizeOptionalString(string? value)
+        => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+}
@@ -0,0 +1,207 @@
+using System.Text.Json;
+using Aryx.AgentHost.Contracts;
+
+namespace Aryx.AgentHost.Services;
+
+internal static class HookConfigLoader
+{
+    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web)
+    {
+        AllowTrailingCommas = true,
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+    };
+
+    public static async Task<ResolvedHookSet> LoadAsync(string projectPath, CancellationToken cancellationToken)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(projectPath);
+
+        string hooksDirectory = Path.Combine(projectPath, ".github", "hooks");
+        if (!Directory.Exists(hooksDirectory))
+        {
+            return ResolvedHookSet.Empty;
+        }
+
+        string[] hookFiles;
+        try
+        {
+            hookFiles = Directory.GetFiles(hooksDirectory, "*.json", SearchOption.TopDirectoryOnly);
+        }
+        catch (IOException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to enumerate hook files in '{hooksDirectory}': {exception.Message}");
+            return ResolvedHookSet.Empty;
+        }
+        catch (UnauthorizedAccessException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to enumerate hook files in '{hooksDirectory}': {exception.Message}");
+            return ResolvedHookSet.Empty;
+        }
+
+        if (hookFiles.Length == 0)
+        {
+            return ResolvedHookSet.Empty;
+        }
+
+        Array.Sort(hookFiles, StringComparer.OrdinalIgnoreCase);
+
+        List<HookCommandDefinition> sessionStart = [];
+        List<HookCommandDefinition> sessionEnd = [];
+        List<HookCommandDefinition> userPromptSubmitted = [];
+        List<HookCommandDefinition> preToolUse = [];
+        List<HookCommandDefinition> postToolUse = [];
+        List<HookCommandDefinition> errorOccurred = [];
+
+        foreach (string hookFile in hookFiles)
+        {
+            HookConfigFile? config = await ReadHookConfigAsync(hookFile, cancellationToken).ConfigureAwait(false);
+            if (config is null)
+            {
+                continue;
+            }
+
+            if (config.Version != 1)
+            {
+                Console.Error.WriteLine($"[aryx hooks] Skipping '{hookFile}' because it declares unsupported version '{config.Version}'.");
+                continue;
+            }
+
+            AddHooks(sessionStart, config.Hooks.SessionStart, HookTypeNames.SessionStart, hookFile);
+            AddHooks(sessionEnd, config.Hooks.SessionEnd, HookTypeNames.SessionEnd, hookFile);
+            AddHooks(userPromptSubmitted, config.Hooks.UserPromptSubmitted, HookTypeNames.UserPromptSubmitted, hookFile);
+            AddHooks(preToolUse, config.Hooks.PreToolUse, HookTypeNames.PreToolUse, hookFile);
+            AddHooks(postToolUse, config.Hooks.PostToolUse, HookTypeNames.PostToolUse, hookFile);
+            AddHooks(errorOccurred, config.Hooks.ErrorOccurred, HookTypeNames.ErrorOccurred, hookFile);
+        }
+
+        if (
+            sessionStart.Count == 0
+            && sessionEnd.Count == 0
+            && userPromptSubmitted.Count == 0
+            && preToolUse.Count == 0
+            && postToolUse.Count == 0
+            && errorOccurred.Count == 0)
+        {
+            return ResolvedHookSet.Empty;
+        }
+
+        return new ResolvedHookSet
+        {
+            SessionStart = [.. sessionStart],
+            SessionEnd = [.. sessionEnd],
+            UserPromptSubmitted = [.. userPromptSubmitted],
+            PreToolUse = [.. preToolUse],
+            PostToolUse = [.. postToolUse],
+            ErrorOccurred = [.. errorOccurred],
+        };
+    }
+
+    private static void AddHooks(
+        ICollection<HookCommandDefinition> target,
+        IReadOnlyList<HookCommandDefinition>? definitions,
+        string hookType,
+        string hookFile)
+    {
+        if (definitions is not { Count: > 0 })
+        {
+            return;
+        }
+
+        foreach (HookCommandDefinition definition in definitions)
+        {
+            HookCommandDefinition? normalized = NormalizeDefinition(definition, hookType, hookFile);
+            if (normalized is not null)
+            {
+                target.Add(normalized);
+            }
+        }
+    }
+
+    private static HookCommandDefinition? NormalizeDefinition(
+        HookCommandDefinition definition,
+        string hookType,
+        string hookFile)
+    {
+        string type = NormalizeOptionalString(definition.Type) ?? string.Empty;
+        if (!string.Equals(type, "command", StringComparison.OrdinalIgnoreCase))
+        {
+            Console.Error.WriteLine($"[aryx hooks] Skipping '{hookType}' entry in '{hookFile}' because type '{definition.Type}' is unsupported.");
+            return null;
+        }
+
+        string? bash = NormalizeOptionalString(definition.Bash);
+        string? powerShell = NormalizeOptionalString(definition.PowerShell);
+        if (bash is null && powerShell is null)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Skipping '{hookType}' entry in '{hookFile}' because no shell command is configured.");
+            return null;
+        }
+
+        int? timeoutSec = definition.TimeoutSec;
+        if (timeoutSec is <= 0)
+        {
+            timeoutSec = null;
+        }
+
+        IReadOnlyDictionary<string, string>? env = NormalizeEnvironment(definition.Env);
+
+        return new HookCommandDefinition
+        {
+            Type = "command",
+            Bash = bash,
+            PowerShell = powerShell,
+            Cwd = NormalizeOptionalString(definition.Cwd),
+            Env = env,
+            TimeoutSec = timeoutSec,
+        };
+    }
+
+    private static async Task<HookConfigFile?> ReadHookConfigAsync(string hookFile, CancellationToken cancellationToken)
+    {
+        try
+        {
+            await using FileStream stream = File.OpenRead(hookFile);
+            return await JsonSerializer.DeserializeAsync<HookConfigFile>(stream, JsonOptions, cancellationToken).ConfigureAwait(false);
+        }
+        catch (JsonException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to parse '{hookFile}': {exception.Message}");
+            return null;
+        }
+        catch (IOException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to read '{hookFile}': {exception.Message}");
+            return null;
+        }
+        catch (UnauthorizedAccessException exception)
+        {
+            Console.Error.WriteLine($"[aryx hooks] Failed to read '{hookFile}': {exception.Message}");
+            return null;
+        }
+    }
+
+    private static IReadOnlyDictionary<string, string>? NormalizeEnvironment(IReadOnlyDictionary<string, string>? environment)
+    {
+        if (environment is not { Count: > 0 })
+        {
+            return null;
+        }
+
+        Dictionary<string, string> normalized = new(StringComparer.Ordinal);
+        foreach ((string key, string value) in environment)
+        {
+            string? normalizedKey = NormalizeOptionalString(key);
+            if (normalizedKey is null)
+            {
+                continue;
+            }
+
+            normalized[normalizedKey] = value;
+        }
+
+        return normalized.Count == 0 ? null : normalized;
+    }
+
+    private static string? NormalizeOptionalString(string? value)
+        => string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+}