feat: add --model flag and preferences file for LLM model override

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer

[AhmedTMM]

Summary

• Adds --model / -m CLI flag to override the agent's default LLM model
• Adds persistent per-agent model config via ~/.config/spawn/preferences.json
• Model resolution priority: --model flag > preferences file > agent hardcoded default

Usage

# CLI flag (one-time override)
spawn codex gcp --model openai/gpt-5.3-codex
# Via env var
MODEL_ID=openai/gpt-5.3-codex spawn codex gcp
# Persistent preferences file (~/.config/spawn/preferences.json)
{
"models": {
"codex": "openai/gpt-5.3-codex",
"openclaw": "anthropic/claude-sonnet-4.6"
}
}

Context

The long-term plan is for a web UI to invoke spawn commands programmatically to provision cloud machines. The --model flag enables the web UI to pass model selection as a CLI arg (along with --headless --output json).

The preferences file supports setups like GitHub/Telegram/WhatsApp integrations where the config is written once and reused across invocations.

Files changed

• packages/cli/src/flags.ts — added --model, -m to known flags
• packages/cli/src/index.ts — extract --model flag, set MODEL_ID env var
• packages/cli/src/commands/help.ts — added to usage, examples, and env vars sections
• packages/cli/src/shared/orchestrate.ts — load model from preferences file, updated priority order
• packages/cli/src/shared/paths.ts — added getSpawnPreferencesPath()
• packages/cli/package.json — version bump to 0.17.0

Test plan

• bunx @biomejs/biome check — 0 errors
• bun test — 1380 tests pass

🤖 Generated with Claude Code

[louisgv]

Security Review

Verdict: APPROVED
Commit: 9ad5a56

Findings

No security issues found. All inputs are properly validated and sanitized.

Security Analysis

1. Command Injection Protection: ✅ SECURE

   • Model ID from --model flag is validated via validateModelId() with strict regex: /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*\/[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/
   • Prevents shell metacharacters and command injection
   • Test coverage: packages/cli/src/tests/orchestrate.test.ts:363

2. Path Traversal Protection: ✅ SECURE

   • Preferences file path is hardcoded via getSpawnPreferencesPath()
   • Uses join(getUserHome(), ".config", "spawn", "preferences.json")
   • No user input in path construction

3. JSON Parsing Safety: ✅ SECURE

   • Uses tryCatchIf(isFileError, ...) for error handling
   • Valibot schema validation prevents malformed data
   • Returns null on parse failure (fail-safe)

4. Preferences File Injection: ✅ SECURE

   • Even if attacker modifies preferences.json, model ID still goes through validateModelId()
   • Priority order (flag > preferences > default) is secure

Tests

• bun test: ✅ PASS (1380/1380 tests passing)
• biome lint: ✅ PASS (0 errors)
• bash -n: N/A (no shell scripts modified)

Code Quality

• Version bump: ✅ 0.16.19 → 0.17.0 (minor - new feature)
• Help text updated: ✅
• Flag registration: ✅ Added to KNOWN_FLAGS
• Type safety: ✅ Uses valibot schema validation

---

-- security/pr-reviewer