feat(agentic): thread --time into provider subprocess reasoning flags

[Serhan-Asad]

Summary

Mirrors the CLI-side fix from gltanaka/pdd#1293 onto the public promptdriven/pdd repo, since the GitHub App worker image installs from promptdriven/pdd@main.

Closes the gap between the top-level --time flag and the agentic subprocess launches used by pdd fix <issue-url>, pdd analysis/bug <issue-url>, and pdd checkup <issue-url>.

ctx.obj["time"] already routes into LiteLLM-driven steps (the analysis planner, verifier, classifier) via the CSV-driven reasoning_effort mapping in llm_invoke.py. But the subprocess calls that actually write code (run_agentic_task → _run_with_provider → Codex/Claude Code/Gemini CLIs) only ever forwarded --model, never a reasoning signal. A --time 0.85 run produced the same provider argv as an unspecified run.

What changed

pdd/core/cli.py

Maps --time → PDD_REASONING_EFFORT={low,medium,high} using the same thresholds llm_invoke.py uses (>0.7 high, >0.3 medium, else low). When --time is omitted, the env var is left untouched.

pdd/agentic_common.py

_run_with_provider reads PDD_REASONING_EFFORT (validated against {low, medium, high}) and:

• Codex: injects -c model_reasoning_effort=<level> before the exec subcommand.
• Claude Code CLI: no reasoning-effort flag today; logs once in verbose mode.
• Gemini CLI: same — no flag today, logged in verbose mode.

Tests

• argv assertions for all three providers (parametrized Codex low/med/high with -c ordered strictly before exec; Anthropic and Gemini argv unchanged when env set).
• CliRunner coverage of --time → env mapping including boundary values.
• Suite: 196 passed.

Why this PR exists

