Release v0.4.4: App-server multi-modal inputs, exec CLI parity, typed deltas

This release closes significant parity gaps with the upstream Codex CLI and
app-server protocol, adding multi-modal input support, comprehensive CLI flag
forwarding, and typed event handling for previously raw notifications.

App-server transport enhancements:

- Thread.run/3 and run_streamed/3 now accept UserInput block lists containing
  text, image, and localImage types in addition to plain string input
- Thread start/resume forwards model, model_provider, config, base_instructions,
  developer_instructions, and experimental_raw_events parameters
- Codex.Options defaults for model and reasoning_effort are applied to
  app-server thread starts when not explicitly overridden
- Sandbox policy accepts full structured format with type, writable_roots,
  network_access, exclude_tmpdir_env_var, and exclude_slash_tmp fields
- Added command_write_stdin/4 for interactive terminal command input

Typed app-server notifications:

- ReasoningSummaryPartAdded for incremental reasoning summary updates
- FileChangeOutputDelta for streaming file change apply-patch output
- TerminalInteraction for interactive stdin write events
- McpToolCallProgress for MCP tool execution progress messages
- AccountUpdated, AccountRateLimitsUpdated, AccountLoginCompleted for auth state
- McpServerOauthLoginCompleted for MCP OAuth flow completion
- WindowsWorldWritableWarning for Windows security warnings
- TurnCompleted now includes error field from turn.error payloads

Exec CLI parity:

- Added profile, oss, local_provider, full_auto, output_last_message, and color
  flags to thread options with proper CLI argument forwarding
- Added dangerously_bypass_approvals_and_sandbox flag (mutually exclusive with
  full_auto)
- Generic config_overrides field accepts string list or key/value pairs for
  arbitrary -c key=value overrides
- Exec.review/2 and review_stream/2 run codex exec review with uncommitted,
  base_branch, commit, or custom prompt targets
- Codex.resume_thread(:last) maps to codex exec resume --last

Reasoning item fidelity:

- Items.Reasoning now preserves summary and content as separate list fields
- Text field is still populated by joining summary and content for backwards
  compatibility
- ItemAdapter and Items.parse handle structured reasoning consistently

Approval handling:

- Approval hooks can return grant_root option to accept file-change approvals
  with the proposed root for the current session
- ApprovalDecision encodes grant_root as acceptForSession response

Bug fixes:

- Streamed turn failures handle non-text final_response payloads without
  crashing by extracting error details from turn.error when present
- Structured /new input blocks (single text block containing /new) properly
  reset conversation state for app-server and exec transport runs
- Tool guardrail handler exceptions are caught and surfaced as GuardrailError
  instead of crashing the turn process
- Approval hook exceptions are caught and surfaced as Error with kind
  approval_hook_failed
- Progress telemetry metadata merge handles nil base metadata gracefully
- Thread.Backoff clamps exponential delay to prevent integer overflow on high
  attempt counts
- Tool call deduplication uses fallback key based on tool_name and arguments
  hash when call_id is nil

Test coverage:

- Added tests for multi-modal input handling in app-server transport
- Added tests for structured /new reset behavior
- Added tests for guardrail and approval hook exception handling
- Added tests for exec CLI flag forwarding and review subcommand
- Added tests for reasoning summary/content preservation
- Added notification adapter tests for all new typed events
- Added backoff overflow protection tests

Author: nshkrdotcom

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.4] - 2025-12-29
+
+### Added
+
+- App-server `UserInput` list support for `Codex.Thread.run/3` and `run_streamed/3` (text/image/localImage)
+- Thread/turn app-server params for model/provider/config/instructions, sandbox_policy, and experimental raw events, with defaults for model + reasoning effort
+- Typed app-server notifications for reasoning summaries/deltas, command/file output deltas, terminal interaction, MCP progress, and account updates
+- Exec CLI parity flags (`--profile`, `--oss`, `--local-provider`, `--full-auto`, `--dangerously-bypass-approvals-and-sandbox`, `--output-last-message`, `--color`)
+- Generic `-c key=value` config overrides, exec review wrapper, and resume --last support
+- Grant-root approval handling for file changes and `Codex.AppServer.command_write_stdin/4`
+
+### Changed
+
+- Reasoning items now preserve `summary`/`content` structure instead of flattened text
+- App-server `turn.error` payloads are surfaced on `Codex.Events.TurnCompleted`
+
+### Fixed
+
+- Streamed turn failures now handle non-text `final_response` payloads without crashing and include `turn.error` details when present
+- Structured `/new` input blocks now reset conversation state for app-server/exec turn runs and streams
+- Tool guardrail and approval hook exceptions are surfaced as errors instead of crashing the turn
+- Progress telemetry metadata now merges even when base metadata is nil
+
+### Documentation
+
+- Updated README and API reference for new input types, exec flags, and app-server deltas
+
 ## [0.4.3] - 2025-12-27
 
 ### Added

README.md

@@ -16,9 +16,9 @@ An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and
 ## Features
 
 - **End-to-End Codex Lifecycle**: Spawn, resume, and manage full Codex threads with rich turn instrumentation.
