feat(claude_code): per-agent reasoning effort via claudeConfig

[vprudnikoff]

What

Adds a claudeConfig field to the agent profile, the Claude Code analog of codexConfig (PR #278) for the codex provider. The claude_code provider maps it to Claude Code CLI flags at launch:

claudeConfig key	Claude Code flag
effort	--effort <level>
fallback_model	--fallback-model <model>

The top-level model field still maps to --model (unchanged), mirroring how codex keeps model separate from codexConfig.

Why

Today the only lever for a claude_code agent's reasoning effort is the machine-global effortLevel in ~/.claude/settings.json (or the CLAUDE_CODE_EFFORT_LEVEL env var, which the provider already preserves). That silently differs between machines: an orchestrator profile meant to run at xhigh falls back to the Claude Code default (high) on any host where the global setting is absent. codexConfig already solves the equivalent problem per-agent for codex; this brings parity to claude_code.

Example

name: cto
provider: claude_code
claudeConfig:
  effort: xhigh

Tests

test/providers/test_claude_code_unit.py::TestClaudeCodeProviderClaudeConfig: effort flag emitted when set, fallback-model emitted when set, no flag when claudeConfig is absent. Docs updated in docs/agent-profile.md.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@1224cd0). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #283   +/-   ##
=======================================
  Coverage        ?   92.15%           
=======================================
  Files           ?       70           
  Lines           ?     7115           
  Branches        ?        0           
=======================================
  Hits            ?     6557           
  Misses          ?      558           
  Partials        ?        0           

Flag	Coverage Δ
unittests	92.15% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds per-agent Claude Code launch overrides by introducing a claudeConfig map on AgentProfile, and mapping selected keys to Claude Code CLI flags when building the claude command. This brings profile-level control over reasoning effort / fallback model without relying on machine-global ~/.claude/settings.json settings.

Changes:

• Add claudeConfig to AgentProfile and document it in docs/agent-profile.md.
• Update ClaudeCodeProvider._build_claude_command() to emit --effort and --fallback-model when profile.claudeConfig is set.
• Add unit tests ensuring the flags are emitted/omitted as expected.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/cli_agent_orchestrator/providers/claude_code.py	Map profile.claudeConfig entries to claude CLI flags during command construction.
src/cli_agent_orchestrator/models/agent_profile.py	Extend the agent profile schema with the new optional claudeConfig field.
test/providers/test_claude_code_unit.py	Add unit tests covering claudeConfig → CLI flag behavior.
docs/agent-profile.md	Document the new claudeConfig profile field and its flag mappings.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vprudnikoff]

For context: codexConfig is introduced by the sibling PR #278 (feat/codex-agent-config). This launch-override comment intentionally mirrors that field — claudeConfig is the claude_code analog — so it resolves once both PRs merge. If reviewers prefer this PR to stand alone regardless of merge order, I'm happy to drop the codexConfig mention and describe the behavior on its own.

[vprudnikoff]

For context: codexConfig is added by the sibling PR #278 (feat/codex-agent-config). claudeConfig here is the deliberate claude_code analog of that field, so this comment cross-references it on purpose; it becomes accurate once both PRs merge. If you'd rather keep this PR independent of merge order, I can drop the codexConfig reference and just describe claudeConfig on its own.

[vprudnikoff]

Context: codexConfig is introduced by the sibling PR #278 (feat/codex-agent-config). These two are a pair — per-agent provider config: codexConfig for the codex provider, claudeConfig for claude_code — so the cross-reference is intentional and resolves once both land. If you'd prefer each PR to read as fully self-contained regardless of merge order, I'm happy to drop the codexConfig mention here.

[haofeif]

@vprudnikoff great PR. I think this needs one behavior fix before approval.

The new claudeConfig.effort emits --effort, but the provider still preserves CLAUDE_CODE_EFFORT_LEVEL in the spawned Claude environment. Claude's model-config docs say the environment variable takes precedence over the other effort mechanisms, so a host-level CLAUDE_CODE_EFFORT_LEVEL can silently override the profile's per-agent effort. That undercuts the PR's stated goal of avoiding machine-global effort drift.

Could we make claudeConfig.effort win explicitly, either by unsetting CLAUDE_CODE_EFFORT_LEVEL when a profile effort is present or by setting it to the same profile value, and add a regression test for that command construction?

On the existing codexConfig comments: I saw your note that #278 is the paired PR. That is fine if #283 is intentionally sequenced after #278, but if this PR may merge independently I would still drop the codexConfig references so the docs are accurate on current main.

One smaller compatibility note: local Claude Code 2.1.181 help says --fallback-model only works with --print, while CAO launches interactive sessions. The public docs no longer show that limitation, so I would just verify/document the minimum Claude Code behavior for that field.

## Checks Run

