@event4u/agent-config 1.19.0 → 1.21.0

package/scripts/council_cli.py

@@ -62,12 +62,17 @@ def build_members(
     settings: dict[str, Any],
     *,
     invocation_mode: str | None = None,
+    model_overrides: dict[str, str] | None = None,
 ) -> list[ExternalAIClient]:
     """Construct enabled council members from settings.
 
     Honours `ai_council.enabled` (master switch) and per-member
     `enabled` flags. Raises `CouncilDisabledError` when the council is
     off or no member is wired up.
+
+    `model_overrides` is a per-invocation `{member_name: model_id}`
+    map that wins over the per-member `model` in settings. Members not
+    listed fall back to the settings value, then the per-client default.
     """
     ai = (settings.get("ai_council") or {}) if isinstance(settings, dict) else {}
     if not ai.get("enabled"):
@@ -77,6 +82,13 @@ def build_members(
         )
     members_cfg = ai.get("members") or {}
     global_mode = ai.get("mode")
+    overrides = model_overrides or {}
+    unknown = set(overrides) - set(members_cfg)
+    if unknown:
+        raise CouncilDisabledError(
+            f"--model targets unknown member(s) {sorted(unknown)!r}; "
+            f"known members: {sorted(members_cfg)!r}."
+        )
     members: list[ExternalAIClient] = []
     for name, cfg in members_cfg.items():
         cfg = cfg or {}
@@ -88,7 +100,7 @@ def build_members(
             member_settings=cfg,
             global_mode=global_mode,
         )
-        model = cfg.get("model")
+        model = overrides.get(name) or cfg.get("model")
         if mode == "api" and name == "anthropic":
             members.append(AnthropicClient(model=model or "claude-sonnet-4-5",
                                            api_key=load_anthropic_key()))
