Feature request: make /pet a first-class companion command drawer

What variant of Codex are you using?

Codex Desktop app 26.721.41059 on macOS, with the bundled Hatch Pet workflow and valid custom V2 pets. The proposal is intended to be cross-platform.

What feature would you like to see?

Summary

Turn /pet into a first-class, discoverable companion command drawer for pet status, switching, creation, validation, repair, and preview-before-action.

The narrow product idea is:

/pet should be the front door to pet capabilities. It should show intent, current state, safety boundary, and the next observable consequence before anything consequential happens.

This is an orchestration/discoverability proposal. It does not require every related pet runtime API to ship at once.

User job

When a user adopts or builds a Codex pet, they want one local control surface to understand what the pet is following, manage its package, and preview safe interactions, so they can use the pet as a legible activity companion rather than hunt through Settings, skills, task checkboxes, and undocumented manifests.

Success could be measured by:

• common pet operations available in two interactions or fewer;
• no invisible task binding or side effect;
• actionable validation errors instead of silent omission;
• pet state always names the task/event that caused it;
• image-heavy pet creation shows a storage estimate/warning before it starts.

Proposed command surface

Typing /pet with no arguments opens a keyboard-accessible drawer/card with:

1. Current companion

• selected pet and package health;
• show/hide state and overlay position;
• followed task: automatic or manually pinned;
• current animation state and cause.

1. Quick actions

• /pet show
• /pet hide
• /pet list
• /pet switch [name]
• /pet status
• /pet hatch [description]
• /pet validate [name|path]
• /pet repair [name|path]
• /pet storage

1. Optional action intents

• list only actions already advertised by Codex or an installed/authorized app;
• show action, consent level, stop rule, and target before invocation;
• create a local intent/receipt first;
• continue through the existing approval broker;
• never allow arbitrary shell, executable paths, credentials, connector scope grants, or silent external actions.

Legible state mapping

The standard pet states already provide a useful ambient vocabulary:

| Pet state | Meaning shown in the drawer |
|---|---|
| idle | no followed task is active |
| running | task work is in progress |
| waiting | user input or approval is required |
| review | output is ready to inspect |
| failed | task is blocked or failed, with a recoverable next step |

Each state should expose one cause and one observable consequence. For example: “Waiting — Task X needs approval” rather than only playing an animation.

Hatch / validate / repair behavior

/pet hatch can route into the bundled Hatch Pet workflow, but the drawer should first display:

• inferred name/style and source references;
• V1/V2 target contract;
• estimated visual jobs and local storage impact;
• progress stages;
• whether image bytes may be retained in task history;
• the destination package;
• a cancel/continue choice before external generation or spend.

/pet validate should be read-only and produce per-folder, per-manifest, atlas-geometry, transparency, and runtime-compatibility errors.

/pet repair should propose the smallest repair, preserve passing rows/assets, and require review before replacing an installed pet.

Why this proposal

Local companion prototypes suggest a useful causal chain:

command or selection
→ visible intent card
→ pet/task state cue
→ boundary or approval
→ local receipt

The pet becomes more useful when it explains work and consent, not merely decorates it. The same drawer can compose existing pet proposals without granting the pet ambient authority.

Safety and compatibility

• Existing /pet show/tuck behavior and pets without new metadata continue working.
• Immediate local operations such as show, hide, list, status, and switch remain low-risk.
• Hatch, repair, recording, computer control, connector actions, external generation, posting, or spend retain explicit approval boundaries.
• Custom pet packages remain local and receive no ambient conversation access.
• Invalid packages surface actionable errors instead of disappearing.
• Pet creation should use bounded artifact storage, warn on large rollout growth, and prefer references/deduplication over repeated inline image bytes.
• Managed workspaces may disable creation or action intents independently of pet display.

Suggested incremental delivery

Phase 1: front door only

• /pet drawer
• show/hide/list/switch/status
• hatch/validate/repair routing
• clear task-state cause
• package/storage diagnostics

Phase 2: permissioned intent preview

• context-menu/action cards
• allowlisted action registry
• approval broker integration
• local receipts

Phase 3: richer optional runtime contracts

• lifecycle/progression
• configurable animations/events
• outfits or modes
• automatic highest-priority task following

Acceptance criteria

• /pet with no arguments opens a discoverable keyboard-accessible surface.
• Selected pet, health, visibility, followed task, state, and state cause are visible.
• A built-in or custom pet can be switched in two interactions or fewer without interrupting tasks or changing overlay position.
• Hatch shows a bounded plan and storage warning before generation.
• Validate returns actionable V1/V2 package errors.
• Repair never overwrites an installed package before review.
• Action intents are inert until resolved through an existing advertised action and required approval.
• Every consequential path emits a local receipt describing source, intent, decision, and result.

Related issues

This proposal is an umbrella/front-door experience and should compose with narrower requests:

• #20778 — Hatch Pet/slash-command discoverability
• #29296 — quick pet switching
• #32994 — automatic highest-priority task tracking
• #20863 — configurable animation sequences/activity events
• #21657 — custom interaction hooks/APIs
• #34145 — manifest-defined permissioned actions
• #29932 — persistent lifecycle/progression state
• #34240 — V2 look-direction runtime behavior

Non-goals

• arbitrary code execution from a pet manifest;
• automatic connector installation or permission grants;
• silently starting capture, Computer Use, external generation, posting, or spend;
• requiring lifecycle/game mechanics for users who only want the current lightweight pet.

pip install codex-rescue==0.1.0a5
codex-rescue doctor <path-to-rollout.jsonl>