Scrum4Me/docs/runbooks/job-model-selection.md

title	status	audience	language	last_updated	when_to_read
Job-model-selectie per ClaudeJob-kind	active	ai-agent contributor	nl	2026-05-09	Vóór het wijzigen van model/thinking/permission-mode-keuze of bij debugging van 'verkeerd model gebruikt'-incidents.

Job-model-selectie per ClaudeJob-kind

PBI-67. Per ClaudeJob.kind bepaalt de Scrum4Me-mcp resolver scrum4me-mcp/src/lib/job-config.ts welk Claude-model + thinking- budget + permission-mode + max_turns + allowed_tools de Claude Code- worker moet gebruiken.

Dezelfde resolver staat — als één-op-één spiegel — in lib/job-config.ts voor de enqueue-laag, zodat we bij job-creatie het resolved resultaat al snapshotten in ClaudeJob.requested_*.

---

Override-cascade

   1. Task.requires_opus = true   →  forceer claude-opus-4-7
   2. Job.requested_*             →  snapshot bij enqueue
   3. Product.preferred_*         →  product-brede default
   4. KIND_DEFAULTS               →  per kind onderstaand

Eerste match wint. max_turns en allowed_tools blijven in V1 altijd kind-default — geen product- of task-override.

---

Kind-default-matrix

Kind	Model	Thinking-budget	Permission-mode	max_turns	allowed_tools
IDEA_GRILL	claude-sonnet-4-6	12 000	plan	15	Read, Grep, Glob, WebSearch, AskUserQuestion
IDEA_MAKE_PLAN	claude-opus-4-7	24 000	plan	20	Read, Grep, Glob, WebSearch, AskUserQuestion, Write
PLAN_CHAT	claude-sonnet-4-6	6 000	plan	5	Read, Grep, AskUserQuestion
TASK_IMPLEMENTATION	claude-sonnet-4-6	6 000	bypassPermissions	50	(alle)
SPRINT_IMPLEMENTATION	claude-sonnet-4-6	6 000	bypassPermissions	(geen)	(alle)

Note over max_turns (sinds queue-loop-refactor): dit veld blijft audit-only. Claude CLI 2.1.x heeft géén --max-turns flag — de waarde wordt gesnapshot in ClaudeJob.requested_* voor cost-attribution maar niet doorgegeven aan Claude. Zie worker-idempotency.md.

Note over thinking_budget: de CLI heeft alleen --effort {low,medium,high,xhigh,max}. De runner mapt het numerieke budget naar de juiste effort-laag via mapBudgetToEffort() in lib/job-config.ts.

Note over allowed_tools: de defaults sluiten bewust mcp__scrum4me__wait_for_job, check_queue_empty en get_idea_context uit. De runner claimt voor Claude — vangrail tegen recursieve claims binnen één invocation.

bypassPermissions is verdedigbaar voor de implement-kinds omdat elke run in een geïsoleerde git-worktree start (zie branch-and-commit.md). Productie-product? Zet Product.preferred_permission_mode = 'acceptEdits'.

---

Wanneer overrul je een default?

Scenario	Wijzig op	Voorbeeld
Cross-file refactor of architectuurkeuze in TASK_IMPLEMENTATION	Task.requires_opus = true	Een PBI met "rip out auth middleware"
Klant wil budget-control op een product	Product.preferred_model = claude-sonnet-4-6	Side-product met Haiku-only-budget
Productie-product zonder bypassPermissions	Product.preferred_permission_mode = 'acceptEdits'	Klant-facing repo waar elke wijziging review nodig heeft
Ad-hoc: Opus voor één specifieke story-job	ClaudeJob.requested_model = claude-opus-4-7 (handmatige UPDATE)	Nood-debug van prod-incident
Geen thinking voor een PLAN_CHAT (snelle reactie)	Product.thinking_budget_default = 0 (alle kinds in dat product)	Demo-product

---

Auditspoor

Kolom	Wat	Wanneer ingevuld
requested_model	Resolved model op enqueue-tijd	actions/* enqueue-laag via lib/job-config-snapshot.ts
requested_thinking_budget	Resolved budget op enqueue-tijd	idem
requested_permission_mode	Resolved permission-mode	idem
model_id	Werkelijk gebruikt model	update_job_status na worker-run
actual_thinking_tokens	Werkelijk verbruikte thinking-tokens	idem

Verschillen tussen requested_model en model_id zijn zichtbaar in admin → Jobs → Kosten (rood-gemarkeerd modelveld + tooltip). Meestal duidt dat op een worker die de CLI-flag niet doorgaf — controleer de worker-script tegen de flag-tabel in worker-idempotency.md.

---

Runner-architectuur (sinds 2026-05-09 queue-loop-refactor)

scrum4me-docker/bin/run-one-job.ts draait één Claude-invocation per geclaimde job. De runner leest de config uit de wait_for_job-payload (resolved via deze module) en bouwt kind-specifieke CLI-flags. Voor de exacte flag-mapping (incl. --effort en --allowedTools) zie worker-idempotency.md.

Praktische gevolgen:

• Per job-spawn een nieuwe Claude-invocation met andere flags — geen config-mismatch tussen jobs in dezelfde queue-run.
• Verschillen tussen requested_model en model_id in admin → Jobs duiden óf op handmatige DB-overrides tussen enqueue en claim, óf op Claude die zelf een ander model rapporteerde (bv. fallback bij overload).
• Plan: queue-loop-extraction.md.

Cost-attribution

Thinking-tokens worden bij Anthropic-billing gerekend tegen de input-rate van het model. lib/insights/token-stats.ts en lib/insights/token-history.ts doen hetzelfde:

COALESCE(cj.actual_thinking_tokens, 0) * mp.input_price_per_1m / 1000000.0

Voor per-kind aggregatie binnen een sprint: gebruik getTokenStatsByKind(userId, sprintId).

---

Referenties

• Plan: docs/plans/job-model-selection.md
• Resolver (MCP): scrum4me-mcp/src/lib/job-config.ts
• Resolver (main): lib/job-config.ts
• Snapshot-helper: lib/job-config-snapshot.ts
• Worker-flag-mapping: worker-idempotency.md
• Schema: prisma/schema.prisma → Product, Task, ClaudeJob velden uit migration 20260508085909_add_job_model_selection_fields