codex-computer-use-mcp 0.3.1 → 0.3.3

package/ARCHITECTURE.md

@@ -2,6 +2,14 @@
 
 Code Mode remains outside this package. See [ADR 0001: Keep Code Mode in a standalone MCP process](docs/adr/0001-standalone-code-mode-mcp.md).
 
+## Design intent
+
+This package is a thin transport adapter to the official signed Computer Use tools. It has no independent policy or security role. Codex and macOS remain authoritative for tool behavior, access decisions, and platform controls.
+
+Preserve the official capability surface. Add adapter code only when the transport, zero-model-turn architecture, component compatibility, or process lifecycle requires it.
+
+Canonical app resolution, same-app locking, focus completion telemetry, and metadata-only audit came from the earlier background-computer-use wrapper. The current release retains them for compatibility. They do not provide extra authorization or sandbox boundaries. This inventory does not justify extending them. A maintainer must explicitly approve their removal or material simplification.
+
 ## Official API evidence
 
 The architecture uses public source and the installed signed binaries; it does not speak a private Computer Use socket protocol.
@@ -61,7 +69,7 @@ The relevant construction difference is the macOS responsible-process chain:
 - unsupported: ad-hoc/no-Team-ID Node parent → signed helper;
 - supported: Node/Pi → strict-valid OpenAI-signed app-bundled Codex (`2DC432GLL2`) → strict-valid OpenAI-signed helper (`2DC432GLL2`).
 
-Process sampling confirmed the helper children were direct descendants of signed app-server; helper processes may create their own process groups. App-server and helper therefore share one private per-call cwd. Cleanup preserves partial ancestry results, recovers any reparented process by that unique cwd, freezes the owned set to stability, then kills and verifies every process rather than assuming one PGID. Enumeration, freeze, or exit uncertainty fails cleanup closed. The app-server has the expected sandbox/application-group entitlement keys; the helper has OpenAI application/team identifiers, application groups, and keychain-access-group entitlements. Ordinary Node has no Team ID or entitlement set. The service's peer audit token is not exposed through the supported MCP layer. No private socket inspection, identity spoofing, copied signing material, re-signing, injection, or TCC change was attempted. The remaining enforcement boundary is therefore OS peer/responsible-process identity, not a missing public JSON field.
+Process sampling confirmed the helper children were direct descendants of signed app-server; helper processes may create their own process groups. App-server and helper therefore share one private broker-session cwd. One-shot MCP calls close that session after the call; Pi retains it only across the required `get_app_state` and following action. Cleanup preserves partial ancestry results, recovers any reparented process by that unique cwd, freezes the owned set to stability, then kills and verifies every process rather than assuming one PGID. Enumeration, freeze, or exit uncertainty fails cleanup closed. The app-server has the expected sandbox/application-group entitlement keys; the helper has OpenAI application/team identifiers, application groups, and keychain-access-group entitlements. Ordinary Node has no Team ID or entitlement set. The service's peer audit token is not exposed through the supported MCP layer. No private socket inspection, identity spoofing, copied signing material, re-signing, injection, or TCC change was attempted. The remaining enforcement boundary is therefore OS peer/responsible-process identity, not a missing public JSON field.
 
 Command, environment, cwd, and config differences were also isolated: both paths invoke the same signed helper with `mcp`; the accepted path gives it a signed parent plus a private fixed cwd/config environment. Matching public MCP fields did not alter the raw error, while the signed-parent path succeeds without model credentials.
 
