taskchef 7.27.2 → 7.28.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.2",
+  "version": "7.28.1",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -162,6 +162,16 @@ Use $taskchef-executor to execute and report this delegated TaskChef assignment.
 <!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 ```
 
+### Model roles
+
+TaskChef can apply personal Planner, Implementer, and Reviewer model preferences
+from `~/.codex/agents/`. Planning-only tasks use Planner, while coding tasks and
+single tasks that plan and then execute use Implementer throughout. To apply
+both models, finish a Planner task that saves its plan, then create a separate
+Implementer task using that plan. Reviewer preferences apply when a workflow
+explicitly starts a review subagent. Explicit per-task model choices take
+precedence, and changes affect only tasks created afterward.
+
 ## Work with and report executors
 
 Open an executor as an ordinary Codex task. Each executor reports `working`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.2",
+  "version": "7.28.1",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -37,6 +37,7 @@
     "docs/images/reported-work-duration-mobile.jpg",
     "index.js",
     "mcp",
+    "scripts/roles",
     "scripts/benchmark-dispatch-prepare.js",
     "scripts/e2e-benchmark.js",
     "src",

package/scripts/roles/resolve_roles.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Read native Codex agent preferences without applying their instruction layers.
+
+Requires Python 3.11+. Standalone, standard library only. TaskChef packages an
+identical copy; neither installation imports the other at runtime.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tomllib
+
+ROLES = ('planner', 'implementer', 'reviewer')
+EFFORTS = ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra')
+
+
+def read_layer(directory):
+    found = {}
+    problems = []
+    try:
+        with os.scandir(directory) as entries:
+            files = sorted(Path(entry.path) for entry in entries if entry.name.endswith('.toml'))
+        for file in files:
+            try:
+                if file.stat().st_size > 65536:
+                    raise ValueError('profile exceeds 64 KiB')
+                with file.open('rb') as stream:
+                    data = tomllib.load(stream)
+                name = data.get('name')
+                if name not in ROLES:
+                    if file.stem in ROLES:
+                        raise ValueError('name must match the role filename')
+                    continue
+                errors = []
+                for field in ('description', 'developer_instructions'):
+                    if not isinstance(data.get(field), str) or not data[field].strip():
+                        errors.append(f'{field} must be a nonempty string')
+                model = data.get('model')
+                effort = data.get('model_reasoning_effort')
+                entry = {'source': str(file), 'model': model, 'effort': effort, 'problems': errors}
+                if name in found:
+                    entry['problems'].append('duplicate role name in the same directory')
+                found[name] = entry
+            except (OSError, ValueError) as error:
+                # Do not expose TOML lines, which can contain unrelated private data.
+                message = f'{file}: unreadable or malformed agent TOML ({type(error).__name__})'
+                problems.append(message)
+                if file.stem in ROLES:
+                    found[file.stem] = {'source': str(file), 'model': None, 'effort': None, 'problems': [message]}
+    except FileNotFoundError:
+        return found, problems
+    except OSError:
+        message = f'{directory}: cannot read agent directory'
+        problems.append(message)
+        found = {role: {'source': str(directory), 'model': None, 'effort': None, 'problems': [message]} for role in ROLES}
+    return found, problems
+
+
+def resolve(codex_home=None, explicit_model=None, explicit_effort=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    personal, problems = read_layer(home / 'agents')
+    catalog = None
+    catalog_source = str(home / 'models_cache.json')
+    try:
+        cache = json.loads(Path(catalog_source).read_text())
+        if not isinstance(cache, dict) or not isinstance(cache.get('models'), list):
+            raise ValueError('invalid catalog')
+        for model in cache['models']:
+            if not isinstance(model, dict) or not isinstance(model.get('slug'), str):
+                raise ValueError('invalid model entry')
+            levels = model.get('supported_reasoning_levels')
+            if not isinstance(levels, list) or any(not isinstance(level, dict) or not isinstance(level.get('effort'), str) for level in levels):
+                raise ValueError('invalid effort catalog')
+        catalog = {model['slug']: model for model in cache['models']}
+    except FileNotFoundError:
+        pass
+    except (OSError, ValueError, KeyError, TypeError):
+        problems.append('Local Codex model catalog is unreadable or malformed; validate availability with the current native tool.')
+    results = []
+    for role in ROLES:
+        entry = personal.get(role)
+        source = entry['source'] if entry else None
+        model = entry['model'] if entry else None
+        effort = entry['effort'] if entry else None
+        errors = list(entry['problems']) if entry else []
+        if explicit_model is not None:
+            model, effort = explicit_model, explicit_effort
+            effective_source = 'explicit user model choice'
+            errors = []
+        else:
+            effective_source = source
+            if explicit_effort is not None:
+                effort = explicit_effort
+        if model is not None and (not isinstance(model, str) or not model.strip() or len(model) > 256):
+            errors.append('model must be a nonempty string of at most 256 characters')
+        if effort is not None and effort not in EFFORTS:
+            errors.append('reasoning effort is unsupported')
+        status = 'invalid' if errors else 'configured' if (model is not None or effort is not None) else 'missing'
+        availability = 'not checked; native tool must validate before dispatch'
+        if model and not errors and catalog is not None:
+            if model not in catalog:
+                errors.append('model absent from local Codex catalog; confirm against the current native tool before dispatch')
+                status = 'unavailable'
+            else:
+                supported = [v.get('effort') for v in catalog[model].get('supported_reasoning_levels', []) if isinstance(v, dict)]
+                if effort and effort not in supported:
+                    errors.append('effort absent from local model catalog; confirm against the current native tool')
+                    status = 'unavailable'
+                availability = 'present in cached catalog; current native tool is authoritative'
+        overrides = {}
+        if status == 'configured':
+            if model is not None:
+                overrides['model'] = model
+            if effort is not None:
+                overrides['thinking'] = effort
+        results.append({'role': role, 'source': source, 'effectiveSource': effective_source,
+                        'model': model, 'effort': effort, 'status': status,
+                        'availability': availability, 'problems': errors,
+                        'taskOverrides': overrides,
+                        'subagentOverrides': {('reasoning_effort' if k == 'thinking' else k): v for k, v in overrides.items()},
+                        'fallback': 'inherit parent settings' if role == 'reviewer' else 'native new-task default (not guaranteed dispatcher inheritance)'})
+    model_options = [] if catalog is None else [
+        {'value': slug, 'label': entry.get('display_name') or slug,
+         'efforts': [level['effort'] for level in entry['supported_reasoning_levels']]}
+        for slug, entry in catalog.items() if entry.get('visibility') != 'hide'
+    ]
+    return {'roles': results, 'problems': problems, 'catalogSource': catalog_source if catalog is not None else None,
+            'modelOptions': model_options,
+            'precedence': 'explicit user model (and its explicit effort) > personal role > native defaults; explicit effort alone overrides role effort',
+            'scope': 'Model and effort only; agent instructions, tools, permissions, and other TOML keys are not applied by this adapter.'}
+
+
+def setup(role, model, effort, codex_home=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    existing, problems = read_layer(home / 'agents')
+    if role in existing or problems:
+        return {'created': False, 'role': role, 'problems': problems or ['existing role preserved'], 'source': existing.get(role, {}).get('source')}
+    if not model.strip() or len(model) > 256 or effort not in EFFORTS:
+        raise ValueError('invalid model or effort')
+    directory = home / 'agents'
+    directory.mkdir(parents=True, exist_ok=True)
+    target = directory / f'{role}.toml'
+    data = {'name': role, 'description': f'{role.capitalize()} model preferences',
+            'developer_instructions': f'Perform the assigned {role} work within the user\'s requested scope.',
+            'model': model, 'model_reasoning_effort': effort}
+    try:
+        with target.open('x') as stream:
+            stream.write(''.join(f'{key} = {json.dumps(value)}\n' for key, value in data.items()))
+    except FileExistsError:
+        return {'created': False, 'role': role, 'source': str(target), 'problems': ['existing file preserved']}
+    return {'created': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
+
+
+def multiline_state(line, state=None):
+    """Track TOML multiline strings without interpreting their contents as keys."""
+    index = 0
+    while index < len(line):
+        if state:
+            closing = line.find(state, index)
+            while closing >= 0 and state == '"""':
+                escapes = 0
+                cursor = closing - 1
+                while cursor >= 0 and line[cursor] == '\\':
+                    escapes += 1
+                    cursor -= 1
+                if escapes % 2 == 0:
+                    break
+                closing = line.find(state, closing + 3)
+            if closing < 0:
+                return state
+            state = None
+            index = closing + 3
+            continue
+        if line[index] == '#':
+            return None
+        if line.startswith('"""', index) or line.startswith("'''", index):
+            state = line[index:index + 3]
+            index += 3
+            continue
+        if line[index] in ('"', "'"):
+            quote = line[index]
+            index += 1
+            while index < len(line):
+                if line[index] == quote and (quote == "'" or index == 0 or line[index - 1] != '\\'):
+                    index += 1
+                    break
+                if quote == '"' and line[index] == '\\':
+                    index += 2
+                else:
+                    index += 1
+            continue
+        index += 1
+    return state
+
+
+def replace_top_level_preferences(content, model, effort):
+    replacements = {
+        'model': json.dumps(model),
+        'model_reasoning_effort': json.dumps(effort),
+    }
+    assignment = re.compile(
+        r'^(?P<prefix>\s*(?P<key>model|model_reasoning_effort|["\']model["\']|["\']model_reasoning_effort["\'])\s*=\s*).*$'
+    )
+    lines = content.splitlines(keepends=True)
+    state = None
+    boundary = len(lines)
+    found = set()
+    for index, line in enumerate(lines):
+        if state is None and re.match(r'^\s*\[', line):
+            boundary = index
+            break
+        if state is None:
+            body = line.rstrip('\r\n')
+            ending = line[len(body):]
+            match = assignment.match(body)
+            if match:
+                key = match.group('key').strip('"\'')
+                lines[index] = f"{match.group('prefix')}{replacements[key]}{ending}"
+                found.add(key)
+        state = multiline_state(line, state)
+    missing = [f'{key} = {value}\n' for key, value in replacements.items() if key not in found]
+    if missing:
+        prefix = '' if boundary == 0 or lines[boundary - 1].endswith(('\n', '\r')) else '\n'
+        lines[boundary:boundary] = [prefix + ''.join(missing)]
+    candidate = ''.join(lines)
+    expected = tomllib.loads(content)
+    expected['model'] = model
+    expected['model_reasoning_effort'] = effort
+    if tomllib.loads(candidate) != expected:
+        raise ValueError('agent TOML could not be updated without changing unrelated settings')
+    return candidate
+
+
+def update(role, model, effort, codex_home=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    resolved = resolve(codex_home=str(home))
+    options = {entry['value']: entry for entry in resolved['modelOptions']}
+    if model not in options or effort not in options[model]['efforts']:
+        raise ValueError('model or reasoning effort is unavailable')
+    existing, layer_problems = read_layer(home / 'agents')
+    role_entry = existing.get(role)
+    if layer_problems or (role_entry and role_entry['problems']):
+        raise ValueError('existing role configuration must be fixed before editing')
+    if role_entry is None:
+        return setup(role, model, effort, str(home))
+    target = Path(role_entry['source'])
+    agents = (home / 'agents').resolve()
+    if target.is_symlink() or target.resolve().parent != agents:
+        raise ValueError('role source is outside the personal agent directory')
+    content = replace_top_level_preferences(target.read_text(), model, effort)
+    temporary = target.with_name(f'.{target.name}.{os.getpid()}.tmp')
+    try:
+        temporary.write_text(content)
+        os.chmod(temporary, target.stat().st_mode & 0o777)
+        os.replace(temporary, target)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+    return {'updated': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--codex-home')
+    parser.add_argument('--role', choices=ROLES)
+    parser.add_argument('--model')
+    parser.add_argument('--effort')
+    parser.add_argument('--setup', action='store_true')
+    parser.add_argument('--update', action='store_true')
+    args = parser.parse_args()
+    if args.setup and args.update:
+        parser.error('--setup and --update are mutually exclusive')
+    if args.setup:
+        if not (args.role and args.model and args.effort):
+            parser.error('--setup requires --role, --model, and --effort')
+        result = setup(args.role, args.model, args.effort, args.codex_home)
+    elif args.update:
+        if not (args.role and args.model and args.effort):
+            parser.error('--update requires --role, --model, and --effort')
+        result = update(args.role, args.model, args.effort, args.codex_home)
+    else:
+        result = resolve(args.codex_home, args.model, args.effort)
+        if args.role:
+            result['roles'] = [r for r in result['roles'] if r['role'] == args.role]
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/skills/taskchef-bootstrap/SKILL.md

@@ -56,3 +56,29 @@ For adding, importing, removing, listing, or reindexing projects, read
 [project index](references/project-index.md). Preserve exact canonical local
 Codex project identity and existing curated entries; opening a folder is not
 proof of registration. Completion requires verifying the intended index entry.
+
+## Optional model roles
+
+Offer planner, implementer, and reviewer profiles during setup. Model and effort
+preferences belong in user configuration, never defaults hard-coded in skills.
+If the user provides values, configure them without asking again. Otherwise
+explain the optional profiles and retain native defaults until values are chosen.
+
+Run `python3 <plugin-root>/scripts/roles/resolve_roles.py` to preview personal
+roles. Python 3.11+ is required for this optional helper. Create each requested
+missing profile with:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --setup --role <role> --model <requested-model> --effort <requested-effort>
+```
+
+This authorized role setup may create `$CODEX_HOME/agents/<role>.toml` (default
+`~/.codex/agents/`) outside the dispatcher workspace. Existing definitions,
+including custom filenames, are preserved. Report conflicts and diagnostics;
+never overwrite a custom role. Re-run the preview and check model/effort against
+the available native interface. Missing roles are optional: TaskChef omits
+new-task overrides; reviewers inherit parent settings. Native new-task defaults
+are not guaranteed dispatcher inheritance. Read the delegate's
+[role resolution](../taskchef-delegate/references/model-roles.md) for precedence
+and adapter limits. Open the dashboard's `/#settings` preview to show the
+configured sources, requested effective settings, fallback, and problems.

