Merge pull request #3496 from docker/feat/hooks-dropin-and-config-dir-env

feat: hooks.d drop-in directory and config-dir env override

Author: dgageot

cmd/root/config_dir_test.go

@@ -0,0 +1,24 @@
+package root
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestResolveConfigDir_Precedence(t *testing.T) {
+	// Not parallel: t.Setenv mutates process-wide env vars. Both vars are
+	// explicitly neutralized first so an env leak from the developer's
+	// shell cannot skew the assertions.
+	t.Setenv(envConfigDir, "")
+	t.Setenv(cagentEnvConfigDir, "")
+	assert.Empty(t, resolveConfigDir(""))
+
+	t.Setenv(cagentEnvConfigDir, "/from-cagent-env")
+	assert.Equal(t, "/from-cagent-env", resolveConfigDir(""))
+
+	t.Setenv(envConfigDir, "/from-docker-agent-env")
+	assert.Equal(t, "/from-docker-agent-env", resolveConfigDir(""))
+
+	assert.Equal(t, "/from-flag", resolveConfigDir("/from-flag"))
+}

cmd/root/root.go

@@ -36,6 +36,19 @@ type rootFlags struct {
 	dataDir     string
 }
 
+const (
+	envConfigDir       = "DOCKER_AGENT_CONFIG_DIR"
+	cagentEnvConfigDir = "CAGENT_CONFIG_DIR"
+)
+
+// resolveConfigDir picks the config directory override with flag > env >
+// default precedence. The env fallbacks let external tools point docker-agent
+// at a non-default config dir (e.g. to locate hooks.d) without controlling
+// its argv.
+func resolveConfigDir(flagValue string) string {
+	return cmp.Or(flagValue, os.Getenv(envConfigDir), os.Getenv(cagentEnvConfigDir))
+}
+
 func NewRootCmd() *cobra.Command {
 	var flags rootFlags
 
@@ -54,7 +67,7 @@ New to docker agent? Take the hands-on tour: docker agent getting-started`,
 			if dir := flags.cacheDir; dir != "" {
 				paths.SetCacheDir(dir)
 			}
-			if dir := flags.configDir; dir != "" {
+			if dir := resolveConfigDir(flags.configDir); dir != "" {
 				paths.SetConfigDir(dir)
 			}
 			if dir := flags.dataDir; dir != "" {

cmd/root/run.go

@@ -327,7 +327,7 @@ func (f *runExecFlags) runOrExec(ctx context.Context, out *cli.Printer, args []s
 	// User settings only apply if the flag wasn't explicitly set by the user
 	userSettings := userconfig.Get()
 	f.applyUserSettings(ctx, userSettings)
-	f.runConfig.GlobalHooks = userSettings.GlobalHooks()
+	f.runConfig.GlobalHooks = config.MergeHooks(userSettings.GlobalHooks(), config.LoadHookDropIns())
 
 	// Apply alias options if this is an alias reference
 	// Alias options only apply if the flag wasn't explicitly set by the user

docs/configuration/hooks/index.md

@@ -142,10 +142,31 @@ Global hooks use the same schema as agent-level hooks and are additive. If an ev
 
 1. Agent-config hooks from the agent YAML
 2. Global hooks from `settings.hooks`
-3. CLI hooks from `--hook-*` flags
+3. Hook drop-ins from `<config-dir>/hooks.d/` (lexicographic file order)
+4. CLI hooks from `--hook-*` flags
 
 Global hooks cannot be suppressed by an individual agent. Use them for user-wide audit logging, personal guardrails, notifications, and setup/cleanup behavior that should apply everywhere.
 
+### Hook drop-in files (`hooks.d`)
+
+External tools that integrate with docker-agent (terminal emulators, IDEs, audit or observability sidecars) shouldn't have to rewrite your `config.yaml` to install a hook. Instead, docker-agent also loads every `*.yaml` / `*.yml` file from the `hooks.d` directory next to your user config (default: `~/.config/cagent/hooks.d/`). Each file is a standalone hooks block with the same schema as the content of `settings.hooks`:
+
+```yaml
+# ~/.config/cagent/hooks.d/50-mytool.yaml
+session_start:
+  - type: command
+    command: mytool notify --event session-start
+stop:
+  - type: command
+    command: mytool notify --event stop
+```
+
+- Files are loaded in lexicographic order and merged additively after `settings.hooks` (use numeric prefixes like `10-`, `50-` to control ordering).
+- A malformed file is skipped with a logged warning; a broken drop-in never breaks a run.
+- Installing an integration means writing one self-contained file; uninstalling means deleting it. No shared-file edits, no conflicts between tools.
+
+The config directory can be relocated with the `--config-dir` flag or the `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) environment variable, which external tools can use to locate `hooks.d` under non-default config dirs.
+
 ## Built-in Hooks
 
 In addition to shell `command` hooks, docker-agent ships a small library of **built-in hooks** — in-process Go functions that run without spawning a subprocess. They're invoked with `type: builtin`, where `command` is the builtin's registered name and `args` are passed through as the builtin's parameters.