@@ -90,40 +98,42 @@ codex mcp-server model tools
 nested prompts or result summaries
 ```
 
-## Restriction inventory
+## Current adapter inventory
 
-| Released wrapper restriction | Classification | Direct design |
+| Mechanism or former restriction | Role in the direct design | Current treatment |
 |---|---|---|
-| Reviewed ChatGPT/Codex/client paths | **official-required** | current per-user installed-component contract plus exact legacy plugin layout; canonicalized and verified |
-| Strict signatures and OpenAI Team ID | **security-essential** | retained |
-| Signed-parent/responsible-process chain | **official-required** | retained through signed app-server |
-| Private Sky socket/native-pipe access | **unsupported/private** | prohibited |
-| Nested Codex model and prompt | **compatibility-only** | removed |
-| Model selection and reasoning effort | **compatibility-only** | removed; dummy unreachable provider prevents model transport |
-| Responses websocket prewarm on empty thread | **accidental app-server behavior** | disabled with non-websocket dummy provider |
-| Plugin/remote-control startup networking | **accidental app-server behavior** | corresponding features disabled |
-| Model-written multi-step task plan | **compatibility-only** | removed |
-| Model result schema/summary | **compatibility-only** | removed |
-| Streamed model-event target/method validation | **compatibility-only** | replaced by pre-dispatch typed call validation |
-| Per-operation tool allowlists and call budgets | **compatibility-only** | one typed method per direct request |
-| Task text, cleanup instructions, required-capabilities fields | **compatibility-only** | removed |
-| Dictionary-only special policy | **accidental** | removed |
-| Wrapper app/intent allowlists in full mode | **accidental** | absent |
-| Safe/full wrapper modes | **compatibility-only** | removed; one durable no-permissions interface exposes all ten methods |
-| Wrapper approval prompts/configuration | **compatibility-only** | removed; no command, config, environment, or per-call selector remains |
-| Official first-party app access | **official-required** | official Codex Full access auto-accepts normal empty-schema app approval elicitations; any elicitation app-server emits is forwarded unchanged |
-| macOS TCC | **official-required** | retained; never modified |
-| Exact ten-tool inventory/schema | **security-essential** | retained and checked before each call |
-| Canonical bundle identity | **security-essential** | retained before targeted dispatch |
-| Same-app kernel lock | **security-essential** | retained in one fixed per-user namespace shared across Pi/MCP state roots |
-| Automatic background app launch | **accidental** | removed; the official tool owns app behavior |
-| Global focus watcher and final sample | **security-essential detection** | retained |
-| Timeout/cancellation process-tree termination | **security-essential** | retained with strict enumeration, freeze, kill, stdio-close, and exit verification |
-| Per-call temporary worker cleanup | **security-essential** | retained with isolated `CODEX_HOME` |
-| Codex token usage accounting | **compatibility-only** | removed; no model turn exists |
-| Content-safe private audit | **security-essential** | retained with direct-call fields |
-| Full-result spill files | **unsafe/accidental** | prohibited; truncation is in-memory only |
-| Browser-host integration | **out of scope** | unchanged |
+| Reviewed ChatGPT/Codex/client paths | official transport compatibility | current per-user installed-component contract plus exact legacy plugin layout; canonicalized and verified |
+| Strict signatures and OpenAI Team ID | official component verification | retained to verify the selected signed transport components |
+| Signed-parent/responsible-process chain | official transport requirement | retained through signed app-server |
+| Private Sky socket/native-pipe access | unsupported/private route | prohibited |
+| Nested Codex model and prompt | former compatibility layer | removed |
+| Model selection and reasoning effort | former compatibility layer | removed; dummy unreachable provider prevents model transport |
+| Responses websocket prewarm on empty thread | accidental app-server behavior | disabled with non-websocket dummy provider |
+| Plugin/remote-control startup networking | accidental app-server behavior | corresponding features disabled |
+| Model-written multi-step task plan | former compatibility layer | removed |
+| Model result schema/summary | former compatibility layer | removed |
+| Streamed model-event target/method validation | former compatibility layer | replaced by pre-dispatch typed call validation |
+| Per-operation tool allowlists and call budgets | former wrapper policy | removed; one typed method per direct request |
+| Task text, cleanup instructions, required-capabilities fields | former compatibility layer | removed |
+| Dictionary-only special policy | former wrapper policy | removed |
+| Wrapper app/intent allowlists in full mode | former wrapper policy | absent |
+| Safe/full wrapper modes | former wrapper policy | removed; one durable no-permissions interface exposes all ten methods |
+| Wrapper approval prompts/configuration | former wrapper policy | removed; no command, config, environment, or per-call selector remains |
+| Official first-party app access | official Codex control | official Codex Full access auto-accepts normal empty-schema app approval elicitations; any elicitation app-server emits is forwarded unchanged |
+| macOS TCC | official platform control | retained; never modified |
+| Exact ten-tool inventory/schema | protocol compatibility check | retained and checked before each call |
+| Canonical bundle identity | legacy wrapper behavior | retained for the current release contract; not an independent authorization boundary |
+| Same-app kernel lock | legacy wrapper coordination | retained in one fixed per-user namespace shared across Pi/MCP state roots |
+| Automatic background app launch | accidental wrapper behavior | removed; the official tool owns app behavior |
+| Global focus watcher and final sample | legacy completion telemetry | retained for the current release contract; not a preventive sandbox |
+| Timeout/cancellation process-tree termination | operational lifecycle | retained with strict enumeration, freeze, kill, stdio-close, and exit verification |
+| Temporary broker-session cleanup | operational lifecycle | retained with isolated `CODEX_HOME`; Pi closes after the inspection-action pair, replacement inspection, or session shutdown |
+| Codex token usage accounting | former compatibility layer | removed; no model turn exists |
+| Content-safe private audit | legacy observability behavior | retained with direct-call fields; not an authorization mechanism |
+| Full-result spill files | output hygiene | prohibited; truncation is in-memory only |
+| Browser-host integration | out of scope | unchanged |
+
+These roles explain the current code. They do not authorize new safeguards. Only propose hardening for a concrete, realistically reachable failure in the supported path.
 
 ## No-permissions and elicitation boundary
 
@@ -133,11 +143,13 @@ App-server is created with `approvalPolicy: "never"` and `sandbox: "danger-full-
 
 The broker still handles any `mcpServer/elicitation/request` that app-server emits. Pi advertises OpenAI-form support and renders emitted form, OpenAI-form, and URL requests. Generic stdio MCP forwards supported standard modes as `elicitation/create`. The response path preserves `accept`, `decline`, `cancel`, structured content, and response metadata; no callback or compatible UI yields `cancel`, never an invented decision.
 
