codex

modules/applications/codex/home.nix

@@ -1,6 +1,325 @@
-{ inputs, pkgs, ... }:
 {
-  home.packages = [
+  config,
-    inputs.llm-agents.packages.${pkgs.stdenv.hostPlatform.system}.codex
+  inputs,
-  ];
+  lib,
+  pkgs,
+  ...
+}:
+let
+  codexPackage = inputs.llm-agents.packages.${pkgs.stdenv.hostPlatform.system}.codex;
+
+  tomlFormat = pkgs.formats.toml { };
+
+  mkAgent = name: settings: {
+    source = tomlFormat.generate "codex-agent-${name}.toml" settings;
+  };
+
+  agentFiles = {
+    # Overrides Codex's built-in explorer role.
+    "explorer.toml" = mkAgent "explorer" {
+      name = "explorer";
+      description = "Read-only repository exploration, code-path tracing, and evidence gathering.";
+
+      model = "gpt-5.6-luna";
+      model_reasoning_effort = "high";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      sandbox_mode = "read-only";
+      web_search = "disabled";
+
+      developer_instructions = ''
+        You are a read-only repository explorer.
+
+        Investigate only the scope assigned by the parent agent. Do not edit files,
+        run state-changing commands, or spawn subagents. Prefer targeted searches
+        with rg and git plus narrow file reads over broad repository dumps.
+
+        Trace definitions, imports, call paths, configuration flow, and ownership.
+        Distinguish verified facts from hypotheses.
+
+        Return a concise report in English containing:
+        - scope examined;
+        - relevant files and symbols;
+        - the actual execution or configuration flow;
+        - supporting evidence;
+        - remaining unknowns.
+
+        Do not return long raw logs unless a short excerpt is necessary evidence.
+      '';
+    };
+
+    "docs-researcher.toml" = mkAgent "docs-researcher" {
+      name = "docs_researcher";
+      description = "Current, version-specific research using primary and official sources.";
+
+      model = "gpt-5.6-luna";
+      model_reasoning_effort = "medium";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      sandbox_mode = "read-only";
+
+      web_search = "live";
+      tools.web_search.context_size = "high";
+
+      developer_instructions = ''
+        Research the assigned question using current, version-specific evidence.
+        Prefer official documentation, source repositories, specifications, release
+        notes, and primary research. Use the source language when it materially
+        improves retrieval. Do not edit repository files or spawn subagents.
+
+        Return a concise report in English containing:
+        - confirmed behavior and the applicable version;
+        - exact sources and relevant sections;
+        - disagreements between sources;
+        - clearly labeled inferences and uncertainties;
+        - implementation implications for the parent agent.
+      '';
+    };
+
+    # Overrides Codex's built-in worker role.
+    "worker.toml" = mkAgent "worker" {
+      name = "worker";
+      description = "Focused implementation and ordinary debugging after scope and acceptance criteria are defined.";
+
+      model = "gpt-5.6-terra";
+      model_reasoning_effort = "medium";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      sandbox_mode = "workspace-write";
+      web_search = "cached";
+
+      developer_instructions = ''
+        Implement only the scope and acceptance criteria assigned by the parent.
+        Inspect the relevant code before editing, preserve repository conventions,
+        and make the smallest coherent change that solves the task. Do not spawn
+        subagents.
+
+        Use the configured Codex sandbox and Auto-review for command permissions.
+        Do not create a separate approval workflow.
+
+        Unless explicitly requested, do not commit, push, rebase, deploy, activate
+        a system configuration, modify secrets, add unrelated dependencies, update
+        lockfiles, or perform unrelated refactoring.
+
+        Run focused validation when appropriate. Return a concise report in English
+        containing changed files, rationale, exact validation commands and exit
+        status, acceptance-criteria evidence, and remaining risks.
+      '';
+    };
+
+    "validator.toml" = mkAgent "validator" {
+      name = "validator";
+      description = "Focused build, test, lint, evaluation, and regression validation.";
+
+      model = "gpt-5.6-luna";
+      model_reasoning_effort = "high";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      # Tests and builds often need to create temporary or generated files.
+      sandbox_mode = "workspace-write";
+      web_search = "disabled";
+
+      developer_instructions = ''
+        Run only the validation requested by the parent agent. Do not intentionally
+        edit tracked source files, update lockfiles, install dependencies globally,
+        or spawn subagents. Check repository status before and after commands when
+        generated files are possible.
+
+        Return a concise report in English containing every command executed, its
+        exit status, the relevant output or failure excerpt, any generated or changed
+        files, and what remains unverified. Never report a check as passed unless it
+        actually completed successfully.
+      '';
+    };
+
+    "reviewer.toml" = mkAgent "reviewer" {
+      name = "reviewer";
+      description = "Independent review of the actual diff for correctness, security, regressions, and missing tests.";
+
+      model = "gpt-5.6-terra";
+      model_reasoning_effort = "high";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      sandbox_mode = "read-only";
+      web_search = "cached";
+
+      developer_instructions = ''
+        Independently review the actual working tree, diff, and relevant code. Do
+        not trust the implementer's summary as evidence. Do not edit files or spawn
+        subagents.
+
+        Prioritize correctness, security, compatibility, regressions, error handling,
+        and test coverage. Avoid style-only findings unless they have an operational
+        consequence.
+
+        Begin with PASS, FAIL, or INCONCLUSIVE. Then provide findings in severity
+        order with exact files and symbols, evidence or reproduction steps, and the
+        smallest safe correction. State which acceptance criteria and important paths
+        were checked and which were not.
+      '';
+    };
+
+    "deep-debugger.toml" = mkAgent "deep-debugger" {
+      name = "deep_debugger";
+      description = "Root-cause analysis and repair for complex failures that normal implementation did not resolve.";
+
+      model = "gpt-5.6-terra";
+      model_reasoning_effort = "xhigh";
+      model_reasoning_summary = "concise";
+      model_verbosity = "low";
+
+      sandbox_mode = "workspace-write";
+
+      web_search = "live";
+      tools.web_search.context_size = "medium";
+
+      developer_instructions = ''
+        Use this role only for a complex or unresolved failure. Start from the
+        observed evidence, reproduce when feasible, trace the causal path, and fix
+        the root cause rather than masking the symptom. Add or run a focused
+        regression check. Avoid broad speculative refactors and do not spawn
+        subagents.
+
+        Use the configured Codex sandbox and Auto-review for command permissions.
+        Unless explicitly requested, do not commit, push, rebase, deploy, activate
+        a system configuration, modify secrets, or update unrelated dependencies.
+
+        Return a concise report in English containing the root cause, evidence,
+        changed files, exact validation commands and results, and remaining risks.
+      '';
+    };
+  };
+
+  mkAgentTargets =
+    prefix:
+    lib.mapAttrs' (fileName: file: lib.nameValuePair "${prefix}/agents/${fileName}" file) agentFiles;
+in
+{
+  programs.codex = {
+    enable = true;
+    package = codexPackage;
+
+    settings = {
+      # Parent/orchestrator.
+      #
+      # Sol medium is the economical default. Complex planning gets high through
+      # plan_mode_reasoning_effort, while Max/Ultra are selected per session.
+      model = "gpt-5.6-sol";
+      model_reasoning_effort = "medium";
+      plan_mode_reasoning_effort = "high";
+
+      model_reasoning_summary = "concise";
+      model_verbosity = "medium";
+
+      # Limits how much of one tool result is retained in conversation history.
+      # This does not limit command execution itself.
+      tool_output_token_limit = 12000;
+
+      # Routine in-sandbox actions run normally. Requests to cross the sandbox
+      # boundary are reviewed by Codex Auto-review instead of the user.
+      sandbox_mode = "workspace-write";
+      approval_policy = "on-request";
+      approvals_reviewer = "auto_review";
+
+      # Shell network access remains a sandbox boundary. Benign requests can be
+      # approved automatically by Auto-review.
+      sandbox_workspace_write.network_access = false;
+
+      # Parent gets cached search by default. docs_researcher and deep_debugger
+      # override this to live search.
+      web_search = "cached";
+      tools.web_search.context_size = "medium";
+
+      # Codex is updated through the llm-agents flake input.
+      check_for_update_on_startup = false;
+
+      agents = {
+        enabled = true;
+
+        # Excludes the primary Sol thread.
+        max_concurrent_threads_per_session = 4;
+
+        # Fallback for an unnamed or explicitly ad-hoc subagent.
+        default_subagent_model = "gpt-5.6-terra";
+        default_subagent_reasoning_effort = "medium";
+
+        interrupt_message = true;
+      };
+
+      projects."/home/moons/dotfiles".trust_level = "trusted";
+    };
+
+    # Written to CODEX_HOME/AGENTS.md and inherited by every repository.
+    context = ''
+      # Global Codex operating policy
+
+      ## Language
+
+      - Use English for agent-to-agent assignments, technical working notes, and
+        delegated reports.
+      - Use another language for search and source reading when it materially
+        improves retrieval or accuracy.
+      - Reply to the user in the language used by the user; default to Japanese.
+      - Preserve code identifiers, commands, paths, API names, and diagnostics in
+        their original form.
+
+      ## Orchestration
+
+        The primary Sol thread is an orchestrator, not an implementation worker.
+
+        - The primary owns requirements, task decomposition, acceptance criteria,
+          risk decisions, coordination, and final synthesis.
+        - For any task that requires modifying repository files, the primary MUST
+          delegate the implementation to `worker`. The primary MUST NOT perform
+          repository edits itself.
+        - Delegate repository exploration to `explorer` when investigation beyond
+          a small, obvious local read is required.
+        - Delegate current or version-specific external research to `docs_researcher`.
+        - Delegate builds, tests, linting, evaluation, and regression checks to
+          `validator` when they are substantial enough to produce nontrivial output.
+        - After a nontrivial implementation, delegate independent diff review to
+          `reviewer`.
+        - Use `deep_debugger` when an ordinary worker attempt fails or when the
+          failure is intrinsically difficult.
+        - The primary may handle trivial read-only questions directly when spawning
+          another agent would clearly cost more than the work itself.
+        - Use at most one write-capable subagent in the same worktree at a time.
+        - Subagents must not spawn subagents.
+
+      ## Implementation
+
+      - Read every applicable project `AGENTS.md` before changing code.
+      - Make the smallest coherent change that satisfies the acceptance criteria and
+        preserve existing repository conventions.
+      - Do not commit, push, rebase, deploy, activate system configuration, or modify
+        secrets unless the user explicitly requests it.
+      - Do not add dependencies or update lockfiles unless required by the task; state
+        the reason when doing so.
+      - For Nix changes, run evaluation, build, formatting, or check commands suited to
+        the changed scope. Do not run `switch` unless the user explicitly requests it.
+
+      ## Validation and reporting
+
+      - Validate against the actual diff, repository state, and command exit status.
+      - Never claim that a command, test, build, or check ran when it did not.
+      - State exactly what was verified, what failed, and what remains unverified.
+      - Keep the final user-facing response focused on decisions, changes, evidence,
+        and remaining risks rather than internal coordination details.
+    '';
+  };
+
+  # Home Manager release-26.05 has programs.codex.settings/context, but no
+  # dedicated option for CODEX_HOME/agents/*.toml. Manage custom agents as
+  # ordinary files.
+  #
+  # Match programs.codex's XDG behavior so this also works if
+  # home.preferXdgDirectories is changed later.
+  home.file = lib.mkIf (!config.home.preferXdgDirectories) (mkAgentTargets ".codex");
+
+  xdg.configFile = lib.mkIf config.home.preferXdgDirectories (mkAgentTargets "codex");
 }