feat(localize): ground task literals in ranked primary evidence

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
         run: go build -o gortex ./cmd/gortex/
 
       - name: Test
-        run: go test -race -timeout=20m -coverprofile=coverage.out ./...
+        run: go test -race -timeout=30m -coverprofile=coverage.out ./...
 
       - name: Upload coverage
         if: matrix.os == 'ubuntu-latest' && matrix.go-version == '1.26'

cmd/gortex/testdata/agent-render/codex.txt

@@ -5,7 +5,7 @@ direct_only_tool_namespaces = ['mcp__gortex', 'gortex']
 
 [hooks]
 [[hooks.PostToolUse]]
-matcher = '^(Bash|apply_patch)$'
+matcher = '^(Bash|apply_patch|(mcp__gortex__|gortex__)(explore|search|read|relations|trace|analyze))$'
 
 [[hooks.PostToolUse.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'
@@ -14,20 +14,11 @@ timeout = 5
 type = 'command'
 
 [[hooks.PreToolUse]]
-matcher = '^Bash$'
+matcher = '.*'
 
 [[hooks.PreToolUse.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'
-statusMessage = 'Loading Gortex Bash guidance...'
-timeout = 5
-type = 'command'
-
-[[hooks.PreToolUse]]
-matcher = '^mcp__gortex__read$'
-
-[[hooks.PreToolUse.hooks]]
-command = 'gortex hook --agent=codex --mode=enrich'
-statusMessage = 'Loading Gortex read guidance...'
+statusMessage = 'Loading Gortex tool guidance...'
 timeout = 5
 type = 'command'
 
@@ -40,6 +31,13 @@ statusMessage = 'Loading Gortex graph orientation...'
 timeout = 5
 type = 'command'
 
+[[hooks.Stop]]
+[[hooks.Stop.hooks]]
+command = 'gortex hook --agent=codex --mode=enrich'
+statusMessage = 'Checking Gortex evidence authority...'
+timeout = 5
+type = 'command'
+
 [[hooks.UserPromptSubmit]]
 [[hooks.UserPromptSubmit.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'
@@ -607,7 +605,7 @@ direct_only_tool_namespaces = ['mcp__gortex', 'gortex']
 
 [hooks]
 [[hooks.PostToolUse]]
-matcher = '^(Bash|apply_patch)$'
+matcher = '^(Bash|apply_patch|(mcp__gortex__|gortex__)(explore|search|read|relations|trace|analyze))$'
 
 [[hooks.PostToolUse.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'
@@ -616,20 +614,11 @@ timeout = 5
 type = 'command'
 
 [[hooks.PreToolUse]]
-matcher = '^Bash$'
+matcher = '.*'
 
 [[hooks.PreToolUse.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'
-statusMessage = 'Loading Gortex Bash guidance...'
-timeout = 5
-type = 'command'
-
-[[hooks.PreToolUse]]
-matcher = '^mcp__gortex__read$'
-
-[[hooks.PreToolUse.hooks]]
-command = 'gortex hook --agent=codex --mode=enrich'
-statusMessage = 'Loading Gortex read guidance...'
+statusMessage = 'Loading Gortex tool guidance...'
 timeout = 5
 type = 'command'
 
@@ -642,6 +631,13 @@ statusMessage = 'Loading Gortex graph orientation...'
 timeout = 5
 type = 'command'
 
+[[hooks.Stop]]
+[[hooks.Stop.hooks]]
+command = 'gortex hook --agent=codex --mode=enrich'
+statusMessage = 'Checking Gortex evidence authority...'
+timeout = 5
+type = 'command'
+
 [[hooks.UserPromptSubmit]]
 [[hooks.UserPromptSubmit.hooks]]
 command = 'gortex hook --agent=codex --mode=enrich'

docs/agents.md

@@ -376,6 +376,7 @@ Current Codex hook coverage:
 | Surface | Coverage |
 | ------- | -------- |
 | `SessionStart` | Matches `startup|resume|clear|compact` and emits graph-tools orientation for new, resumed, cleared, and compacted sessions. |
+| Hook-observable local-tool `PreToolUse` terminal gate | Uses one match-all installer-owned hook so an enforceable localization `answer_ready` contract blocks every local tool Codex routes through `PreToolUse`, including Bash, `apply_patch`, MCP tools, and other local function tools. Hosted tools such as `WebSearch`, and specialized paths that opt out of the default hook path, are outside this host boundary. Without a terminal marker it is a local no-op; advisory completion still permits non-navigation contract operations. |
 | Bash `PreToolUse` | Advises by default; `deny` hard-blocks graph-detectable fallback reads/searches; `rewrite` converts only an unambiguous indexed `cat <source>` into the exact public `gortex call read` mirror. Compound or ambiguous commands remain advisory. A shell command that would *rewrite* indexed source — `sed -i` / `perl -pi`, a `>` / `>>` redirect, `tee`, or an inline interpreter script opening the path for writing — gets the same redirect Edit and Write get, escalating to a hard block under `GORTEX_HOOK_BLOCK_EDIT`. Writing a path the daemon does not know is a new file and passes through. |
 | Gortex MCP `read` `PreToolUse` | Advises broad file/editing-context reads by default; `deny` blocks them; `rewrite` preserves the request and adds `options.compress_bodies=true`. Selector-driven reads with no explicit operation are covered. |
 | Bash `PostToolUse` | Adds graph context for grep/search, source reads, and conservative file-list shapes: `find -name`, `fd`, `ls`, `tree -fi`, and `git ls-files`; bounded `sed`/`awk` reads get file graph context. Execution-capable or ambiguous forms are no-ops. |

internal/agents/codex/adapter.go

@@ -62,11 +62,20 @@ const (
 	v060CodexSessionStartMessage        = "IMPORTANT: Prefer Gortex MCP tools (search_symbols, get_callers, get_file_summary, edit_file) over Read/Grep/Glob/Edit."
 	v060CodexSessionStartCommand        = "printf '%s\\n' '" + v060CodexSessionStartMessage + "'"
 	v060CodexSessionStartWindowsCommand = "powershell -NoProfile -Command \"Write-Output '" + v060CodexSessionStartMessage + "'\""
-	codexPreToolUseMatcher              = "^Bash$"
-	codexMCPReadPreToolUseMatcher       = "^mcp__gortex__read$"
-	codexPostToolUseMatcher             = "^(Bash|apply_patch)$"
-	codexHookTimeoutSeconds             = 5
-	codexHookModeEnvVar                 = "GORTEX_CODEX_HOOK_MODE"
+	// Codex matchers are regular expressions. A match-all PreToolUse hook is
+	// required because terminal localization covers every local tool routed
+	// through Codex's hook path; hosted and specialized opt-out tools remain
+	// outside the host's hook boundary. Without a marker the handler is a
+	// strict local no-op.
+	codexPreToolUseMatcher = ".*"
+	// Retained as migration fingerprints in tests: upsertCodexHookSet removes
+	// both split predecessors by managed command identity before installing the
+	// singleton match-all hook.
+	codexLegacyBashPreToolUseMatcher          = "^Bash$"
+	codexLegacyMCPNavigationPreToolUseMatcher = "^(mcp__gortex__|gortex__)(explore|search|read|relations|trace|analyze)$"
+	codexPostToolUseMatcher                   = "^(Bash|apply_patch|(mcp__gortex__|gortex__)(explore|search|read|relations|trace|analyze))$"
+	codexHookTimeoutSeconds                   = 5
+	codexHookModeEnvVar                       = "GORTEX_CODEX_HOOK_MODE"
 	// Codex merges its home instructions file into every session ahead of
 	// the repo's own AGENTS.md, preferring the override name when present.
 	codexGlobalInstructionsFile         = "AGENTS.md"
@@ -550,11 +559,77 @@ func upsertSessionStartHook(root map[string]any, env agents.Env, opts agents.App
 }
 
 func upsertPreToolUseHook(root map[string]any, env agents.Env, opts agents.ApplyOpts) bool {
-	desired := []map[string]any{
-		codexPreToolUseHookEntry(env),
-		codexMCPReadPreToolUseHookEntry(env),
+	// Codex permits several handlers in one matcher group. Normalize at handler
+	// granularity before replacing legacy Gortex matchers: this preserves every
+	// co-located user handler while collapsing duplicate managed invocations.
+	splitChanged := splitMixedCodexPreToolUseGroups(root)
+	desired := []map[string]any{codexPreToolUseHookEntry(env)}
+	upsertChanged := upsertCodexHookSet(root, "PreToolUse", codexHookEntryIsGortexPreToolUse, desired, opts)
+	return splitChanged || upsertChanged
+}
+
+func splitMixedCodexPreToolUseGroups(root map[string]any) bool {
+	hooks, ok := root["hooks"].(map[string]any)
+	if !ok {
+		return false
+	}
+	entries, ok := codexHookList(hooks["PreToolUse"])
+	if !ok {
+		return false
+	}
+
+	normalized := make([]any, 0, len(entries))
+	changed := false
+	for _, entry := range entries {
+		group, ok := entry.(map[string]any)
+		if !ok {
+			normalized = append(normalized, entry)
+			continue
+		}
+		handlers, ok := codexHookList(group["hooks"])
+		if !ok {
+			normalized = append(normalized, entry)
+			continue
+		}
+		managed := 0
+		kept := make([]any, 0, len(handlers))
+		for _, handler := range handlers {
+			fields, ok := handler.(map[string]any)
+			if ok {
+				command, _ := fields["command"].(string)
+				if codexCommandInvokesCodexHook(command) {
+					managed++
+					continue
+				}
+			}
+			kept = append(kept, handler)
+		}
+		switch {
+		case managed == 0:
+			normalized = append(normalized, entry)
+		case managed == 1 && len(handlers) == 1:
+			// Leave a singleton managed group for upsertCodexHookSet to
+			// validate or replace. A current singleton remains idempotent.
+			normalized = append(normalized, entry)
+		default:
+			changed = true
+			if len(kept) == 0 {
+				continue
+			}
+			preserved := make(map[string]any, len(group))
+			for key, value := range group {
+				preserved[key] = value
+			}
+			preserved["hooks"] = kept
+			normalized = append(normalized, preserved)
+		}
+	}
+	if !changed {
+		return false
 	}
-	return upsertCodexHookSet(root, "PreToolUse", codexHookEntryIsGortexPreToolUse, desired, opts)
+	hooks["PreToolUse"] = normalized
+	root["hooks"] = hooks
+	return true
 }
 
 func upsertPostToolUseHook(root map[string]any, env agents.Env, opts agents.ApplyOpts) bool {
@@ -565,6 +640,10 @@ func upsertUserPromptSubmitHook(root map[string]any, env agents.Env, opts agents
 	return upsertCodexHookSet(root, "UserPromptSubmit", codexHookEntryIsGortexUserPromptSubmit, []map[string]any{codexUserPromptSubmitHookEntry(env)}, opts)
 }
 
+func upsertStopHook(root map[string]any, env agents.Env, opts agents.ApplyOpts) bool {
+	return upsertCodexHookSet(root, "Stop", codexHookEntryIsGortexStop, []map[string]any{codexStopHookEntry(env)}, opts)
+}
+
 // InstallHooksOnly refreshes the Codex lifecycle hooks in configPath without
 // touching MCP server entries, AGENTS.md, or any other Codex adapter surface.
 func InstallHooksOnly(w io.Writer, configPath string, env agents.Env, opts agents.ApplyOpts) (agents.FileAction, error) {
@@ -585,7 +664,8 @@ func upsertCodexHooks(root map[string]any, env agents.Env, opts agents.ApplyOpts
 	preChanged := upsertPreToolUseHook(root, env, opts)
 	postChanged := upsertPostToolUseHook(root, env, opts)
 	promptChanged := upsertUserPromptSubmitHook(root, env, opts)
-	return sessionChanged || preChanged || postChanged || promptChanged
+	stopChanged := upsertStopHook(root, env, opts)
+	return sessionChanged || preChanged || postChanged || promptChanged || stopChanged
 }
 
 func upsertCodexHookSet(root map[string]any, event string, isGortex func(any) bool, desired []map[string]any, opts agents.ApplyOpts) bool {
@@ -734,6 +814,10 @@ func codexHookEntryIsGortexUserPromptSubmit(entry any) bool {
 	return codexHookEntryInvokesCodexHook(entry)
 }
 
+func codexHookEntryIsGortexStop(entry any) bool {
+	return codexHookEntryInvokesCodexHook(entry)
+}
+
 func codexHookEntryInvokesCodexHook(entry any) bool {
 	group, ok := entry.(map[string]any)
 	if !ok {
@@ -789,21 +873,7 @@ func codexPreToolUseHookEntry(env agents.Env) map[string]any {
 				"type":          "command",
 				"command":       codexPreToolUseCommand(env),
 				"timeout":       codexHookTimeoutSeconds,
-				"statusMessage": "Loading Gortex Bash guidance...",
-			},
-		},
-	}
-}
-
-func codexMCPReadPreToolUseHookEntry(env agents.Env) map[string]any {
-	return map[string]any{
-		"matcher": codexMCPReadPreToolUseMatcher,
-		"hooks": []any{
-			map[string]any{
-				"type":          "command",
-				"command":       codexPreToolUseCommand(env),
-				"timeout":       codexHookTimeoutSeconds,
-				"statusMessage": "Loading Gortex read guidance...",
+				"statusMessage": "Loading Gortex tool guidance...",
 			},
 		},
 	}
@@ -841,6 +911,22 @@ func codexUserPromptSubmitHookEntry(env agents.Env) map[string]any {
 	}
 }
 
+// codexStopHookEntry has no matcher: Stop applies to every final response.
+// Older Codex hosts that omit last_assistant_message remain fail-open in the
+// shared Stop handler.
+func codexStopHookEntry(env agents.Env) map[string]any {
+	return map[string]any{
+		"hooks": []any{
+			map[string]any{
+				"type":          "command",
+				"command":       codexHookCommand(env),
+				"timeout":       codexHookTimeoutSeconds,
+				"statusMessage": "Checking Gortex evidence authority...",
+			},
+		},
+	}
+}
+
 func codexPreToolUseCommand(env agents.Env) string {
 	return codexHookCommand(env)
 }