Add token-efficient CLI output compression and mandatory multi-agent execution (#35)

## Token Efficiency (CLAUDE_TOKEN_EFFICIENCY=1, default enabled)

Two-layer approach to minimize context token consumption:

1. Behavioral guidance (system-prompts/token_efficient_cli.md):
   Injected via SessionStart hook with mandatory MUST/MUST NOT rules
   for compact CLI flags (git -sb, ruff --output-format concise --quiet,
   pytest -q --tb=short, etc). Rules added to all 8 agent definitions
   and orchestrator template for full subagent coverage.

2. Output compression (hooks/compact_run.py):
   PreToolUse hook rewrites matching Bash commands through compact_run.py
   for post-execution output compression. Supports git (push/pull/commit/
   fetch/add/merge/rebase/stash), pytest, cargo test, npm/pnpm/yarn/bun
   test, npx (vitest/jest/mocha/playwright), go test, make test/check,
   docker/kubectl logs. Cross-platform Python (not bash).

## Mandatory Multi-Agent Execution

- Plan mode defaults to team mode when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  (fallback to subagent only when team_mode_score <= -3)
- Minimum 2 subtasks per plan (single-subtask plans prohibited)
- Execution section with teammate/agent table added to plan output format
- 3 reinforcement points in workflow_orchestrator.md for compliance

## Test Suite (196 tests)

- tests/test_compact_run.py: 100 tests for all output compression handlers
- tests/test_token_rewrite_hook.py: command matching, metachar detection, env gating
- tests/test_inject_token_efficiency.py: injection hook, file reading, JSON output
- tests/test_integration.py: end-to-end subprocess execution
- pytest.ini and conftest.py with importlib-based module loading
- CI workflow enabled with ruff lint + pytest

## Other Changes

- Statusline reorganized: row 1 static info, row 2 dynamic metrics
- Removed alwaysThinkingEnabled from settings
- Windows .exe command normalization in rewrite hook and compact_run
- Configurable subprocess timeout (COMPACT_RUN_TIMEOUT, default 120s)
- Plugin version bumped to 1.12.0

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: barkain

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "workflow-orchestrator",
       "source": "./",
       "description": "Delegation system with workflow orchestration, specialized agents, and parallel execution for Claude Code",
-      "version": "1.11.1",
+      "version": "1.12.0",
       "author": {
         "name": "Nadav Barkai"
       },

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow-orchestrator",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Delegation system with workflow orchestration, specialized agents, and parallel execution for Claude Code",
   "author": {
     "name": "Nadav Barkai"

.github/workflows/ci.yml

@@ -29,43 +29,25 @@ jobs:
         with:
           fetch-depth: 0
 
-      # Tests removed - will reimplement later
-      # The previous test suite had hardcoded paths and environment issues
-      # that made it incompatible with CI environments
-
-      # - name: Setup test environment
-      #   run: |
-      #     find tests -name "*.sh" -type f -exec chmod +x {} \;
-      #     find hooks -name "*.sh" -type f -exec chmod +x {} \;
-      #     test -f tests/run_integration_tests.sh || exit 1
-      #     mkdir -p .claude/state
-
-      # - name: Install uv
-      #   uses: astral-sh/setup-uv@v7
-      #   with:
-      #     enable-cache: true
-      #   if: hashFiles('hooks/PostToolUse/python_posttooluse_hook.sh') != ''
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
 
-      # - name: Install Python 3.12
-      #   run: uv python install 3.12
-      #   if: hashFiles('hooks/PostToolUse/python_posttooluse_hook.sh') != ''
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
-      # - name: Run integration tests
-      #   run: |
-      #     bash tests/run_integration_tests.sh --verbose
-      #   env:
-      #     VERBOSE: 1
-      #     CI: true
+      - name: Setup test environment
+        run: mkdir -p .claude/state
 
-      # - name: Upload test logs
-      #   uses: actions/upload-artifact@v4
-      #   if: always()
-      #   with:
-      #     name: test-logs
-      #     path: |
-      #       tests/test-logs/
-      #       tests/output/
-      #     retention-days: 7
+      - name: Run linting
+        run: |
+          uvx ruff check --no-fix .
+          uvx ruff format --check .
 
-      - name: Placeholder
-        run: echo "Test suite will be reimplemented with proper CI compatibility"
+      - name: Run tests
+        run: uvx pytest tests/ -v --tb=short
+        env:
+          CI: true

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.12.0] - 2026-03-14
+
+### Added
+- Token-efficient CLI usage: behavioral guidance injection and output compression hook for reduced context consumption
+- Mandatory multi-agent execution: all plans now produce 2+ subtasks
+- Token efficiency rules enforced across all 8 agent definitions
+- `inject_token_efficiency.py` SessionStart hook and `token_rewrite_hook.py` PreToolUse hook
+
+### Changed
+- Reorganized statusline layout: static info on row 1, metrics on row 2
+- Removed `alwaysThinkingEnabled` from settings
+
 ## [1.11.1] - 2026-03-10
 
 ### Fixed

CLAUDE.md

@@ -46,14 +46,15 @@ uvx ruff format .                # Format code (auto-fix)
 uvx ruff check --no-fix .       # Lint code (check only)
 uvx pyright .                    # Type checking
 uvx deadcode hooks/ scripts/    # Dead code detection
+uvx pytest tests/ -v            # Run test suite
 ```
 
 The PostToolUse hook enforces a specific ruff rule subset on edited Python files:
 ```bash
 uvx ruff check --select F,E711,E712,UP006,UP007,UP035,UP037,T201,S <file>
 ```
 
-CI workflow exists (`.github/workflows/ci.yml`) but tests are currently disabled/placeholder.
+Test suite exists in `tests/` with comprehensive coverage for hooks and token efficiency features.
 
 ---
 
@@ -105,14 +106,14 @@ User prompt
   → Stop hook: calculate turn duration, quality analysis
 ```
 
-### Hook System (6 lifecycle events, 12 scripts)
+### Hook System (6 lifecycle events, 15 scripts)
 
 | Event | Scripts | Purpose |
 |-------|---------|---------|
-| **PreToolUse** (`*`) | `require_delegation.py`, `validate_task_graph_compliance.py` | Block non-allowed tools; validate Agent/Task invocations against active task graph |
+| **PreToolUse** (`*`, `Bash`) | `require_delegation.py`, `validate_task_graph_compliance.py`, `token_rewrite_hook.py` | Block non-allowed tools; validate Agent/Task invocations against active task graph; rewrite Bash commands for token efficiency |
 | **PostToolUse** | `python_posttooluse_hook.py` (Edit/Write/MultiEdit), `remind_skill_continuation.py` (ExitPlanMode\|Skill\|SlashCommand), `validate_task_graph_depth.py` + `remind_todo_after_task.py` (Agent/Task) | Python validation (Ruff, Pyright, security), workflow continuation state (triggers on ExitPlanMode for plan mode flows), depth-3 enforcement, task reminders |
 | **UserPromptSubmit** | `clear-delegation-sessions.py` | Clear delegation state, record turn start timestamp, clear team state (`team_mode_active`, `team_config.json`), rotate logs |
-| **SessionStart** (`startup\|resume\|clear\|compact`) | `inject_workflow_orchestrator.py`, `inject-output-style.py` | Inject system prompt + output style |
+| **SessionStart** (`startup\|resume\|clear\|compact`) | `inject_workflow_orchestrator.py`, `inject-output-style.py`, `inject_token_efficiency.py` | Inject system prompt + output style + token efficiency guidance |
 | **SubagentStop** (`*`) | `remind_todo_update.py` (async), `trigger_verification.py` | Remind to update tasks, suggest verification |
 | **Stop** | `python_stop_hook.py` | Turn duration, workflow continuation (block stop + inject "continue"), quality analysis |
 
@@ -165,7 +166,9 @@ All 8 agents include a conditional COMMUNICATION MODE section: when running as a
 
 The framework supports two execution modes, selected at planning time during native plan mode:
 
-**Subagent mode** (default): Current pipeline. Main agent spawns Agent tool instances per wave. Agents return `DONE|{path}`. Context-efficient, optimal for most workflows.
+Multi-agent execution is mandatory — all plans produce ≥2 subtasks. Default is team mode when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, otherwise parallel subagents.
+
+**Subagent mode**: Current pipeline. Main agent spawns Agent tool instances per wave. Agents return `DONE|{path}`. Context-efficient, used when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is not set.
 
 **Team mode** (experimental): Uses Claude Code's Agent Teams feature. Lead agent calls `TeamCreate(team_name=...)`, then spawns teammates via `Agent(team_name=..., subagent_type=..., prompt=...)`. The `team_name` parameter makes Agent invocations teammates (shared context, `SendMessage`) vs isolated subagents. Teammates self-claim tasks, communicate peer-to-peer. Bridge pattern syncs team task completions to framework Tasks API. Teammates use `SendMessage(type: "message")` for point-to-point communication and `SendMessage(type: "broadcast")` for team-wide announcements. Broadcast sends N separate messages (one per teammate) so prefer point-to-point messaging; reserve broadcast for critical announcements only.
 
@@ -177,7 +180,8 @@ Two team workflow patterns:
 - Phase count >8: +2, Tier 3 complexity: +2, cross-phase data flow: +3
 - Review-fix cycles: +3, iterative refinement: +2, user keyword "collaborate"/"team": +5
 - Breadth task: -5, phase count <=3: -3
-- Score >=5 with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` = team mode
+- With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`: default to team mode; only fall back to subagent when `team_mode_score <= -3` (breadth-only tasks)
+- Without env var: always parallel subagent mode (≥2 subtasks mandatory)
 
 **When team mode is active:**
 - `validate_task_graph_compliance.py` hook is bypassed (team handles dependencies)
@@ -240,6 +244,21 @@ Agent config format: YAML frontmatter (`name`, `description`, optional `tools`/`
 | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `0` | Enable Agent Teams dual-mode (`1` to enable team mode scoring and tools) |
 | `CLAUDE_CODE_ENABLE_TASKS` | `true` | Set `false` to revert to TodoWrite |
 | `CLAUDE_CODE_TASK_LIST_ID` | Per-session | Share task list across sessions |
+| `CLAUDE_TOKEN_EFFICIENCY` | `1` | Enable token-efficient CLI output compression (`0` to disable) |
+
+---
+
+## Token-Efficient CLI Usage
+
+Minimize command output to reduce context consumption. Enabled by default (`CLAUDE_TOKEN_EFFICIENCY=1`).
+
+**Two-layer approach:**
+1. **Behavioral guidance** (`system-prompts/token_efficient_cli.md`): Injected via SessionStart, teaches compact flag usage (e.g., `git status -sb`, `pytest -q --tb=short`)
+2. **Output compression** (`hooks/compact_run.py`): PreToolUse hook rewrites matching Bash commands through `compact_run.py`, which compresses git/test/log output post-execution
+
+**Supported command families:** git (push/pull/commit/etc), pytest, cargo test, npm/pnpm/yarn/bun test, npx (vitest/jest/mocha/playwright), go test, make test/check, docker/kubectl logs
+
+Disable: `export CLAUDE_TOKEN_EFFICIENCY=0`
 
 ---
 
@@ -274,7 +293,7 @@ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 The PreToolUse hook blocks all team tools (`TeamCreate`, `SendMessage`, pattern `*team*`/`*teammate*`) unless this env var is set. The hook prints a specific error message indicating the env var is missing.
 
 **Team mode not activating despite keywords:**
-Ensure `team_mode_score >= 5`. Simple tasks (<=3 phases) get -3, breadth tasks get -5. Add explicit keywords like "collaborate" or "team" (+5) to trigger team mode. Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set -- without it, plan mode always selects `"subagent"` mode regardless of score.
+When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, team mode is the default. It only falls back to subagent mode when `team_mode_score <= -3` (breadth-only tasks with no complexity factors). Without the env var, plan mode always selects `"subagent"` mode (with ≥2 subtasks mandatory).
 
 **Team state files stale after crash:**
 ```bash

README.md

@@ -227,6 +227,11 @@ CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1     # Disable async background tasks
 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1     # Enable Agent Teams dual-mode execution
 ```
 
+**Token Efficiency:**
+```bash
+CLAUDE_TOKEN_EFFICIENCY=1                  # Enable token-efficient CLI output (default: 1)
+```
+
 **Debug & Control:**
 ```bash
 DEBUG_DELEGATION_HOOK=1                    # Enable hook debug logging
@@ -245,29 +250,18 @@ See [Environment Variables](./docs/environment-variables.md) for detailed config
 
 The `plugin-hooks.json` configures the delegation enforcement hooks using cross-platform Python scripts:
 
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [{"type": "command", "command": "uv run --no-project --script \"${CLAUDE_PLUGIN_ROOT}/hooks/PreToolUse/require_delegation.py\""}]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [{"type": "command", "command": "uv run --no-project --script \"${CLAUDE_PLUGIN_ROOT}/hooks/UserPromptSubmit/clear-delegation-sessions.py\""}]
-      }
-    ]
-  }
-}
-```
-
 **Note:** All hooks use `uv run --no-project --script` for cross-platform compatibility (Windows, macOS, Linux). The `--no-project` flag allows execution without requiring a pyproject.toml, and `--script` directly runs Python scripts using uv's managed interpreter.
 
-**PreToolUse Hook**: Intercepts every tool call and enforces delegation policy
-**UserPromptSubmit Hook**: Clears delegation state between user prompts to ensure fresh enforcement
-**SessionStart Hook**: Automatically appends workflow_orchestrator system prompt for seamless multi-step workflow detection
+**Hook Events (6 lifecycle points, 15 scripts):**
+
+| Event | Scripts | Purpose |
+|-------|---------|---------|
+| **PreToolUse** | `validate_task_graph_compliance.py`, `require_delegation.py`, `token_rewrite_hook.py` (Bash only) | Validate task graph compliance; block non-delegated tools; rewrite Bash commands for token efficiency |
+| **PostToolUse** | `python_posttooluse_hook.py` (Edit/Write), `remind_skill_continuation.py` (ExitPlanMode/Skill/SlashCommand), `validate_task_graph_depth.py` (Agent/Task), `remind_todo_after_task.py` (Agent/Task, async) | Python validation (Ruff/Pyright); workflow continuation state; depth-3 enforcement; task reminders |
+| **UserPromptSubmit** | `clear-delegation-sessions.py` | Clear delegation/team state, record turn timestamp |
+| **SessionStart** | `inject_workflow_orchestrator.py`, `inject-output-style.py`, `inject_token_efficiency.py` | Inject system prompts (workflow orchestration, output style, token efficiency) |
+| **SubagentStop** | `remind_todo_update.py` (async), `trigger_verification.py` | Remind to update tasks, suggest verification |
+| **Stop** | `python_stop_hook.py` | Turn duration tracking, workflow continuation |
 
 ### workflow_orchestrator Requirements
 
@@ -505,6 +499,33 @@ Team mode creates two additional state files (automatically cleaned up on comple
 | Permissions set at spawn        | Teammates inherit lead's permission mode                     |
 | Split panes need tmux/iTerm2    | Not supported in VS Code terminal or Windows Terminal        |
 
+## Token-Efficient CLI Usage
+
+The framework minimizes command output to reduce context consumption and preserve tokens for meaningful work. Token efficiency is enabled by default (`CLAUDE_TOKEN_EFFICIENCY=1`).
+
+### Two-Layer Approach
+
+1. **Behavioral Guidance** — The `token_efficient_cli.md` system prompt (injected via SessionStart) teaches compact flag usage:
+   - `git status -sb` (short branch format)
+   - `pytest -q --tb=short` (quiet mode, short tracebacks)
+   - `npm test -- -q` (quiet test output)
+   - Encourages `--help` parsing and targeted commands
+
+2. **Output Compression** — The `token_rewrite_hook.py` PreToolUse hook rewrites matching Bash commands through `compact_run.py`, which compresses git/test/log output post-execution:
+   - Git: `push`, `pull`, `commit`, `merge`, `rebase`, `status`, etc.
+   - Test runners: `pytest`, `cargo test`, `npm/pnpm/yarn/bun test`, `vitest`, `jest`, `mocha`, etc.
+   - Logs: `docker logs`, `kubectl logs`, `make` output
+
+### Disable Token Efficiency
+
+To temporarily disable token-efficient output:
+
+```bash
+export CLAUDE_TOKEN_EFFICIENCY=0
+```
+
+This disables both the behavioral guidance and output compression layers.
+
 ## Contributing
 
 We welcome contributions to the Claude Code Workflow Orchestration System! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
@@ -563,6 +584,31 @@ Found a bug or have a feature request? Please open a GitHub Issue with:
 
 Always run quality checks locally before submitting to catch issues early.
 
+### Test Suite
+
+The project includes a comprehensive test suite covering hooks, token efficiency, and integration:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with verbose output and coverage
+uv run pytest -v --cov=hooks --cov=scripts --cov=system-prompts
+
+# Run specific test file
+uv run pytest tests/test_token_rewrite_hook.py -v
+
+# Run tests matching a pattern
+uv run pytest -k "token_efficiency" -v
+```
+
+Test files:
+- `tests/test_token_rewrite_hook.py` - Token rewriting hook tests
+- `tests/test_inject_token_efficiency.py` - Token efficiency injection tests
+- `tests/test_compact_run.py` - Compact output runner tests
+- `tests/test_integration.py` - End-to-end integration tests
+- `tests/conftest.py` - Test fixtures and configuration
+
 ### We Value
 
 - Clear, well-documented code

