# Jiva v0.3.3 — Context & Persona Alignment

**Release Date:** February 28, 2026  
**Type:** Feature Release

## Overview

This release implements the Context & Persona Alignment plan, making all three agents (Manager, Worker, Client) fully context-aware and consistent. It introduces persona-aware validation for the Client agent and replaces the blunt `failureCount` escalation with a richer `CompletionSignal` model for smarter per-subtask corrective strategies.

## New Features

### Shared `AgentContext` (Improvement #1)

- **`AgentContext` type** (`src/core/types/agent-context.ts`): A shared payload containing workspace directory, fresh directive, bounded conversation history (user + assistant + tool roles), and persona context — built once per turn by `DualAgent.buildAgentContext()` and passed to all three agents.
- **`serializeAgentContext()` utility** (`src/core/utils/serialize-agent-context.ts`): Produces a consistent, role-appropriate string block for each agent with configurable token budget limits.
- **Fresh directive per call**: Manager no longer bakes the directive at construction time — it is injected fresh each LLM call, so mid-session directive changes are reflected immediately.
- **Worker now receives directive**: Previously missing, the Worker's system prompt now includes the directive.
- **Client receives full context**: Directive, conversation history, and persona validation context are now included in all Client LLM prompts.
- **Conversation history includes all roles**: `getRecentContext()` now includes `user`, `assistant`, and `tool` messages (previously user-only), preventing coherence failures and duplicate tool calls.

### Client Persona Awareness (Improvement #2)

- **`buildValidationContext()` in DualAgent**: Generates a validation-specific persona context for the Client containing persona name, skill names/descriptions, and constraints — deliberately different from the execution block given to Manager/Worker.
- **Validation-framed persona context**: The Client sees what correct behavior looks like (descriptive, criteria-oriented) rather than how to behave (which would risk the Client directing execution).

### CompletionSignal (Improvement #3)

- **`CompletionSignal` type** (`src/core/types/completion-signal.ts`): A per-subtask assessment with `confidence`, `progressMade`, `blockerType`, and `suggestedStrategy` fields.
- **`analyzeCompletionSignal()` in ClientAgent**: LLM-based analysis producing a signal alongside each `ValidationResult`.
- **Per-subtask retry budget**: Each subtask gets up to 2 correction attempts (configurable). Budget resets per subtask — no session-wide escalation.
- **Corrective strategy dispatch**: `DualAgent` reads `CompletionSignal.blockerType` to choose retry, rephrase, decompose, skip, or escalate — replacing the blunt `failureCount` escalation.
- **`failureCount` demoted to telemetry-only**: No longer drives involvement level escalation. `THOROUGH` involvement is now reserved for explicit user test requests.
- **`resetFailureTracking()` → `resetSessionState()`**: Renamed for clarity (old method kept as deprecated alias for backward compatibility).

### Sub-Agent Context Guidance (Improvement #4 — Phase 1)

- **Prompt-level convention**: Worker's `spawn_agent` documentation now instructs Manager to include relevant directive constraints and conversation summary when spawning sub-agents.
- **AgentSpawner documentation**: Phase 2 note added for optional `parentContext` parameter.

### Tool-Calling Model Support

- **New `'tool-calling'` model type**: An optional dedicated LLM can be configured as the primary model for tool execution (reliable standard-JSON tool-call formatting), with the reasoning model as the secondary fallback.
- **`chatWithFallback()` in `ModelOrchestrator`**: Routes calls to the tool-calling model or reasoning model based on the active phase.
- **2+2 JSON parse failure strategy**: Up to 2 failures on the primary model trigger an automatic switch to the secondary; 2 further failures on the secondary cause a hard-stop. On hard-stop, `failedTools` is always non-empty so the Client's data-driven `CompletionSignal` fires (`strategy: escalate`) instead of retrying indefinitely.
- **Config & CLI**: `tool-calling` is now a valid model type in `JivaConfigSchema`. `jiva config` setup wizard and `update` flow include the new model slot.
- **HTTP session**: Configured via `JIVA_TOOL_CALLING_MODEL_BASE_URL` / `JIVA_TOOL_CALLING_MODEL_API_KEY` / `JIVA_TOOL_CALLING_MODEL_NAME` environment variables.

