konstruct/.planning/phases/02-agent-features/02-06-SUMMARY.md

---
phase: 02-agent-features
plan: "06"
subsystem: orchestrator
tags: [escalation, whatsapp, outbound-routing, pipeline-wiring, system-prompt, tdd]
dependency_graph:
  requires:
    - 02-agent-features/02-02 (tasks.py pipeline rewrite)
    - 02-agent-features/02-04 (escalation handler)
    - 02-agent-features/02-05 (WhatsApp outbound + multimodal)
  provides:
    - Escalation handler wired into _process_message pre/post-check
    - WhatsApp outbound routing wired end-to-end (handle_message -> _send_response)
    - Tier-2 WhatsApp business-function scoping in system prompt builder
  affects:
    - packages/orchestrator/orchestrator/tasks.py
    - packages/orchestrator/orchestrator/agents/builder.py
    - tests/unit/test_pipeline_wiring.py
tech_stack:
  added: []
  patterns:
    - Module-level imports in tasks.py for testability (patchable at orchestrator.tasks.*)
    - _build_response_extras() helper for channel-aware extras assembly
    - _build_conversation_metadata() helper for billing keyword v1 detection
    - extras dict pattern: unified channel metadata dict passed through pipeline
key_files:
  created:
    - tests/unit/test_pipeline_wiring.py
  modified:
    - packages/orchestrator/orchestrator/tasks.py
    - packages/orchestrator/orchestrator/agents/builder.py
decisions:
  - "Module-level imports in tasks.py: moved key imports to module level so unit tests can patch at orchestrator.tasks.* rather than source modules"
  - "extras dict unified: Slack (placeholder_ts, channel_id, bot_token) and WhatsApp (phone_number_id, bot_token, wa_id) both carried in one dict through the pipeline"
  - "_build_response_extras(): Slack path injects DB-loaded slack_bot_token; WhatsApp path uses gateway-injected bot_token (no DB lookup needed)"
  - "Escalation pre-check before pending_tool_confirm check: already-escalated convos skip ALL processing including tool confirmations"
  - "wa_id extracted in handle_message from msg.sender.user_id after model_validate, injected into extras dict"
metrics:
  duration: "9m 53s"
  completed_date: "2026-03-24"
  tasks_completed: 2
  files_modified: 3
---

# Phase 2 Plan 06: Escalation and WhatsApp Routing Re-Wire Summary

Re-wired orphaned escalation handler and broken WhatsApp outbound routing into the orchestrator pipeline; added tier-2 WhatsApp business-function scoping to the system prompt builder.

## What Was Built

### Task 1: Escalation + Outbound Routing Re-wire in tasks.py

**Problem:** Plans 02-02 and 02-05 rewrote tasks.py but dropped two integrations:
- `check_escalation_rules` / `escalate_to_human` were never called (orphaned)
- All responses went to `_update_slack_placeholder` directly — WhatsApp replies silently lost
- `handle_message` didn't pop WhatsApp extras before `model_validate` (unknown field errors)

**Solution:**

1. **Module-level imports:** Moved `aioredis`, `check_escalation_rules`, `escalate_to_human`, `build_messages_with_memory`, `run_agent`, `AuditLogger`, `embed_text`, `retrieve_relevant`, `append_message`, `get_recent_messages`, `get_tools_for_agent`, `settings`, `async_session_factory`, `engine`, `escalation_status_key`, `configure_rls_hook`, `current_tenant_id` to module level for testability.

2. **WhatsApp extra extraction in `handle_message`:** Now pops `phone_number_id` and `bot_token` (WhatsApp access_token) before `model_validate`. Extracts `wa_id` from `msg.sender.user_id` after validation. Builds unified `extras` dict.

3. **`_process_message` signature change:** Now accepts `extras: dict | None = None` instead of `placeholder_ts` and `channel_id` separately.

4. **`_build_response_extras()` helper:** Assembles channel-specific response extras:
   - Slack: `{bot_token: db_token, channel_id: ..., placeholder_ts: ...}`
   - WhatsApp: `{phone_number_id: ..., bot_token: gateway_token, wa_id: ...}`