agents/code-cleanup-optimizer.md

@@ -56,6 +56,16 @@ Explain why changes improve the code. Distinguish critical improvements from nic
 
 ---
 
+## CLI Efficiency (MANDATORY)
+
+Use compact CLI flags to minimize output tokens:
+- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
+- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
+- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
+- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
+- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
+- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+
 ## FILE WRITING
 
 - You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)

agents/code-reviewer.md

@@ -50,6 +50,16 @@ Provide specific, actionable feedback explaining the 'why' behind recommendation
 - Return EXACTLY: `DONE|{output_file_path}`
 - No summaries, no explanations -- only the path
 
+## CLI Efficiency (MANDATORY)
+
+Use compact CLI flags to minimize output tokens:
+- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
+- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
+- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
+- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
+- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
+- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+
 ## FILE WRITING
 
 - You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)

agents/codebase-context-analyzer.md

@@ -52,6 +52,16 @@ Communicate with precision, cite specific files/functions/lines. State explicitl
 - Return EXACTLY: `DONE|{output_file_path}`
 - No summaries, no explanations -- only the path
 
+## CLI Efficiency (MANDATORY)
+
+Use compact CLI flags to minimize output tokens:
+- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
+- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
+- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
+- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
+- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
+- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+
 ## FILE WRITING
 
 - You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)

agents/dependency-manager.md

@@ -64,6 +64,16 @@ Analyze current state, identify conflicts, provide clear plan with risk assessme
 - Return EXACTLY: `DONE|{output_file_path}`
 - No summaries, no explanations -- only the path
 
+## CLI Efficiency (MANDATORY)
+
+Use compact CLI flags to minimize output tokens:
+- Git: `--quiet` on push/pull/commit, `-sb` on status, `--oneline -n 10` on log, `--stat` on diff
+- Tests: `pytest -q --tb=short --no-header`, `npm test -- --silent`
+- Ruff: ALWAYS `ruff check --output-format concise --quiet`, NEVER bare `ruff check`
+- Files: `ls -1` not `ls -la`, `head -50` not `cat`, `wc -l` before reading
+- Search: `rg -l` for file list, `rg -m 5` to cap matches, scope to directories
+- Always: `| head -N` when output may exceed 50 lines, `--no-pager` on git
+
 ## FILE WRITING
 
 - You HAVE Write tool access for the scratchpad directory ($CLAUDE_SCRATCHPAD_DIR)