Skip to content

Launch Policy

The launch policy engine governs agent behavior during the run phase by applying a set of typed mutations to the launch environment. Policies are resolved during the build phase and control agent autonomy, prompt modes, and provider-specific configuration.

Operator Prompt Mode

The OperatorPromptMode determines how the agent interacts with the operator during execution:

Mode Description
as_is Standard mode. Normal operator interaction and prompts are enabled. No launch policy is applied.
unattended Fully automated mode. All interactive prompts are suppressed and the launch policy strategy configures the tool for hands-off execution.

When no mode is specified or as_is is selected, the policy engine returns the executable and base arguments without applying any strategy.

Policy Strategy

A LaunchPolicyStrategy is the core unit of the policy engine. Each strategy contains:

  • strategy_id: Unique identifier (e.g., claude-unattended-2.1.81).
  • operator_prompt_mode: Which mode this strategy applies to.
  • backends: List of supported launch surfaces (e.g., raw_launch, claude_headless, codex_headless). Note: LaunchSurface (build-phase) includes raw_launch for generic local execution, while the run-phase BackendKind type uses local_interactive instead; raw_launch maps to local_interactive at runtime.
  • supported_versions: PEP 440-style version specifier for tool version compatibility (e.g., >=2.1.81).
  • minimal_inputs: Contract requirements — acceptable credential forms, whether user-prepared state is needed.
  • owned_paths: File paths and keys the strategy manages to avoid conflicts with user configuration.
  • actions: Ordered list of mutations to apply to the launch environment.

Policy Resolution

Strategies are resolved from the versioned registry with this precedence:

Priority Source Description
1 HOUMAO_LAUNCH_POLICY_OVERRIDE_STRATEGY Environment variable. Must name a strategy_id that matches the requested mode and backend.
2 Registry documents Tool-specific YAML files in agents/launch_policy/registry/. Filtered by mode, backend, and detected tool version. Must produce exactly one match.
3 No policy When mode is None or as_is, the engine returns the raw executable with no mutations.

Resolution detects the tool version by running <executable> --version and parsing the semantic version. The detected version is matched against each strategy's supported_versions specifier.

Provider Hooks

Provider hooks are named actions within a strategy that perform provider-specific setup:

Claude Hooks

Hook Description
claude.ensure_api_key_approval Seeds API-key approval state in .claude.json without storing the full key.
claude.ensure_project_trust Seeds workspace trust state for the resolved working directory.

Codex Hooks

Hook Description
codex.canonicalize_unattended_launch_inputs Strips caller-supplied overrides that target unattended surfaces (e.g., --full-auto, --sandbox).
codex.validate_credential_readiness Ensures auth.json exists or a config-backed env-only provider is set up.
codex.ensure_project_trust Seeds project trust level in config.toml.
codex.ensure_model_migration_state Seeds model migration state in config.toml.
codex.append_unattended_cli_overrides Appends final Codex CLI -c override arguments for approval_policy, sandbox_mode, and notice.hide_full_access_warning so project-local config.toml cannot weaken unattended posture.

Gemini Hooks

Hook Description
gemini.canonicalize_unattended_launch_inputs Strips caller-supplied --yolo, --approval-mode, and --sandbox overrides so the maintained unattended Gemini posture can be re-applied deterministically.
gemini.ensure_unattended_runtime_state Repairs or patches .gemini/settings.json only when copied runtime-home settings would weaken unattended Gemini approval, sandbox, or tool-availability posture.

Hooks run within a provider state mutation lock for thread-safe file access.

Gemini Unattended Posture

Maintained Gemini unattended startup is owned by launch policy rather than by copied setup defaults. For gemini_headless, the policy engine force-applies --approval-mode=yolo and --sandbox=false so non-interactive Gemini keeps shell and file-mutation tools available instead of falling back to Gemini CLI's default headless read-only posture.

This ownership is authoritative for the unattended path. If adapter defaults, recipe overrides, direct launch args, or copied .gemini/settings.json content request a weaker approval mode, enable sandboxing, or restrict the built-in tool registry, launch policy replaces or repairs those owned surfaces before provider start. Non-unattended Gemini launches remain as_is.

Versioned Registry

The registry stores strategies in per-tool YAML files under agents/launch_policy/registry/:

agents/launch_policy/registry/
  claude.yaml     # strategies for Claude Code
  codex.yaml      # strategies for Codex CLI

Each file enforces schema_version: 1 and contains one or more strategy definitions. Multiple strategies can coexist in one file with different supported_versions ranges — the resolution logic selects the unique matching strategy for the detected tool version.

Integration with the Build Phase

During BrainBuilder.build(), the launch policy is resolved and included in the BrainManifest. The resolution flow:

  1. The build request specifies an operator_prompt_mode (from the recipe, the resolved launch profile, or direct input).
  2. The policy engine detects the tool version and finds the matching strategy from the registry.
  3. The strategy's actions are applied to the launch environment (environment variables, config file mutations, provider hooks).
  4. The resolved strategy provenance is recorded in the manifest for diagnostic traceability.

See Also