codex install: auto-enable codex_hooks in config.toml

Removes the manual prerequisite. applyCodex now ensures
`codex_hooks = true` is present at the top level of
`~/.codex/config.toml` before writing hooks.json:

  - file missing → create with the flag
  - flag missing → append the line (with backup of original)
  - flag = false → flip to true (with backup of original)
  - flag = true → no-op

Backups follow the same .agentlock-backup-<ts> naming as hooks.json,
and the same checkSafeCodexTarget guard protects writes into a real
~/.codex (still gated by AGENTLOCK_ALLOW_APPLY_REAL_HOME=1). The
codex_hooks_disabled error path is gone on both daemon and CLI.
Tests cover all three write cases plus the no-op.

Author: knhn1004

cli/src/commands/install.ts

@@ -423,11 +423,6 @@ export async function runInstall(argv: string[] = []): Promise<void> {
           "use --config-dir ./dev/.claude (or ./dev/.codex) for dev runs, or set\n" +
           "AGENTLOCK_ALLOW_APPLY_REAL_HOME=1 on the daemon for real installs.\n",
       );
-    } else if (msg.includes("codex_hooks_disabled")) {
-      process.stderr.write(
-        "\ncodex install refused: codex_hooks must be enabled first.\n" +
-          "add `codex_hooks = true` to your ~/.codex/config.toml and retry.\n",
-      );
     } else {
       process.stderr.write(`\napply failed: ${msg}\n`);
     }

control-plane/internal/api/install.go

@@ -380,10 +380,6 @@ func installApplyHandler(d Deps) http.HandlerFunc {
 						writeError(w, http.StatusForbidden, "unsafe_target", err.Error())
 						return
 					}
-					if errors.Is(err, errCodexFlagDisabled) {
-						writeError(w, http.StatusFailedDependency, "codex_hooks_disabled", err.Error())
-						return
-					}
 					log.Printf("install.apply: applyCodex: %v", err)
 					writeError(w, http.StatusInternalServerError, "apply_error", "codex install failed")
 					return

control-plane/internal/api/install_codex.go

@@ -4,8 +4,11 @@
 // daemon. See docs/reference/hook-daemon-path.md.
 //
 // Codex's lifecycle hooks are gated by `codex_hooks = true` in
-// ~/.codex/config.toml. Apply refuses if the flag is unset; we never
-// write into the user's TOML.
+// ~/.codex/config.toml. Apply auto-enables the flag (creating the file
+// if needed, backing it up if it existed) so users don't have to hand-
+// edit their TOML before installing. The same checkSafeCodexTarget
+// guard that protects hooks.json also protects config.toml — writes
+// into a real ~/.codex still require AGENTLOCK_ALLOW_APPLY_REAL_HOME=1.
 
 package api
 