-- **Multi-Transport Support**: Default exec JSONL (`codex exec --experimental-json`) plus stateful app-server JSON-RPC over stdio (`codex app-server`).
-- **Upstream Compatibility**: Automatically handles select app-server protocol differences across Codex CLI versions (e.g. MCP list method rename fallbacks).
-- **Streaming & Structured Output**: Real-time events plus first-class JSON schema handling for deterministic parsing.
+- **Multi-Transport Support**: Default exec JSONL (`codex exec --experimental-json`) plus stateful app-server JSON-RPC over stdio (`codex app-server`) with multi-modal `UserInput` blocks.
+- **Upstream Compatibility**: Mirrors Codex CLI flags (profile/OSS/full-auto/color, config overrides, review/resume) and handles app-server protocol drift (e.g. MCP list method rename fallbacks).
+- **Streaming & Structured Output**: Real-time events plus reasoning summary/content preservation and typed app-server deltas.
 - **File & Attachment Pipeline**: Secure temp file registry, change events, and fixture harvesting helpers.
 - **Approval Hooks & Sandbox Policies**: Dynamic or static approval flows with registry-backed persistence.
 - **Tooling & MCP Integration**: Built-in registry for Codex tool manifests and MCP client helpers.
@@ -33,7 +33,7 @@ Add `codex_sdk` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:codex_sdk, "~> 0.4.3"}
+    {:codex_sdk, "~> 0.4.4"}
   ]
 end
 ```
@@ -120,11 +120,25 @@ The SDK defaults to exec JSONL for backwards compatibility. To use the stateful
 {:ok, %{"data" => skills}} = Codex.AppServer.skills_list(conn, cwds: ["/project"])
 ```
 
+Multi-modal input is supported on app-server transport:
+
+```elixir
+input = [
+  %{type: :text, text: "Explain this screenshot"},
+  %{type: :local_image, path: "/tmp/screenshot.png"}
+]
+
+{:ok, result} = Codex.Thread.run(thread, input)
+```
+
+Note: exec JSONL transport still accepts text input only; list inputs return `{:error, {:unsupported_input, :exec}}`.
+
 App-server-only APIs include:
 
 - `Codex.AppServer.thread_list/2`, `thread_archive/2`
 - `Codex.AppServer.model_list/2`, `config_read/2`, `config_write/4`, `config_batch_write/3`
 - `Codex.AppServer.turn_interrupt/3`
+- `Codex.AppServer.command_write_stdin/4` (interactive command stdin)
 - `Codex.AppServer.Account.*` and `Codex.AppServer.Mcp.*` endpoints
 - Approvals via `Codex.AppServer.subscribe/2` + `Codex.AppServer.respond/3`
 
@@ -258,6 +272,13 @@ thread_id = "thread_abc123"
 {:ok, result} = Codex.Thread.run(thread, "Continue from where we left off")
 ```
 
+Resume the most recent session (equivalent to `codex exec resume --last`):
+
+```elixir
+{:ok, thread} = Codex.resume_thread(:last)
+{:ok, result} = Codex.Thread.run(thread, "Continue from where we left off")
+```
+
 ### Configuration Options
 
 ```elixir
@@ -355,6 +376,9 @@ Codex respects upstream safe-command markers: tool events flagged with `requires
 bypass approval gating automatically, keeping low-risk workspace actions fast while still blocking
 requests that require review.
 
+For app-server file-change approvals, hooks can return `{:allow, grant_root: "/path"}` to accept
+the proposed root for the current session.
+
 Tool-call events can also arrive pre-approved via `approved_by_policy` (or `approved`) from the
 CLI; the SDK mirrors that bypass and skips hooks while still emitting telemetry. Sandbox warnings
 are normalized so Windows paths dedupe cleanly (e.g., `C:/Temp` and `C:\\Temp` coalesce). See
@@ -558,7 +582,14 @@ HexDocs hosts the complete documentation set referenced in `mix.exs`:
 
 ## Project Status
 
-**Current Version**: 0.4.3 (Upstream sync: error details + config layering)
+**Current Version**: 0.4.4 (Upstream parity: app-server inputs + exec flags)
+
+### v0.4.4 Highlights
+
+- App-server `UserInput` lists (text/image/localImage), full thread/turn params, and sandbox policies
+- Typed app-server notifications for terminal interaction, reasoning summaries, and output deltas
+- Exec parity: profile/OSS/full-auto/color/output-last-message flags, generic `-c` overrides, review wrapper, resume --last
+- Reasoning items now preserve `summary`/`content` structure instead of flattened text
 
 ### v0.4.3 Highlights
 

VERSION

@@ -1 +1 @@
-0.4.3
+0.4.4

docs/02-architecture.md

@@ -120,13 +120,15 @@ defstruct [
 
 **Key Functions**:
 ```elixir
-@spec run(t(), String.t(), Codex.Turn.Options.t()) ::
+@spec run(t(), String.t() | [map()], Codex.Turn.Options.t()) ::
   {:ok, Codex.Turn.Result.t()} | {:error, term()}
 
-@spec run_streamed(t(), String.t(), Codex.Turn.Options.t()) ::
+@spec run_streamed(t(), String.t() | [map()], Codex.Turn.Options.t()) ::
   {:ok, Enumerable.t()} | {:error, term()}
 ```
 
+App-server transport accepts `UserInput` block lists (text/image/localImage); exec JSONL expects text input.
+
 **Execution Flow** (Blocking Mode):
 1. Create output schema file if needed
 2. Start `Codex.Exec` GenServer with options