small-scripts/FUTURE.md

# Future Ideas

## Script runner / installer

- **Problem:** Manually symlinking each script to `~/sbin` is tedious
- **Idea:** A `scripts/install.sh` that symlinks all scripts in `scripts/` to `~/sbin`, with `--dryrun` support naturally
- **Open questions:** Should it handle removal of stale symlinks? Version checking?
- **Depends on:** Having at least 2-3 scripts to justify the automation

## CI test runner

- **Problem:** Tests are only run manually
- **Idea:** Gitea CI action that runs `tests/run-all.sh` on push
- **Open questions:** What runner is available on Gitea? Docker-based?
- **Depends on:** Gitea CI being available (cluster-bootstrap M10)

## claude-profile engagement modes — follow-up integration

The initial engagement mode picker (chat / quick / deep / hybrid / orch) ships with `claude-profile` and writes `active-mode.env` into the active profile directory. Several integration pieces are deferred to future work — none block v1 but each unlocks the design fully:

### `bg-model-call` wrapper

- **Problem:** The `deep` and `hybrid` modes both reference `bg-model-call` as the standardised way to fire a third-party model (MiniMax, etc.) in the background and have the result land in a sentinel file. The wrapper does not exist yet — modes currently just describe the pattern.
- **Idea:** A new small-script `bg-model-call` that takes a model name, a prompt file, and an output file; runs the appropriate container in the background; writes the result + a sentinel `.done` file when finished. Standardises timeouts, exit codes, and the sentinel format so `ScheduleWakeup` prompts can be self-contained.
- **Open questions:** Which third-party models do we actually want to wire up in v1 (MiniMax M2 only, or also others)? Where do API credentials live (secrets folder, with what naming)? Does the wrapper run via Docker on the local host, or via the agent-runtimes control plane?
- **Depends on:** Spec for the wrapper. This is its own small-scripts entry.

### `switch mode` skill (mid-session re-pick)

- **Problem:** The mode is fixed at launch by `claude-profile`. Switching mid-session currently requires `/clear` + relaunch. For the common case "started in deep, this turned out to be trivial, drop to quick" there is no in-session path.
- **Idea:** A `switch-mode` skill (in custom-claude-skills) that re-runs the picker logic by writing a new `active-mode.env`, then asking the harness to apply it. The driver model can't actually swap mid-session (`--model` is launch-only), so the skill works by either (a) instructing the user to relaunch, or (b) updating the active-mode.env so the next `/clear` picks up the new mode without re-prompting. Option (b) is more useful in practice.
- **Open questions:** Should the skill be invoked by typing literal "switch mode" (matched by a UserPromptSubmit hook) or by a slash command `/switch-mode`? The mode files all assume the literal phrase.
- **Depends on:** No technical blockers; depends on someone actually wanting to switch modes, which may turn out to be rare in practice.

### MiniMax-driven session with Claude container subagents (inverted architecture)

- **Problem:** The current `claude-profile` design assumes Claude Code is the main loop and Claude models are the driver. The cheapest available driver is Haiku (`hybrid` mode), which is still Anthropic-priced and still consumes Claude OAuth quota for every conversational turn. For long-running sessions where most turns are mundane routing and only occasional turns need real reasoning, the driver is the dominant cost. A non-Claude driver (MiniMax M2 specifically — comparable agentic ability at a fraction of the per-token cost, on a different vendor and quota pool) would unlock substantially cheaper long sessions while still letting us reach for Opus/Sonnet on demand via container subagents.
- **Idea:** A new launcher (working name: `agent-profile` or `minimax-profile`, parallel to `claude-profile`) that runs MiniMax as the conversational driver and treats Claude Code instances running inside containers as named subagents. The container subagents are dispatched via the existing agent-runtimes control plane — same infrastructure the `orch` mode already uses, just invoked from a different driver. Result-passing is file-based (already established as the right pattern in this session): the MiniMax driver writes a prompt file, fires a container, polls for a sentinel, reads the result file. No multi-megabyte tool-call payloads streaming through MiniMax's context window.