@@ -911,4 +932,4 @@ $ docker agent run agentcatalog/coder \
 > [!NOTE]
 > **Merging behavior**
 >
-> Agent-config, global, and CLI hooks are additive. For each event, hooks run in this order: agent-config hooks first, then global hooks from `settings.hooks`, then CLI hooks. No source replaces another, and individual agents cannot opt out of global hooks.
+> Agent-config, global, drop-in, and CLI hooks are additive. For each event, hooks run in this order: agent-config hooks first, then global hooks from `settings.hooks`, then [hook drop-ins](#hook-drop-in-files-hooksd) from `hooks.d/`, then CLI hooks. No source replaces another, and individual agents cannot opt out of global hooks.

docs/features/cli/index.md

@@ -558,7 +558,7 @@ These flags are available on every `docker agent` command:
 | `--log-file <path>`       | Custom debug log location (only used with `--debug`)                                   |
 | `-o, --otel`              | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. |
 | `--cache-dir <path>`      | Override the cache directory (default: `~/Library/Caches/cagent` on macOS)             |
-| `--config-dir <path>`     | Override the config directory (default: `~/.config/cagent`)                            |
+| `--config-dir <path>`     | Override the config directory (default: `~/.config/cagent`). Also reads `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) env var. |
 | `--data-dir <path>`       | Override the data directory (default: `~/.cagent`)                                     |
 | `--help`                  | Show help for any command                                                              |
 

pkg/config/hooks_dropin.go

@@ -0,0 +1,71 @@
+package config
+
+import (
+	"log/slog"
+	"os"
+	"path/filepath"
+
+	"github.com/goccy/go-yaml"
+
+	"github.com/docker/docker-agent/pkg/config/latest"
+	"github.com/docker/docker-agent/pkg/paths"
+)
+
+// LoadHookDropIns loads user-level hook drop-in files from the hooks.d
+// directory under the config dir. Each *.yaml / *.yml file holds a standalone
+// HooksConfig (the same schema as the userconfig `settings.hooks` block).
+// Files are merged additively in lexicographic order, so external tools can
+// install and uninstall hooks by adding or deleting one self-contained file
+// instead of rewriting the shared config.yaml. Returns nil when no drop-in
+// hooks exist.
+func LoadHookDropIns() *latest.HooksConfig {
+	return loadHookDropIns(filepath.Join(paths.GetConfigDir(), "hooks.d"))
+}
+
+func loadHookDropIns(dir string) *latest.HooksConfig {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			slog.Warn("Failed to read hooks drop-in directory", "dir", dir, "error", err)
+		}
+		return nil
+	}
+
+	// os.ReadDir returns entries sorted by filename, which pins the
+	// documented lexicographic merge order.
+	var merged *latest.HooksConfig
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		if ext := filepath.Ext(entry.Name()); ext != ".yaml" && ext != ".yml" {
+			continue
+		}
+		path := filepath.Join(dir, entry.Name())
+		hooks, err := readHookDropIn(path)
+		if err != nil {
+			// A broken drop-in must never break the run: warn and skip.
+			slog.Warn("Skipping invalid hooks drop-in file", "path", path, "error", err)
+			continue
+		}
+		merged = MergeHooks(merged, hooks)
+	}
+	return merged
+}
+
+// readHookDropIn parses one drop-in file. Parsing is strict so a typo'd
+// event name surfaces as a warning instead of being silently ignored.
+func readHookDropIn(path string) (*latest.HooksConfig, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var hooks latest.HooksConfig
+	if err := yaml.UnmarshalWithOptions(data, &hooks, yaml.Strict()); err != nil {
+		return nil, err
+	}
+	if err := hooks.Validate(); err != nil {
+		return nil, err
+	}
+	return &hooks, nil
+}

pkg/config/hooks_dropin_test.go

@@ -0,0 +1,110 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/docker/docker-agent/pkg/paths"
+)
+
+func writeHookDropIn(t *testing.T, dir, name, content string) {
+	t.Helper()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o600))
+}
+
+func TestLoadHookDropIns_MissingDir(t *testing.T) {
+	t.Parallel()
+	assert.Nil(t, loadHookDropIns(filepath.Join(t.TempDir(), "hooks.d")))
+}
+
+func TestLoadHookDropIns_LexicographicOrder(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	writeHookDropIn(t, dir, "20-second.yaml", "stop:\n  - type: command\n    command: echo second\n")
+	writeHookDropIn(t, dir, "10-first.yaml", "stop:\n  - type: command\n    command: echo first\n")
+
+	hooks := loadHookDropIns(dir)
+	require.NotNil(t, hooks)
+	require.Len(t, hooks.Stop, 2)
+	assert.Equal(t, "echo first", hooks.Stop[0].Command)
+	assert.Equal(t, "echo second", hooks.Stop[1].Command)
+}
+
+func TestLoadHookDropIns_MergesAcrossEvents(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	writeHookDropIn(t, dir, "a.yaml", `
+session_start:
+  - type: command
+    command: echo start
+pre_tool_use:
+  - matcher: shell
+    hooks:
+      - type: command
+        command: audit.sh
+`)
+	writeHookDropIn(t, dir, "b.yml", "stop:\n  - type: command\n    command: echo stop\n")
+
+	hooks := loadHookDropIns(dir)
+	require.NotNil(t, hooks)
+	require.Len(t, hooks.SessionStart, 1)
+	assert.Equal(t, "echo start", hooks.SessionStart[0].Command)
+	require.Len(t, hooks.PreToolUse, 1)
+	assert.Equal(t, "shell", hooks.PreToolUse[0].Matcher)
+	require.Len(t, hooks.Stop, 1)
+	assert.Equal(t, "echo stop", hooks.Stop[0].Command)
+}
+
+func TestLoadHookDropIns_SkipsMalformedFiles(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	writeHookDropIn(t, dir, "10-broken-yaml.yaml", "stop: [unclosed\n")
+	writeHookDropIn(t, dir, "20-unknown-key.yaml", "not_a_hook_event:\n  - type: command\n    command: echo hi\n")
+	writeHookDropIn(t, dir, "30-invalid-hook-type.yaml", "stop:\n  - type: teleport\n    command: echo hi\n")
+	writeHookDropIn(t, dir, "40-valid.yaml", "stop:\n  - type: command\n    command: echo ok\n")
+
+	hooks := loadHookDropIns(dir)
+	require.NotNil(t, hooks)
+	require.Len(t, hooks.Stop, 1)
+	assert.Equal(t, "echo ok", hooks.Stop[0].Command)
+}
+
+func TestLoadHookDropIns_IgnoresNonYAMLAndSubdirs(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	writeHookDropIn(t, dir, "README.md", "# not yaml")
+	writeHookDropIn(t, dir, "50-disabled.yaml.bak", "stop:\n  - type: command\n    command: echo no\n")
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "sub.yaml"), 0o700))
+	writeHookDropIn(t, filepath.Join(dir, "sub.yaml"), "inner.yaml", "stop:\n  - type: command\n    command: echo nested\n")
+
+	assert.Nil(t, loadHookDropIns(dir))
+}
+
+func TestLoadHookDropIns_EmptyAndCommentOnlyFiles(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	writeHookDropIn(t, dir, "a.yaml", "")
+	writeHookDropIn(t, dir, "b.yaml", "# comment only\n")
+
+	assert.Nil(t, loadHookDropIns(dir))
+}
+
+func TestLoadHookDropIns_UsesConfigDir(t *testing.T) {
+	// Not parallel: overrides the process-global config dir.
+	configDir := t.TempDir()
+	paths.SetConfigDir(configDir)
+	t.Cleanup(func() { paths.SetConfigDir("") })
+
+	hooksDir := filepath.Join(configDir, "hooks.d")
+	require.NoError(t, os.MkdirAll(hooksDir, 0o700))
+	writeHookDropIn(t, hooksDir, "a.yaml", "stop:\n  - type: command\n    command: echo hi\n")
+
+	hooks := LoadHookDropIns()
+	require.NotNil(t, hooks)
+	require.Len(t, hooks.Stop, 1)
+	assert.Equal(t, "echo hi", hooks.Stop[0].Command)
+}