saving-token 0.1.0 → 1.1.0

package/README.md

@@ -1,46 +1,81 @@
 # saving-token
 
-A native writer makes file changes; the parent agent decides and reviews. You choose the writer model during setup. The parent model and global defaults stay unchanged.
+A native writer makes file changes; the host directs and reviews. The writer
+model is selected during setup, while the host model and global defaults stay
+unchanged.
 
-Inspired by [karpathy-guidelines](https://github.com/multica-ai/andrej-karpathy-skills). Delegation aims to reduce parent-context output; extra context and retries can increase total tokens.
+Inspired by [karpathy-guidelines](https://github.com/multica-ai/andrej-karpathy-skills).
+
+The writer is used only when the host model is stronger; otherwise the host
+works directly.
 
 ## Install
 
-### Codex via npm (after publication)
+### Interactive setup
+
+```bash
+bash skills/saving-token/scripts/setup.sh
+```
+
+Use **Up/Down** and **Enter** to choose the platform, writer model, optional
+reasoning effort, and final action. Press **Esc** to cancel. The final menu
+starts on **Cancel**. Model entries are suggestions only; availability is not
+checked. The effort menu includes the host default and values accepted by the
+target; account and model support still depend on the host.
+
+The model menu has no free-text entry. Use `--model` for a custom model ID or
+for non-interactive setup:
+
+```bash
+bash skills/saving-token/scripts/setup.sh \
+  --target codex --model '<model-id>' --yes
+```
+
+`--target` and `--model` are required without a terminal. Add
+`--reasoning-effort <effort>` when supported by the selected model. `--yes`
+approves the displayed installation and replacements; it never chooses a
+model. Rerun setup to change the writer. Extra files in an existing Skill
+directory are preserved.
 
-After the package is published to npm, run:
+### npm wrapper
+
+After publication, run:
 
 ```bash
 npx saving-token@latest install --agent codex
 ```
 
-This interactively prompts you to choose a writer model and optional reasoning effort, then asks you to confirm installation.
+The wrapper supports `install --agent codex` and keeps the interactive menus.
+Use the Bash script directly for `--target`, `--model`, `--reasoning-effort`,
+or `--yes`.
 
-### Manual / multi-platform
+To refresh only the suggested models in an existing Codex installation, run:
 
 ```bash
-bash skills/saving-token/scripts/setup.sh
+npx saving-token@latest update-models --agent codex
 ```
 
-Choose **platform → model → optional reasoning effort → confirm**. The model menu offers a few suggestions and a custom ID option, with no default selection. Suggestions do not verify account availability. Leave effort blank to use the host's default behavior.
+It changes no writer configuration and shows no setup menus. Use the Bash
+script with `--update-models --target claude` or `cursor` for those platforms.
+
+### Installed paths
 
-| Platform | Skill location | Writer configuration |
+| Platform | Skill | Writer configuration |
 |---|---|---|
 | Codex | `${CODEX_HOME:-~/.codex}/skills/saving-token/` | `${CODEX_HOME:-~/.codex}/agents/saving-token-writer.toml` |
 | Claude Code | `~/.claude/skills/saving-token/` | `~/.claude/agents/saving-token-writer.md` |
 | Cursor | `~/.cursor/skills/saving-token/` | `~/.cursor/agents/saving-token-writer.md` |
 
-Restart the host, then invoke `$saving-token` in Codex or `/saving-token` in standalone Claude Code and Cursor. Automatic Skill discovery remains available. Verify the writer model in runtime task metadata when exposed; generated configuration alone does not prove routing. Claude Code and Cursor may substitute a model under account or administrator policy.
+Restart the host, then invoke `$saving-token` in Codex or `/saving-token` in
+standalone Claude Code and Cursor. A generated configuration does not prove
+runtime routing; verify the model in exposed task metadata when available.
+Claude Code and Cursor may substitute a model under account or administrator
+policy.
 
-To automate an already approved installation:
-
-```bash
-bash skills/saving-token/scripts/setup.sh --target codex --model '<model-id>' --yes
-```
-
-`--target` and `--model` are required without a terminal. Add `--reasoning-effort <effort>` only if supported by the selected model. Explicit `--model` skips the menu; `--yes` approves installation and displayed replacements, without choosing a model.
-
-Rerun setup to change the writer model. Existing distributed Skill files and the writer configuration are replaced after confirmation; extra files in the Skill directory are preserved. Setup also works from the installed Skill's `scripts/setup.sh`.
+The writer implements and verifies delegated changes. The host personally
+reviews the actual changes and verification evidence against the requirements,
+sends defects back to the same writer for fixes and re-review, and announces
+completion only after review passes.
 
 ## Claude Code plugin
 
@@ -49,15 +84,12 @@ Rerun setup to change the writer model. Existing distributed Skill files and the
 /plugin install saving-token@saving-token
 ```
 
-Claude's plugin configuration collects the required `writer_model` as text; it does not use the script's menu. The plugin leaves reasoning effort to the host. Invoke `/saving-token:saving-token`; its writer is `saving-token:saving-token-writer`. Change the model through plugin configuration, then reload the session. Use either the plugin or standalone installation.
-
-## Structure
-
-- [`skills/saving-token/SKILL.md`](skills/saving-token/SKILL.md): canonical delegation and review rules.
-- `skills/saving-token/scripts/setup.sh` and `assets/`: standalone installer and native agent templates.
-- `agents/` and `.claude-plugin/`: Claude plugin writer and marketplace metadata.
-- `AGENTS.md`, `CLAUDE.md`, [`CURSOR.md`](CURSOR.md), and `.cursor/rules/`: repository adapters that point to the Skill.
-
-Other hosts can read the Skill or `AGENTS.md`, but delegation requires writable native subagents and independent model configuration. Without those capabilities, support is instruction-only.
+The plugin collects `writer_model` through its configuration and leaves effort
+to the host. Invoke `/saving-token:saving-token`; its writer is
+`saving-token:saving-token-writer`. Use either the plugin or standalone setup.
 
-Official references: [Codex subagents](https://developers.openai.com/codex/subagents), [Claude subagents](https://code.claude.com/docs/en/sub-agents), [Claude plugins](https://code.claude.com/docs/en/plugins-reference), [Cursor subagents](https://cursor.com/docs/subagents), [Agent Skills](https://agentskills.io/specification).
+Official references: [Codex subagents](https://developers.openai.com/codex/subagents),
+[Claude subagents](https://code.claude.com/docs/en/sub-agents),
+[Claude plugins](https://code.claude.com/docs/en/plugins-reference),
+[Cursor subagents](https://cursor.com/docs/subagents), and
+[Agent Skills](https://agentskills.io/specification).

package/bin/saving-token.cjs

@@ -8,11 +8,11 @@ const args = process.argv.slice(2);
 
 if (
   args.length !== 3 ||
-  args[0] !== 'install' ||
+  !['install', 'update-models'].includes(args[0]) ||
   args[1] !== '--agent' ||
   args[2] !== 'codex'
 ) {
-  console.error('Usage: saving-token install --agent codex');
+  console.error('Usage: saving-token <install|update-models> --agent codex');
   process.exit(1);
 }
 
@@ -24,7 +24,12 @@ const setupPath = path.join(
   'scripts',
   'setup.sh'
 );
-const result = spawnSync('bash', [setupPath, '--target', 'codex'], {
+const setupArgs = [setupPath, '--target', 'codex'];
+if (args[0] === 'update-models') {
+  setupArgs.push('--update-models');
+}
+
+const result = spawnSync('bash', setupArgs, {
   stdio: 'inherit'
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saving-token",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "bin": {
     "saving-token": "bin/saving-token.cjs"
   },

package/skills/saving-token/SKILL.md

@@ -18,24 +18,31 @@ If your identity is `saving-token-writer` or `saving-token:saving-token-writer`,
 - If a writable native writer or independent model configuration is unavailable, report instruction-only compatibility and ask before implementing directly.
 - Configuration is not runtime proof. Check exposed model metadata and disclose mismatches; never silently substitute a model yourself. Claude Code and Cursor may apply host-level fallback.
 
+## Model gate
+
+- Delegate only when the current host model is stronger than the configured writer model.
+- If the comparison is unknown, do not delegate; the parent completes the task directly under normal authorization.
+
 ## Delegate
 
 - Delegate every file write, including edits, deletions, documents, temporary scripts, and formatting.
 - Give goals and acceptance criteria, not implementation text to paste. Prefer file paths and issue locations over copied source or conversation history.
 - Batch related changes into one scoped task and reuse the writer for revisions.
 - The writer follows project rules and authorization boundaries, preserves user edits, implements directly, and runs relevant checks.
+- Put exact focused commands in `Verify`; the writer runs them with the change.
+- For slow E2E or independent confirmation, use a verification-only native subagent. It must not modify files and returns commands, exit codes, result counts when available, and code failures or environmental blockers.
 
 ```text
 Goal: <expected behavior>
-Scope: <paths; prohibited changes>
-Verify: <acceptance criteria and checks>
-Return: changed paths; check results; blockers.
+Scope: <paths; prohibited changes; or verification-only, no file changes>
+Verify: <exact commands>
+Return: changed paths; commands, exit codes, result counts when available; code failures or environmental blockers.
 ```
 
 ## Accept
 
-- Inspect the actual diff, new files, and check evidence; never accept from the writer summary alone.
-- Send remaining defects and acceptance conditions to the same writer, then review again. Stop and report blockers or repeated failures without progress.
+- After the writer finishes, the host must personally review the actual diff, new files, and verification evidence against the requirements, never relying on the writer's summary alone; send any defects to the same writer for fixes and re-review, and announce completion only after the review passes.
+- Stop and report blockers or repeated failures without progress.
 - Report the outcome, verification, and material routing uncertainty concisely. Keep full logs in files when needed.
 
 Delegation aims to reduce parent-context output; a second context and retries can increase total token usage.

package/skills/saving-token/assets/claude/saving-token-writer.md.template

@@ -12,4 +12,5 @@ disallowedTools:
 Implement directly. Never delegate or invoke another subagent.
 Follow project rules and authorization boundaries, and preserve existing user edits.
 Make only the requested changes and run the requested checks.
-Return changed paths, check commands and results, and blockers only.
+For verification-only work, do not modify files.
+Return changed paths; commands, exit codes, result counts when available; and code failures or environmental blockers only.

package/skills/saving-token/assets/codex/saving-token-writer.toml.template

@@ -7,5 +7,6 @@ developer_instructions = """
 Implement directly. Do not delegate further.
 Follow project rules and preserve existing user edits.
 Run the requested checks.
-Return changed paths, check results, and blockers only.
+For verification-only work, do not modify files.
+Return changed paths; commands, exit codes, result counts when available; and code failures or environmental blockers only.
 """

package/skills/saving-token/assets/cursor/saving-token-writer.md.template

@@ -11,4 +11,5 @@ is_background: false
 Implement directly. Never delegate or invoke another subagent.
 Follow project rules and authorization boundaries, and preserve existing user edits.
 Make only the requested changes and run the requested checks.
-Return changed paths, check commands and results, and blockers only.
+For verification-only work, do not modify files.
+Return changed paths; commands, exit codes, result counts when available; and code failures or environmental blockers only.

package/skills/saving-token/scripts/setup.sh

@@ -3,16 +3,102 @@ set -euo pipefail
 
 fail() { printf 'Error: %s\n' "$*" >&2; exit 1; }
 
+cursor_hidden=false
+terminal_state=''
+restore_cursor() {
+  if [[ "$cursor_hidden" == true ]]; then
+    printf '\033[?25h'
+    cursor_hidden=false
+  fi
+  if [[ -n "$terminal_state" ]]; then
+    stty "$terminal_state" 2>/dev/null || stty echo
+    terminal_state=''
+  fi
+}
+trap restore_cursor EXIT
+trap 'exit 130' INT TERM
+
+choose_menu() {
+  local prompt=$1
+  shift
+  local -a labels values
+  local entry label value key sequence
+  local selected=0 rendered=false line_count
+  MENU_RESULT=''
+
+  for entry in "$@"; do
+    label=${entry%%|*}
+    value=${entry#*|}
+    labels[${#labels[@]}]=$label
+    values[${#values[@]}]=$value
+  done
+  line_count=$(( ${#labels[@]} + 1 ))
+  terminal_state=$(stty -g)
+  stty -echo
+  printf '\033[?25l'
+  cursor_hidden=true
+
+  while :; do
+    if [[ "$rendered" == true ]]; then
+      printf '\033[%sA' "$line_count"
+    fi
+    printf '\033[2K\r%s (Up/Down, Enter to select, Esc to cancel)\n' "$prompt"
+    for entry in "${!labels[@]}"; do
+      printf '\033[2K\r'
+      if [[ "$entry" -eq "$selected" ]]; then
+        printf '> %s\n' "${labels[$entry]}"
+      else
+        printf '  %s\n' "${labels[$entry]}"
+      fi
+    done
+    rendered=true
+
+    if ! IFS= read -r -s -n 1 key; then
+      restore_cursor
+      return 2
+    fi
+    case "$key" in
+      ''|$'\n'|$'\r')
+        MENU_RESULT=${values[$selected]}
+        restore_cursor
+        printf '\n'
+        return 0
+        ;;
+      $'\033')
+        if IFS= read -r -s -n 2 -t 1 sequence; then
+          case "$sequence" in
+            '[A') selected=$(( (selected + ${#labels[@]} - 1) % ${#labels[@]} )) ;;
+            '[B') selected=$(( (selected + 1) % ${#labels[@]} )) ;;
+            *) restore_cursor; printf '\n'; return 1 ;;
+          esac
+        else
+          restore_cursor
+          printf '\n'
+          return 1
+        fi
+        ;;
+    esac
+  done
+}
+
+cancel_install() {
+  printf 'Installation cancelled; no files were changed.\n'
+  exit 0
+}
+
 usage() {
   cat <<'HELP'
 Usage: setup.sh [--target codex|claude|cursor] [--model ID]
                 [--reasoning-effort EFFORT] [--yes]
+       setup.sh --update-models --target codex|claude|cursor
 
-Choose a platform and writer model, preview, then confirm installation.
+Use Up/Down and Enter to choose a platform, model, effort, and confirmation.
+Esc cancels before any files are changed.
   --target PLATFORM          Prompted when omitted; required without a terminal.
   --model ID                 Skip the model menu; required without a terminal.
   --reasoning-effort EFFORT   Optional. Omit to use the host's default behavior.
   --yes                      Approve installation and displayed replacements.
+  --update-models            Update only model suggestions in an installed Skill.
   -h, --help                 Show this help.
 
 Model suggestions are not an account availability check. Use only models and
@@ -28,6 +114,7 @@ reasoning_effort=''
 model_was_set=false
 effort_was_set=false
 assume_yes=false
+update_models=false
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -40,16 +127,24 @@ while [[ $# -gt 0 ]]; do
       esac
       shift 2 ;;
     --yes) assume_yes=true; shift ;;
+    --update-models) update_models=true; shift ;;
     -h|--help) usage; exit 0 ;;
     *) fail "Unknown option: $1" ;;
   esac
 done
 
 [[ -n "${HOME:-}" ]] || fail 'HOME is not set.'
+if [[ "$update_models" == true ]]; then
+  [[ -n "$target" ]] || fail 'Pass --target with --update-models.'
+  [[ "$model_was_set" == false && "$effort_was_set" == false && "$assume_yes" == false ]] || fail '--update-models cannot be combined with --model, --reasoning-effort, or --yes.'
+fi
 if [[ -z "$target" ]]; then
   [[ -t 0 ]] || fail 'Pass --target in non-interactive use.'
-  IFS= read -r -p 'Platform: 1) codex  2) claude  3) cursor: ' target || fail 'No platform selected.'
-  case "$target" in 1) target=codex ;; 2) target=claude ;; 3) target=cursor ;; esac
+  if choose_menu 'Choose a platform:' 'Codex|codex' 'Claude Code|claude' 'Cursor|cursor'; then
+    target=$MENU_RESULT
+  else
+    cancel_install
+  fi
 fi
 
 case "$target" in
@@ -58,37 +153,75 @@ case "$target" in
     skill_target="$codex_home/skills/saving-token"
     agent_dir="$codex_home/agents"
     agent_file='saving-token-writer.toml'
-    models=(gpt-5.6-luna gpt-5.6-terra gpt-5.3-codex-spark)
+    models=(gpt-6-luna gpt-6-sol gpt-6-astra)
     ;;
   claude)
     skill_target="$HOME/.claude/skills/saving-token"
     agent_dir="$HOME/.claude/agents"
     agent_file='saving-token-writer.md'
-    models=(haiku sonnet opus)
+    models=(claude-haiku-4-5-20251001 claude-sonnet-5 claude-opus-5-5 claude-fable-5-1)
     ;;
   cursor)
     skill_target="$HOME/.cursor/skills/saving-token"
     agent_dir="$HOME/.cursor/agents"
     agent_file='saving-token-writer.md'
-    models=(composer-2.5 gpt-5.6-sol)
+    models=(composer-2.5 gpt-5.6-luna gpt-5.6-terra gpt-5.6-sol claude-sonnet-5 claude-opus-5-5 claude-fable-5-1)
     ;;
   *) fail "Unsupported target '$target'. Expected codex, claude, or cursor." ;;
 esac
 
+update_installed_model_suggestions() {
+  local installed_setup temporary_setup model_line
+
+  installed_setup="$skill_target/scripts/setup.sh"
+  [[ -f "$installed_setup" ]] || fail "No installed Skill script found at $installed_setup. Run install first."
+
+  model_line="    models=(${models[*]})"
+
+  temporary_setup="$(mktemp "$(dirname -- "$installed_setup")/.saving-token-setup.XXXXXX")"
+  cp -p "$installed_setup" "$temporary_setup"
+  if ! awk -v target="$target" -v model_line="$model_line" '
+    $0 == "  " target ")" { in_target = 1; print; next }
+    in_target && $0 == "    ;;" { in_target = 0; print; next }
+    in_target && $0 ~ /^    models=\([^)]*\)$/ {
+      replacements++
+      print model_line
+      next
+    }
+    { print }
+    END { exit replacements == 1 ? 0 : 1 }
+  ' "$installed_setup" > "$temporary_setup"; then
+    rm -f "$temporary_setup"
+    fail "Could not find one model list for $target in $installed_setup. Run install to refresh the Skill."
+  fi
+  if ! bash -n "$temporary_setup"; then
+    rm -f "$temporary_setup"
+    fail 'Updated Skill script failed syntax validation.'
+  fi
+  if cmp -s "$installed_setup" "$temporary_setup"; then
+    rm -f "$temporary_setup"
+    printf 'Model suggestions for %s are already current.\n' "$target"
+    return
+  fi
+
+  mv -f "$temporary_setup" "$installed_setup"
+  printf 'Updated model suggestions for %s in %s. Writer configuration was not changed.\n' "$target" "$installed_setup"
+}
+
+if [[ "$update_models" == true ]]; then
+  update_installed_model_suggestions
+  exit 0
+fi
+
 if [[ "$model_was_set" != true ]]; then
   [[ -t 0 ]] || fail 'Pass --model in non-interactive use.'
-  printf '\nWriter model suggestions (availability depends on your account):\n'
-  for i in "${!models[@]}"; do printf '  %s) %s\n' "$((i + 1))" "${models[$i]}"; done
-  printf '  c) Custom model ID\n  q) Cancel\n'
-  IFS= read -r -p 'Choose a model: ' choice || fail 'No model selected.'
-  case "$choice" in
-    q|Q) printf 'Installation cancelled; no files were changed.\n'; exit 0 ;;
-    c|C) IFS= read -r -p 'Writer model ID: ' writer_model || fail 'No model selected.' ;;
-    [1-3])
-      [[ "$choice" -le "${#models[@]}" ]] || fail 'Invalid model selection.'
-      writer_model=${models[$((choice - 1))]} ;;
-    *) fail 'Choose a listed number, c, or q; no model is selected by default.' ;;
-  esac
+  model_options=()
+  for model in "${models[@]}"; do model_options[${#model_options[@]}]="$model|$model"; done
+  if choose_menu 'Choose a writer model:' "${model_options[@]}"; then
+    writer_model=$MENU_RESULT
+  else
+    cancel_install
+  fi
 fi
 [[ "$writer_model" =~ ^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$ ]] || fail 'Model ID must be nonempty, without whitespace or parameters; use letters, digits, ., _, :, /, or -.'
 
@@ -97,7 +230,24 @@ case "$writer_model" in
 esac
 
 if [[ "$effort_was_set" != true && "$assume_yes" != true && -t 0 ]]; then
-  IFS= read -r -p 'Reasoning effort (Enter to omit): ' reasoning_effort || fail 'Input cancelled.'
+  effort_options=('Use host default (omit)|')
+  case "$target" in
+    codex) effort_options+=(
+      'none|none' 'minimal|minimal' 'low|low' 'medium|medium' 'high|high'
+      'xhigh|xhigh' 'max|max' 'ultra|ultra'
+    ) ;;
+    claude) effort_options+=(
+      'low|low' 'medium|medium' 'high|high' 'xhigh|xhigh' 'max|max'
+    ) ;;
+    cursor) effort_options+=(
+      'low|low' 'medium|medium' 'high|high' 'xhigh|xhigh' 'max|max' 'ultra|ultra'
+    ) ;;
+  esac
+  if choose_menu 'Choose reasoning effort (model support may vary):' "${effort_options[@]}"; then
+    reasoning_effort=$MENU_RESULT
+  else
+    cancel_install
+  fi
 fi
 case "$reasoning_effort" in
   ''|none|minimal|low|medium|high|xhigh|max|ultra) ;;
@@ -135,11 +285,12 @@ fi
 [[ ! -e "$agent_target" ]] || printf 'Existing writer configuration will be replaced.\n'
 
 if [[ "$assume_yes" != true ]]; then
-  IFS= read -r -p 'Install this configuration? [y/N] ' answer || fail 'Confirmation required; use --yes after approval.'
-  case "$answer" in
-    y|Y|yes|YES|Yes) ;;
-    *) printf 'Installation cancelled; no files were changed.\n'; exit 0 ;;
-  esac
+  [[ -t 0 ]] || fail 'Pass --yes in non-interactive use.'
+  if choose_menu 'Install this configuration?' 'Cancel|no' 'Install|yes'; then
+    [[ "$MENU_RESULT" == yes ]] || cancel_install
+  else
+    cancel_install
+  fi
 else
   printf 'Install this configuration? yes (--yes)\n'
 fi