@@ -25,8 +28,7 @@ import (
 const codexMCPGapWarning = "Codex CLI: PreToolUse only fires for shell tool calls today. MCP tool calls are NOT gated by OpenAgentLock until upstream expands hook coverage."
 
 var (
-	errCodexFlagDisabled = errors.New("codex_hooks = true is missing from config.toml; enable it before installing")
-	codexFlagLineRegex   = regexp.MustCompile(`(?m)^\s*codex_hooks\s*=\s*(true|false)\b`)
+	codexFlagLineRegex = regexp.MustCompile(`(?m)^\s*codex_hooks\s*=\s*(true|false)\b`)
 )
 
 // codexHooksPath returns the absolute path to the hooks.json file we'd
@@ -160,12 +162,13 @@ func applyCodex(daemonURL, configDirOverride, agentlockBinary string, overrides
 	if err != nil {
 		return installManifestE{}, fileOp{}, nil, err
 	}
-	enabled, err := codexFlagEnabled(tomlPath)
+	tomlNote, err := ensureCodexFlagEnabled(tomlPath)
 	if err != nil {
 		return installManifestE{}, fileOp{}, nil, err
 	}
-	if !enabled {
-		return installManifestE{}, fileOp{}, nil, fmt.Errorf("%w (path: %s)", errCodexFlagDisabled, tomlPath)
+	warnings := []string{codexMCPGapWarning}
+	if tomlNote != "" {
+		warnings = append(warnings, tomlNote)
 	}
 
 	hooksPath, err := codexHooksPath(configDirOverride, overrides)
@@ -216,7 +219,123 @@ func applyCodex(daemonURL, configDirOverride, agentlockBinary string, overrides
 			Path:       abs,
 			Reason:     fmt.Sprintf("wired Codex CLI hooks → %s (via shim)", daemonURL),
 			BackupPath: backupPath,
-		}, []string{codexMCPGapWarning}, nil
+		}, warnings, nil
+}
+
+// ensureCodexFlagEnabled idempotently makes sure
+// `codex_hooks = true` is a top-level key in the user's config.toml.
+// Cases:
+//  1. file missing → create with `codex_hooks = true\n`
+//  2. flag missing → append `codex_hooks = true\n`
+//  3. flag = false → rewrite to true (with backup)
+//  4. flag = true → no-op
+//
+// Returns a human-readable note when a write happened (empty string =
+// no change), so the caller can surface it as an install warning. The
+// real-home guard mirrors hooks.json: writes into a real ~/.codex
+// require AGENTLOCK_ALLOW_APPLY_REAL_HOME=1.
+func ensureCodexFlagEnabled(tomlPath string) (string, error) {
+	abs, err := filepath.Abs(tomlPath)
+	if err != nil {
+		return "", fmt.Errorf("resolve %s: %w", tomlPath, err)
+	}
+	if err := checkSafeCodexTarget(abs); err != nil {
+		return "", err
+	}
+
+	existing, readErr := os.ReadFile(abs)
+	if readErr != nil && !errors.Is(readErr, os.ErrNotExist) {
+		return "", fmt.Errorf("read %s: %w", abs, readErr)
+	}
+
+	// Case 1: file missing → create with the flag set.
+	if errors.Is(readErr, os.ErrNotExist) {
+		if err := os.MkdirAll(filepath.Dir(abs), 0o700); err != nil {
+			return "", fmt.Errorf("mkdir %s: %w", filepath.Dir(abs), err)
+		}
+		if err := policy.AtomicWriteFile(abs, []byte("codex_hooks = true\n"), 0o644); err != nil {
+			return "", fmt.Errorf("write %s: %w", abs, err)
+		}
+		return fmt.Sprintf("created %s with codex_hooks = true", abs), nil
+	}
+
+	// Look only at top-level (pre-first-section) lines, mirroring
+	// codexFlagEnabled.
+	state, idx := topLevelCodexFlag(existing)
+	switch state {
+	case "true":
+		return "", nil // case 4: already set
+	case "false":
+		// case 3: rewrite the matching line.
+		updated := append([]byte(nil), existing[:idx.start]...)
+		updated = append(updated, []byte("codex_hooks = true")...)
+		updated = append(updated, existing[idx.end:]...)
+		backup := fmt.Sprintf("%s.agentlock-backup-%d", abs, time.Now().UnixNano())
+		if err := policy.AtomicWriteFile(backup, existing, 0o600); err != nil {
+			return "", fmt.Errorf("write backup: %w", err)
+		}
+		if err := policy.AtomicWriteFile(abs, updated, 0o644); err != nil {
+			return "", fmt.Errorf("write %s: %w", abs, err)
+		}
+		return fmt.Sprintf("flipped codex_hooks false→true in %s (backup: %s)", abs, backup), nil
+	default:
+		// case 2: append. Make sure we don't glue onto a partial line.
+		var buf []byte
+		buf = append(buf, existing...)
+		if len(buf) > 0 && buf[len(buf)-1] != '\n' {
+			buf = append(buf, '\n')
+		}
+		buf = append(buf, []byte("codex_hooks = true\n")...)
+		backup := fmt.Sprintf("%s.agentlock-backup-%d", abs, time.Now().UnixNano())
+		if err := policy.AtomicWriteFile(backup, existing, 0o600); err != nil {
+			return "", fmt.Errorf("write backup: %w", err)
+		}
+		if err := policy.AtomicWriteFile(abs, buf, 0o644); err != nil {
+			return "", fmt.Errorf("write %s: %w", abs, err)
+		}
+		return fmt.Sprintf("added codex_hooks = true to %s (backup: %s)", abs, backup), nil
+	}
+}
+
+type codexFlagSpan struct{ start, end int }
+
+// topLevelCodexFlag scans bytes for the first top-level (pre-section)
+// `codex_hooks = (true|false)` line. Returns "" if none found.
+func topLevelCodexFlag(b []byte) (string, codexFlagSpan) {
+	cursor := 0
+	for cursor < len(b) {
+		nl := indexByteFrom(b, '\n', cursor)
+		end := nl
+		if end < 0 {
+			end = len(b)
+		}
+		line := b[cursor:end]
+		trimmed := strings.TrimSpace(string(line))
+		if strings.HasPrefix(trimmed, "[") {
+			return "", codexFlagSpan{}
+		}
+		if trimmed != "" && !strings.HasPrefix(trimmed, "#") {
+			if m := codexFlagLineRegex.FindSubmatchIndex(line); m != nil {
+				return string(line[m[2]:m[3]]), codexFlagSpan{cursor + m[0], cursor + m[1]}
+			}
+		}
+		if nl < 0 {
+			break
+		}
+		cursor = nl + 1
+	}
+	return "", codexFlagSpan{}
+}
+
+func indexByteFrom(b []byte, c byte, from int) int {
+	if from >= len(b) {
+		return -1
+	}
+	idx := strings.IndexByte(string(b[from:]), c)
+	if idx < 0 {
+		return -1
+	}
+	return from + idx
 }
 
 // checkSafeCodexTarget refuses to let apply write into the developer's

control-plane/internal/api/install_codex_test.go

@@ -91,33 +91,76 @@ func TestInstallPlan_CodexProducesWriteOpAndWarning(t *testing.T) {
 	}
 }
 