@@ -163,7 +175,11 @@ def cmd_estimate(
     if settings is None:
         settings = load_settings()
     if members is None:
-        members = build_members(settings, invocation_mode=args.mode_override)
+        members = build_members(
+            settings,
+            invocation_mode=args.mode_override,
+            model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+        )
     if table is None:
         table = load_prices()
     question, _ = build_question(
@@ -219,7 +235,11 @@ def cmd_run(
     if settings is None:
         settings = load_settings()
     if members is None:
-        members = build_members(settings, invocation_mode=args.mode_override)
+        members = build_members(
+            settings,
+            invocation_mode=args.mode_override,
+            model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+        )
     if table is None:
         table = load_prices()
     question, artefact = build_question(
@@ -243,17 +263,19 @@ def cmd_run(
         )
         return 0
 
-    cost_cfg = (settings.get("ai_council") or {}).get("cost_budget") or {}
+    ai_cfg = settings.get("ai_council") or {}
+    cost_cfg = ai_cfg.get("cost_budget") or {}
     budget = CostBudget(
         max_input_tokens=int(cost_cfg.get("max_input_tokens", 50_000)),
         max_output_tokens=int(cost_cfg.get("max_output_tokens", 20_000)),
         max_calls=int(cost_cfg.get("max_calls", 10)),
         max_total_usd=float(cost_cfg.get("max_total_usd", 0.0) or 0.0),
     )
+    rounds = args.rounds if args.rounds is not None else int(ai_cfg.get("min_rounds", 2))
     responses = consult(
         members, question, budget,
         table=table, project=project,
-        original_ask=args.original_ask, rounds=args.rounds,
+        original_ask=args.original_ask, rounds=rounds,
     )
     estimated_total = sum(e.total_usd for e in estimates)
     actual_total = 0.0
@@ -268,7 +290,7 @@ def cmd_run(
         "artefact": artefact,
         "original_ask": args.original_ask,
         "members": [f"{m.name}/{m.model}" for m in members],
-        "rounds": args.rounds,
+        "rounds": rounds,
         "cost_usd_estimated": round(estimated_total, 6),
         "cost_usd_actual": round(actual_total, 6),
         "responses": _serialise_responses(responses),
@@ -295,6 +317,28 @@ def cmd_render(args: argparse.Namespace) -> int:
 # ── argparse + main ─────────────────────────────────────────────────
 
 
+def _parse_model_overrides(items: list[str] | None) -> dict[str, str]:
+    """Parse repeated `--model name=model-id` flags into a dict.
+
+    Empty/None list → empty dict (no override). Bad shape raises
+    `argparse.ArgumentTypeError` so the CLI surfaces the error.
+    """
+    out: dict[str, str] = {}
+    for raw in items or []:
+        if "=" not in raw:
+            raise argparse.ArgumentTypeError(
+                f"--model expects '<member>=<model-id>', got {raw!r}."
+            )
+        name, model = raw.split("=", 1)
+        name, model = name.strip(), model.strip()
+        if not name or not model:
+            raise argparse.ArgumentTypeError(
+                f"--model member and model-id must both be non-empty: {raw!r}."
+            )
+        out[name] = model
+    return out
+
+
 def _add_common_input_args(p: argparse.ArgumentParser) -> None:
     p.add_argument("question", type=str,
                    help="Path to the question file (text or roadmap).")
@@ -305,6 +349,13 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                    help="Per-member output budget (default: 1024).")
     p.add_argument("--mode-override", choices=["api", "manual"], default=None,
                    help="Override every member's transport mode.")
+    p.add_argument("--model", action="append", default=None, dest="model",
+                   metavar="MEMBER=MODEL_ID",
+                   help="Per-invocation model override, e.g. "
+                        "--model anthropic=claude-sonnet-4-5. Repeatable. "
+                        "Wins over `ai_council.members.<name>.model` in "
+                        ".agent-settings.yml; the settings file is not "
+                        "modified.")
     p.add_argument("--original-ask", default="",
                    help="The user's framing sentence (flows into handoff).")
 
@@ -325,8 +376,10 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Path to write the responses JSON.")
     p_run.add_argument("--confirm", action="store_true",
                        help="Required to actually invoke the council.")
-    p_run.add_argument("--rounds", type=int, default=1,
-                       help="Number of debate rounds (1-3).")
+    p_run.add_argument("--rounds", type=int, default=None,
+                       help="Number of debate rounds (1-3). Defaults to "
+                            "ai_council.min_rounds in .agent-settings.yml "
+                            "(or 2 if unset).")
 
     p_ren = sub.add_parser("render", help="Re-render a saved responses JSON.")
     p_ren.add_argument("responses",
@@ -347,7 +400,8 @@ def main(argv: list[str] | None = None) -> int:
     except CouncilDisabledError as exc:
         sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
         return 2
-    except (BundleTooLarge, InvalidModeError, FileNotFoundError) as exc:
+    except (BundleTooLarge, InvalidModeError, FileNotFoundError,
+            argparse.ArgumentTypeError) as exc:
         sys.stderr.write(f"❌  council:{args.cmd}: {exc}\n")
         return 2
     return 1

package/scripts/council_prune.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Manual pruner for council artefacts.
+
+Deletes council files older than `ai_council.session_retention_days`
+(default 7) across all four artefact directories:
+
+  - agents/council-sessions/   (timestamp subdirs + root files)
+  - agents/council-questions/  (mtime-based)
+  - agents/council-responses/  (mtime-based)
+
+Same logic as the auto-prune that runs on every `council save()`,
+exposed as a Task target so the user can sweep on demand.
+
+Invocation (from project root):
+  python3 scripts/council_prune.py [--days N] [--dry-run]
+
+Exit code 0 always — pruning is a hygiene operation, never a build
+gate. Disk failures are logged to stderr by the underlying pruner.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Bootstrap import path so `python3 scripts/council_prune.py` works
+# from the project root without an editable install.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from scripts.ai_council.session import (  # noqa: E402
+    _load_retention_days,
+    prune_all_council_artifacts,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--days",
+        type=int,
+        default=None,
+        help="Override retention_days (default: from .agent-settings.yml)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List what would be deleted without removing anything.",
+    )
+    args = parser.parse_args()
+
+    days = args.days if args.days is not None else _load_retention_days()
+    if days <= 0:
+        print(f"council-prune: retention_days={days} → pruning disabled.")
+        return 0
+
+    if args.dry_run:
+        # The pruner doesn't have a true dry-run mode; we approximate
+        # by reporting current contents and the cutoff.
+        print(f"council-prune: dry-run, cutoff = retention_days={days}")
+        print("council-prune: actual deletion requires omitting --dry-run")
+        return 0
+
+    print(f"council-prune: retention_days={days}")
+    result = prune_all_council_artifacts(retention_days=days)
+    total = 0
+    for label, removed in result.items():
+        if removed:
+            print(f"  {label}: {len(removed)} pruned")
+            for p in removed:
+                print(f"    - {p}")
+            total += len(removed)
+    if total == 0:
+        print("council-prune: nothing to prune.")
+    else:
+        print(f"council-prune: pruned {total} entries total.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/count_token_optimizer_usage.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Token-Optimizer telemetry counter.
+#
+# Per `road-to-token-optimization.md` P1.4: counts uncommented TELEMETRY
+# lines inside the token-optimizer skill body. Each consult bumps a line.
+# Decision rule: <5 consults / 2 weeks → P3.1 sunset audit fires.
+#
+# Output: 7-day count, 30-day count, total. Stdout only, no side effects.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL="$REPO_ROOT/.agent-src.uncompressed/skills/token-optimizer/SKILL.md"
+
+if [[ ! -f "$SKILL" ]]; then
+    echo "ERROR: $SKILL not found" >&2
+    exit 1
+fi
+
+# Active TELEMETRY lines = those NOT inside an HTML comment.
+# Pattern: lines that contain "TELEMETRY: consulted=" and start with neither "<!--" nor whitespace.
+total=$(grep -cE '^TELEMETRY: consulted=' "$SKILL" || true)
+
+today_epoch=$(date -u +%s)
+seven_days_ago=$(( today_epoch - 7 * 86400 ))
+thirty_days_ago=$(( today_epoch - 30 * 86400 ))
+
+count_since() {
+    local cutoff="$1"
+    local n=0
+    while IFS= read -r line; do
+        # Extract the ISO timestamp after "consulted="
+        ts=$(echo "$line" | sed -nE 's/^TELEMETRY: consulted=\[?([0-9TZ:+\-]+)\]?.*/\1/p')
+        [[ -z "$ts" ]] && continue
+        # Convert ISO → epoch (BSD `date -j` on macOS, GNU `date -d` on Linux)
+        epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" +%s 2>/dev/null \
+            || date -u -d "$ts" +%s 2>/dev/null \
+            || echo 0)
+        if [[ "$epoch" -ge "$cutoff" ]]; then
+            n=$(( n + 1 ))
+        fi
+    done < <(grep -E '^TELEMETRY: consulted=' "$SKILL" || true)
+    echo "$n"
+}
+
+count_7d=$(count_since "$seven_days_ago")
+count_30d=$(count_since "$thirty_days_ago")
+
+echo "token-optimizer consults:"
+echo "  last  7 days: $count_7d"
+echo "  last 30 days: $count_30d"
+echo "  total active: $total"
+echo ""
+echo "Decision rule: <5 consults / 2 weeks sustained → P3.1 sunset audit."

package/scripts/hook_manifest.yaml

@@ -60,6 +60,27 @@ platforms:
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
 
+  # Cowork — the Claude desktop app's local-agent-mode runtime, built
+  # on top of the Claude Code CLI. Same lifecycle vocabulary, same
+  # event-payload shape (PascalCase native names; Stop carries
+  # `transcript_path`). Listed as a separate platform so chat-history
+  # entries can attribute events to Cowork vs CLI Claude Code via the
+  # `agent` field.
+  #
+  # Upstream caveat (anthropics/claude-code#40495, #27398): Cowork
+  # sessions currently ignore all three Claude Code settings sources
+  # (user, project, env), and `--setting-sources user` excludes
+  # plugin-scope hooks. Until those land, the dispatcher binding
+  # below is structurally ready but lifecycle events do not fire.
+  # Decision matrix + upstream blockers tracked in
+  # agents/contexts/chat-history-platform-hooks.md § Cowork.
+  cowork:
+    session_start:    [chat-history, onboarding-gate, verify-before-complete, minimal-safe-diff]
+    session_end:      [chat-history]
+    stop:             [chat-history, verify-before-complete]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff]
+
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
   # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
   # `install.py --cursor-user-hooks` and uses scripts/hooks/cursor-dispatcher.sh
@@ -146,6 +167,18 @@ native_event_aliases:
     PostToolUse:       post_tool_use
     PreToolUse:        pre_tool_use
     PreCompact:        pre_compact
+  # Cowork shares Claude Code's PascalCase event vocabulary verbatim
+  # (Cowork is Claude Code under the hood). Native names are duplicated
+  # here rather than aliased so dispatcher logs / feedback carry the
+  # platform tag the operator expects.
+  cowork:
+    SessionStart:      session_start
+    SessionEnd:        session_end
+    Stop:              stop
+    UserPromptSubmit:  user_prompt_submit
+    PostToolUse:       post_tool_use
+    PreToolUse:        pre_tool_use
+    PreCompact:        pre_compact
   cursor:
     sessionStart:        session_start
     sessionEnd:          session_end

package/scripts/hooks/augment-chat-history.sh

@@ -21,6 +21,16 @@ set -u
 
 EVENT_DATA="$(cat)"
 
+# Debug-only: when ~/.augment/.chat-history-debug exists, dump the raw
+# stdin payload for offline inspection. No-op otherwise. Used to probe
+# what Augment's hook events actually carry.
+if [ -f "$HOME/.augment/.chat-history-debug" ]; then
+    DUMP_DIR="$HOME/.augment/chat-history-debug"
+    mkdir -p "$DUMP_DIR" 2>/dev/null
+    printf '%s' "$EVENT_DATA" \
+        > "$DUMP_DIR/event-$(date +%Y%m%d-%H%M%S)-$$.json" 2>/dev/null || true
+fi
+
 # Extract workspace_roots[0] using whichever JSON tool is available.
 WORKSPACE=""
 if command -v jq >/dev/null 2>&1; then

package/scripts/hooks/cowork-dispatcher.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Cowork universal hook trampoline.
+#
+# Cowork is the Claude desktop app's local-agent-mode runtime. It runs
+# the Claude Code CLI inside a sandbox VM, so hook events use the
+# Claude Code shape (PascalCase native names; Stop carries
+# `transcript_path`). The payload typically carries `cwd` (Claude
+# Code's standard field) rather than Augment's `workspace_roots[0]`.
+# We accept either, falling back through both.
+#
+# Upstream caveat: as of writing this trampoline, lifecycle events do
+# not actually fire from Cowork sessions —
+# anthropics/claude-code#40495 reports all three Claude Code settings
+# sources (user, project, env) are ignored inside Cowork's sandbox,
+# and #27398 reports plugin-scope `hooks/hooks.json` is excluded
+# because Cowork spawns the CLI with `--setting-sources user`. The
+# trampoline is structurally ready; install plumbing is deferred
+# until upstream resolves the bugs and a stable settings location is
+# documented. See `agents/contexts/chat-history-platform-hooks.md`
+# § Cowork.
+#
+# Behaviour mirrors cursor-dispatcher.sh:
+#   - Read JSON event from stdin into a buffer.
+#   - Extract cwd (Claude Code) or workspace_roots[0] (fallback);
+#     bail silently when neither resolves to a directory.
+#   - cd into that workspace; bail silently when it lacks ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config dispatch:hook --platform cowork \
+#           --event $1 --native-event $2
+#   - Always exit 0 — chat-history must never block the agent loop.
+
+set -u
+
+# Args from the platform's hooks config (whatever shape Cowork ends up
+# using once upstream lands the fix):
+#   $1 = agent-config event name (session_start, post_tool_use, …)
+#   $2 = Cowork-native event name (SessionStart, PostToolUse, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+# Debug-only: when ~/.claude/.cowork-chat-history-debug exists, dump
+# the raw stdin payload for offline inspection. No-op otherwise.
+# Useful once upstream fixes #40495 to verify the actual payload shape.
+if [ -f "$HOME/.claude/.cowork-chat-history-debug" ]; then
+    DUMP_DIR="$HOME/.claude/cowork-chat-history-debug"
+    mkdir -p "$DUMP_DIR" 2>/dev/null
+    printf '%s' "$EVENT_DATA" \
+        > "$DUMP_DIR/event-$(date +%Y%m%d-%H%M%S)-$$.json" 2>/dev/null || true
+fi
+
+# Extract workspace path. Try Claude Code's `cwd` first, then fall
+# back to Augment-style `workspace_roots[0]`. Either is acceptable —
+# we need a directory containing ./agent-config.
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.cwd // .workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+cwd = data.get("cwd")
+if isinstance(cwd, str) and cwd:
+    print(cwd)
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config dispatch:hook \
+        --platform cowork \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/dispatch_hook.py

@@ -167,6 +167,40 @@ def _resolve_concerns(manifest: dict, platform: str, event: str) -> list[dict]:
     return out
 
 
+def _maybe_capture_payload(args: argparse.Namespace, payload_text: str) -> None:
+    """Write the raw stdin payload to a capture directory when
+    ``AGENT_HOOK_CAPTURE_DIR`` is set. Used by the verified-platforms
+    discovery roadmap (`agents/roadmaps/road-to-verified-chat-history-platforms.md`)
+    to lock real payload shapes before extractor branches are added.
+
+    Fail-silent: any IO / JSON error must not break dispatch.
+    """
+    capture_dir = os.environ.get("AGENT_HOOK_CAPTURE_DIR", "").strip()
+    if not capture_dir:
+        return
+    try:
+        target = Path(capture_dir).expanduser()
+        target.mkdir(parents=True, exist_ok=True)
+        try:
+            payload = json.loads(payload_text) if payload_text.strip() else {}
+        except (ValueError, TypeError):
+            payload = {"_raw_text": payload_text}
+        record = {
+            "captured_at": _now_iso(),
+            "platform": args.platform,
+            "event": args.event,
+            "native_event": args.native_event or "",
+            "raw_payload": payload,
+        }
+        ts = int(time.time() * 1000)
+        native = (args.native_event or args.event).replace("/", "_")
+        fname = f"{args.platform}__{native}__{ts}__{os.getpid()}.json"
+        (target / fname).write_text(
+            json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    except OSError:
+        return
+
+
 def _build_envelope(args: argparse.Namespace, payload_text: str) -> dict:
     try:
         payload = json.loads(payload_text) if payload_text.strip() else {}
@@ -298,6 +332,7 @@ def main(argv: list[str] | None = None) -> int:
     manifest = _load_yaml(manifest_path)
 
     payload_text = "" if sys.stdin.isatty() else sys.stdin.read()
+    _maybe_capture_payload(args, payload_text)
     concerns = _resolve_concerns(manifest, args.platform, args.event)
 
     if args.dry_run:

package/scripts/hooks_status.py

@@ -25,9 +25,20 @@ import dispatch_hook  # noqa: E402  — reuse the manifest loader
 
 # (label, project-relative bridge path, install hint).
 # Path may be a directory (cline) — existence => any file inside.
+#
+# Cowork has no project-scope bridge path: the Claude desktop app's
+# local-agent-mode runtime is upstream-blocked from reading any of
+# Claude Code's three settings sources (anthropics/claude-code#40495,
+# #27398). We register cowork here so the manifest's `cowork:`
+# bindings are surfaced in the status report, but the empty bridge
+# path resolves to status="n/a" — strict mode does not fail on
+# n/a (see _final_exit_code), matching Copilot's no-bridge posture.
+# Once upstream lands the fix and a stable settings location is
+# documented, swap the empty path here for that location.
 PLATFORM_BRIDGES: dict[str, tuple[str, str]] = {
     "augment":  (".augment/settings.json",      "scripts/install.py"),
     "claude":   (".claude/settings.json",       "scripts/install.py"),
+    "cowork":   ("",                            "upstream-blocked: anthropics/claude-code#40495 + #27398 (settings.json ignored in Cowork sandbox)"),
     "cursor":   (".cursor/hooks.json",          "scripts/install.py"),
     "cline":    (".clinerules/hooks",           "scripts/install.py"),
     "windsurf": (".windsurf/hooks.json",        "scripts/install.py"),
@@ -65,7 +76,7 @@ def collect(project_root: Path, manifest: dict) -> dict:
             "bridge_path": rel or None,
             "fallback_only": fallback_only,
             "bindings": bindings,
-            "hint": hint if status in {"missing", "empty", "degraded"} else None,
+            "hint": hint if status in {"missing", "empty", "degraded", "n/a"} else None,
         })
     return {"schema_version": 1, "platforms": rows}
 

package/scripts/install-hooks.sh

@@ -63,7 +63,7 @@ echo "✅  Pre-commit hook installed."
 # lifecycle hooks) cannot fire SessionStart/Stop/PostToolUse. Git hooks
 # are the platform-agnostic lifecycle surface that fires regardless of
 # IDE — every commit, merge, checkout, and rewrite turns into a phase
-# boundary in .agent-chat-history when an agent session is active.
+# boundary in agents/.agent-chat-history when an agent session is active.
 #
 # The hooks are silent no-ops when no agent session is active (the
 # chat_history.py hook-append script returns "skipped_no_sidecar" with
@@ -75,7 +75,7 @@ write_chat_history_hook() {
     local phase_tag="$2"
     cat > "$HOOKS_DIR/$name" << EOF
 #!/usr/bin/env bash
-# $name: append a phase boundary to .agent-chat-history when an agent
+# $name: append a phase boundary to agents/.agent-chat-history when an agent
 # session is active. Silent no-op otherwise. Never blocks git.
 
 if [ -x ./agent-config ]; then