```bash
git fetch origin main
git -C /tmp/cao-pr283 fetch origin pull/283/head
git -C /tmp/cao-pr283-merge reset --hard origin/main
git -C /tmp/cao-pr283-merge merge --no-commit --no-ff pr-283
git diff --check
uv run pytest test/providers/test_claude_code_unit.py -q
claude -v
claude --claude-help
curl -L https://code.claude.com/docs/en/model-config.md
curl -L https://code.claude.com/docs/en/env-vars.md
curl -L https://code.claude.com/docs/en/cli-reference.md

Results:

• git diff --check: passed
• test/providers/test_claude_code_unit.py: 111 passed
• Local Claude Code: 2.1.181

[haofeif]

@vprudnikoff do you get a chance to work on this PR to address the feedbacks and the conflicts ? many thanks.

[gutosantos82]

PR Review: #283 — feat(claude_code): per-agent reasoning effort via claudeConfig

Summary

Adds a claudeConfig object to the agent profile so a claude_code agent can set
per-agent reasoning effort (--effort) and fallback_model (--fallback-model) at
launch, instead of depending on the machine-global effortLevel in
~/.claude/settings.json. The implementation is small, safe, and follows the existing
flag-emission pattern; the flags are real Claude Code launch options and values are
shell-escaped via shlex.join. No blocking issues. The recurring, cross-reviewer theme is
documentation/model-consistency drift: the PR repeatedly calls this "the Claude analog
of codexConfig", but no codexConfig field exists in the codebase — the real codex knob
is codexProfile, which is validated and shaped differently. Recommend fixing the wording,
adding light validation, and a CHANGELOG entry before merge.

Blocking (must fix before merge)

None. The introduced code is functionally correct and secure.

Important (should fix)

• [correctness/consistency] src/cli_agent_orchestrator/providers/claude_code.py:131-136, models/agent_profile.py:62 — No validation of effort/fallback_model; any value is forwarded verbatim via str(...). A typo or invalid level ({"effort": "High"}, {"effort": "mx"}, effort: 3 → --effort 3) produces a flag Claude Code rejects, so the spawned claude process exits immediately and CAO surfaces the opaque "Claude Code initialization timed out after 30 seconds" (claude_code.py:337) rather than a clear config error. This also diverges from how every other per-provider knob is modeled (codexProfile/hermesProfile use Field(min_length=1)). This lands in providers/ (high-risk area), so weighting as important. Fix: validate effort against the accepted set (a Literal or model validator) and reject non-str types; fail fast with a clear ProviderError.
• [conventions] CHANGELOG.md — User-facing feature ships with no CHANGELOG entry. The [Unreleased] > Added section exists (CHANGELOG.md:7-11) and the sibling hermesProfile feature set the precedent one line above. Fix: add an ### Added bullet under [Unreleased].
• [consistency] docs/agent-profile.md:37 — Effort enum is both unenforced and incomplete: docs list low|medium|high|xhigh, but Claude Code CLI also accepts max (omitted) and the code enforces no enum at all. Fix: include max and either validate the set or phrase as "e.g.". (Note: the correctness reviewer treated xhigh/max as valid; confirm the exact accepted set against the installed CLI.)

Nits (optional)

• [conventions/consistency] src/cli_agent_orchestrator/providers/claude_code.py:129 — getattr(profile, "claudeConfig", None) is unnecessary defensive access for a declared pydantic field, and inconsistent with siblings profile.codexProfile (codex.py:187) / profile.hermesProfile (hermes.py:148) which use direct attribute access. (It does match the local native_agent getattr, the outlier.) Use profile.claudeConfig directly.
• [correctness] src/cli_agent_orchestrator/providers/claude_code.py:131-136 — str() coercion turns non-string YAML (true, 3, lists) into invalid flags rather than rejecting them; folds into the validation fix above.
• [consistency] docs/claude-code.md (not updated) — Doc-parity gap: codexProfile gets a dedicated section in docs/codex-cli.md; claudeConfig gets only a one-line bullet. Consider a short section in docs/claude-code.md.

Prior feedback (already raised — not restating)

• ↩︎ Phantom "analog of codexConfig" wording / doc↔code drift — codexConfig doesn't exist on main, so the references should be dropped or corrected — already raised by @haofeif; we concur.

Tests

Adequate for the happy path and consistent with file conventions (new
TestClaudeCodeProviderClaudeConfig, mirrors TestClaudeCodeProviderModelFlag). The
tests do reach the real code path — the tests reviewer verified the MagicMock
truthy-attribute trap is narrowly avoided by the isinstance(native, str) guard at
claude_code.py:107-108 (worth a comment, since relaxing that guard would silently divert
all three tests into the --agent branch).

Coverage gaps (all on the changed lines):

• [important] The two defensive guards in the diff have zero coverage: empty-string value {"effort": ""} (the if effort: guard) and non-dict claudeConfig (the isinstance(..., dict) guard). The only negative test uses None.
• [nit] Both keys set together (effort + fallback_model) untested; no co-test with a set top-level --model; assertions use bare substring checks rather than shlex.split token checks (robust here only because values are enum-like); the "absent" test asserts only --effort absent, not --fallback-model.

Recommend ~3 small tests: empty-string value, non-dict config, and both-keys-together — these are exactly the guard branches added in this PR.

Verdict

Approve with nits. No blocking or security issues; the introduced code is correct and
safe. Before merge, the author should (1) fix the false "analog of codexConfig" wording
across the three code/doc sites and the PR body, (2) add light validation for effort
(and reject non-str types) so misconfigs fail fast instead of as a 30s launch timeout,
(3) add a CHANGELOG entry, and (4) correct/complete the effort enum in the docs. The
untested guard branches are worth 3 quick tests.

[haofeif]

@vprudnikoff can you please help to resolve the conflict ?