-func TestInstallApply_CodexRefusedWhenFlagDisabled(t *testing.T) {
+func TestInstallApply_CodexAutoEnablesFlagWhenMissing(t *testing.T) {
 	t.Setenv("AGENTLOCK_ALLOW_APPLY", "1")
 	fx := newGateFixture(t, enforcePolicyYAML)
 	dir := t.TempDir()
-	// config.toml exists but the flag isn't set to true.
+	// config.toml exists but the flag isn't set: auto-append.
 	writeCodexConfigToml(t, dir, "# nothing relevant\n")
 
 	res := postCodexApply(t, fx, dir, "/usr/local/bin/agentlock")
 	defer res.Body.Close()
-	if res.StatusCode != http.StatusFailedDependency {
-		t.Fatalf("status = %d, want 424", res.StatusCode)
+	if res.StatusCode != http.StatusOK {
+		buf := new(bytes.Buffer)
+		_, _ = buf.ReadFrom(res.Body)
+		t.Fatalf("status = %d body=%s", res.StatusCode, buf.String())
 	}
-	var body map[string]string
-	_ = json.NewDecoder(res.Body).Decode(&body)
-	if body["error"] != "codex_hooks_disabled" {
-		t.Fatalf("error = %v", body["error"])
+	got, err := os.ReadFile(filepath.Join(dir, "config.toml"))
+	if err != nil {
+		t.Fatalf("read config.toml: %v", err)
+	}
+	if !strings.Contains(string(got), "codex_hooks = true") {
+		t.Fatalf("expected codex_hooks = true appended, got:\n%s", got)
 	}
 }
 
-func TestInstallApply_CodexRefusedWhenConfigMissing(t *testing.T) {
+func TestInstallApply_CodexFlipsFalseToTrue(t *testing.T) {
+	t.Setenv("AGENTLOCK_ALLOW_APPLY", "1")
+	fx := newGateFixture(t, enforcePolicyYAML)
+	dir := t.TempDir()
+	writeCodexConfigToml(t, dir, "codex_hooks = false\n")
+
+	res := postCodexApply(t, fx, dir, "/usr/local/bin/agentlock")
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		buf := new(bytes.Buffer)
+		_, _ = buf.ReadFrom(res.Body)
+		t.Fatalf("status = %d body=%s", res.StatusCode, buf.String())
+	}
+	got, err := os.ReadFile(filepath.Join(dir, "config.toml"))
+	if err != nil {
+		t.Fatalf("read config.toml: %v", err)
+	}
+	if !strings.Contains(string(got), "codex_hooks = true") {
+		t.Fatalf("expected flipped to true, got:\n%s", got)
+	}
+	if strings.Contains(string(got), "codex_hooks = false") {
+		t.Fatalf("expected old false line replaced, got:\n%s", got)
+	}
+	// Backup of the original false-state should exist alongside.
+	matches, _ := filepath.Glob(filepath.Join(dir, "config.toml.agentlock-backup-*"))
+	if len(matches) != 1 {
+		t.Fatalf("expected 1 backup, got %v", matches)
+	}
+}
+
+func TestInstallApply_CodexCreatesConfigWhenMissing(t *testing.T) {
 	t.Setenv("AGENTLOCK_ALLOW_APPLY", "1")
 	fx := newGateFixture(t, enforcePolicyYAML)
 	dir := t.TempDir() // no config.toml at all
 	res := postCodexApply(t, fx, dir, "/usr/local/bin/agentlock")
 	defer res.Body.Close()
-	if res.StatusCode != http.StatusFailedDependency {
-		t.Fatalf("status = %d, want 424", res.StatusCode)
+	if res.StatusCode != http.StatusOK {
+		buf := new(bytes.Buffer)
+		_, _ = buf.ReadFrom(res.Body)
+		t.Fatalf("status = %d body=%s", res.StatusCode, buf.String())
+	}
+	got, err := os.ReadFile(filepath.Join(dir, "config.toml"))
+	if err != nil {
+		t.Fatalf("expected config.toml created: %v", err)
+	}
+	if string(got) != "codex_hooks = true\n" {
+		t.Fatalf("expected fresh codex_hooks=true file, got:\n%s", got)
 	}
 }
 

docs/guide/getting-started.md

@@ -130,7 +130,7 @@ Then pick a signer tier and run `install`. Two recommended paths:
     agentlock install --tier software
     ```
 
-Pick the harnesses to harden, review the diff, confirm. The installer writes harness-specific configuration (e.g. `~/.claude/settings.json` hook entries, `~/.codex/config.toml` `codex_hooks`) and registers a clean rollback path you can invoke later with `agentlock uninstall`.
+Pick the harnesses to harden, review the diff, confirm. The installer writes harness-specific configuration (e.g. `~/.claude/settings.json` hook entries, `~/.codex/hooks.json`, plus `codex_hooks = true` in `~/.codex/config.toml` — auto-set on first install, with a backup of the original) and registers a clean rollback path you can invoke later with `agentlock uninstall`.
 
 Open the dashboard at <http://127.0.0.1:7879/> to watch live activity.
 

docs/reference/hooks.md

@@ -29,7 +29,7 @@ event = "pre_tool"
 command = ["agentlock", "hook", "codex", "pre-tool"]
 ```
 
-The installer refuses to wire Codex without `codex_hooks = true` in your config; the flag is opt-in upstream.
+`agentlock install` auto-enables the flag for you: it creates `~/.codex/config.toml` if missing, flips `codex_hooks = false` to `true`, or appends the line to an existing TOML — backing the original up first. The flag stays user-removable; we never enable it without an install run.
 
 Codex command hooks are bash-only today; MCP coverage at the hook layer is a tracked upstream gap, not something we can paper over.