package/skills/taskchef-delegate/SKILL.md

@@ -49,6 +49,13 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 3. Route against configured project `name`, `description`, and canonical
    `githubRepos`; use `path` only as checkout identity. Require exactly one
    match and an exact native-project path. Ask instead of guessing.
+   Select `planner` for a requested planning assignment and `implementer` for
+   coding work. Use the personal `modelRoles` from preparation;
+   resolve explicit user choices and follow [model roles](references/model-roles.md).
+   Small coding changes need no separate planning task. For a planning/coding
+   split, the saved plan is the handoff to a separately requested implementation
+   assignment; do not switch models during a turn or coordinate phases automatically.
+   Resolve configuration problems before recording the task.
 4. Build each executor instruction in this exact shape:
 
    - Begin with the actual assignment on the first line and keep its complete

package/skills/taskchef-delegate/references/model-roles.md

@@ -0,0 +1,52 @@
+# Dispatch model roles
+
+Preparation includes personal model previews. Role preferences use native Codex
+agent TOML under `$CODEX_HOME/agents/` (default `~/.codex/agents/`); they are
+optional. The resolver requires Python 3.11+.
+
+Select `planner` for a planning assignment or `implementer` for coding. Pass
+its `taskOverrides` as native `model` and `thinking` arguments only after checking
+those values against the current create-task tool's supported model/effort
+choices. A missing role means omit both arguments and use the native new-task
+default. This is not guaranteed to inherit the dispatcher's model.
+
+Explicit user model choices take precedence over the personal role and native
+defaults. An explicit model without explicit effort omits effort and uses the native
+interface's omission behavior; do not mix in a different role's effort or claim
+a specific effective effort without evidence. Explicit effort
+alone replaces the resolved role effort. To resolve explicit choices, or recheck a preview after configuration
+changes, run:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --role implementer --model <user-model> --effort <user-effort>
+```
+
+Omit flags the user did not specify. Resolve the plugin root from this skill's
+real path, two parents above the skill directory. Do not substitute dispatcher
+paths for the target project or infer model names from skill prose.
+
+Report malformed profiles, duplicate names, unavailable models/efforts, and
+resolver failures. Do not quietly fall back and claim preferences were honored.
+The local model catalog is advisory: explain if a current native tool disproves
+its stale warning. Otherwise resolve the problem or obtain a valid explicit
+choice before task creation. Native creation failures retain normal TaskChef
+failure reporting. A preparation without role fields supports historical
+installations: check role files before deciding that no preferences exist.
+
+Only model and effort are adapted. The native agent file's instructions, tools,
+permissions, and other settings are not applied by create-task arguments. A
+role name in a title is not a native role selector. If the native interface adds
+a role selector, use it only with verified effective settings.
+
+For a plan-to-implementation handoff, a planner assignment can save
+`plans/addition.md` describing a pure addition function and the acceptance
+example `2 + 3 = 5`. A later implementer assignment reads that exact plan,
+implements the function, runs the example, and uses fresh reviewer subagents.
+The dispatcher returns after each creation; it does not wait for or launch
+subsequent phases automatically. A small addition change can instead go
+straight to the implementer.
+
+A single assignment that asks to plan and then execute is an implementation
+assignment. Use the implementer model for that whole task; do not switch models
+mid-turn. To apply both configured roles, dispatch a planner task first, wait
+for its saved plan, then dispatch a separate implementer task using that plan.