/agent-shims

name: agent-shims
description: 'Safely manage Codex Rig role-agent shims: doctor, status, or remove; install only reports its platform block. One action only.'

> Before asking, read [User Questions](../../shared/codex-user-questions.md). Waits, plan updates, and test runs follow [Agent Waits](../../shared/native-skill-contract.md#agent-waits), [Plan Updates](../../shared/native-skill-contract.md#plan-updates), and [Sandboxed Test Runs](../../shared/native-skill-contract.md#sandboxed-test-runs).

Agent Shims

After user intervention or repeated invocation, follow [Resume And Re-entry](../../shared/helper-cli-contract.md#resume-and-re-entry): complete selected action's verification and diagnostic instructions below. This manager keeps its non-artifact lifecycle; it doesn't skip its closing checks or replace final explanation with raw JSON.

This is experimental lifecycle tool. Installing authenticated standalone agent TOML does not prove that active collaboration interface can select that custom profile. A task name or child path matching role name is not proof. Use installed shims only when runtime exposes explicit custom-agent selector and observed child metadata plus verifier output prove selection; otherwise use blank-agent role-card injection.

Accept exactly one action: `doctor`, `status`, `install`, or `remove`. Reject missing, extra, or unknown arguments without writes.

Any follow-up question follows [User Questions](../../shared/codex-user-questions.md): put accepted action names or required input format in the permitted native control after showing context; use plain chat only when no permitted native control is suitable. Preserve the manager's exact-digest removal confirmation syntax; never substitute a generic yes/no response for that digest-bound input. The blocked `install` action still requires no approval prompt.

Resolve `PLUGIN_ROOT` two levels above this installed skill directory. Run `PLUGIN_ROOT/bin/python PLUGIN_ROOT/scripts/manage_role_agents.py <action>` with the selected action; on native Windows use `PLUGIN_ROOT/bin/python.cmd`. Never copy manager, resolve it through source checkout, or edit generated agent files directly.

• `doctor`: run read-only live prerequisite check, render its JSON result for person.
• `status`: run read-only health and installed-roster summary, render its JSON result for person.
• `install`: report stable platform block. Never request approval; no new shim plan or write is allowed.
• `remove`: use the manager's exact-digest removal confirmation to remove every intact managed shim. Never delete by filename prefix or marker alone. On failure, apply the same per-failure-category recovery guidance in item 4 below for `doctor` and `status` — it applies to `remove`'s failure modes too.

Preserve manager's exit contract: `0` success/converged, `2` usage, `3` cancelled, `4` drift/conflict, `5` prerequisite blocked, `6` untrusted state, `7` internal/recovery failure. Never retry mutating action after codes `4`, `6`, or `7`; report evidence, keep files untouched.

For `doctor` and `status`, never return only raw JSON or generic safety label:

1. Start with plain-English explanation of whether shims are usable and what needs attention. Then give `Healthy`, `Degraded`, or `Blocked`, followed by first non-pass check and its exact detail; never expose raw diagnostic JSON as whole answer. 2. List every other non-pass check once, then summarize `state`, `targets`, `recovery`, namespace candidates. 3. State `No files changed.` 4. Give narrow safe next step. For package or active-package failures, refresh or reinstall Codex Rig, start fresh session. For executable failures, report selected path, rerun from fresh session with stable Python and Codex selection. For permission, owner, type, or link failures, inspect only named path, verify its metadata before changing anything. For corrupt, inconsistent, modified, or foreign evidence, back it up, never adopt, edit, or delete it automatically. For recognized recovery residue, use `remove`, review its authenticated approval digest.

Never recommend recursive `chmod`, `chown`, deletion, or link replacement from diagnostic alone. On POSIX systems, a protected agent target may be readable by other users, but it must be owned by current user, have no group/world write or special permission bits; private lifecycle state remains exact mode `0700`. Not applicable on Windows, where `remove` is platform-blocked.

After successful removal, tell user to start fresh Codex session. Thin shims intentionally depend on installed plugin cache; uninstalling plugin makes remaining shims unavailable until safely removed or reinstalled.

Output Contract

This manager has no canonical `.reports` result lifecycle, remains explicit exception in `../../shared/final-handoff-contract.md`: its final-response structure is advisory, not executable. Never claim digest-bound final-response validation until manager gains canonical run/result artifact.

Final chat follows ordered frame from `../../shared/quality-gates.md`:

• `Outcome` includes action, `Healthy|Degraded|Blocked|Removed|Rejected`, exit code, whether files changed.
• `Results` has one action per row and exactly `Action | Outcome | Verification | Remaining limit`; `doctor` and `status` include every non-pass check once.
• Apply shared `Verification`, `Remaining`, `Next steps`, `Confidence`, retaining exact-digest/read-only evidence, safe recovery only, no inferred custom-profile selection. `Artifact` links retained manager JSON or states `None — this lifecycle helper created no durable result artifact`. Raw JSON alone never substitutes for the outcome.

Keep usage rejection and exit codes `2|3|4|5|6|7` explicit. Never present blocked install, cancelled remove, drift/conflict, untrusted state, or recovery failure as success.