-## Pi tool disclosure boundary
+## Pi tool and session boundary
+
+The Pi extension registers and activates all ten official definitions on `session_start`, additively preserving active tools owned by Pi and other extensions. Keeping inspection and interaction methods on the same direct surface avoids provider-bound tool discovery creating a second, incompatible client binding.
 
-The Pi extension registers all ten official definitions. On `session_start` it preserves active tools owned by Pi and other extensions, keeps `computer_use_list_apps` and `computer_use_get_app_state` active, and removes only the eight Computer Use interaction definitions from the initial active set. After a successful `get_app_state` result, it additively activates those eight definitions without removing any currently active tool.
+For `get_app_state`, Pi starts one verified zero-turn app-server runtime and signed Computer Use client. The following direct interaction is serialized through that same runtime and thread, preserving the official active-app lease. The retained process tree is closed and verified after the action, before a replacement inspection, or during `session_shutdown`. One-shot MCP calls still start and close a broker session within the call. Exact inventory and schemas are revalidated before every dispatch in either path.
 
-This is context disclosure, not a wrapper permission gate. The schemas, execution path, and no-permissions policy do not change. Loader and interaction definitions remain registered throughout the session. The interaction definitions omit `promptSnippet` and `promptGuidelines`, allowing Pi 0.80.7's native deferred-loading representation to add schemas at the tool-result position without changing the system-prompt prefix. Providers without native support use Pi's next-request fallback.
+This lifecycle changes neither the schemas nor the no-permissions policy. Interaction definitions omit extra `promptSnippet` and `promptGuidelines` metadata and rely on their official descriptions.
 
 ## Output boundary
 

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+This changelog records user-visible changes from version 0.3.2 onwards.
+
+## 0.3.3 - 2026-07-27
+
+### Fixed
+
+- Support the macOS 27 `lsappinfo` `bundleID` output so frontmost-app detection can proceed to official Computer Use dispatch. [Brad Hallett](https://github.com/bradhallett) contributed this fix in [PR #6](https://github.com/tmustier/codex-computer-use-mcp/pull/6).
+
+### Documentation
+
+- Clarify that this package is a thin transport adapter and distinguish official transport requirements from retained legacy wrapper behavior in [PR #12](https://github.com/tmustier/codex-computer-use-mcp/pull/12).

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Contributions are welcome, especially compatibility fixes, direct-protocol tests, adversarial boundary tests, and clearer host diagnostics.
+Contributions are welcome, especially compatibility fixes, direct-protocol tests, realistic regression coverage, and clearer host diagnostics.
 
 ## Setup
 
@@ -20,12 +20,13 @@ Development and live acceptance require macOS and the official ChatGPT Computer
 - Do not add a nested model, action planner, prompt, subagent, or model-written result summary to direct dispatch.
 - Do not use private pipes/sockets, credential extraction, app injection, re-signing, sender impersonation, TCC automation, or automatic approval acceptance.
 - Keep app-server in a credential-free isolated `CODEX_HOME` with only official Computer Use configured.
-- Add a regression test for every protocol, policy, focus, cleanup, or audit fix.
+- Add a regression test for each concrete protocol, compatibility, lifecycle, or current-behavior fix.
 - Never log or persist arguments, typed values, screenshots, app-state/result content, elicitation contents, prompts, credentials, or tokens.
-- Treat focus checks as post-action detection rather than preventive isolation.
+- Do not add wrapper-side permission policy, risk classification, allowlists, gates, or speculative defence-in-depth on top of official Codex and macOS controls.
+- Treat current focus checks as legacy post-action completion telemetry, not preventive isolation or a precedent for further hardening.
 - Document reviewed ChatGPT component paths, launcher contracts, and upstream schema/API assumptions.
 - Include strict core/Pi type checks, tests, build, audit, package inspection, and real-app acceptance evidence.
-- Obtain independent exact-head review for security-boundary changes.
+- Review material transport or published-behavior changes at the exact head, and keep findings tied to realistic supported paths.
 
 Repository/package renaming, merge, npm publication, and GitHub release require separate maintainer approval.
 

package/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration and rollback
 
-Version 0.2.0 was the breaking direct-tool architecture change from version 0.1.0. Version 0.3.0 keeps that exact ten-tool contract and adds Pi 0.80.7 progressive disclosure. Version 0.3.1 follows ChatGPT's current per-user Computer Use component layout. Use the relevant section below.
+Version 0.2.0 was the breaking direct-tool architecture change from version 0.1.0. Version 0.3.0 added Pi progressive disclosure, version 0.3.1 followed ChatGPT's current per-user Computer Use component layout, version 0.3.2 restored one complete direct Pi surface with shared inspection-action session continuity, and version 0.3.3 adds macOS 27 compatibility. Use the relevant section below.
 
 ## What changes
 
@@ -88,6 +88,26 @@ ChatGPT 26.721 moved the signed Computer Use app out of the bundled plugin and i
 
 The resolver does not read `HOME` or `CODEX_HOME` and has no arbitrary path override. Missing, symlinked, invalidly signed, or wrong-Team-ID clients fail closed.
 
+## Upgrade from version 0.3.1 to 0.3.2
+
+Version 0.3.2 activates all ten direct Pi tools at session start and retains one verified signed-client session across `get_app_state` and the following action.
+
+1. Verify that npm resolves `codex-computer-use-mcp@0.3.2` exactly, then install that exact package.
+2. Start a fresh Pi process; do not rely on hot reload for the retained process lifecycle.
+3. Verify all ten `computer_use_*` tools are active through the direct extension binding.
+4. With an unlocked Mac and a benign background app, call `computer_use_get_app_state`, then one harmless interaction against the same app.
+5. Verify the state and action used one app-server runtime/thread, the action did not report an inactive Computer Use session, focus remained preserved, and cleanup completed.
+
+The exact schemas, strict signature and OpenAI Team ID checks, canonical client and app resolution, Full access policy, zero-turn attestation, inventory validation, kernel lock, focus telemetry, process-tree cleanup, and content-safe audit remain mandatory.
+
+## Upgrade from version 0.3.2 to 0.3.3
+
+Version 0.3.3 accepts both the legacy `CFBundleIdentifier` key and the macOS 27 `bundleID` key from `lsappinfo`. This prevents frontmost-app detection from rejecting official Computer Use dispatch on macOS 27. No configuration migration is required.
+
+1. Verify that npm resolves `codex-computer-use-mcp@0.3.3` exactly, then install that exact package.
+2. Start a fresh Pi process so it loads the updated extension code.
+3. On an unlocked Mac, run `computer_use_get_app_state` against a benign background app and verify that the result succeeds without moving focus.
+
 ## Rollback
 
 1. Stop the current Pi process.
@@ -102,4 +122,4 @@ Direct state can be removed only after rollback evidence is captured and no proc
 
 ## Generic MCP gateway
 
-If Pi uses `mcp.json`, retain `directTools: false`. Use the exact `0.3.1` package shown in `integrations/pi/mcp.json.example`. During source acceptance, use a distinct temporary server name and source path, then remove it. The direct Pi adapter is the primary live path; do not leave the version 0.1 aggregate server active after the switch.
+If Pi uses `mcp.json`, retain `directTools: false`. Use the exact `0.3.3` package shown in `integrations/pi/mcp.json.example`. During source acceptance, use a distinct temporary server name and source path, then remove it. The direct Pi adapter is the primary live path; do not leave the version 0.1 aggregate server active after the switch.

package/PROOF.md

@@ -1,6 +1,6 @@
 # Direct architecture proof and acceptance record
 
-This file records evidence for the 0.2 direct-tool branch. It is not a compatibility promise for future ChatGPT versions.
+This file records evidence for the 0.2 direct-tool branch. It does not promise compatibility with future ChatGPT versions or authorize more wrapper safeguards. Historical proof for focus telemetry, locking, cleanup, and audit records released behavior. It does not give the wrapper an independent policy or security role.
 
 ## Supported direct path
 
@@ -76,8 +76,8 @@ Current branch tests cover:
 - signed app-server elicitation forwarding, exact user responses, headless cancellation, and cancellation while a UI callback is pending;
 - standard form/URL forwarding across a real MCP SDK client/server transport;
 - Pi source registration for every direct capability with no nested planner, permission command, or wrapper-generated approval UI;
-- Pi session-start disclosure of only the two inspection definitions while preserving unrelated active tools;
-- purely additive activation of all eight interaction definitions after successful `get_app_state`, with no lazy-tool prompt metadata;
+- Pi session-start registration and activation of all ten direct definitions while preserving unrelated active tools;
+- one retained broker/client session across `get_app_state` and the following action, with deterministic active-app lease continuity and verified close;
 - Pi form, opaque OpenAI-form, URL, decline, and headless-cancel elicitation handling.
 
 ## Official Full access approval probe
@@ -119,7 +119,10 @@ Evidence:
 
 Earlier exploratory attempts exposed and fixed two acceptance-quality issues rather than being counted as proof: common `CMD+A` needed normalization to the official `Meta_L+a` key form, and TextEdit state restoration had to be reset before a fresh run. The final evidence above is from the corrected direct path.
 
-## Pi 0.80.7 progressive-disclosure measurement
+## Historical Pi 0.80.7 progressive-disclosure measurement
+
+This measurement describes version 0.3.0 and 0.3.1. Version 0.3.2 intentionally supersedes progressive disclosure because it could leave direct interaction tools absent or make a provider-discovered interaction use a different client from direct `get_app_state`.
+
 
 A fresh Pi 0.80.7 process loaded only the source Computer Use extension plus a read-only observer. All ten definitions were registered. The initial active Computer Use set was exactly:
 
@@ -130,7 +133,7 @@ Serializing names, descriptions, schemas, and prompt guidelines measured 6,063 b
 
 A second fresh process exercised the exported activation path from inside a tool execution. Pi's tool result recorded the exact eight interaction names in `addedToolNames`; the before/after active sets retained both inspection tools and removed zero tools. The lazily activated definitions had no `promptSnippet` or `promptGuidelines`.
 
-With `openai-codex/gpt-5.6-sol`, the first request reported 5,723 uncached input tokens. The immediately following request after additive activation reported 1,008 uncached input tokens and 5,632 cache-read tokens. This is live provider evidence that the initial prefix remained reusable while Pi inserted the eight definitions at the tool-result load point. The activation probe used the same `activateInteractionTools` function called after a successful production `get_app_state`; automated tests bind that successful-result branch and exact additive set.
+With `openai-codex/gpt-5.6-sol`, the first request reported 5,723 uncached input tokens. The immediately following request after additive activation reported 1,008 uncached input tokens and 5,632 cache-read tokens. This was live provider evidence that the initial prefix remained reusable while Pi inserted the eight definitions at the tool-result load point. Version 0.3.2 removes that activation path in favor of complete direct registration and signed-client session continuity.
 
 ## Review and release status
 

package/README.md

@@ -1,6 +1,6 @@
 # Codex Computer Use MCP
 
-Version 0.3.1 exposes the official signed macOS Computer Use capabilities as direct typed tools for Pi and MCP clients. The calling agent chooses every tool and argument itself.
+Version 0.3.3 exposes the official signed macOS Computer Use capabilities as direct typed tools for Pi and MCP clients. The calling agent chooses every tool and argument itself.
 
 The primary path has:
 
@@ -33,9 +33,9 @@ Pi registers namespaced tools to avoid collisions with Pi's built-ins. The MCP s
 
 The MCP façade preserves the official signed helper's tool descriptions, input schemas, and annotations exactly. The Pi façade preserves its descriptions and input schemas; Pi's tool API does not expose MCP annotations. In particular, all ten MCP methods have `destructiveHint: false`; the wrapper does not conflate changing UI state with destructive behavior or add argument restrictions absent from the official schemas.
 
-Pi 0.80.7 and newer registers all ten definitions but initially activates only `computer_use_list_apps` and `computer_use_get_app_state`. A successful `get_app_state` call additively activates the eight interaction definitions for the following model request. Other active Pi and extension tools remain active. The lazily activated tools omit `promptSnippet` and `promptGuidelines`, allowing Pi's native deferred-loading path to preserve the stable system-prompt prefix.
+Pi registers and activates all ten definitions together in every fresh session, while preserving active tools owned by Pi and other extensions. This prevents interaction methods from being absent or loaded through an incompatible provider binding.
 
-As the official contract specifies, Pi—not a nested planner—calls `computer_use_get_app_state` once per assistant turn before interacting with an app, then chooses and executes actions itself.
+As the official contract specifies, Pi—not a nested planner—calls `computer_use_get_app_state` once per assistant turn before interacting with an app, then chooses and executes actions itself. The adapter retains one verified app-server runtime and signed Computer Use client for that inspection-action pair, so the action reuses the official active-app session established by `get_app_state`. It closes and verifies the retained process tree after the action, when a new inspection supersedes it, or on Pi session shutdown.
 
 ## Authorization policy: durable no-permissions
 
@@ -43,13 +43,13 @@ As the official contract specifies, Pi—not a nested planner—calls `computer_
 
 The app-server runtime uses the official Full access combination: `approvalPolicy: "never"` and `sandbox: "danger-full-access"`. In the pinned Codex host, that maps to a disabled permission profile and automatically accepts empty-schema MCP approval elicitations. Normal Computer Use app-access checks therefore proceed without a per-app prompt, just as they do in Codex Full access. The bridge does not edit the service's persistent per-bundle approval file. If app-server emits an elicitation instead of resolving it under Full access, the bridge still forwards it faithfully to the invoking client; unsupported clients return `cancel`, never a fabricated `accept` or `decline`.
 
-No-permissions does **not** bypass:
+No-permissions leaves the official and transport requirements unchanged:
 
-- macOS Screen Recording, Accessibility, or TCC controls;
-- strict OpenAI Team ID and code-signature checks;
-- exact upstream ten-tool schema verification;
-- canonical app identity resolution and per-user/per-app kernel locks shared across Pi and MCP state roots;
-- focus telemetry, timeouts, verified process-tree cleanup, or private audit logging.
+- macOS Screen Recording, Accessibility, and TCC controls remain authoritative;
+- the adapter still selects and verifies the official signed components required for the supported transport;
+- the wrapper verifies compatibility with the upstream ten-tool contract.
+
+The current release also retains behavior from the earlier background-computer-use wrapper. This includes canonical app resolution, per-user/per-app coordination, focus completion telemetry, process cleanup, and metadata-only audit. These provide compatibility, lifecycle management, and observability. They do not provide extra authorization or a sandbox. Do not use them as a foundation for more wrapper safeguards.
 
 ## Why the signed app-server is required
 
@@ -67,7 +67,7 @@ See [`ARCHITECTURE.md`](ARCHITECTURE.md) for source links and the full restricti
 
 - macOS
 - Node.js 22 or newer
-- Pi 0.80.7 or newer for native progressive tool disclosure
+- Pi 0.80.7 or newer
 - official ChatGPT macOS app at `/Applications/ChatGPT.app`
 - official Computer Use component installed by ChatGPT under `~/.codex/computer-use/`
 
@@ -77,16 +77,16 @@ The direct bridge starts app-server with a new private `CODEX_HOME` containing n
 
 ### Locked-screen limitation
 
-Version 0.3.1 supports direct local calls in an unlocked macOS session. It does not support window or accessibility actions after the Mac locks.
+Version 0.3.3 supports direct local calls in an unlocked macOS session. It does not support window or accessibility actions after the Mac locks.
 
-OpenAI's [locked Computer Use](https://developers.openai.com/codex/app/computer-use#use-computer-use-while-your-mac-is-locked) is limited to active, trusted ChatGPT turns started from a connected device. It does not authorize other apps or local processes to unlock the Mac. This package uses local zero-turn dispatch, so targeted calls can fail with official error `-10005` while the Mac is locked. Support for locked local use remains a follow-up and is not part of version 0.3.1.
+OpenAI's [locked Computer Use](https://developers.openai.com/codex/app/computer-use#use-computer-use-while-your-mac-is-locked) is limited to active, trusted ChatGPT turns started from a connected device. It does not authorize other apps or local processes to unlock the Mac. This package uses local zero-turn dispatch, so targeted calls can fail with official error `-10005` while the Mac is locked. Support for locked local use remains a follow-up and is not part of version 0.3.3.
 
 ## Pi integration
 
 Install the exact release from npm:
 
 ```bash
-pi install npm:codex-computer-use-mcp@0.3.1
+pi install npm:codex-computer-use-mcp@0.3.3
 ```
 
 To evaluate a source checkout instead:
@@ -103,7 +103,7 @@ Command:
 /computer-use-status
 ```
 
-The native Pi adapter is the primary product path. It registers all ten typed tools directly, starts each session with the two inspection tools active, and additively activates the eight interaction tools after successful app inspection. It exposes no mode-changing command or wrapper-generated approval UI. Official app-access approval elicitations are resolved by Codex Full access before they reach Pi. Any elicitation that app-server does emit is shown through Pi's UI, and only the user's choice is returned to the service.
+The native Pi adapter is the primary product path. It registers and activates all ten typed tools directly, and routes the required `get_app_state` and following action through one retained signed-client session. It exposes no mode-changing command or wrapper-generated approval UI. Official app-access approval elicitations are resolved by Codex Full access before they reach Pi. Any elicitation that app-server does emit is shown through Pi's UI, and only the user's choice is returned to the service.
 
 ## MCP server
 
@@ -131,9 +131,9 @@ For Pi's generic MCP gateway, keep `directTools: false` so this powerful surface
 
 The generic MCP server exposes the same no-permissions behavior: official Codex Full access, no wrapper permission gate, and all ten methods. App-access approvals are resolved inside the official host. Any standard form or URL elicitation that app-server emits is forwarded as an MCP `elicitation/create` request. The upstream client response is returned unchanged; unsupported or headless clients cancel rather than fabricate a decision.
 
-## Security and privacy
+## Execution and privacy
 
-Each call:
+For the current released implementation, each call:
 
 1. validates typed arguments;
 2. applies the single durable no-permissions policy with no mode or prompt branch;
@@ -148,7 +148,7 @@ Each call:
 11. rejects any model-turn notification, including during teardown;
 12. combines partial-preserving ancestry enumeration with private-working-directory ownership recovery, then freezes, terminates, and verifies the app-server plus separately grouped or reparented helpers; finally it removes temporary state, releases the lock, and writes a content-safe audit with separate broker/lease cleanup evidence.
 
-Focus checks are detection/completion criteria, not a preventive macOS sandbox. If the target becomes frontmost, the call is reported as failed even though an individual official action may already have completed.
+Focus telemetry is legacy completion behavior from the earlier background-computer-use wrapper. It does not provide an official Codex access control or a preventive macOS sandbox. The current release reports the call as failed if the target becomes frontmost. An individual official action may already have completed. Do not use this telemetry as a reason to add further defensive policy.
 
 Tool results may contain visible target-app text or screenshots because that is the purpose of Computer Use. They return only to the invoking Pi/MCP client. Audits never retain arguments, typed values, screenshots, app-state payloads, result text, prompts, credentials, or tokens—only bounded metadata such as method, canonical/hashed app identity, byte counts, content types, outcome, focus, broker version, and zero-turn evidence.
 
@@ -172,7 +172,7 @@ npm pack --dry-run
 
 Registry dependency tarballs are exact-pinned with integrity and the package includes `npm-shrinkwrap.json`.
 
-See [`PROOF.md`](PROOF.md), [`SECURITY.md`](SECURITY.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md).
+See [`CHANGELOG.md`](CHANGELOG.md), [`PROOF.md`](PROOF.md), [`SECURITY.md`](SECURITY.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md). Agent contributors must also follow [`AGENTS.md`](AGENTS.md). It records the maintainer's thin-adapter intent and review standard.
 
 ## License
 

package/SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Reporting a vulnerability
 
-Do not open a public issue for a vulnerability that could weaken signing, contract verification, no-permissions dispatch, first-party access handling, app identity, locking, focus telemetry, cleanup, or audit integrity.
+Do not open a public issue for a concrete vulnerability in the supported production path. This includes realistic paths to untrusted component execution, unauthorized wrapper dispatch, credential or result-content exposure, or materially false completion reporting.
 
-Use GitHub private vulnerability reporting. Include the affected commit/version, the smallest non-sensitive reproduction, expected versus observed behavior, and whether an official action completed before failure.
+Use GitHub private vulnerability reporting. Include the affected commit and version, a small non-sensitive reproduction, and the expected and observed behavior. Provide evidence that the path is realistically reachable. State whether an official action completed before failure. Speculative hardening ideas without a reachable material effect are not vulnerability reports.
 
 Never include credentials, tokens, customer/private content, sensitive screenshots, raw app-state payloads, elicitation contents, or private audit files.
 
@@ -16,7 +16,15 @@ The API requires a loaded thread ID. The bridge creates an empty, pathless, ephe
 
 This is direct tool dispatch—not model orchestration.
 
-## Security invariants
+## Authority and non-goals
+
+This package is a thin adapter to official Codex Computer Use. Codex and macOS remain authoritative for tool behavior, app access, and platform permissions. The wrapper must not add permission policy, risk classification, app allowlists, action gates, content inspection, or speculative defence-in-depth.
+
+The earlier background-computer-use wrapper provided canonical app resolution, same-app locking, focus completion telemetry, and metadata-only audit. The current release retains these legacy behaviors. They do not provide independent security or authorization boundaries. Do not expand them because a hypothetical safeguard is possible. A maintainer must explicitly approve their removal or material simplification because this changes the release contract.
+
+## Current adapter invariants
+
+These invariants describe the supported transport, zero-model-turn architecture, current released behavior, process lifecycle, and privacy contract. They are not a general security framework or a mandate to add safeguards.
 
 1. Only the fixed app-bundled Codex path and reviewed official Computer Use layouts are allowed in production. The current client is resolved from the OS account home under `~/.codex/computer-use/`; `HOME`, `CODEX_HOME`, arbitrary paths, and symlinked layouts are not accepted. The former exact plugin-bundle layout is considered only when the current component is absent.
 2. Both binaries pass strict code-signature verification and OpenAI Team ID `2DC432GLL2` checks before dispatch. A present current-layout client that fails verification never falls back.
@@ -24,15 +32,15 @@ This is direct tool dispatch—not model orchestration.
 4. `no-permissions` is the only wrapper policy: all ten methods are exposed and no wrapper permission prompt is opened.
 5. There is no config file, environment override, command, tool argument, per-call branch, or alternate safe/full route that an agent can select.
 6. App-server uses the official Full access combination, `approvalPolicy: "never"` plus `sandbox: "danger-full-access"`. The pinned Codex host automatically accepts empty-schema MCP approval elicitations, so normal first-party app-access checks proceed without prompts. The wrapper does not synthesize this response or edit persistent per-app approvals. Any elicitation app-server emits is forwarded faithfully; an unavailable client cancels.
-7. Target selectors resolve to canonical installed bundle IDs before dispatch.
-8. Same-app work is excluded across native Pi, generic MCP, and custom state roots with one fixed per-user kernel `lockf` lease namespace.
-9. Target focus events, periodic samples, watcher health, queued ASN resolution, and final state are checked. This is post-action detection, not a preventive OS sandbox.
+7. As current legacy wrapper behavior, target selectors resolve to canonical installed bundle IDs before dispatch.
+8. As current legacy wrapper coordination, same-app work is excluded across native Pi, generic MCP, and custom state roots with one fixed per-user kernel `lockf` lease namespace.
+9. As current legacy completion telemetry, target focus events, periodic samples, watcher health, queued ASN resolution, and final state are checked. This is post-action reporting, not a preventive OS sandbox or an official Codex access control.
 10. One direct request emits one official `mcpServer/tool/call`; no model turn, subagent, shell, web, plugin, prompt, or reachable model transport is available.
-11. App-server and helper share one private per-call working directory. Cleanup combines strict ancestry enumeration (preserving partial results) with working-directory ownership recovery, freezes processes to a stable set, kills every owned process, awaits stdio closure, and verifies exit. This still finds a helper reparented by an early app-server exit; enumeration/freeze/exit uncertainty is fatal.
+11. App-server and helper share one private broker-session working directory. One-shot calls close it immediately; Pi retains it only across the required `get_app_state` and following action, then closes it after the action, before replacement inspection, or on session shutdown. Cleanup combines strict ancestry enumeration (preserving partial results) with working-directory ownership recovery, freezes processes to a stable set, kills every owned process, awaits stdio closure, and verifies exit. This still finds a helper reparented by an early app-server exit; enumeration/freeze/exit uncertainty is fatal.
 12. Protocol JSONL is bounded before an unterminated line can exceed 8 MB in memory.
 13. Per-call `CODEX_HOME` and work directories are mode-private and recursively removed.
 14. Only validated text/image result blocks cross to the invoking client. No full-result spill file is written.
-15. Audits contain metadata only, including separate `brokerCleanupVerified` and `appLeaseReleased` evidence; lease-release failure changes the audited outcome before surfacing. Arguments, values, screenshots, app-state text, result content, prompts, approvals, credentials, and tokens are forbidden.
+15. Audits contain metadata only, including separate `brokerCleanupVerified` and `appLeaseReleased` evidence. A retained Pi inspection truthfully records broker cleanup as pending (`false`); the paired action does not return if final retained-session cleanup fails. Lease-release failure changes the audited outcome before surfacing. Arguments, values, screenshots, app-state text, result content, prompts, approvals, credentials, and tokens are forbidden.
 16. Policy rejections are audited; audit failure is fatal once a secure state path exists.
 17. Runtime and development dependency tarballs are exact-pinned with integrity in `npm-shrinkwrap.json`.
 
@@ -56,6 +64,6 @@ Computer Use returns the official app-state text and screenshots to the invoking
 
 ## Supported versions
 
-Only the latest approved release is supported. Version 0.3.1 supports direct local calls in an unlocked macOS session. Targeted local calls while the Mac is locked are not supported.
+Only the latest approved release is supported. Version 0.3.3 supports direct local calls in an unlocked macOS session. Targeted local calls while the Mac is locked are not supported.
 
 App-server is experimental and bundle paths or schemas can change. Drift fails closed until reviewed.

package/dist/direct-broker.d.ts

@@ -25,7 +25,7 @@ export interface DirectBrokerResult {
     elicitationRequests: number;
     modelTurnsStarted: 0;
     ephemeralThread: true;
-    brokerCleanupVerified: true;
+    brokerCleanupVerified: boolean;
 }
 export interface DirectBrokerOptions {
     timeoutMs?: number;
@@ -90,5 +90,15 @@ export declare function verifyOfficialDirectBroker(options?: ResolveOfficialComp
     client: OfficialComputerUseClient;
 };
 export declare function buildDirectAppServerArgs(mcpCwd?: string, clientPath?: string): string[];
+export interface OfficialDirectToolSession {
+    call(method: DirectMethod, args: DirectToolArguments, options?: Pick<DirectBrokerOptions, "timeoutMs" | "signal" | "onElicitation" | "supportsOpenAiFormElicitation">): Promise<DirectBrokerResult>;
+    close(): Promise<void>;
+}
+/**
+ * Start one verified app-server runtime and retain its signed Computer Use MCP
+ * client across calls. Pi uses this for the required get_app_state -> action
+ * sequence; one-shot callers continue to use callOfficialDirectTool below.
+ */
+export declare function createOfficialDirectToolSession(options?: DirectBrokerOptions): Promise<OfficialDirectToolSession>;
 export declare function callOfficialDirectTool(method: DirectMethod, args: DirectToolArguments, options?: DirectBrokerOptions): Promise<DirectBrokerResult>;
 export {};