#### Architectural shape
1. **Driver layer** — a MiniMax agentic harness (either MiniMax's own CLI if one exists at the time, or a thin custom harness built on the MiniMax SDK with a tool-calling interface). This is **not** Claude Code; the existing CLAUDE.md / skills / hooks / status-line mechanisms do not apply directly. Some equivalents may need to be reimplemented or ported.
2. **Subagent dispatch layer** — a small set of tools the MiniMax driver can call: `consult_opus(prompt_file, out_file)`, `consult_sonnet(prompt_file, out_file)`, `consult_minimax_self(...)` (for parallel MiniMax thinking on the same machine). Each tool is a thin shim that submits a task to the agent-runtimes control plane and waits on a sentinel file, identical in shape to the `bg-model-call` wrapper described above.
3. **Result passing** — file-based, as in the rest of this design. The MiniMax driver never reads a multi-thousand-token Claude response into its own context unless it explicitly chooses to. Default flow: write prompt → fire container → wait → read summary line → optionally read full file.
4. **Engagement modes (parallel set)** — `chat`, `quick`, `deep`, `hybrid`, `orch` may or may not all map cleanly. `hybrid` (cheap driver, premium subagents) is the obvious fit and arguably the *only* mode that makes sense here — if you're not in hybrid you're either using a cheaper driver for trivial work (re-launch in `chat`) or wanting a Claude driver (use `claude-profile`). Worth designing as one mode rather than five.

#### Credential management — the load-bearing piece

This is where the user's explicit ask sits, and where it's easy to go wrong:

- **MiniMax credentials** for the driver: API key, lives at `~/dev/claude/secrets/minimax/api_key` (proposed; user to confirm naming). Read by the MiniMax driver process at launch only. Never written into a container, never logged, never put on a command line (use stdin or env-var injection at exec time).
- **Claude credentials** for container subagents: the existing `~/dev/claude/secrets/claude/long_lived_oauth_token` (per cross-project memory) — already used by agent-runtimes containers via `CLAUDE_CODE_OAUTH_TOKEN`. No change needed; the containers already know how to read it.
- **Strict separation:** the MiniMax driver process must NOT have access to the Claude OAuth token. The containers must NOT have access to the MiniMax key. Each side reads only its own credential file at point of use. This rules out a "load all secrets into env at launch" pattern.
- **No credential crosses to subprocess args.** MiniMax key into the driver via env or stdin only. Claude OAuth into the container via the existing agent-runtimes mechanism (volume mount or env var, set by the control plane, not by the driver process).
- **Audit boundary:** if the MiniMax driver ever needs to be told "run a Claude container," it asks the control plane to do it. The driver does not invoke `docker run` directly. This keeps the credential boundary at the control plane, where it already exists, rather than moving it into the driver.
- **Cross-project memory feedback already covers this:** "Stream secrets from files" — read tokens from source files at point of use; never reconstruct from context. Apply that same rule to both credential pools.

#### Open questions
1. **Does MiniMax M2 ship a usable agentic CLI/harness in 2026?** If yes, how mature — does it have tool-calling, file editing, persistent context, hooks? If no, the work is "build a minimal agentic harness" first, which is a significant project on its own.
2. **Tool-call interop:** MiniMax's function-calling format vs. Claude Code's tool-result format. If we want a Claude container to be able to surface useful structured data back, the driver needs to translate. File-passing avoids most of this — JSON/markdown files are vendor-neutral.
3. **Where does this launcher live?** Same `small-scripts` repo, or its own project? Lean toward small-scripts initially; promote to its own project once it has its own modes/specs/tests at a similar scale to claude-profile.
4. **Status line / WezTerm theming:** Currently driven by `claude-profile`'s WezTerm escape sequences. The MiniMax driver runs in the same terminal — does it reuse that theming, or pick its own colour to make the inverted-architecture session visually distinct?
5. **Does this replace `hybrid` mode entirely, or coexist?** `hybrid` (Claude Haiku driver) is a strict superset functionally — same tools, same Claude harness — but more expensive than MiniMax. Some users may prefer staying inside Claude's harness even at higher cost; others may want the MiniMax surface for cost reasons. Likely coexist.
6. **Failure modes when the MiniMax API is degraded:** Claude Code has decent retry/backoff. A custom MiniMax driver needs the same — and a clean way to fall back to a local model or to `claude-profile --mode hybrid` if MiniMax is unreachable for a sustained period.
7. **Subagent quota economics:** if every container subagent burns Claude OAuth quota, and the driver burns MiniMax quota, are we actually saving money? Sketch out a typical-session token budget under both architectures (claude-profile hybrid vs. minimax-profile) before committing — this might be the kind of "feels cheaper but isn't" optimisation that wastes a weekend.

#### Depends on
- **MiniMax M2 maturity** — specifically whether an agentic harness exists or needs building. Worth re-checking every few months.
- **agent-runtimes control plane** — already exists and is actively used; no new infrastructure required there, but the control plane needs a small documented contract for "submit a Claude consult task and return the result file path."
- **The `bg-model-call` wrapper from this same FUTURE.md section** — if that ships first, the subagent dispatch layer here is mostly already built; this entry becomes "new driver harness on top of an existing wrapper."
- **A token-budget sketch** — before any code is written, estimate a 4-hour session under both architectures with realistic ratios of routine vs. reasoning turns. If the savings are <30%, this is a research project, not a productivity win.