The companion GitHub App PR (promptdriven/pdd_cloud#1162) plumbs pdd-effort-* labels → --time argv position, but the worker installs the CLI from promptdriven/pdd@main. Without this PR merged first, the worker would install a CLI where --time reaches argv but doesn't change provider reasoning behavior.

Merge order: this PR first, then pdd_cloud#1162 (rebased onto main, Dockerfile stays at @main).

Test plan

• Unit tests cover the mapping, argv flag ordering (Codex-specific), and per-provider no-op assertions.
• Existing provider success tests still pass — change is additive (adds argv tokens only when env is set with valid value).
• End-to-end validation once pdd_cloud#1162 lands on top.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR introduces pdd/reasoning.py as a shared time_to_effort_level() helper, sets PDD_REASONING_EFFORT in the CLI for unplumbed callers, and threads an explicit reasoning_time kwarg through all five issue-URL commands down to _run_with_provider, where Codex receives -c model_reasoning_effort=<level> before exec.

• Default value leaks into kwarg path: cli.py stores DEFAULT_TIME = 0.25 in ctx.obj[\"time\"] unconditionally, so reasoning_time=ctx.obj.get(\"time\") passed by every plumbed command is always 0.25, never None. _run_with_provider's if reasoning_time is not None: branch therefore always fires, injecting -c model_reasoning_effort=low into Codex and printing the "no reasoning-effort flag" notice to Claude/Gemini for every run — even when --time was never supplied. The env-var path (for unplumbed callers) is correctly guarded by if time is not None:, but that guard is bypassed for all five plumbed commands.
• Notice verbosity: The Claude/Gemini "no reasoning-effort flag" message is gated on not quiet rather than verbose, so it will appear in normal (non-verbose) runs once the default-propagation bug causes it to always trigger.

Confidence Score: 4/5

Safe to merge after addressing the default-value propagation bug; no data loss or security concerns.

One P1 finding: ctx.obj["time"] always defaults to DEFAULT_TIME=0.25, so reasoning_time is never None for the five plumbed commands, causing Codex to always receive -c model_reasoning_effort=low and Claude/Gemini to always print the notice — behavior the PR explicitly says should not happen without --time. All other changes (new reasoning.py helper, Codex argv ordering, test coverage) look correct.

pdd/core/cli.py (ctx.obj["time"] default), pdd/commands/fix.py, analysis.py, modify.py, checkup.py, maintenance.py (all pass ctx.obj.get("time") which is never None)

Important Files Changed

Filename	Overview
pdd/reasoning.py	New helper module with time_to_effort_level() mapping float→{low,medium,high}; clean single-responsibility unit, well-tested.
pdd/core/cli.py	Sets PDD_REASONING_EFFORT only when --time is explicit (correct), but also unconditionally stores DEFAULT_TIME (0.25) in ctx.obj["time"], causing plumbed commands to always forward a non-None reasoning_time.
pdd/agentic_common.py	Adds reasoning_time kwarg and env-var fallback in _run_with_provider; Codex -c injection is correct in isolation, but always fires due to the default value propagation bug; notice message fires in non-quiet rather than verbose-only mode.
pdd/commands/analysis.py	Forwards reasoning_time=obj.get("time") which is always non-None (DEFAULT_TIME=0.25 fallback), so Codex always receives -c model_reasoning_effort=low even without an explicit --time flag.
pdd/agentic_bug_orchestrator.py	Correctly threads reasoning_time through to run_agentic_task calls in the 11-step orchestrator; additive change, no regressions introduced.
tests/test_time_reasoning_effort_env.py	Comprehensive test coverage for threshold boundaries, env-var plumbing, full Codex chain, and per-command kwarg forwarding; test_no_time_flag_leaves_env_unset correctly validates the env-var path but does not catch the kwarg path regression.
tests/test_reasoning.py	Parametrized boundary tests for time_to_effort_level — thorough and correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["pdd --time 0.85 fix <url>"] --> B["cli.py: time is not None?"]
    B -- "Yes (explicit --time)" --> C["os.environ['PDD_REASONING_EFFORT'] = 'high'"]
    B -- "No (omitted)" --> D["env var left untouched ✓"]
    A --> E["ctx.obj['time'] = time ?? DEFAULT_TIME\n(always float, never None)"]
    E --> F["commands/fix.py:\nreasoning_time=ctx.obj.get('time')\n⚠️ always 0.25 when --time omitted"]
    F --> G["run_agentic_e2e_fix(reasoning_time=0.25)"]
    G --> H["run_agentic_task(reasoning_time=0.25)"]
    H --> I["_run_with_provider(reasoning_time=0.25)"]
    I --> J{"reasoning_time is not None?"}
    J -- "Yes (always true)" --> K["time_to_effort_level(0.25) → 'low'"]
    K --> L["Codex: -c model_reasoning_effort=low\n⚠️ injected even without --time"]
    K --> M["Claude/Gemini: print notice\n⚠️ fires in non-quiet mode always"]
    J -- "No (never reached)" --> N["read PDD_REASONING_EFFORT env var"]
    N --> O["inject if set, skip if unset ✓"]
    style F fill:#ffcccc
    style K fill:#ffcccc
    style L fill:#ffcccc
    style M fill:#ffcccc

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: pdd/commands/analysis.py
Line: 247

Comment:
**`reasoning_time` is never `None` for plumbed callers — default always injects `low` effort**

`ctx.obj["time"]` is unconditionally set in `cli.py`:
```python
ctx.obj["time"] = time if time is not None else DEFAULT_TIME  # always 0.25 when --time omitted
```

So `obj.get("time")` here returns `0.25` (not `None`) whenever `--time` is absent. That `0.25` propagates to `_run_with_provider`, which hits the `if reasoning_time is not None:` branch and maps it to `"low"`, injecting `-c model_reasoning_effort=low` into every Codex invocation — even when the user never passed `--time`.

This contradicts the PR's stated design: *"When `--time` is omitted, the env var is left untouched."* The env-var path in `cli.py` is correctly guarded by `if time is not None:`, but all five plumbed commands bypass that guard by forwarding `ctx.obj.get("time")` which is always a float.

The same issue applies to `pdd/commands/fix.py:156`, `pdd/commands/modify.py:266`, `pdd/commands/checkup.py:113`, and `pdd/commands/maintenance.py:208`.

A fix is to store the explicit-flag state separately and only forward a non-None value when the user actually typed `--time`:
```python
# in cli.py
ctx.obj["time"] = time  # keep None when --time was not provided
ctx.obj["time_default"] = time if time is not None else DEFAULT_TIME  # for LiteLLM steps
```
and downstream commands use `reasoning_time=ctx.obj.get("time")` (which is now `None` when omitted).

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: pdd/agentic_common.py
Line: 1190-1200

Comment:
**Notice fires in normal mode, not just verbose — and fires for every Codex default effort**

The comment says *"Always surface outside --quiet mode"*, but given the P1 above (default `0.25` → `"low"` always propagates), this message fires on every `pdd fix`/`pdd bug`/`pdd change`/`pdd checkup`/`pdd sync` invocation in normal mode, even when the user didn't touch `--time`. The PR description says *"logs once in verbose mode"*, but the guard is `not quiet`, so users who have never heard of `--time` will see this diagnostic in every run.

Once the `None`-propagation bug is fixed this becomes moot for the unintentional case; but the `not quiet` vs. `verbose` discrepancy with the PR description is worth aligning.

```suggestion
        if reasoning_effort and verbose and not quiet:
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: pdd/agentic_common.py
Line: 784-787

Comment:
**Docstring parameter name mismatch** — the docstring here says `time:` but the parameter is `reasoning_time`. Same issue in `_run_with_provider` (line 1116). IDEs and generated docs will show the wrong name; trivial to align.

```suggestion
        reasoning_time: Reasoning-allocation float in [0.0, 1.0] forwarded from the
            top-level ``pdd --time`` flag. When provided, overrides the
            ``PDD_REASONING_EFFORT`` env var for argv injection. ``None``
            means "fall back to env" so unplumbed call sites keep working.
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "test: accept additive reasoning_time kwa..." | Re-trigger Greptile}

[greptile-apps]

reasoning_time is never None for plumbed callers — default always injects low effort

ctx.obj["time"] is unconditionally set in cli.py:

ctx.obj["time"] = time if time is not None else DEFAULT_TIME  # always 0.25 when --time omitted

So obj.get("time") here returns 0.25 (not None) whenever --time is absent. That 0.25 propagates to _run_with_provider, which hits the if reasoning_time is not None: branch and maps it to "low", injecting -c model_reasoning_effort=low into every Codex invocation — even when the user never passed --time.

This contradicts the PR's stated design: "When --time is omitted, the env var is left untouched." The env-var path in cli.py is correctly guarded by if time is not None:, but all five plumbed commands bypass that guard by forwarding ctx.obj.get("time") which is always a float.

The same issue applies to pdd/commands/fix.py:156, pdd/commands/modify.py:266, pdd/commands/checkup.py:113, and pdd/commands/maintenance.py:208.

A fix is to store the explicit-flag state separately and only forward a non-None value when the user actually typed --time:

# in cli.py
ctx.obj["time"] = time  # keep None when --time was not provided
ctx.obj["time_default"] = time if time is not None else DEFAULT_TIME  # for LiteLLM steps

and downstream commands use reasoning_time=ctx.obj.get("time") (which is now None when omitted).

Prompt To Fix With AI

This is a comment left during a code review.
Path: pdd/commands/analysis.py
Line: 247

Comment:
**`reasoning_time` is never `None` for plumbed callers — default always injects `low` effort**

`ctx.obj["time"]` is unconditionally set in `cli.py`:
```python
ctx.obj["time"] = time if time is not None else DEFAULT_TIME  # always 0.25 when --time omitted
```

So `obj.get("time")` here returns `0.25` (not `None`) whenever `--time` is absent. That `0.25` propagates to `_run_with_provider`, which hits the `if reasoning_time is not None:` branch and maps it to `"low"`, injecting `-c model_reasoning_effort=low` into every Codex invocation — even when the user never passed `--time`.

This contradicts the PR's stated design: *"When `--time` is omitted, the env var is left untouched."* The env-var path in `cli.py` is correctly guarded by `if time is not None:`, but all five plumbed commands bypass that guard by forwarding `ctx.obj.get("time")` which is always a float.

The same issue applies to `pdd/commands/fix.py:156`, `pdd/commands/modify.py:266`, `pdd/commands/checkup.py:113`, and `pdd/commands/maintenance.py:208`.

A fix is to store the explicit-flag state separately and only forward a non-None value when the user actually typed `--time`:
```python
# in cli.py
ctx.obj["time"] = time  # keep None when --time was not provided
ctx.obj["time_default"] = time if time is not None else DEFAULT_TIME  # for LiteLLM steps
```
and downstream commands use `reasoning_time=ctx.obj.get("time")` (which is now `None` when omitted).

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Notice fires in normal mode, not just verbose — and fires for every Codex default effort

The comment says "Always surface outside --quiet mode", but given the P1 above (default 0.25 → "low" always propagates), this message fires on every pdd fix/pdd bug/pdd change/pdd checkup/pdd sync invocation in normal mode, even when the user didn't touch --time. The PR description says "logs once in verbose mode", but the guard is not quiet, so users who have never heard of --time will see this diagnostic in every run.

Once the None-propagation bug is fixed this becomes moot for the unintentional case; but the not quiet vs. verbose discrepancy with the PR description is worth aligning.

Suggested change

	if reasoning_effort and not quiet:
	# Always surface outside --quiet mode — silently dropping the user's
	# reasoning signal is a support-ticket generator. The Claude Code CLI
	# has no --reasoning-effort flag today, so clarify that the effort
	# applies to LiteLLM-invoked steps (analysis/verification) but not
	# to this code-writing subprocess.
	console.print(
	f"[dim]PDD_REASONING_EFFORT={reasoning_effort} requested, but Claude Code CLI "
	"has no reasoning-effort flag; applies to llm_invoke steps only, "
	"not this subprocess.[/dim]"
	)
	if reasoning_effort and verbose and not quiet:

Prompt To Fix With AI

This is a comment left during a code review.
Path: pdd/agentic_common.py
Line: 1190-1200

Comment:
**Notice fires in normal mode, not just verbose — and fires for every Codex default effort**

The comment says *"Always surface outside --quiet mode"*, but given the P1 above (default `0.25` → `"low"` always propagates), this message fires on every `pdd fix`/`pdd bug`/`pdd change`/`pdd checkup`/`pdd sync` invocation in normal mode, even when the user didn't touch `--time`. The PR description says *"logs once in verbose mode"*, but the guard is `not quiet`, so users who have never heard of `--time` will see this diagnostic in every run.

Once the `None`-propagation bug is fixed this becomes moot for the unintentional case; but the `not quiet` vs. `verbose` discrepancy with the PR description is worth aligning.

```suggestion
        if reasoning_effort and verbose and not quiet:
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Docstring parameter name mismatch — the docstring here says time: but the parameter is reasoning_time. Same issue in _run_with_provider (line 1116). IDEs and generated docs will show the wrong name; trivial to align.

Suggested change

	``PDD_REASONING_EFFORT`` env var for argv injection. ``None``
	means "fall back to env" so unplumbed call sites keep working.
	Returns:
	reasoning_time: Reasoning-allocation float in [0.0, 1.0] forwarded from the
	top-level ``pdd --time`` flag. When provided, overrides the
	``PDD_REASONING_EFFORT`` env var for argv injection. ``None``
	means "fall back to env" so unplumbed call sites keep working.

Prompt To Fix With AI

This is a comment left during a code review.
Path: pdd/agentic_common.py
Line: 784-787

Comment:
**Docstring parameter name mismatch** — the docstring here says `time:` but the parameter is `reasoning_time`. Same issue in `_run_with_provider` (line 1116). IDEs and generated docs will show the wrong name; trivial to align.

```suggestion
        reasoning_time: Reasoning-allocation float in [0.0, 1.0] forwarded from the
            top-level ``pdd --time`` flag. When provided, overrides the
            ``PDD_REASONING_EFFORT`` env var for argv injection. ``None``
            means "fall back to env" so unplumbed call sites keep working.
```

How can I resolve this? If you propose a fix, please make it concise.

[Serhan-Asad]

The Unit Tests failures here are pre-existing on main — same 10 tests fail on the latest main runs (02a5e5b7eb, run #24874428346). Reproducible across the last 3 main runs. None of the failures touch cli.py, agentic_common.py, reasoning.py, or any file this PR modifies. They're guard tests for missing scripts (scripts/ci_detect_changed_modules.py, utils/mcp/prompts/) and prompt-drift assertions for behaviors not in this PR's scope.

Happy to merge as-is, or wait if you want main green first.