opencode-codeops 1.9.0 → 1.10.1

package/scripts/codeops_effort.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Record and clear the opt-in reasoning-effort level for a CodeOps session run.
+
+The skills call this helper when a user passes `--auto-effort`. It writes one
+small JSON file inside the session's CodeOps temp directory; the plugin reads
+that file on every request and applies the level. The command fails closed:
+an invalid level or a directory outside the CodeOps temp root exits with
+status 2 and writes nothing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+#: The only levels a session flag may record.
+EFFORT_LEVELS = ("low", "medium", "high", "max")
+
+#: Name of the state file the plugin reads.
+STATE_FILE_NAME = "reasoning-effort.json"
+
+
+def codeops_tmp_root() -> Path:
+    """Return the CodeOps-owned temp root for the active temp directory.
+
+    The root mirrors the layout `bin/lib/tmp-hygiene.mjs` owns, so the helper
+    and the plugin resolve the same per-session directory.
+
+    Returns:
+        Resolved path of the CodeOps temp root.
+    """
+    return Path(tempfile.gettempdir()).resolve() / "opencode" / "codeops"
+
+
+def resolve_session_dir(raw_dir: str) -> Path | None:
+    """Validate a session directory argument against the CodeOps temp root.
+
+    A directory is accepted only when it exists, resolves strictly inside the
+    CodeOps temp root, and is not the root itself. Symlinks are resolved, so a
+    link that points outside the root is rejected.
+
+    Args:
+        raw_dir: The `--dir` argument as provided by the caller.
+
+    Returns:
+        The resolved session directory, or None when it is not acceptable.
+    """
+    try:
+        resolved = Path(raw_dir).resolve(strict=True)
+    except (OSError, RuntimeError):
+        # RuntimeError covers a symlink loop on Python 3.12, which the
+        # filesystem reports as ELOOP rather than a plain OSError.
+        return None
+    root = codeops_tmp_root()
+    if resolved == root or root not in resolved.parents:
+        return None
+    if not resolved.is_dir():
+        return None
+    return resolved
+
+
+def state_path(session_dir: Path) -> Path:
+    """Return the state-file path inside a validated session directory.
+
+    Args:
+        session_dir: A directory accepted by `resolve_session_dir`.
+
+    Returns:
+        Path of the reasoning-effort state file.
+    """
+    return session_dir / STATE_FILE_NAME
+
+
+def set_level(session_dir: Path, level: str) -> int:
+    """Write the session level atomically and report it.
+
+    The payload is written to a temporary file in the same directory and then
+    moved over the final name with `os.replace`, so a reader never observes a
+    partially written file.
+
+    Args:
+        session_dir: A validated session directory.
+        level: One of `EFFORT_LEVELS`.
+
+    Returns:
+        Process exit code 0.
+    """
+    payload = {
+        "schema": 1,
+        "reasoning": level,
+        "setAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    }
+    path = state_path(session_dir)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f"{STATE_FILE_NAME}.", suffix=".tmp", dir=session_dir
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, separators=(",", ":"), sort_keys=True)
+            handle.write("\n")
+        os.replace(temporary_name, path)
+    except OSError:
+        try:
+            os.unlink(temporary_name)
+        except OSError:
+            pass
+        print("Error: could not write the reasoning-effort state file.", file=sys.stderr)
+        return 2
+    print(f"Reasoning effort set: {level} for this session run.")
+    return 0
+
+
+def clear_level(session_dir: Path) -> int:
+    """Remove the session level when present and report the cleanup.
+
+    Args:
+        session_dir: A validated session directory.
+
+    Returns:
+        Process exit code 0.
+    """
+    try:
+        state_path(session_dir).unlink()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        print("Error: could not remove the reasoning-effort state file.", file=sys.stderr)
+        return 2
+    print("Reasoning effort cleared.")
+    return 0
+
+
+def show_status(session_dir: Path) -> int:
+    """Print the stored session level, or the empty-state message.
+
+    Args:
+        session_dir: A validated session directory.
+
+    Returns:
+        Process exit code 0.
+    """
+    level = None
+    try:
+        payload = json.loads(state_path(session_dir).read_text(encoding="utf-8"))
+        if (
+            isinstance(payload, dict)
+            and payload.get("schema") == 1
+            and payload.get("reasoning") in EFFORT_LEVELS
+        ):
+            level = payload["reasoning"]
+    except (OSError, json.JSONDecodeError):
+        level = None
+    if level is None:
+        print("No session reasoning effort set.")
+    else:
+        print(f"Session reasoning effort: {level}")
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse the command-line arguments.
+
+    Returns:
+        The parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    set_parser = sub.add_parser("set", help="record a session reasoning level")
+    set_parser.add_argument("--dir", required=True, help="session temp directory")
+    set_parser.add_argument("--reasoning", required=True, help="level to record")
+
+    clear_parser = sub.add_parser("clear", help="remove the session reasoning level")
+    clear_parser.add_argument("--dir", required=True, help="session temp directory")
+
+    status_parser = sub.add_parser("status", help="print the session reasoning level")
+    status_parser.add_argument("--dir", required=True, help="session temp directory")
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Run the requested command.
+
+    Returns:
+        Process exit code: 0 on success, 2 on invalid input.
+    """
+    args = parse_args()
+    session_dir = resolve_session_dir(args.dir)
+    if session_dir is None:
+        print(
+            "Error: --dir must be an existing session directory inside the CodeOps temp root.",
+            file=sys.stderr,
+        )
+        return 2
+    if args.command == "set":
+        if args.reasoning not in EFFORT_LEVELS:
+            print(
+                "Error: --reasoning must be one of: " + ", ".join(EFFORT_LEVELS) + ".",
+                file=sys.stderr,
+            )
+            return 2
+        return set_level(session_dir, args.reasoning)
+    if args.command == "clear":
+        return clear_level(session_dir)
+    return show_status(session_dir)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/exec-plan/SKILL.md

@@ -36,6 +36,18 @@ do not report or implement optional additions raised during execution or review.
 Exploration may create `SE-*` proposals, but only the user may choose `Keep` and authorize a plan
 update.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means each phase's `Reasoning:` level is printed as a suggestion only, more than one
+or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. A bare
+flag follows each phase's suggestion; `--auto-effort=<level>` forces that level for the whole run,
+including every dispatch marker composed during it. The run clears the level before its final
+summary.
+
 Execute the implementation plan at `plans/$ARGUMENTS/99-execution-plan.md`. The first
 argument is the feature name; an optional flag selects the commit mode.
 

package/skills/exec-plan/execution-protocol.md

@@ -70,6 +70,10 @@ scope baseline; missing mode context fails closed to strict scope.
 When opt-in outcome metrics are enabled, record only a content-free execution-stage event through
 `codeops_outcomes.py`; metrics never gate execution.
 
+When the phase header carries `> **Reasoning**: <level> — <reason>`, record it as the phase's
+advisory level for dispatch markers, inline reporting, and applied-level reporting. It is a
+suggestion: no gate reads it, and its absence means "inherit".
+
 **Spec-author dispatch (profile-gated).** Tasks marked `[spec-author]` dispatch the
 spec-test-author agent — packet per `_shared/quality-profile.md` — BEFORE any implementation
 task of that phase, and the red phase is confirmed from its report. A spec test that cannot be
@@ -300,12 +304,46 @@ receives nothing else and must not need anything else:
 - the scope mode (`strict` or `explore`) and confirmed product scope baseline; missing or invalid
   scope context fails closed to strict mode. Missing or invalid original-goal or smallest-design
   context blocks dispatch;
-- the target file paths and the project's verify command.
+- the target file paths and the project's verify command;
+- the phase's reasoning marker line (`[codeops-effort: <level>]`), resolved from the run's forced
+  `--auto-effort=<level>` level, else the phase's `Reasoning:` suggestion; omitted when neither
+  exists.
 
 Excerpting owned content into a packet is the intended retrieval mechanism, not restatement. The
 quoted AR/ST/spec content is context for the executor's *understanding* — it must not surface as a
 citation in shipped code (the executor carries the same doc-standard ban and self-check).
 
+**Reasoning marker.** Every dispatched unit — executor, reviewer, auditor, spec-test author,
+specialist, or scout — receives one standalone marker line in its packet:
+
+```text
+[codeops-effort: medium]
+```
+
+Place it immediately after the `[codeops-dispatch …]` header for quality agents, or as the first
+line for packets without a header. When neither the forced run level nor the phase suggestion
+exists, add no marker: routing policy still applies, otherwise the child inherits the parent
+variant. The marker is packet context; it never appears in shipped code comments. The
+complexity-gate design challenger is excluded because its independence contract forbids extra
+packet shaping.
+
+**Applied-level reporting.** For every dispatch, report the level and its source in the dispatch
+commentary, for example `Dispatch: executor — reasoning: medium (phase suggestion)`,
+`— reasoning: high (routing default)`, or `— inherited`. Reporting is observational; it never
+gates a dispatch.
+
+**Inline phases.** When a phase runs inline (the default):
+
+1. Print `Suggested reasoning: <level> — <reason>` before the phase's first task when the phase
+   header carries the line.
+2. Without `--auto-effort`, change nothing else — the session keeps its own variant.
+3. With `--auto-effort`, set the session level for the phase through
+   `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_effort.py" set --dir "$CODEOPS_TMPDIR" --reasoning <level>`
+   and update it when the next phase's suggestion differs; with `--auto-effort=<level>`, set that
+   level once and keep it for the whole run. A phase without a `Reasoning:` line leaves the
+   session level unchanged.
+4. When `$CODEOPS_TMPDIR` is empty or the helper fails, print an advise-only note and continue.
+
 **Division of labor.** The PARENT — never the executor — updates `99-execution-plan.md`
 (two-stage marks), the Progress header, and the roadmap. The executor implements task-by-task,
 runs verify per the Verify-output capture rule, and reports per task. Mark `[~]` as the executor
@@ -404,8 +442,10 @@ otherwise still `[~]` — with the progress counter and Last Updated stamp curre
 2. **🚨 First: update `99-execution-plan.md`** with ALL completed tasks (before anything else).
 3. Run the verify command (output captured per the Verify-output capture rule).
 4. Handle the commit per the active commit mode (see [commit-modes.md](commit-modes.md)).
-5. Report the session summary (must include `Execution Plan Updated: ✅`).
-6. **Cleanup:** delete every temporary artifact this session created — verify logs under
+5. If this run set a session level through `--auto-effort`, clear it before the summary:
+   `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_effort.py" clear --dir "$CODEOPS_TMPDIR"`.
+6. Report the session summary (must include `Execution Plan Updated: ✅`).
+7. **Cleanup:** delete every temporary artifact this session created — verify logs under
    `$CODEOPS_TMPDIR`, scratch directories, temporary diffs — per
    `_shared/workspace-hygiene.md`, and report `Cleanup: done` or name what was kept and why.
 

package/skills/grill-me/SKILL.md

@@ -21,6 +21,16 @@ implementation work begins.
 
 > **CodeOps Artifact Schema**: 1
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Core Directive
 
 > **Interview the user relentlessly about every aspect of the topic until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.**

package/skills/make-plan/SKILL.md

@@ -24,6 +24,16 @@ If `$ARGUMENTS` contains exactly one exact standalone `--explore-scope` token be
 do not report or plan optional additions. Exploration may propose `SE-*` items but
 never accepts them; only the user may choose `Keep`.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Plan readiness proof
 
 A plan is not ready merely because its documents exist. Before presenting it as executable,
@@ -106,6 +116,7 @@ Mini-plan shape:
 
 > **Type**: Task (lightweight) · **Feature**: search · **CodeOps Artifact Schema**: 1
 > **Progress**: 0/3 tasks (0%)
+> **Reasoning**: medium — bounded UI change reusing existing patterns
 
 ## Objective
 Debounce the search box to 300ms to cut redundant queries.
@@ -121,6 +132,12 @@ shared debounce subsystem.
 **Verify**: [project verify command]
 ```
 
+Every phase and every task mini-plan carries the same advisory
+`> **Reasoning**: <level> — <reason>` line. Derive the level from the signals the plan already
+records, using [../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Plan
+suggestion derivation, and keep the reason a short plain-language phrase. The line is a
+suggestion: no gate reads it, deleting it is valid, and its absence means "inherit".
+
 Everything below is the **full feature** pipeline; skip it for tasks.
 
 ## Project configuration

package/skills/make-plan/templates.md

@@ -458,6 +458,8 @@ task-size criteria in [quality-checklist.md](quality-checklist.md))
 > committed, staged, unstaged, and untracked phase-start state)_
 > **Lenses**: [add-on lenses — include this line only when the target repo carries a quality
 > profile; informational: activation stays profile-driven]
+> **Reasoning**: [advisory level — `low`, `medium`, `high`, or `max`, with a one-line reason;
+> derivation in `../../_shared/reasoning-effort.md` §Plan suggestion derivation]
 
 ### Step 1.1: [Step Objective]
 

package/skills/make-requirements/SKILL.md

@@ -27,6 +27,16 @@ requirements decisions under that policy and propagate its downward-only context
 invoked supported children; an unsupported child fails closed. This mode does not grant action permission or scope expansion. **Normal mode:** without the exact token, every material choice
 still requires an explicit user decision; historical delegated records must not infer delegated authority.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Transform a rough project idea into a structured, complete set of formal
 **requirement documents (RDs)**. This skill is upstream of, and independent
 from, the make-plan skill — neither requires the other.

package/skills/preflight/SKILL.md

@@ -33,6 +33,16 @@ If `$ARGUMENTS` contains exactly one exact standalone `--explore-scope` token be
 do not report optional additions as findings or suggestions. Exploration records them
 as separate `SE-*` proposals; finding resolution never chooses `Keep`.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`, or `max` with `--thorough`) is printed
+as a suggestion only, more than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Run a rigorous quality audit of the artifact named in `$ARGUMENTS`, **grounded in the actual
 codebase**. Find every issue, ambiguity, contradiction, gap, and risk; verify every claim and
 assumption against the real code; present each finding with options + a recommendation; iterate

package/skills/retro-requirements/SKILL.md

@@ -20,6 +20,16 @@ description: >-
 
 > **CodeOps Artifact Schema**: 1
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Analyze an existing codebase — any language, any framework — and produce a
 structured **reconstruction brief** that can be fed to the make-requirements
 skill to generate formal requirement documents capable of rebuilding the entire

package/skills/setup-routing/SKILL.md

@@ -50,6 +50,8 @@ Present:
 
 - detected domains and concrete evidence;
 - phase tag → capability/effort policy;
+- reasoning-effort defaults per role when risk signals justify them (see
+  [routing.md](routing.md) §Reasoning effort policy);
 - required specialist reviewers;
 - proposed concurrency limit;
 - whether custom TOML agents add value over dynamic packets; and

package/skills/setup-routing/routing.md

@@ -27,7 +27,7 @@ CodeOps routing lives under the optional `routing` and `quality` fields in `code
 
 Allowed effort values follow the active OpenCode release. Prefer `medium` for bounded reconnaissance, `high` for correctness/security review, and higher supported levels only for genuinely demanding semantic or architectural work.
 
-An optional per-role `reasoning` field sets the provider reasoning-effort passthrough (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Generated project specialists default to `max` through their brief or the embedded `reasoningEffort`; a routing value wins over the brief. A model that rejects the option is overridden here — there is no automatic provider-capability detection.
+An optional per-role `reasoning` field sets the provider reasoning-effort passthrough (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Generated project specialists default to `max` through their brief or the embedded `reasoningEffort`; a routing value wins over the brief and is embedded without provider-capability detection. At runtime the plugin applies a level only when the active model exposes a matching variant; an unsupported value leaves the request unchanged (see the policy below).
 
 ```json
 "roles": {
@@ -35,6 +35,21 @@ An optional per-role `reasoning` field sets the provider reasoning-effort passth
 }
 ```
 
+## Reasoning effort policy
+
+A role's `reasoning` entry is a project default, not the only source. The runtime resolution
+order is `dispatch marker > session auto-effort > routing role default > inherit parent variant`
+(see [../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md)). A dispatch marker
+comes from an execution plan's per-phase suggestion; a session level comes from an explicit
+`--auto-effort` run. Both override the routing default for their scope, and routing applies only
+when a role entry exists — with no entry the child inherits the parent variant.
+
+The suggestion vocabulary is `low`, `medium`, `high`, and `max`, while the routing field accepts
+the wider provider enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). The deepseek
+flash model exposes `low`/`medium`/`high`/`max`; prefer `low` for mechanical work, `medium` for
+bounded implementation, `high` for planning and review, and `max` only for adversarial analysis.
+An unsupported value is skipped at runtime, so a routing entry never produces a provider error.
+
 Model pins are optional per role. When omitted, OpenCode resolves the model from the explicit spawn, project defaults, and parent session. A missing pin must never block the workflow.
 
 Reviewer selection is driven by risk tags:

package/skills/upgrade-plan/SKILL.md

@@ -7,6 +7,16 @@ description: Upgrade an existing CodeOps requirements set, specification, plan,
 
 The current CodeOps artifact schema is `1`. Historical Claude CodeOps `3.x` stamps describe the producing skill release, not this schema. Treat them as legacy input requiring assessment, not as numeric predecessors of schema 1.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Scope
 
 Upgrade content and structure in place. Layout moves belong to `setup-codeops`. Never combine a layout migration and semantic/schema upgrade into one irreversible operation.