Support ACP session metadata pass-through for Codex threadStart/config #215

Summary

codex-acp currently accepts a narrow set of ACP session inputs and maps them into Codex app-server state. For integrations that need per-session behavior, there does not seem to be a documented way to forward metadata such as systemPrompt, developer instructions, or arbitrary Codex threadStart.config overrides.

Use case

ACP clients such as OpenClaw/acp-harness need to forward their runtime prompt and session options to external ACP agents.

For example, Claude ACP can consume _meta.systemPrompt, but codex-acp currently appears to ignore it. This makes it hard for ACP clients to provide equivalent behavior across agents.

Current behavior

From src/CodexAcpClient.ts on main:

• newSession() calls codexClient.threadStart({ config, modelProvider, cwd }).
• createSessionConfig() builds project trust roots, sandbox writable roots, MCP server config, and gateway provider config.
• _meta.additionalRoots is read as a fallback for additionalDirectories, then mapped into Codex skill extra roots.
• _meta.systemPrompt and other generic session options are not mapped into Codex app-server threadStart params or config.

Proposed behavior

Please add a documented pass-through mechanism for ACP clients to provide Codex session/thread options.

One possible shape:

_meta: {
  codex?: {
    config?: Record<string, unknown>;
    threadStart?: {
      baseInstructions?: string;
      developerInstructions?: string;
      config?: Record<string, unknown>;
    };
  };

  // optional compatibility alias used by some ACP clients
  systemPrompt?: string | { append: string };
}

Possible mapping:

• _meta.codex.config merges into the existing threadStart.config.
• _meta.codex.threadStart.baseInstructions maps to Codex app-server baseInstructions.
• _meta.codex.threadStart.developerInstructions maps to Codex app-server developerInstructions.
• _meta.systemPrompt could either be ignored explicitly, documented as unsupported, or mapped as a compatibility alias to developerInstructions / config.instructions.

Why this matters

ACP clients can already pass session metadata through _meta, and different ACP agents expose similar functionality differently. A Codex-specific pass-through would let clients integrate Codex ACP without patching or forking codex-acp.

It would also make skills/prompt/session behavior easier to align across ACP adapters while keeping Codex-specific behavior namespaced under _meta.codex.

Compatibility

This can be additive and should not affect existing clients:

• Existing additionalDirectories and _meta.additionalRoots behavior can remain unchanged.
• Existing CODEX_CONFIG behavior can remain the base config.
• New _meta.codex.config can be merged after the base config so per-session callers can override intentionally.