5. **Escalation pre-check:** Before the pending tool confirmation block, checks Redis `escalation_status_key`. If `b"escalated"`, returns early with assistant-mode reply — no LLM call.

6. **All response delivery via `_send_response()`:** Replaced all three `_update_slack_placeholder` calls in `_process_message` with `_send_response(msg.channel, text, response_extras)`. `_update_slack_placeholder` remains the implementation detail inside `_send_response`.

7. **Escalation post-check:** After `run_agent()` returns, calls `check_escalation_rules()` with `_build_conversation_metadata()` output. If a rule matches AND `agent.escalation_assignee` is set, calls `escalate_to_human()` and replaces `response_text` with the confirmation message.

8. **`_build_conversation_metadata()` helper:** Scans recent messages + current text for billing keywords (`billing`, `invoice`, `charge`, `refund`, `payment`, `subscription`). Returns `{billing_dispute: bool, attempts: int}`.

### Task 2: Tier-2 WhatsApp Scoping in builder.py

Added `channel: str = ""` parameter to `build_system_prompt()`, `build_messages_with_memory()`, and `build_messages_with_media()`.

When `channel == "whatsapp"` and `agent.tool_assignments` is non-empty, `build_system_prompt()` appends:

```
You are responding on WhatsApp. You only handle: {topics}.
If the user asks about something outside these topics,
politely redirect them to the allowed topics.
```

`_process_message` now passes `str(msg.channel)` to `build_messages_with_memory()`.

## Test Results

26 new tests in `tests/unit/test_pipeline_wiring.py` — all passing:
- 4 tests: `handle_message` WhatsApp extra extraction
- 3 tests: `_send_response` channel routing
- 2 tests: `_process_message` uses `_send_response` (not `_update_slack_placeholder`)
- 1 test: escalation pre-check skips LLM
- 3 tests: escalation post-check (rule match, assignee set/unset)
- 4 tests: `_build_conversation_metadata` billing keyword detection
- 5 tests: `build_system_prompt` WhatsApp scoping
- 4 tests: `build_messages_with_memory` channel parameter

Existing tests: 66 passing (no regressions):
- `test_escalation.py` (26 tests)
- `test_whatsapp_scoping.py` (14 tests)
- `test_whatsapp_normalize.py` (17 tests)
- `test_whatsapp_verify.py` (9 tests)

## Verification

```
check_escalation_rules wired at: tasks.py:71 (import), :504 (call)
escalate_to_human wired at: tasks.py:71 (import), :514 (call)
_send_response called at: tasks.py:355, :395, :438, :556
_update_slack_placeholder: only inside _send_response (not directly in _process_message)
"You only handle": builder.py:187
```

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 2 - Architecture] Module-level imports for testability**
- **Found during:** Task 1 GREEN phase
- **Issue:** plan specified local imports matching existing pattern, but local imports in `_process_message` make it impossible to patch at `orchestrator.tasks.*` — patching requires module-level binding
- **Fix:** Moved all key imports to module level; kept only `Agent`/`ChannelConnection` ORM models as local imports (to avoid circular import risks at module load time)
- **Files modified:** `packages/orchestrator/orchestrator/tasks.py`
- **Commit:** bd217a4

**2. [Rule 1 - Bug] wa_id set in extras dict from handle_message**
- **Found during:** Task 1 test verification
- **Issue:** Plan specified extracting `wa_id` from `msg.sender.user_id` inside `_process_message`, but `extras` dict was already built in `handle_message` before `_process_message` is called — need to set wa_id in handle_message after model_validate
- **Fix:** `handle_message` extracts `wa_id = msg.sender.user_id` after `model_validate` when `channel == "whatsapp"` and injects into extras dict
- **Files modified:** `packages/orchestrator/orchestrator/tasks.py`
- **Commit:** bd217a4

## Self-Check: PASSED

- FOUND: packages/orchestrator/orchestrator/tasks.py
- FOUND: packages/orchestrator/orchestrator/agents/builder.py
- FOUND: tests/unit/test_pipeline_wiring.py
- FOUND: .planning/phases/02-agent-features/02-06-SUMMARY.md
- FOUND commit: bd217a4 (feat implementation)
- FOUND commit: 77c9cfc (test RED phase)
- 92 tests pass (26 new + 66 existing regressions)