### Worker Robustness

- **`failedTools: ToolFailure[]` in `WorkerResult`**: Structured per-tool failure data (tool name, args, last error, attempt count) replaces opaque error strings.
- **Per-tool circuit breaker**: A warning is injected into the conversation after 2 failures with the same `(tool, args)` signature; a hard-stop is enforced after 3, blocking further calls via the exact-signature dedup set.
- **Exact tool-signature deduplication** (`executedToolSignatures`): Prevents identical `(tool, args)` pairs from being re-called within a subtask, catching same-file reads and other repetitive calls before the name-only check triggers.
- **Improved completion prompt**: `shouldPromptForCompletion()` no longer uses the instruction text; `create_directory` is excluded from "significant operations" so a directory creation alone does not trigger an early completion check.
- **Honest max-iterations messaging**: When the iteration limit is hit with successful tools, the result now says "Validation required" instead of claiming success — ensuring the Client validates rather than approving automatically.

### DualAgent Orchestration Fixes

- **Correction subtasks inserted at `i+1`** (not appended): Ensures a correction runs before any downstream subtasks that depend on it.
- **Context correction prefix**: All correction subtasks are prefixed with an explicit "CONTEXT CORRECTION" note so the Worker isn't misled by prior conversation turns that claimed success.
- **`escalate` strategy preserves original Worker result**: No longer overwrites `results[]` with a generic ⚠️ string; the Worker's detail (including tool error specifics) is retained for synthesis.
- **`results` carries `approved: boolean`**: Every subtask result is tagged with the Client's verdict, enabling honest synthesis.
- **`synthesizeResponse()` always invokes Manager**: The raw-result short-circuit (returned Worker output directly for single short subtasks) is removed — Manager synthesis now always runs.
- **`resetConversation()` clears conversation ID**: Prevents the next auto-save from appending to the previous conversation's storage entry.

### Manager Honest Synthesis

- Synthesis prompt now separates **validated completed work** from **Client-rejected subtasks**.
- Manager is explicitly instructed not to claim files were created or actions performed if the corresponding subtask was rejected.

### Client Validation Fixes

- **Zero-tools guard exempts `failedTools`**: A Worker that attempted tools but got errors is no longer penalised with an additional "no tools used" rejection.
- **Success check exempts `failedTools`**: The generic "retry with appropriate tool usage" issue is suppressed when structured failures already explain the outcome.
- **Data-driven `CompletionSignal` short-circuit**: If `failedTools.length > 0`, the Client returns `{ confidence: 'none', blockerType: 'tool_failure', suggestedStrategy: 'escalate' }` immediately — no LLM inference needed.

## Bug Fixes

- **`getRecentContext()` now includes assistant + tool roles** — fixes coherence failures where agents couldn't see prior outputs.
- **Manager directive is no longer stale** — fresh directive injected per LLM call instead of only at construction.
- **Worker receives directive** — previously had no access to workspace directive.
- **Client receives workspace context** — now has directive, conversation history, and persona validation context.
- **Repetitive tool-call interrupt message updated** — now correctly handles non-browser tasks instead of giving browser-specific advice.

## Upgrade Instructions

```bash
npm install -g jiva-core@0.3.3
```

## Backward Compatibility

- All changes are additive. Existing consumers that only read `approved` / `issues` / `nextAction` from `ValidationResult` are unaffected.
- `WorkerResult.failedTools` defaults to an empty array — existing callers that don't read it are unaffected.
- The tool-calling model is fully optional; omitting it preserves the existing single-model behaviour.
- `resetFailureTracking()` still works (deprecated alias for `resetSessionState()`).
- Default behavior remains the same for users without directives or personas.
